@ni/fast-foundation 0.0.2

package/dist/esm/design-token/design-token.js

@@ -0,0 +1,657 @@
+import { __decorate } from "tslib";
+import { CSSDirective, defaultExecutionContext, FASTElement, observable, Observable, } from "@ni/fast-element";
+import { composedParent } from "../utilities/composed-parent.js";
+import { composedContains } from "../utilities/composed-contains.js";
+import { PropertyTargetManager, RootStyleSheetTarget, } from "./custom-property-manager.js";
+import { defaultElement } from "./custom-property-manager.js";
+/**
+ * Implementation of {@link (DesignToken:interface)}
+ */
+class DesignTokenImpl extends CSSDirective {
+    get appliedTo() {
+        return [...this._appliedTo];
+    }
+    static from(nameOrConfig) {
+        return new DesignTokenImpl({
+            name: typeof nameOrConfig === "string" ? nameOrConfig : nameOrConfig.name,
+            cssCustomPropertyName: typeof nameOrConfig === "string"
+                ? nameOrConfig
+                : nameOrConfig.cssCustomPropertyName === void 0
+                    ? nameOrConfig.name
+                    : nameOrConfig.cssCustomPropertyName,
+        });
+    }
+    static isCSSDesignToken(token) {
+        return typeof token.cssCustomProperty === "string";
+    }
+    static isDerivedDesignTokenValue(value) {
+        return typeof value === "function";
+    }
+    /**
+     * Gets a token by ID. Returns undefined if the token was not found.
+     * @param id - The ID of the token
+     * @returns
+     */
+    static getTokenById(id) {
+        return DesignTokenImpl.tokensById.get(id);
+    }
+    getOrCreateSubscriberSet(target = this) {
+        return (this.subscribers.get(target) ||
+            (this.subscribers.set(target, new Set()) && this.subscribers.get(target)));
+    }
+    constructor(configuration) {
+        super();
+        this.subscribers = new WeakMap();
+        this._appliedTo = new Set();
+        this.name = configuration.name;
+        if (configuration.cssCustomPropertyName !== null) {
+            this.cssCustomProperty = `--${configuration.cssCustomPropertyName}`;
+            this.cssVar = `var(${this.cssCustomProperty})`;
+        }
+        this.id = DesignTokenImpl.uniqueId();
+        DesignTokenImpl.tokensById.set(this.id, this);
+    }
+    createCSS() {
+        return this.cssVar || "";
+    }
+    getValueFor(element) {
+        const value = DesignTokenNode.getOrCreate(element).get(this);
+        if (value !== undefined) {
+            return value;
+        }
+        throw new Error(`Value could not be retrieved for token named "${this.name}". Ensure the value is set for ${element} or an ancestor of ${element}.`);
+    }
+    setValueFor(element, value) {
+        this._appliedTo.add(element);
+        if (value instanceof DesignTokenImpl) {
+            value = this.alias(value);
+        }
+        DesignTokenNode.getOrCreate(element).set(this, value);
+        return this;
+    }
+    deleteValueFor(element) {
+        this._appliedTo.delete(element);
+        if (DesignTokenNode.existsFor(element)) {
+            DesignTokenNode.getOrCreate(element).delete(this);
+        }
+        return this;
+    }
+    withDefault(value) {
+        this.setValueFor(defaultElement, value);
+        return this;
+    }
+    subscribe(subscriber, target) {
+        const subscriberSet = this.getOrCreateSubscriberSet(target);
+        if (target && !DesignTokenNode.existsFor(target)) {
+            DesignTokenNode.getOrCreate(target);
+        }
+        if (!subscriberSet.has(subscriber)) {
+            subscriberSet.add(subscriber);
+        }
+    }
+    unsubscribe(subscriber, target) {
+        const list = this.subscribers.get(target || this);
+        if (list && list.has(subscriber)) {
+            list.delete(subscriber);
+        }
+    }
+    /**
+     * Notifies subscribers that the value for an element has changed.
+     * @param element - The element to emit a notification for
+     */
+    notify(element) {
+        const record = Object.freeze({ token: this, target: element });
+        if (this.subscribers.has(this)) {
+            this.subscribers.get(this).forEach(sub => sub.handleChange(record));
+        }
+        if (this.subscribers.has(element)) {
+            this.subscribers.get(element).forEach(sub => sub.handleChange(record));
+        }
+    }
+    /**
+     * Alias the token to the provided token.
+     * @param token - the token to alias to
+     */
+    alias(token) {
+        return ((target) => token.getValueFor(target));
+    }
+}
+DesignTokenImpl.uniqueId = (() => {
+    let id = 0;
+    return () => {
+        id++;
+        return id.toString(16);
+    };
+})();
+/**
+ * Token storage by token ID
+ */
+DesignTokenImpl.tokensById = new Map();
+class CustomPropertyReflector {
+    startReflection(token, target) {
+        token.subscribe(this, target);
+        this.handleChange({ token, target });
+    }
+    stopReflection(token, target) {
+        token.unsubscribe(this, target);
+        this.remove(token, target);
+    }
+    handleChange(record) {
+        const { token, target } = record;
+        this.add(token, target);
+    }
+    add(token, target) {
+        PropertyTargetManager.getOrCreate(target).setProperty(token.cssCustomProperty, this.resolveCSSValue(DesignTokenNode.getOrCreate(target).get(token)));
+    }
+    remove(token, target) {
+        PropertyTargetManager.getOrCreate(target).removeProperty(token.cssCustomProperty);
+    }
+    resolveCSSValue(value) {
+        return value && typeof value.createCSS === "function" ? value.createCSS() : value;
+    }
+}
+/**
+ * A light wrapper around BindingObserver to handle value caching and
+ * token notification
+ */
+class DesignTokenBindingObserver {
+    constructor(source, token, node) {
+        this.source = source;
+        this.token = token;
+        this.node = node;
+        this.dependencies = new Set();
+        this.observer = Observable.binding(source, this, false);
+        // This is a little bit hacky because it's using internal APIs of BindingObserverImpl.
+        // BindingObserverImpl queues updates to batch it's notifications which doesn't work for this
+        // scenario because the DesignToken.getValueFor API is not async. Without this, using DesignToken.getValueFor()
+        // after DesignToken.setValueFor() when setting a dependency of the value being retrieved can return a stale
+        // value. Assigning .handleChange to .call forces immediate invocation of this classes handleChange() method,
+        // allowing resolution of values synchronously.
+        // TODO: https://github.com/microsoft/fast/issues/5110
+        this.observer.handleChange = this.observer.call;
+        this.handleChange();
+    }
+    disconnect() {
+        this.observer.disconnect();
+    }
+    /**
+     * @internal
+     */
+    handleChange() {
+        try {
+            this.node.store.set(this.token, this.observer.observe(this.node.target, defaultExecutionContext));
+        }
+        catch (e) {
+            console.error(e);
+        }
+    }
+}
+/**
+ * Stores resolved token/value pairs and notifies on changes
+ */
+class Store {
+    constructor() {
+        this.values = new Map();
+    }
+    set(token, value) {
+        if (this.values.get(token) !== value) {
+            this.values.set(token, value);
+            Observable.getNotifier(this).notify(token.id);
+        }
+    }
+    get(token) {
+        Observable.track(this, token.id);
+        return this.values.get(token);
+    }
+    delete(token) {
+        this.values.delete(token);
+        Observable.getNotifier(this).notify(token.id);
+    }
+    all() {
+        return this.values.entries();
+    }
+}
+const nodeCache = new WeakMap();
+const childToParent = new WeakMap();
+/**
+ * A node responsible for setting and getting token values,
+ * emitting values to CSS custom properties, and maintaining
+ * inheritance structures.
+ */
+class DesignTokenNode {
+    /**
+     * Returns a DesignTokenNode for an element.
+     * Creates a new instance if one does not already exist for a node,
+     * otherwise returns the cached instance
+     *
+     * @param target - The HTML element to retrieve a DesignTokenNode for
+     */
+    static getOrCreate(target) {
+        return nodeCache.get(target) || new DesignTokenNode(target);
+    }
+    /**
+     * Determines if a DesignTokenNode has been created for a target
+     * @param target - The element to test
+     */
+    static existsFor(target) {
+        return nodeCache.has(target);
+    }
+    /**
+     * Searches for and return the nearest parent DesignTokenNode.
+     * Null is returned if no node is found or the node provided is for a default element.
+     */
+    static findParent(node) {
+        if (!(defaultElement === node.target)) {
+            let parent = composedParent(node.target);
+            while (parent !== null) {
+                if (nodeCache.has(parent)) {
+                    return nodeCache.get(parent);
+                }
+                parent = composedParent(parent);
+            }
+            return DesignTokenNode.getOrCreate(defaultElement);
+        }
+        return null;
+    }
+    /**
+     * Finds the closest node with a value explicitly assigned for a token, otherwise null.
+     * @param token - The token to look for
+     * @param start - The node to start looking for value assignment
+     * @returns
+     */
+    static findClosestAssignedNode(token, start) {
+        let current = start;
+        do {
+            if (current.has(token)) {
+                return current;
+            }
+            current = current.parent
+                ? current.parent
+                : current.target !== defaultElement
+                    ? DesignTokenNode.getOrCreate(defaultElement)
+                    : null;
+        } while (current !== null);
+        return null;
+    }
+    /**
+     * The parent DesignTokenNode, or null.
+     */
+    get parent() {
+        return childToParent.get(this) || null;
+    }
+    updateCSSTokenReflection(source, token) {
+        if (DesignTokenImpl.isCSSDesignToken(token)) {
+            const parent = this.parent;
+            const reflecting = this.isReflecting(token);
+            if (parent) {
+                const parentValue = parent.get(token);
+                const sourceValue = source.get(token);
+                if (parentValue !== sourceValue && !reflecting) {
+                    this.reflectToCSS(token);
+                }
+                else if (parentValue === sourceValue && reflecting) {
+                    this.stopReflectToCSS(token);
+                }
+            }
+            else if (!reflecting) {
+                this.reflectToCSS(token);
+            }
+        }
+    }
+    constructor(target) {
+        this.target = target;
+        /**
+         * Stores all resolved token values for a node
+         */
+        this.store = new Store();
+        /**
+         * All children assigned to the node
+         */
+        this.children = [];
+        /**
+         * All values explicitly assigned to the node in their raw form
+         */
+        this.assignedValues = new Map();
+        /**
+         * Tokens currently being reflected to CSS custom properties
+         */
+        this.reflecting = new Set();
+        /**
+         * Binding observers for assigned and inherited derived values.
+         */
+        this.bindingObservers = new Map();
+        /**
+         * Emits notifications to token when token values
+         * change the DesignTokenNode
+         */
+        this.tokenValueChangeHandler = {
+            handleChange: (source, arg) => {
+                const token = DesignTokenImpl.getTokenById(arg);
+                if (token) {
+                    // Notify any token subscribers
+                    token.notify(this.target);
+                    this.updateCSSTokenReflection(source, token);
+                }
+            },
+        };
+        nodeCache.set(target, this);
+        // Map store change notifications to token change notifications
+        Observable.getNotifier(this.store).subscribe(this.tokenValueChangeHandler);
+        if (target instanceof FASTElement) {
+            target.$fastController.addBehaviors([this]);
+        }
+        else if (target.isConnected) {
+            this.bind();
+        }
+    }
+    /**
+     * Checks if a token has been assigned an explicit value the node.
+     * @param token - the token to check.
+     */
+    has(token) {
+        return this.assignedValues.has(token);
+    }
+    /**
+     * Gets the value of a token for a node
+     * @param token - The token to retrieve the value for
+     * @returns
+     */
+    get(token) {
+        const value = this.store.get(token);
+        if (value !== undefined) {
+            return value;
+        }
+        const raw = this.getRaw(token);
+        if (raw !== undefined) {
+            this.hydrate(token, raw);
+            return this.get(token);
+        }
+    }
+    /**
+     * Retrieves the raw assigned value of a token from the nearest assigned node.
+     * @param token - The token to retrieve a raw value for
+     * @returns
+     */
+    getRaw(token) {
+        var _a;
+        if (this.assignedValues.has(token)) {
+            return this.assignedValues.get(token);
+        }
+        return (_a = DesignTokenNode.findClosestAssignedNode(token, this)) === null || _a === void 0 ? void 0 : _a.getRaw(token);
+    }
+    /**
+     * Sets a token to a value for a node
+     * @param token - The token to set
+     * @param value - The value to set the token to
+     */
+    set(token, value) {
+        if (DesignTokenImpl.isDerivedDesignTokenValue(this.assignedValues.get(token))) {
+            this.tearDownBindingObserver(token);
+        }
+        this.assignedValues.set(token, value);
+        if (DesignTokenImpl.isDerivedDesignTokenValue(value)) {
+            this.setupBindingObserver(token, value);
+        }
+        else {
+            this.store.set(token, value);
+        }
+    }
+    /**
+     * Deletes a token value for the node.
+     * @param token - The token to delete the value for
+     */
+    delete(token) {
+        this.assignedValues.delete(token);
+        this.tearDownBindingObserver(token);
+        const upstream = this.getRaw(token);
+        if (upstream) {
+            this.hydrate(token, upstream);
+        }
+        else {
+            this.store.delete(token);
+        }
+    }
+    /**
+     * Invoked when the DesignTokenNode.target is attached to the document
+     */
+    bind() {
+        const parent = DesignTokenNode.findParent(this);
+        if (parent) {
+            parent.appendChild(this);
+        }
+        for (const key of this.assignedValues.keys()) {
+            key.notify(this.target);
+        }
+    }
+    /**
+     * Invoked when the DesignTokenNode.target is detached from the document
+     */
+    unbind() {
+        if (this.parent) {
+            const parent = childToParent.get(this);
+            parent.removeChild(this);
+        }
+        for (const token of this.bindingObservers.keys()) {
+            this.tearDownBindingObserver(token);
+        }
+    }
+    /**
+     * Appends a child to a parent DesignTokenNode.
+     * @param child - The child to append to the node
+     */
+    appendChild(child) {
+        if (child.parent) {
+            childToParent.get(child).removeChild(child);
+        }
+        const reParent = this.children.filter(x => child.contains(x));
+        childToParent.set(child, this);
+        this.children.push(child);
+        reParent.forEach(x => child.appendChild(x));
+        Observable.getNotifier(this.store).subscribe(child);
+        // How can we not notify *every* subscriber?
+        for (const [token, value] of this.store.all()) {
+            child.hydrate(token, this.bindingObservers.has(token) ? this.getRaw(token) : value);
+            // Need to stop reflecting any tokens that can now be inherited
+            child.updateCSSTokenReflection(child.store, token);
+        }
+    }
+    /**
+     * Removes a child from a node.
+     * @param child - The child to remove.
+     */
+    removeChild(child) {
+        const childIndex = this.children.indexOf(child);
+        if (childIndex !== -1) {
+            this.children.splice(childIndex, 1);
+        }
+        Observable.getNotifier(this.store).unsubscribe(child);
+        if (child.parent !== this) {
+            return false;
+        }
+        const deleted = childToParent.delete(child);
+        for (const [token] of this.store.all()) {
+            child.hydrate(token, child.getRaw(token));
+            // Need to start reflecting any assigned values that were previously inherited
+            child.updateCSSTokenReflection(child.store, token);
+        }
+        return deleted;
+    }
+    /**
+     * Tests whether a provided node is contained by
+     * the calling node.
+     * @param test - The node to test
+     */
+    contains(test) {
+        return composedContains(this.target, test.target);
+    }
+    /**
+     * Instructs the node to reflect a design token for the provided token.
+     * @param token - The design token to reflect
+     */
+    reflectToCSS(token) {
+        if (!this.isReflecting(token)) {
+            this.reflecting.add(token);
+            DesignTokenNode.cssCustomPropertyReflector.startReflection(token, this.target);
+        }
+    }
+    /**
+     * Stops reflecting a DesignToken to CSS
+     * @param token - The design token to stop reflecting
+     */
+    stopReflectToCSS(token) {
+        if (this.isReflecting(token)) {
+            this.reflecting.delete(token);
+            DesignTokenNode.cssCustomPropertyReflector.stopReflection(token, this.target);
+        }
+    }
+    /**
+     * Determines if a token is being reflected to CSS for a node.
+     * @param token - The token to check for reflection
+     * @returns
+     */
+    isReflecting(token) {
+        return this.reflecting.has(token);
+    }
+    /**
+     * Handle changes to upstream tokens
+     * @param source - The parent DesignTokenNode
+     * @param property - The token ID that changed
+     */
+    handleChange(source, property) {
+        const token = DesignTokenImpl.getTokenById(property);
+        if (!token) {
+            return;
+        }
+        this.hydrate(token, this.getRaw(token));
+        this.updateCSSTokenReflection(this.store, token);
+    }
+    /**
+     * Hydrates a token with a DesignTokenValue, making retrieval available.
+     * @param token - The token to hydrate
+     * @param value - The value to hydrate
+     */
+    hydrate(token, value) {
+        if (!this.has(token)) {
+            const observer = this.bindingObservers.get(token);
+            if (DesignTokenImpl.isDerivedDesignTokenValue(value)) {
+                if (observer) {
+                    // If the binding source doesn't match, we need
+                    // to update the binding
+                    if (observer.source !== value) {
+                        this.tearDownBindingObserver(token);
+                        this.setupBindingObserver(token, value);
+                    }
+                }
+                else {
+                    this.setupBindingObserver(token, value);
+                }
+            }
+            else {
+                if (observer) {
+                    this.tearDownBindingObserver(token);
+                }
+                this.store.set(token, value);
+            }
+        }
+    }
+    /**
+     * Sets up a binding observer for a derived token value that notifies token
+     * subscribers on change.
+     *
+     * @param token - The token to notify when the binding updates
+     * @param source - The binding source
+     */
+    setupBindingObserver(token, source) {
+        const binding = new DesignTokenBindingObserver(source, token, this);
+        this.bindingObservers.set(token, binding);
+        return binding;
+    }
+    /**
+     * Tear down a binding observer for a token.
+     */
+    tearDownBindingObserver(token) {
+        if (this.bindingObservers.has(token)) {
+            this.bindingObservers.get(token).disconnect();
+            this.bindingObservers.delete(token);
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * Responsible for reflecting tokens to CSS custom properties
+ */
+DesignTokenNode.cssCustomPropertyReflector = new CustomPropertyReflector();
+__decorate([
+    observable
+], DesignTokenNode.prototype, "children", void 0);
+function create(nameOrConfig) {
+    return DesignTokenImpl.from(nameOrConfig);
+}
+/* eslint-enable @typescript-eslint/no-unused-vars */
+/**
+ * Factory object for creating {@link (DesignToken:interface)} instances.
+ * @public
+ */
+export const DesignToken = Object.freeze({
+    create,
+    /**
+     * Informs DesignToken that an HTMLElement for which tokens have
+     * been set has been connected to the document.
+     *
+     * The browser does not provide a reliable mechanism to observe an HTMLElement's connectedness
+     * in all scenarios, so invoking this method manually is necessary when:
+     *
+     * 1. Token values are set for an HTMLElement.
+     * 2. The HTMLElement does not inherit from FASTElement.
+     * 3. The HTMLElement is not connected to the document when token values are set.
+     *
+     * @param element - The element to notify
+     * @returns - true if notification was successful, otherwise false.
+     */
+    notifyConnection(element) {
+        if (!element.isConnected || !DesignTokenNode.existsFor(element)) {
+            return false;
+        }
+        DesignTokenNode.getOrCreate(element).bind();
+        return true;
+    },
+    /**
+     * Informs DesignToken that an HTMLElement for which tokens have
+     * been set has been disconnected to the document.
+     *
+     * The browser does not provide a reliable mechanism to observe an HTMLElement's connectedness
+     * in all scenarios, so invoking this method manually is necessary when:
+     *
+     * 1. Token values are set for an HTMLElement.
+     * 2. The HTMLElement does not inherit from FASTElement.
+     *
+     * @param element - The element to notify
+     * @returns - true if notification was successful, otherwise false.
+     */
+    notifyDisconnection(element) {
+        if (element.isConnected || !DesignTokenNode.existsFor(element)) {
+            return false;
+        }
+        DesignTokenNode.getOrCreate(element).unbind();
+        return true;
+    },
+    /**
+     * Registers and element or document as a DesignToken root.
+     * {@link CSSDesignToken | CSSDesignTokens} with default values assigned via
+     * {@link (DesignToken:interface).withDefault} will emit CSS custom properties to all
+     * registered roots.
+     * @param target - The root to register
+     */
+    registerRoot(target = defaultElement) {
+        RootStyleSheetTarget.registerRoot(target);
+    },
+    /**
+     * Unregister an element or document as a DesignToken root.
+     * @param target - The root to deregister
+     */
+    unregisterRoot(target = defaultElement) {
+        RootStyleSheetTarget.unregisterRoot(target);
+    },
+});
+/* eslint-enable @typescript-eslint/no-non-null-assertion */

package/dist/esm/design-token/interfaces.js

@@ -0,0 +1 @@
+export {};