@ni/fast-foundation 0.0.2

package/dist/esm/form-associated/form-associated.js

@@ -0,0 +1,464 @@
+import { attr, booleanConverter, DOM, emptyArray, observable, } from "@ni/fast-element";
+import { keyEnter } from "@ni/fast-web-utilities";
+const proxySlotName = "form-associated-proxy";
+const ElementInternalsKey = "ElementInternals";
+/**
+ * @alpha
+ */
+export const supportsElementInternals = ElementInternalsKey in window &&
+    "setFormValue" in window[ElementInternalsKey].prototype;
+const InternalsMap = new WeakMap();
+/**
+ * Base function for providing Custom Element Form Association.
+ *
+ * @alpha
+ */
+export function FormAssociated(BaseCtor) {
+    const C = class extends BaseCtor {
+        /**
+         * Must evaluate to true to enable elementInternals.
+         * Feature detects API support and resolve respectively
+         *
+         * @internal
+         */
+        static get formAssociated() {
+            return supportsElementInternals;
+        }
+        /**
+         * Returns the validity state of the element
+         *
+         * @alpha
+         */
+        get validity() {
+            return this.elementInternals
+                ? this.elementInternals.validity
+                : this.proxy.validity;
+        }
+        /**
+         * Retrieve a reference to the associated form.
+         * Returns null if not associated to any form.
+         *
+         * @alpha
+         */
+        get form() {
+            return this.elementInternals ? this.elementInternals.form : this.proxy.form;
+        }
+        /**
+         * Retrieve the localized validation message,
+         * or custom validation message if set.
+         *
+         * @alpha
+         */
+        get validationMessage() {
+            return this.elementInternals
+                ? this.elementInternals.validationMessage
+                : this.proxy.validationMessage;
+        }
+        /**
+         * Whether the element will be validated when the
+         * form is submitted
+         */
+        get willValidate() {
+            return this.elementInternals
+                ? this.elementInternals.willValidate
+                : this.proxy.willValidate;
+        }
+        /**
+         * A reference to all associated label elements
+         */
+        get labels() {
+            if (this.elementInternals) {
+                return Object.freeze(Array.from(this.elementInternals.labels));
+            }
+            else if (this.proxy instanceof HTMLElement &&
+                this.proxy.ownerDocument &&
+                this.id) {
+                // Labels associated by wrapping the element: <label><custom-element></custom-element></label>
+                const parentLabels = this.proxy.labels;
+                // Labels associated using the `for` attribute
+                const forLabels = Array.from(this.proxy.getRootNode().querySelectorAll(`[for='${this.id}']`));
+                const labels = parentLabels
+                    ? forLabels.concat(Array.from(parentLabels))
+                    : forLabels;
+                return Object.freeze(labels);
+            }
+            else {
+                return emptyArray;
+            }
+        }
+        /**
+         * Invoked when the `value` property changes
+         * @param previous - the previous value
+         * @param next - the new value
+         *
+         * @remarks
+         * If elements extending `FormAssociated` implement a `valueChanged` method
+         * They must be sure to invoke `super.valueChanged(previous, next)` to ensure
+         * proper functioning of `FormAssociated`
+         */
+        valueChanged(previous, next) {
+            this.dirtyValue = true;
+            if (this.proxy instanceof HTMLElement) {
+                this.proxy.value = this.value;
+            }
+            this.currentValue = this.value;
+            this.setFormValue(this.value);
+            this.validate();
+        }
+        currentValueChanged() {
+            this.value = this.currentValue;
+        }
+        /**
+         * Invoked when the `initialValue` property changes
+         *
+         * @param previous - the previous value
+         * @param next - the new value
+         *
+         * @remarks
+         * If elements extending `FormAssociated` implement a `initialValueChanged` method
+         * They must be sure to invoke `super.initialValueChanged(previous, next)` to ensure
+         * proper functioning of `FormAssociated`
+         */
+        initialValueChanged(previous, next) {
+            // If the value is clean and the component is connected to the DOM
+            // then set value equal to the attribute value.
+            if (!this.dirtyValue) {
+                this.value = this.initialValue;
+                this.dirtyValue = false;
+            }
+        }
+        /**
+         * Invoked when the `disabled` property changes
+         *
+         * @param previous - the previous value
+         * @param next - the new value
+         *
+         * @remarks
+         * If elements extending `FormAssociated` implement a `disabledChanged` method
+         * They must be sure to invoke `super.disabledChanged(previous, next)` to ensure
+         * proper functioning of `FormAssociated`
+         */
+        disabledChanged(previous, next) {
+            if (this.proxy instanceof HTMLElement) {
+                this.proxy.disabled = this.disabled;
+            }
+            DOM.queueUpdate(() => this.classList.toggle("disabled", this.disabled));
+        }
+        /**
+         * Invoked when the `name` property changes
+         *
+         * @param previous - the previous value
+         * @param next - the new value
+         *
+         * @remarks
+         * If elements extending `FormAssociated` implement a `nameChanged` method
+         * They must be sure to invoke `super.nameChanged(previous, next)` to ensure
+         * proper functioning of `FormAssociated`
+         */
+        nameChanged(previous, next) {
+            if (this.proxy instanceof HTMLElement) {
+                this.proxy.name = this.name;
+            }
+        }
+        /**
+         * Invoked when the `required` property changes
+         *
+         * @param previous - the previous value
+         * @param next - the new value
+         *
+         * @remarks
+         * If elements extending `FormAssociated` implement a `requiredChanged` method
+         * They must be sure to invoke `super.requiredChanged(previous, next)` to ensure
+         * proper functioning of `FormAssociated`
+         */
+        requiredChanged(prev, next) {
+            if (this.proxy instanceof HTMLElement) {
+                this.proxy.required = this.required;
+            }
+            DOM.queueUpdate(() => this.classList.toggle("required", this.required));
+            this.validate();
+        }
+        /**
+         * The element internals object. Will only exist
+         * in browsers supporting the attachInternals API
+         */
+        get elementInternals() {
+            if (!supportsElementInternals) {
+                return null;
+            }
+            let internals = InternalsMap.get(this);
+            if (!internals) {
+                internals = this.attachInternals();
+                InternalsMap.set(this, internals);
+            }
+            return internals;
+        }
+        constructor(...args) {
+            super(...args);
+            /**
+             * Track whether the value has been changed from the initial value
+             */
+            this.dirtyValue = false;
+            /**
+             * Sets the element's disabled state. A disabled element will not be included during form submission.
+             *
+             * @remarks
+             * HTML Attribute: disabled
+             */
+            this.disabled = false;
+            /**
+             * These are events that are still fired by the proxy
+             * element based on user / programmatic interaction.
+             *
+             * The proxy implementation should be transparent to
+             * the app author, so block these events from emitting.
+             */
+            this.proxyEventsToBlock = ["change", "click"];
+            this.proxyInitialized = false;
+            this.required = false;
+            this.initialValue = this.initialValue || "";
+            if (!this.elementInternals) {
+                // When elementInternals is not supported, formResetCallback is
+                // bound to an event listener, so ensure the handler's `this`
+                // context is correct.
+                this.formResetCallback = this.formResetCallback.bind(this);
+            }
+        }
+        /**
+         * @internal
+         */
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener("keypress", this._keypressHandler);
+            if (!this.value) {
+                this.value = this.initialValue;
+                this.dirtyValue = false;
+            }
+            if (!this.elementInternals) {
+                this.attachProxy();
+                if (this.form) {
+                    this.form.addEventListener("reset", this.formResetCallback);
+                }
+            }
+        }
+        /**
+         * @internal
+         */
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.proxyEventsToBlock.forEach(name => this.proxy.removeEventListener(name, this.stopPropagation));
+            if (!this.elementInternals && this.form) {
+                this.form.removeEventListener("reset", this.formResetCallback);
+            }
+        }
+        /**
+         * Return the current validity of the element.
+         */
+        checkValidity() {
+            return this.elementInternals
+                ? this.elementInternals.checkValidity()
+                : this.proxy.checkValidity();
+        }
+        /**
+         * Return the current validity of the element.
+         * If false, fires an invalid event at the element.
+         */
+        reportValidity() {
+            return this.elementInternals
+                ? this.elementInternals.reportValidity()
+                : this.proxy.reportValidity();
+        }
+        /**
+         * Set the validity of the control. In cases when the elementInternals object is not
+         * available (and the proxy element is used to report validity), this function will
+         * do nothing unless a message is provided, at which point the setCustomValidity method
+         * of the proxy element will be invoked with the provided message.
+         * @param flags - Validity flags
+         * @param message - Optional message to supply
+         * @param anchor - Optional element used by UA to display an interactive validation UI
+         */
+        setValidity(flags, message, anchor) {
+            if (this.elementInternals) {
+                this.elementInternals.setValidity(flags, message, anchor);
+            }
+            else if (typeof message === "string") {
+                this.proxy.setCustomValidity(message);
+            }
+        }
+        /**
+         * Invoked when a connected component's form or fieldset has its disabled
+         * state changed.
+         * @param disabled - the disabled value of the form / fieldset
+         */
+        formDisabledCallback(disabled) {
+            this.disabled = disabled;
+        }
+        formResetCallback() {
+            this.value = this.initialValue;
+            this.dirtyValue = false;
+        }
+        /**
+         * Attach the proxy element to the DOM
+         */
+        attachProxy() {
+            var _a;
+            if (!this.proxyInitialized) {
+                this.proxyInitialized = true;
+                this.proxy.style.display = "none";
+                this.proxyEventsToBlock.forEach(name => this.proxy.addEventListener(name, this.stopPropagation));
+                // These are typically mapped to the proxy during
+                // property change callbacks, but during initialization
+                // on the initial call of the callback, the proxy is
+                // still undefined. We should find a better way to address this.
+                this.proxy.disabled = this.disabled;
+                this.proxy.required = this.required;
+                if (typeof this.name === "string") {
+                    this.proxy.name = this.name;
+                }
+                if (typeof this.value === "string") {
+                    this.proxy.value = this.value;
+                }
+                this.proxy.setAttribute("slot", proxySlotName);
+                this.proxySlot = document.createElement("slot");
+                this.proxySlot.setAttribute("name", proxySlotName);
+            }
+            (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.appendChild(this.proxySlot);
+            this.appendChild(this.proxy);
+        }
+        /**
+         * Detach the proxy element from the DOM
+         */
+        detachProxy() {
+            var _a;
+            this.removeChild(this.proxy);
+            (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.removeChild(this.proxySlot);
+        }
+        /** {@inheritDoc (FormAssociated:interface).validate} */
+        validate(anchor) {
+            if (this.proxy instanceof HTMLElement) {
+                this.setValidity(this.proxy.validity, this.proxy.validationMessage, anchor);
+            }
+        }
+        /**
+         * Associates the provided value (and optional state) with the parent form.
+         * @param value - The value to set
+         * @param state - The state object provided to during session restores and when autofilling.
+         */
+        setFormValue(value, state) {
+            if (this.elementInternals) {
+                this.elementInternals.setFormValue(value, state || value);
+            }
+        }
+        _keypressHandler(e) {
+            switch (e.key) {
+                case keyEnter:
+                    if (this.form instanceof HTMLFormElement) {
+                        // Implicit submission
+                        const defaultButton = this.form.querySelector("[type=submit]");
+                        defaultButton === null || defaultButton === void 0 ? void 0 : defaultButton.click();
+                    }
+                    break;
+            }
+        }
+        /**
+         * Used to stop propagation of proxy element events
+         * @param e - Event object
+         */
+        stopPropagation(e) {
+            e.stopPropagation();
+        }
+    };
+    attr({ mode: "boolean" })(C.prototype, "disabled");
+    attr({ mode: "fromView", attribute: "value" })(C.prototype, "initialValue");
+    attr({ attribute: "current-value" })(C.prototype, "currentValue");
+    attr(C.prototype, "name");
+    attr({ mode: "boolean" })(C.prototype, "required");
+    observable(C.prototype, "value");
+    return C;
+}
+/**
+ * @alpha
+ */
+export function CheckableFormAssociated(BaseCtor) {
+    class C extends FormAssociated(BaseCtor) {
+    }
+    class D extends C {
+        checkedAttributeChanged() {
+            this.defaultChecked = this.checkedAttribute;
+        }
+        /**
+         * @internal
+         */
+        defaultCheckedChanged() {
+            if (!this.dirtyChecked) {
+                // Setting this.checked will cause us to enter a dirty state,
+                // but if we are clean when defaultChecked is changed, we want to stay
+                // in a clean state, so reset this.dirtyChecked
+                this.checked = this.defaultChecked;
+                this.dirtyChecked = false;
+            }
+        }
+        checkedChanged(prev, next) {
+            if (!this.dirtyChecked) {
+                this.dirtyChecked = true;
+            }
+            this.currentChecked = this.checked;
+            this.updateForm();
+            if (this.proxy instanceof HTMLInputElement) {
+                this.proxy.checked = this.checked;
+            }
+            if (prev !== undefined) {
+                this.$emit("change");
+            }
+            this.validate();
+        }
+        currentCheckedChanged(prev, next) {
+            this.checked = this.currentChecked;
+        }
+        constructor(...args) {
+            super(args);
+            /**
+             * Tracks whether the "checked" property has been changed.
+             * This is necessary to provide consistent behavior with
+             * normal input checkboxes
+             */
+            this.dirtyChecked = false;
+            /**
+             * Provides the default checkedness of the input element
+             * Passed down to proxy
+             *
+             * @public
+             * @remarks
+             * HTML Attribute: checked
+             */
+            this.checkedAttribute = false;
+            /**
+             * The checked state of the control.
+             *
+             * @public
+             */
+            this.checked = false;
+            // Re-initialize dirtyChecked because initialization of other values
+            // causes it to become true
+            this.dirtyChecked = false;
+        }
+        updateForm() {
+            const value = this.checked ? this.value : null;
+            this.setFormValue(value, value);
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.updateForm();
+        }
+        formResetCallback() {
+            super.formResetCallback();
+            this.checked = !!this.checkedAttribute;
+            this.dirtyChecked = false;
+        }
+    }
+    attr({ attribute: "checked", mode: "boolean" })(D.prototype, "checkedAttribute");
+    attr({ attribute: "current-checked", converter: booleanConverter })(D.prototype, "currentChecked");
+    observable(D.prototype, "defaultChecked");
+    observable(D.prototype, "checked");
+    return D;
+}

