@momentum-design/components 0.9.5 → 0.9.7

package/dist/components/button/button.component.d.ts

@@ -0,0 +1,227 @@
+import { CSSResult, PropertyValueMap } from 'lit';
+import { Component } from '../../models';
+import type { ButtonColor, ButtonType, ButtonVariant, PillButtonSize, IconButtonSize } from './button.types';
+/**
+ * `mdc-button` is a component that can be configured in various ways to suit different use cases.
+ *
+ * Button Variants:
+ * - **Primary**: Solid background color.
+ * - **Secondary**: Transparent background with a solid border.
+ * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
+ *
+ * Button Colors:
+ * - **Positive**: Green color.
+ * - **Negative**: Red color.
+ * - **Accent**: Blue color.
+ * - **Promotional**: Purple color.
+ * - **Default**: White color.
+ *
+ * Button Sizes (in REM units):
+ * - **Pill button**: 40, 32, 28, 24.
+ * - **Icon button**: 64, 52, 40, 32, 28, 24.
+ * - **Tertiary icon button**: 20.
+ *
+ * Button Types:
+ * - **Pill button**: A button that contains text value. Commonly used for call to action, tags, or filters.
+ * - **Pill button with icons**: A button containing an icon either on the left or right side of the button.
+ * - **Icon button**: A button represented by just an icon without any text.
+ * The type of button is inferred based on the presence of slot and/or prefix and postfix icons.
+ *
+ * @dependency mdc-icon
+ *
+ * @tagname mdc-button
+ *
+ * @slot - Text label of the button.
+ */
+declare class Button extends Component {
+    /**
+     * The button's active state indicates whether it is currently toggled on (active) or off (inactive).
+     * When the active state is true, the button is considered to be in an active state, meaning it is toggled on.
+     * Conversely, when the active state is false, the button is in an inactive state, indicating it is toggled off.
+     * @default false
+     */
+    active: boolean;
+    /**
+     * Indicates whether the button is disabled.
+     * The button is currently disabled for user interaction; it is not focusable or clickable.
+     * @default false
+     */
+    disabled: boolean;
+    /**
+     * Indicates whether the button is soft disabled.
+     * When set to `true`, the button appears visually disabled but still allows
+     * focus, click, and keyboard actions to be passed through.
+     *
+     * **Important:** When using soft disabled, consumers must ensure that
+     * the button behaves like a disabled button, allowing only focus and
+     * preventing any interactions (clicks or keyboard actions) from triggering unintended actions.
+     * @default false
+     */
+    softDisabled: boolean;
+    /**
+     * The name of the icon to display as a prefix.
+     * The icon is displayed on the left side of the button.
+     */
+    prefixIcon?: string;
+    /**
+     * The name of the icon to display as a postfix.
+     * The icon is displayed on the right side of the button.
+     */
+    postfixIcon?: string;
+    /**
+     * There are 3 variants of button: primary, secondary, tertiary. They are styled differently.
+     * - **Primary**: Solid background color.
+     * - **Secondary**: Transparent background with a solid border.
+     * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
+     * @default primary
+     */
+    variant: ButtonVariant;
+    /**
+     * Button sizing is based on the button type.
+     * - **Pill button**: 40, 32, 28, 24.
+     * - **Icon button**: 64, 52, 40, 32, 28, 24.
+     * - Tertiary icon button cam also be 20.
+     * @default 32
+     */
+    size: PillButtonSize | IconButtonSize;
+    /**
+     * There are 5 colors for button: positive, negative, accent, promotional, default.
+     * @default default
+     */
+    color: ButtonColor;
+    /**
+     * The tabindex of the button.
+     * @default 0
+     */
+    tabIndex: number;
+    /**
+     * This property defines the ARIA role for the element. By default, it is set to 'button'.
+     * Consumers should override this role when:
+     * - The element is being used in a context where a different role is more appropriate.
+     * - Custom behaviors are implemented that require a specific ARIA role for accessibility purposes.
+     * @default button
+     */
+    role: string;
+    /**
+     * This property defines the type attribute for the button element.
+     * The type attribute specifies the behavior of the button when it is clicked.
+     * - **submit**: The button submits the form data to the server.
+     * - **reset**: The button resets the form data to its initial state.
+     * - **button**: The button does nothing when clicked.
+     * @default button
+     */
+    type: ButtonType;
+    /** @internal */
+    private typeInternal;
+    /** @internal */
+    private iconSize;
+    /**
+     * @internal
+     */
+    private prevTabindex;
+    /**
+     * @internal
+     */
+    private prevPrefixIcon?;
+    /**
+     * @internal
+     */
+    private prevPostfixIcon?;
+    /** @internal */
+    static formAssociated: boolean;
+    /** @internal */
+    private internals;
+    /** @internal */
+    get form(): HTMLFormElement | null;
+    constructor();
+    update(changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
+    private executeAction;
+    /**
+     * Modifies the icon name based on the active state.
+     * If the button is active, the icon name is suffixed with '-filled'.
+     * If the button is inactive, the icon name is restored to its original value.
+     * If '-filled' icon is not available, the icon name remains unchanged.
+     *
+     * @param active - The active state.
+     */
+    private modifyIconName;
+    /**
+     * Sets the class of 'icon' for icon buttons.
+     * @param type - The type of the button.
+     */
+    private setClassBasedOnType;
+    /**
+     * Sets the variant attribute for the button component.
+     * If the provided variant is not included in the BUTTON_VARIANTS,
+     * it defaults to the value specified in DEFAULTS.VARIANT.
+     *
+     * @param variant - The variant to set.
+     */
+    private setVariant;
+    /**
+     * Sets the size attribute for the button component.
+     * Validates the size based on the button type (icon, pill, or tertiary).
+     * Defaults to DEFAULTS.SIZE if invalid.
+     *
+     * @param size - The size to set.
+     */
+    private setSize;
+    /**
+     * Sets the color attribute for the button.
+     * Defaults to DEFAULTS.COLOR if invalid or for tertiary buttons.
+     *
+     * @param color - The color to set.
+     */
+    private setColor;
+    /**
+     * Sets or removes the aria-pressed attribute based on the active state.
+     *
+     * @param element - The target element.
+     * @param active - The active state.
+     */
+    private setAriaPressed;
+    /**
+     * Sets the soft-disabled attribute for the button.
+     * When soft-disabled, the button looks to be disabled but remains focusable and clickable.
+     * Also sets/removes aria-disabled attribute.
+     *
+     * @param element - The button element.
+     * @param softDisabled - The soft-disabled state.
+     */
+    private setSoftDisabled;
+    /**
+     * Sets the disabled attribute for the button.
+     * When disabled, the button is not focusable or clickable, and tabindex is set to -1.
+     * The previous tabindex is stored and restored when enabled.
+     * Also sets/removes aria-disabled attribute.
+     *
+     * @param element - The button element.
+     * @param disabled - The disabled state.
+     */
+    private setDisabled;
+    private triggerClickEvent;
+    /**
+     * Handles the keydown event on the button.
+     * If the key is 'Enter' or 'Space', the button is pressed.
+     * If the key is 'Enter', the button is pressed. The native HTML button works in the same way.
+     *
+     * @param event - The keyboard event.
+     */
+    private handleKeyDown;
+    /**
+     * Handles the keyup event on the button.
+     * If the key is 'Enter' or 'Space', the button is clicked.
+     * If the key is 'Space', the button is pressed. The native HTML button works in the same way.
+     *
+     * @param event - The keyboard event.
+     */
+    private handleKeyUp;
+    /**
+     * Infers the type of button based on the presence of slot and/or prefix and postfix icons.
+     * @param slot - default slot of button
+     */
+    private inferButtonType;
+    render(): import("lit-html").TemplateResult<1>;
+    static styles: Array<CSSResult>;
+}
+export default Button;

package/dist/components/button/button.component.js

@@ -0,0 +1,438 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import styles from './button.styles';
+import { Component } from '../../models';
+import { BUTTON_COLORS, BUTTON_TYPE_INTERNAL, BUTTON_VARIANTS, DEFAULTS, ICON_BUTTON_SIZES, PILL_BUTTON_SIZES, } from './button.constants';
+import { getIconNameWithoutStyle, getIconSize } from './button.utils';
+/**
+ * `mdc-button` is a component that can be configured in various ways to suit different use cases.
+ *
+ * Button Variants:
+ * - **Primary**: Solid background color.
+ * - **Secondary**: Transparent background with a solid border.
+ * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
+ *
+ * Button Colors:
+ * - **Positive**: Green color.
+ * - **Negative**: Red color.
+ * - **Accent**: Blue color.
+ * - **Promotional**: Purple color.
+ * - **Default**: White color.
+ *
+ * Button Sizes (in REM units):
+ * - **Pill button**: 40, 32, 28, 24.
+ * - **Icon button**: 64, 52, 40, 32, 28, 24.
+ * - **Tertiary icon button**: 20.
+ *
+ * Button Types:
+ * - **Pill button**: A button that contains text value. Commonly used for call to action, tags, or filters.
+ * - **Pill button with icons**: A button containing an icon either on the left or right side of the button.
+ * - **Icon button**: A button represented by just an icon without any text.
+ * The type of button is inferred based on the presence of slot and/or prefix and postfix icons.
+ *
+ * @dependency mdc-icon
+ *
+ * @tagname mdc-button
+ *
+ * @slot - Text label of the button.
+ */
+class Button extends Component {
+    /** @internal */
+    get form() {
+        return this.internals.form;
+    }
+    constructor() {
+        super();
+        /**
+         * The button's active state indicates whether it is currently toggled on (active) or off (inactive).
+         * When the active state is true, the button is considered to be in an active state, meaning it is toggled on.
+         * Conversely, when the active state is false, the button is in an inactive state, indicating it is toggled off.
+         * @default false
+         */
+        this.active = false;
+        /**
+         * Indicates whether the button is disabled.
+         * The button is currently disabled for user interaction; it is not focusable or clickable.
+         * @default false
+         */
+        this.disabled = false;
+        /**
+         * Indicates whether the button is soft disabled.
+         * When set to `true`, the button appears visually disabled but still allows
+         * focus, click, and keyboard actions to be passed through.
+         *
+         * **Important:** When using soft disabled, consumers must ensure that
+         * the button behaves like a disabled button, allowing only focus and
+         * preventing any interactions (clicks or keyboard actions) from triggering unintended actions.
+         * @default false
+         */
+        this.softDisabled = false;
+        /**
+         * There are 3 variants of button: primary, secondary, tertiary. They are styled differently.
+         * - **Primary**: Solid background color.
+         * - **Secondary**: Transparent background with a solid border.
+         * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
+         * @default primary
+         */
+        this.variant = DEFAULTS.VARIANT;
+        /**
+         * Button sizing is based on the button type.
+         * - **Pill button**: 40, 32, 28, 24.
+         * - **Icon button**: 64, 52, 40, 32, 28, 24.
+         * - Tertiary icon button cam also be 20.
+         * @default 32
+         */
+        this.size = DEFAULTS.SIZE;
+        /**
+         * There are 5 colors for button: positive, negative, accent, promotional, default.
+         * @default default
+         */
+        this.color = DEFAULTS.COLOR;
+        /**
+         * The tabindex of the button.
+         * @default 0
+         */
+        this.tabIndex = 0;
+        /**
+         * This property defines the ARIA role for the element. By default, it is set to 'button'.
+         * Consumers should override this role when:
+         * - The element is being used in a context where a different role is more appropriate.
+         * - Custom behaviors are implemented that require a specific ARIA role for accessibility purposes.
+         * @default button
+         */
+        this.role = 'button';
+        /**
+         * This property defines the type attribute for the button element.
+         * The type attribute specifies the behavior of the button when it is clicked.
+         * - **submit**: The button submits the form data to the server.
+         * - **reset**: The button resets the form data to its initial state.
+         * - **button**: The button does nothing when clicked.
+         * @default button
+         */
+        this.type = DEFAULTS.TYPE;
+        /** @internal */
+        this.typeInternal = DEFAULTS.TYPE_INTERNAL;
+        /** @internal */
+        this.iconSize = 1;
+        /**
+         * @internal
+         */
+        this.prevTabindex = 0;
+        this.addEventListener('click', this.executeAction.bind(this));
+        this.addEventListener('keydown', this.handleKeyDown.bind(this));
+        this.addEventListener('keyup', this.handleKeyUp.bind(this));
+        /** @internal */
+        this.internals = this.attachInternals();
+    }
+    update(changedProperties) {
+        super.update(changedProperties);
+        if (changedProperties.has('disabled')) {
+            this.setDisabled(this, this.disabled);
+        }
+        if (changedProperties.has('softDisabled')) {
+            this.setSoftDisabled(this, this.softDisabled);
+        }
+        if (changedProperties.has('active')) {
+            this.setAriaPressed(this, this.active);
+            this.modifyIconName(this.active);
+        }
+        if (changedProperties.has('size')) {
+            this.setSize(this.size);
+        }
+        if (changedProperties.has('variant')) {
+            this.setVariant(this.variant);
+            this.setSize(this.size);
+        }
+        if (changedProperties.has('color')) {
+            this.setColor(this.color);
+        }
+        if (changedProperties.has('typeInternal')) {
+            this.setSize(this.size);
+            this.setClassBasedOnType(this.typeInternal);
+        }
+        if (changedProperties.has('prefixIcon') || changedProperties.has('postfixIcon')) {
+            this.inferButtonType();
+        }
+    }
+    executeAction() {
+        if (this.type === 'submit' && this.internals.form) {
+            this.internals.form.requestSubmit();
+        }
+        if (this.type === 'reset' && this.internals.form) {
+            this.internals.form.reset();
+        }
+    }
+    /**
+     * Modifies the icon name based on the active state.
+     * If the button is active, the icon name is suffixed with '-filled'.
+     * If the button is inactive, the icon name is restored to its original value.
+     * If '-filled' icon is not available, the icon name remains unchanged.
+     *
+     * @param active - The active state.
+     */
+    modifyIconName(active) {
+        if (active) {
+            if (this.prefixIcon) {
+                this.prevPrefixIcon = this.prefixIcon;
+                this.prefixIcon = `${getIconNameWithoutStyle(this.prefixIcon)}-filled`;
+            }
+            if (this.postfixIcon) {
+                this.prevPostfixIcon = this.postfixIcon;
+                this.postfixIcon = `${getIconNameWithoutStyle(this.postfixIcon)}-filled`;
+            }
+        }
+        else {
+            if (this.prevPrefixIcon) {
+                this.prefixIcon = this.prevPrefixIcon;
+            }
+            if (this.prevPostfixIcon) {
+                this.postfixIcon = this.prevPostfixIcon;
+            }
+        }
+    }
+    /**
+     * Sets the class of 'icon' for icon buttons.
+     * @param type - The type of the button.
+     */
+    setClassBasedOnType(type) {
+        if (type === BUTTON_TYPE_INTERNAL.ICON) {
+            this.classList.add('mdc-icon-button');
+        }
+        else {
+            this.classList.remove('mdc-icon-button');
+        }
+    }
+    /**
+     * Sets the variant attribute for the button component.
+     * If the provided variant is not included in the BUTTON_VARIANTS,
+     * it defaults to the value specified in DEFAULTS.VARIANT.
+     *
+     * @param variant - The variant to set.
+     */
+    setVariant(variant) {
+        this.setAttribute('variant', Object.values(BUTTON_VARIANTS).includes(variant) ? variant : DEFAULTS.VARIANT);
+    }
+    /**
+     * Sets the size attribute for the button component.
+     * Validates the size based on the button type (icon, pill, or tertiary).
+     * Defaults to DEFAULTS.SIZE if invalid.
+     *
+     * @param size - The size to set.
+     */
+    setSize(size) {
+        const isIconType = this.typeInternal === BUTTON_TYPE_INTERNAL.ICON;
+        const isValidSize = isIconType
+            ? (Object.values(ICON_BUTTON_SIZES).includes(size)
+                && !(size === ICON_BUTTON_SIZES[20] && this.variant !== BUTTON_VARIANTS.TERTIARY))
+            : Object.values(PILL_BUTTON_SIZES).includes(size);
+        this.setAttribute('size', isValidSize ? `${size}` : `${DEFAULTS.SIZE}`);
+        this.iconSize = getIconSize(size);
+    }
+    /**
+     * Sets the color attribute for the button.
+     * Defaults to DEFAULTS.COLOR if invalid or for tertiary buttons.
+     *
+     * @param color - The color to set.
+     */
+    setColor(color) {
+        if (!Object.values(BUTTON_COLORS).includes(color) || this.variant === BUTTON_VARIANTS.TERTIARY) {
+            this.setAttribute('color', `${DEFAULTS.COLOR}`);
+        }
+        else {
+            this.setAttribute('color', color);
+        }
+    }
+    /**
+     * Sets or removes the aria-pressed attribute based on the active state.
+     *
+     * @param element - The target element.
+     * @param active - The active state.
+     */
+    setAriaPressed(element, active) {
+        if (active) {
+            element.setAttribute('aria-pressed', 'true');
+        }
+        else {
+            element.removeAttribute('aria-pressed');
+        }
+    }
+    /**
+     * Sets the soft-disabled attribute for the button.
+     * When soft-disabled, the button looks to be disabled but remains focusable and clickable.
+     * Also sets/removes aria-disabled attribute.
+     *
+     * @param element - The button element.
+     * @param softDisabled - The soft-disabled state.
+     */
+    setSoftDisabled(element, softDisabled) {
+        if (softDisabled) {
+            element.setAttribute('aria-disabled', 'true');
+        }
+        else {
+            element.removeAttribute('aria-disabled');
+        }
+    }
+    /**
+     * Sets the disabled attribute for the button.
+     * When disabled, the button is not focusable or clickable, and tabindex is set to -1.
+     * The previous tabindex is stored and restored when enabled.
+     * Also sets/removes aria-disabled attribute.
+     *
+     * @param element - The button element.
+     * @param disabled - The disabled state.
+     */
+    setDisabled(element, disabled) {
+        if (disabled) {
+            element.setAttribute('aria-disabled', 'true');
+            this.prevTabindex = this.tabIndex;
+            this.tabIndex = -1;
+        }
+        else {
+            this.tabIndex = this.prevTabindex;
+            element.removeAttribute('aria-disabled');
+        }
+    }
+    triggerClickEvent() {
+        const clickEvent = new MouseEvent('click', {
+            bubbles: true,
+            cancelable: true,
+            view: window,
+        });
+        this.dispatchEvent(clickEvent);
+        this.executeAction();
+    }
+    /**
+     * Handles the keydown event on the button.
+     * If the key is 'Enter' or 'Space', the button is pressed.
+     * If the key is 'Enter', the button is pressed. The native HTML button works in the same way.
+     *
+     * @param event - The keyboard event.
+     */
+    handleKeyDown(event) {
+        if (['Enter', ' '].includes(event.key)) {
+            this.classList.add('pressed');
+            if (event.key === 'Enter') {
+                this.triggerClickEvent();
+            }
+        }
+    }
+    /**
+     * Handles the keyup event on the button.
+     * If the key is 'Enter' or 'Space', the button is clicked.
+     * If the key is 'Space', the button is pressed. The native HTML button works in the same way.
+     *
+     * @param event - The keyboard event.
+     */
+    handleKeyUp(event) {
+        if (['Enter', ' '].includes(event.key)) {
+            this.classList.remove('pressed');
+            if (event.key === ' ') {
+                this.triggerClickEvent();
+            }
+        }
+    }
+    /**
+     * Infers the type of button based on the presence of slot and/or prefix and postfix icons.
+     * @param slot - default slot of button
+     */
+    inferButtonType() {
+        var _a, _b;
+        const slot = (_b = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('slot')) === null || _b === void 0 ? void 0 : _b.assignedNodes().length;
+        if (slot && (this.prefixIcon || this.postfixIcon)) {
+            this.typeInternal = BUTTON_TYPE_INTERNAL.PILL_WITH_ICON;
+        }
+        else if (!slot && (this.prefixIcon || this.postfixIcon)) {
+            this.typeInternal = BUTTON_TYPE_INTERNAL.ICON;
+        }
+        else {
+            this.typeInternal = BUTTON_TYPE_INTERNAL.PILL;
+        }
+    }
+    // Note: @click is attached to each of the children of the button.
+    // Adding click listener within the constructor will not work properly when button is disabled.
+    // https://discord.com/channels/1012791295170859069/1047015641225371718/threads/1309446072413720576
+    render() {
+        return html `
+      ${this.prefixIcon ? html `
+        <mdc-icon
+          name="${this.prefixIcon}" 
+          part="prefix-icon" 
+          size=${this.iconSize} 
+          length-unit="rem">
+        </mdc-icon>` : ''}
+      <slot @slotchange=${this.inferButtonType}></slot>
+      ${this.postfixIcon ? html `
+        <mdc-icon
+          name="${this.postfixIcon}" 
+          part="postfix-icon" 
+          size=${this.iconSize} 
+          length-unit="rem">
+        </mdc-icon>` : ''}
+    `;
+    }
+}
+/** @internal */
+Button.formAssociated = true;
+Button.styles = [...Component.styles, ...styles];
+__decorate([
+    property({ type: Boolean }),
+    __metadata("design:type", Object)
+], Button.prototype, "active", void 0);
+__decorate([
+    property({ type: Boolean }),
+    __metadata("design:type", Object)
+], Button.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'soft-disabled' }),
+    __metadata("design:type", Object)
+], Button.prototype, "softDisabled", void 0);
+__decorate([
+    property({ type: String, attribute: 'prefix-icon' }),
+    __metadata("design:type", String)
+], Button.prototype, "prefixIcon", void 0);
+__decorate([
+    property({ type: String, attribute: 'postfix-icon' }),
+    __metadata("design:type", String)
+], Button.prototype, "postfixIcon", void 0);
+__decorate([
+    property({ type: String }),
+    __metadata("design:type", String)
+], Button.prototype, "variant", void 0);
+__decorate([
+    property({ type: Number }),
+    __metadata("design:type", Number)
+], Button.prototype, "size", void 0);
+__decorate([
+    property({ type: String }),
+    __metadata("design:type", String)
+], Button.prototype, "color", void 0);
+__decorate([
+    property({ type: Number, reflect: true }),
+    __metadata("design:type", Object)
+], Button.prototype, "tabIndex", void 0);
+__decorate([
+    property({ type: String, reflect: true }),
+    __metadata("design:type", Object)
+], Button.prototype, "role", void 0);
+__decorate([
+    property({ reflect: true }),
+    __metadata("design:type", String)
+], Button.prototype, "type", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", String)
+], Button.prototype, "typeInternal", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], Button.prototype, "iconSize", void 0);
+export default Button;