Repository URL to install this package:
|
Version:
1.0.0-next.10 ▾
|
/**
* @license
* FOURBURNER CONFIDENTIAL
* Unpublished Copyright (C) 2021 FourBurner Technologies, Inc. All Rights Reserved.
*
* NOTICE: All information contained herein is, and remains the property of FOURBURNER TECHNOLOGIES,
* INC. The intellectual and technical concepts contained herein are proprietary to FOURBURNER
* TECHNOLOGIES, INC. and may be covered by U.S. and Foreign Patents, patents in process, and are
* protected by trade secret or copyright law. Dissemination of this information or reproduction of
* this material is strictly forbidden unless prior written permission is obtained from FOURBURNER
* TECHNOLOGIES, INC. Access to the source code contained herein is hereby forbidden to anyone
* except current FOURBURNER TECHNOLOGIES, INC. employees, managers or contractors who have executed
* Confidentiality and Non-disclosure agreements explicitly covering such access.
*
* The copyright notice above does not evidence any actual or intended publication or disclosure of
* this source code, which includes information that is confidential and/or proprietary, and is a
* trade secret, of FOURBURNER TECHNOLOGIES, INC. ANY REPRODUCTION, MODIFICATION, DISTRIBUTION,
* PUBLIC PERFORMANCE, OR PUBLIC DISPLAY OF OR THROUGH USE OF THIS SOURCE CODE WITHOUT THE EXPRESS
* WRITTEN CONSENT OF FOURBURNER TECHNOLOGIES, INC. IS STRICTLY PROHIBITED, AND IN VIOLATION OF
* APPLICABLE LAWS AND INTERNATIONAL TREATIES. THE RECEIPT OR POSSESSION OF THIS SOURCE CODE AND/OR
* RELATED INFORMATION DOES NOT CONVEY OR IMPLY ANY RIGHTS TO REPRODUCE, DISCLOSE OR DISTRIBUTE ITS
* CONTENTS, OR TO MANUFACTURE, USE, OR SELL ANYTHING THAT IT MAY DESCRIBE, IN WHOLE OR IN PART.
*/
import {FocusableOption, FocusMonitor, FocusOrigin} from '@angular/cdk/a11y';
import {BooleanInput, coerceBooleanProperty} from '@angular/cdk/coercion';
import {
AfterViewChecked,
Attribute,
ChangeDetectionStrategy,
ChangeDetectorRef,
Component,
ElementRef,
EventEmitter,
forwardRef,
Inject,
Input,
NgZone,
OnDestroy,
Optional,
Output,
ViewChild,
ViewEncapsulation,
AfterViewInit,
} from '@angular/core';
import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '@angular/forms';
import {
CanColor,
CanDisable,
CanDisableRipple,
HasTabIndex,
TWNDRipple,
mixinColor,
mixinDisabled,
mixinDisableRipple,
mixinTabIndex,
} from '@twnd/ux/core';
import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
import {
TWND_CHECKBOX_DEFAULT_OPTIONS,
TWNDCheckboxDefaultOptions,
TWND_CHECKBOX_DEFAULT_OPTIONS_FACTORY,
} from './checkbox.config';
// Increasing integer for generating unique ids for checkbox components.
let nextUniqueId = 0;
// Default checkbox configuration.
const defaults = TWND_CHECKBOX_DEFAULT_OPTIONS_FACTORY();
/**
* Provider Expression that allows twnd-checkbox to register as a ControlValueAccessor.
* This allows it to support [(ngModel)].
* @docs-private
*/
export const TWND_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = {
provide : NG_VALUE_ACCESSOR,
useExisting : forwardRef(() => TWNDCheckbox),
multi : true,
};
/**
* Represents the different states that require custom transitions between them.
* @docs-private
*/
export const enum TransitionCheckState {
/** The initial state of the component before any user interaction. */
Init,
/** The state representing the component when it's becoming checked. */
Checked,
/** The state representing the component when it's becoming unchecked. */
Unchecked,
/** The state representing the component when it's becoming indeterminate. */
Indeterminate,
}
/** Change event object emitted by TWNDCheckbox. */
export class TWNDCheckboxChange
{
/** The source TWNDCheckbox of the event. */
source: TWNDCheckbox;
/** The new `checked` value of the checkbox. */
checked: boolean;
}
// Boilerplate for applying mixins to TWNDCheckbox.
/** @docs-private */
const _TWNDCheckboxBase = mixinTabIndex(
mixinColor(
mixinDisableRipple(
mixinDisabled(
class {
constructor(public _elementRef: ElementRef) {}
},
),
),
),
);
/**
* A twnd ux checkbox component. Supports all of the functionality of an HTML5 checkbox,
* and exposes a similar API. A TWNDCheckbox can be either checked, unchecked, indeterminate, or
* disabled. Note that all additional accessibility attributes are taken care of by the component,
* so there is no need to provide them yourself. However, if you want to omit a label and still
* have the checkbox be accessible, you may supply an [aria-label] input.
*/
@Component({
selector : 'twnd-checkbox',
templateUrl : 'checkbox.html',
exportAs : 'twndCheckbox',
host : {
'class' : 'twnd-checkbox',
'[id]' : 'id',
'[attr.tabindex]' : 'null',
'[class.twnd-checkbox-indeterminate]' : 'indeterminate',
'[class.twnd-checkbox-checked]' : 'checked',
'[class.twnd-checkbox-disabled]' : 'disabled',
'[class.twnd-checkbox-label-before]' : 'labelPosition == "before"',
'[class._twnd-animation-noopable]' : `_animationMode === 'NoopAnimations'`,
},
providers : [ TWND_CHECKBOX_CONTROL_VALUE_ACCESSOR ],
inputs : [ 'disableRipple', 'color', 'tabIndex' ],
encapsulation : ViewEncapsulation.None,
changeDetection : ChangeDetectionStrategy.OnPush,
})
export class TWNDCheckbox extends _TWNDCheckboxBase implements ControlValueAccessor, AfterViewInit,
AfterViewChecked, OnDestroy,
CanColor, CanDisable, HasTabIndex,
CanDisableRipple, FocusableOption
{
/**
* Attached to the aria-label attribute of the host element. In most cases, aria-labelledby will
* take precedence so this may be omitted.
*/
@Input('aria-label') ariaLabel: string = '';
/**
* Users can specify the `aria-labelledby` attribute which will be forwarded to the input element
*/
@Input('aria-labelledby') ariaLabelledby: string|null = null;
/** The 'aria-describedby' attribute is read after the element's label and field type. */
@Input('aria-describedby') ariaDescribedby: string;
private _uniqueId: string = `twnd-checkbox-${++nextUniqueId}`;
/** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */
@Input() id: string = this._uniqueId;
/** Returns the unique id for the visual hidden input. */
get inputId(): string
{
return `${this.id || this._uniqueId}-input`;
}
/** Whether the checkbox is required. */
@Input() get required(): boolean
{
return this._required;
}
set required(value: BooleanInput)
{
this._required = coerceBooleanProperty(value);
}
private _required: boolean;
/** Whether the label should appear after or before the checkbox. Defaults to 'after' */
@Input() labelPosition: 'before'|'after' = 'after';
/** Name value will be applied to the input element if present */
@Input() name: string|null = null;
/** Event emitted when the checkbox's `checked` value changes. */
@Output()
readonly change: EventEmitter<TWNDCheckboxChange> = new EventEmitter<TWNDCheckboxChange>();
/** Event emitted when the checkbox's `indeterminate` value changes. */
@Output() readonly indeterminateChange: EventEmitter<boolean> = new EventEmitter<boolean>();
/** The value attribute of the native input element */
@Input() value: string;
/** The native `<input type="checkbox">` element */
@ViewChild('input') _inputElement: ElementRef<HTMLInputElement>;
/** Reference to the ripple instance of the checkbox. */
@ViewChild(TWNDRipple) ripple: TWNDRipple;
/**
* Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor.
* @docs-private
*/
_onTouched: () => any = () => {
};
private _currentAnimationClass: string = '';
private _currentCheckState: TransitionCheckState = TransitionCheckState.Init;
private _controlValueAccessorChangeFn: (value: any) => void = () => {
};
constructor(
elementRef: ElementRef<HTMLElement>,
private _changeDetectorRef: ChangeDetectorRef,
private _focusMonitor: FocusMonitor,
private _ngZone: NgZone,
@Attribute('tabindex') tabIndex: string,
@Optional() @Inject(ANIMATION_MODULE_TYPE) public _animationMode?: string,
@Optional() @Inject(TWND_CHECKBOX_DEFAULT_OPTIONS) private _options?:
TWNDCheckboxDefaultOptions,
)
{
super(elementRef);
this._options = this._options || defaults;
this.color = this.defaultColor = this._options.color || defaults.color;
this.tabIndex = parseInt(tabIndex) || 0;
}
ngAfterViewInit()
{
this._focusMonitor.monitor(this._elementRef, true).subscribe(focusOrigin => {
if (!focusOrigin) {
// When a focused element becomes disabled, the browser *immediately* fires a blur event.
// Angular does not expect events to be raised during change detection, so any state change
// (such as a form control's 'ng-touched') will cause a changed-after-checked error.
// See https://github.com/angular/angular/issues/17793. To work around this, we defer
// telling the form control it has been touched until the next tick.
Promise.resolve().then(() => {
this._onTouched();
this._changeDetectorRef.markForCheck();
});
}
});
this._syncIndeterminate(this._indeterminate);
}
// TODO: Delete next major revision.
ngAfterViewChecked() {}
ngOnDestroy()
{
this._focusMonitor.stopMonitoring(this._elementRef);
}
/**
* Whether the checkbox is checked.
*/
@Input() get checked(): boolean
{
return this._checked;
}
set checked(value: boolean)
{
if (value != this.checked) {
this._checked = value;
this._changeDetectorRef.markForCheck();
}
}
private _checked: boolean = false;
/**
* Whether the checkbox is disabled. This fully overrides the implementation provided by
* mixinDisabled, but the mixin is still required because mixinTabIndex requires it.
*/
@Input() override get disabled(): boolean
{
return this._disabled;
}
override set disabled(value: BooleanInput)
{
const newValue = coerceBooleanProperty(value);
if (newValue !== this.disabled) {
this._disabled = newValue;
this._changeDetectorRef.markForCheck();
}
}
private _disabled: boolean = false;
/**
* Whether the checkbox is indeterminate. This is also known as "mixed" mode and can be used to
* represent a checkbox with three states, e.g. a checkbox that represents a nested list of
* checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately
* set to false.
*/
@Input() get indeterminate(): boolean
{
return this._indeterminate;
}
set indeterminate(value: BooleanInput)
{
const changed = value != this._indeterminate;
this._indeterminate = coerceBooleanProperty(value);
if (changed) {
if (this._indeterminate) {
this._transitionCheckState(TransitionCheckState.Indeterminate);
} else {
this._transitionCheckState(
this.checked ? TransitionCheckState.Checked : TransitionCheckState.Unchecked,
);
}
this.indeterminateChange.emit(this._indeterminate);
}
this._syncIndeterminate(this._indeterminate);
}
private _indeterminate: boolean = false;
_isRippleDisabled()
{
return this.disableRipple || this.disabled;
}
/** Method being called whenever the label text changes. */
_onLabelTextChange()
{
// Since the event of the `cdkObserveContent` directive runs outside of the zone, the checkbox
// component will be only marked for check, but no actual change detection runs automatically.
// Instead of going back into the zone in order to trigger a change detection which causes
// *all* components to be checked (if explicitly marked or not using OnPush), we only trigger
// an explicit change detection for the checkbox view and its children.
this._changeDetectorRef.detectChanges();
}
// Implemented as part of ControlValueAccessor.
writeValue(value: any)
{
this.checked = !!value;
}
// Implemented as part of ControlValueAccessor.
registerOnChange(fn: (value: any) => void)
{
this._controlValueAccessorChangeFn = fn;
}
// Implemented as part of ControlValueAccessor.
registerOnTouched(fn: any)
{
this._onTouched = fn;
}
// Implemented as part of ControlValueAccessor.
setDisabledState(isDisabled: boolean)
{
this.disabled = isDisabled;
}
_getAriaChecked(): 'true'|'false'|'mixed'
{
if (this.checked) {
return 'true';
}
return this.indeterminate ? 'mixed' : 'false';
}
private _transitionCheckState(newState: TransitionCheckState)
{
let oldState = this._currentCheckState;
let element: HTMLElement = this._elementRef.nativeElement;
if (oldState === newState) {
return;
}
if (this._currentAnimationClass.length > 0) {
element.classList.remove(this._currentAnimationClass);
}
this._currentAnimationClass = this._getAnimationClassForCheckStateTransition(
oldState,
newState,
);
this._currentCheckState = newState;
if (this._currentAnimationClass.length > 0) {
element.classList.add(this._currentAnimationClass);
// Remove the animation class to avoid animation when the checkbox is moved between containers
const animationClass = this._currentAnimationClass;
this._ngZone.runOutsideAngular(() => {
setTimeout(() => {
element.classList.remove(animationClass);
}, 1000);
});
}
}
private _emitChangeEvent()
{
const event = new TWNDCheckboxChange();
event.source = this;
event.checked = this.checked;
this._controlValueAccessorChangeFn(this.checked);
this.change.emit(event);
// Assigning the value again here is redundant, but we have to do it in case it was
// changed inside the `change` listener which will cause the input to be out of sync.
if (this._inputElement) {
this._inputElement.nativeElement.checked = this.checked;
}
}
/** Toggles the `checked` state of the checkbox. */
toggle(): void
{
this.checked = !this.checked;
}
/**
* Event handler for checkbox input element.
* Toggles checked state if element is not disabled.
* Do not toggle on (change) event since IE doesn't fire change event when
* indeterminate checkbox is clicked.
* @param event
*/
_onInputClick(event: Event)
{
const clickAction = this._options?.clickAction;
// We have to stop propagation for click events on the visual hidden input element.
// By default, when a user clicks on a label element, a generated click event will be
// dispatched on the associated input element. Since we are using a label element as our
// root container, the click event on the `checkbox` will be executed twice.
// The real click event will bubble up, and the generated click event also tries to bubble up.
// This will lead to multiple click events.
// Preventing bubbling for the second event will solve that issue.
event.stopPropagation();
// If resetIndeterminate is false, and the current state is indeterminate, do nothing on click
if (!this.disabled && clickAction !== 'noop') {
// When user manually click on the checkbox, `indeterminate` is set to false.
if (this.indeterminate && clickAction !== 'check') {
Promise.resolve().then(() => {
this._indeterminate = false;
this.indeterminateChange.emit(this._indeterminate);
});
}
this.toggle();
this._transitionCheckState(
this._checked ? TransitionCheckState.Checked : TransitionCheckState.Unchecked,
);
// Emit our custom change event if the native input emitted one.
// It is important to only emit it, if the native input triggered one, because
// we don't want to trigger a change event, when the `checked` variable changes for example.
this._emitChangeEvent();
} else if (!this.disabled && clickAction === 'noop') {
// Reset native input when clicked with noop. The native checkbox becomes checked after
// click, reset it to be align with `checked` value of `twnd-checkbox`.
this._inputElement.nativeElement.checked = this.checked;
this._inputElement.nativeElement.indeterminate = this.indeterminate;
}
}
/** Focuses the checkbox. */
focus(origin?: FocusOrigin, options?: FocusOptions): void
{
if (origin) {
this._focusMonitor.focusVia(this._inputElement, origin, options);
} else {
this._inputElement.nativeElement.focus(options);
}
}
_onInteractionEvent(event: Event)
{
// We always have to stop propagation on the change event.
// Otherwise the change event, from the input element, will bubble up and
// emit its event object to the `change` output.
event.stopPropagation();
}
private _getAnimationClassForCheckStateTransition(
oldState: TransitionCheckState,
newState: TransitionCheckState,
): string
{
// Don't transition if animations are disabled.
if (this._animationMode === 'NoopAnimations') {
return '';
}
let animSuffix: string = '';
switch (oldState) {
case TransitionCheckState.Init:
// Handle edge case where user interacts with checkbox that does not have [(ngModel)] or
// [checked] bound to it.
if (newState === TransitionCheckState.Checked) {
animSuffix = 'unchecked-checked';
} else if (newState == TransitionCheckState.Indeterminate) {
animSuffix = 'unchecked-indeterminate';
} else {
return '';
}
break;
case TransitionCheckState.Unchecked:
animSuffix = newState === TransitionCheckState.Checked ? 'unchecked-checked' :
'unchecked-indeterminate';
break;
case TransitionCheckState.Checked:
animSuffix = newState === TransitionCheckState.Unchecked ? 'checked-unchecked' :
'checked-indeterminate';
break;
case TransitionCheckState.Indeterminate:
animSuffix = newState === TransitionCheckState.Checked ? 'indeterminate-checked' :
'indeterminate-unchecked';
break;
}
return `twnd-checkbox-anim-${animSuffix}`;
}
/**
* Syncs the indeterminate value with the checkbox DOM node.
*
* We sync `indeterminate` directly on the DOM node, because in Ivy the check for whether a
* property is supported on an element boils down to `if (propName in element)`. Domino's
* HTMLInputElement doesn't have an `indeterminate` property so Ivy will warn during
* server-side rendering.
*/
private _syncIndeterminate(value: boolean)
{
const nativeCheckbox = this._inputElement;
if (nativeCheckbox) {
nativeCheckbox.nativeElement.indeterminate = value;
}
}
}