package/dist/esm/form-associated/index.js

@@ -0,0 +1 @@
+export * from "./form-associated.js";

package/dist/esm/foundation-element/foundation-element.js

@@ -0,0 +1,132 @@
+import { __decorate } from "tslib";
+import { FASTElement, observable } from "@ni/fast-element";
+import { ComponentPresentation, DefaultComponentPresentation, } from "../design-system/component-presentation.js";
+/**
+ * Defines a foundation element class that:
+ * 1. Connects the element to its ComponentPresentation
+ * 2. Allows resolving the element template from the instance or ComponentPresentation
+ * 3. Allows resolving the element styles from the instance or ComponentPresentation
+ *
+ * @public
+ */
+export class FoundationElement extends FASTElement {
+    constructor() {
+        super(...arguments);
+        this._presentation = void 0;
+    }
+    /**
+     * A property which resolves the ComponentPresentation instance
+     * for the current component.
+     * @public
+     */
+    get $presentation() {
+        if (this._presentation === void 0) {
+            this._presentation = ComponentPresentation.forTag(this.tagName, this);
+        }
+        return this._presentation;
+    }
+    templateChanged() {
+        if (this.template !== undefined) {
+            this.$fastController.template = this.template;
+        }
+    }
+    stylesChanged() {
+        if (this.styles !== undefined) {
+            this.$fastController.styles = this.styles;
+        }
+    }
+    /**
+     * The connected callback for this FASTElement.
+     * @remarks
+     * This method is invoked by the platform whenever this FoundationElement
+     * becomes connected to the document.
+     * @public
+     */
+    connectedCallback() {
+        if (this.$presentation !== null) {
+            this.$presentation.applyTo(this);
+        }
+        super.connectedCallback();
+    }
+    /**
+     * Defines an element registry function with a set of element definition defaults.
+     * @param elementDefinition - The definition of the element to create the registry
+     * function for.
+     * @public
+     */
+    static compose(elementDefinition) {
+        return (overrideDefinition = {}) => new FoundationElementRegistry(this === FoundationElement
+            ? class extends FoundationElement {
+            }
+            : this, elementDefinition, overrideDefinition);
+    }
+}
+__decorate([
+    observable
+], FoundationElement.prototype, "template", void 0);
+__decorate([
+    observable
+], FoundationElement.prototype, "styles", void 0);
+function resolveOption(option, context, definition) {
+    if (typeof option === "function") {
+        return option(context, definition);
+    }
+    return option;
+}
+/**
+ * Registry capable of defining presentation properties for a DOM Container hierarchy.
+ *
+ * @internal
+ */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export class FoundationElementRegistry {
+    constructor(type, elementDefinition, overrideDefinition) {
+        this.type = type;
+        this.elementDefinition = elementDefinition;
+        this.overrideDefinition = overrideDefinition;
+        this.definition = Object.assign(Object.assign({}, this.elementDefinition), this.overrideDefinition);
+    }
+    register(container, context) {
+        const definition = this.definition;
+        const overrideDefinition = this.overrideDefinition;
+        const prefix = definition.prefix || context.elementPrefix;
+        const name = `${prefix}-${definition.baseName}`;
+        context.tryDefineElement({
+            name,
+            type: this.type,
+            baseClass: this.elementDefinition.baseClass,
+            callback: x => {
+                const presentation = new DefaultComponentPresentation(resolveOption(definition.template, x, definition), resolveOption(definition.styles, x, definition));
+                x.definePresentation(presentation);
+                let shadowOptions = resolveOption(definition.shadowOptions, x, definition);
+                if (x.shadowRootMode) {
+                    // If the design system has overridden the shadow root mode, we need special handling.
+                    if (shadowOptions) {
+                        // If there are shadow options present in the definition, then
+                        // either the component itself has specified an option or the
+                        // registry function has overridden it.
+                        if (!overrideDefinition.shadowOptions) {
+                            // There were shadow options provided by the component and not overridden by
+                            // the registry.
+                            shadowOptions.mode = x.shadowRootMode;
+                        }
+                    }
+                    else if (shadowOptions !== null) {
+                        // If the component author did not provide shadow options,
+                        // and did not null them out (light dom opt-in) then they
+                        // were relying on the FASTElement default. So, if the
+                        // design system provides a mode, we need to create the options
+                        // to override the default.
+                        shadowOptions = { mode: x.shadowRootMode };
+                    }
+                }
+                x.defineElement({
+                    elementOptions: resolveOption(definition.elementOptions, x, definition),
+                    shadowOptions,
+                    attributes: resolveOption(definition.attributes, x, definition),
+                });
+            },
+        });
+    }
+}
+/* eslint-enable @typescript-eslint/no-unused-vars */

package/dist/esm/foundation-element/index.js

@@ -0,0 +1 @@
+export * from "./foundation-element.js";