@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

package/dist/esm/scoped/detection.js

@@ -0,0 +1,102 @@
+/**
+ * Detection and polyfill loading for Scoped Custom Element Registries.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { isDevMode } from "../dev-mode.js";
+/**
+ * Robust feature detection for Scoped Custom Element Registries.
+ *
+ * @remarks
+ * Tests the full API surface, not just the constructor existence.
+ * This ensures the browser actually supports attaching a custom registry
+ * to a shadow root, which is the critical functionality.
+ *
+ * @returns true if the browser supports scoped custom element registries
+ *
+ * @example
+ * ```typescript
+ * if (supportsScopedRegistries()) {
+ *   const registry = new CustomElementRegistry();
+ *   element.attachShadow({ mode: 'open', customElementRegistry: registry });
+ * }
+ * ```
+ *
+ * @public
+ */
+export function supportsScopedRegistries() {
+    try {
+        // Test 1: Can we construct a CustomElementRegistry?
+        const reg = new CustomElementRegistry();
+        // Test 2: Can we use it with attachShadow?
+        const div = document.createElement("div");
+        const shadow = div.attachShadow({
+            mode: "open",
+            customElementRegistry: reg,
+            registry: reg,
+        });
+        const scopedShadow = shadow;
+        return (scopedShadow.customElementRegistry === reg || scopedShadow.registry === reg);
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Idempotency-safe polyfill loading for Scoped Custom Element Registries.
+ *
+ * @remarks
+ * Safe to call from multiple micro-frontend bundles. Uses a global flag
+ * (`window.__scopedRegistryPolyfillApplied`) to prevent double-patching
+ * which could corrupt the CustomElementRegistry prototype.
+ *
+ * If native support is detected, returns immediately without loading the polyfill.
+ * On polyfill load failure, the flag is reset to allow retry on subsequent calls.
+ *
+ * @throws Error if the polyfill fails to load (network error, etc.)
+ *
+ * @example
+ * ```typescript
+ * // At app startup
+ * await ensureScopedRegistrySupport();
+ *
+ * // Now safe to use scoped registries
+ * const registry = new CustomElementRegistry();
+ * ```
+ *
+ * @public
+ */
+export function ensureScopedRegistrySupport() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Check native support first
+        if (supportsScopedRegistries()) {
+            return;
+        }
+        const scope = globalThis;
+        if (scope.__scopedRegistryPolyfillPromise) {
+            return scope.__scopedRegistryPolyfillPromise;
+        }
+        scope.__scopedRegistryPolyfillPromise = import("@webcomponents/scoped-custom-element-registry")
+            .then(() => {
+            scope.__scopedRegistryPolyfillApplied = true;
+            if (isDevMode()) {
+                console.info("[fast-af] Scoped registry polyfill loaded successfully");
+            }
+        })
+            .catch(e => {
+            scope.__scopedRegistryPolyfillApplied = false;
+            scope.__scopedRegistryPolyfillPromise = void 0;
+            const error = new Error("[fast-af] Failed to load scoped registry polyfill");
+            error.cause = e;
+            throw error;
+        });
+        return scope.__scopedRegistryPolyfillPromise;
+    });
+}

package/dist/esm/scoped/index.js

@@ -0,0 +1,69 @@
+/**
+ * Scoped Custom Element Registries support for FAST-AF.
+ *
+ * @remarks
+ * This module provides utilities for working with Scoped Custom Element Registries,
+ * enabling isolated component definitions within shadow roots. This solves namespace
+ * collisions for micro-frontends and design system versioning.
+ *
+ * @example Using ScopedRegistryMixin (recommended)
+ * ```typescript
+ * import { FASTElement, html } from '@lushly-dev/fast-element';
+ * import { ScopedRegistryMixin } from '@lushly-dev/fast-element/scoped.js';
+ *
+ * class MyButton extends HTMLElement {}
+ *
+ * class MyCard extends ScopedRegistryMixin(FASTElement) {
+ *   static elementDefinitions = {
+ *     'my-button': MyButton,
+ *   };
+ * }
+ *
+ * // The shadow root gets the scoped registry, so <my-button> is upgraded without
+ * // being defined globally.
+ * await FASTElement.define(MyCard, {
+ *   name: 'my-card',
+ *   template: html`<my-button>Click me</my-button>`,
+ *   shadowOptions: MyCard.getShadowOptions(),
+ * });
+ * ```
+ *
+ * @example Using createRegistry directly
+ * ```typescript
+ * import {
+ *   createRegistry,
+ *   createRegistryAsync,
+ *   supportsScopedRegistries,
+ *   ensureScopedRegistrySupport,
+ * } from '@lushly-dev/fast-element/scoped.js';
+ *
+ * class MyButton extends HTMLElement {}
+ * class MyInput extends HTMLElement {}
+ *
+ * // Check support
+ * if (supportsScopedRegistries()) {
+ *   const registry = createRegistry([
+ *     [MyButton, 'my-button'],
+ *     [MyInput, 'my-input'],
+ *   ]);
+ *
+ *   element.attachShadow({
+ *     mode: 'open',
+ *     customElementRegistry: registry,
+ *   });
+ * }
+ *
+ * // Or use async version with automatic polyfill
+ * const registry = await createRegistryAsync([
+ *   [MyButton, 'my-button'],
+ * ]);
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Detection
+export { supportsScopedRegistries, ensureScopedRegistrySupport } from "./detection.js";
+// Registry Builder
+export { createRegistry, createRegistryAsync } from "./registry.js";
+// Mixin
+export { ScopedRegistryMixin } from "./mixin.js";

package/dist/esm/scoped/mixin.js

@@ -0,0 +1,127 @@
+/**
+ * ScopedRegistryMixin for FAST Elements.
+ *
+ * @remarks
+ * Provides a mixin that enables components to define and use scoped registries,
+ * following the Lit labs pattern. Child elements are isolated within the
+ * component's shadow root.
+ */
+import { isDevMode } from "../dev-mode.js";
+import { createRegistry } from "./registry.js";
+const initializedConstructors = new WeakSet();
+const scopedRegistries = new WeakMap();
+/**
+ * Creates a mixin that enables scoped custom element registries for a FASTElement.
+ *
+ * @remarks
+ * The ScopedRegistryMixin provides a way to define child elements that are
+ * scoped to the component's shadow root, preventing namespace collisions
+ * in micro-frontend scenarios and enabling design system versioning.
+ *
+ * The mixin adds:
+ * - A static `elementDefinitions` property for defining child elements
+ * - A static `scopedRegistry` getter that lazily creates the registry
+ * - A method to get shadow root options with the scoped registry
+ *
+ * When scoped registries are not supported by the browser, elements fall back
+ * to the global registry with a development warning.
+ *
+ * @param Base - The FASTElement base class to extend
+ * @returns A class that supports scoped element definitions
+ *
+ * @example
+ * ```typescript
+ * import { FASTElement, html, css } from '@lushly-dev/fast-element';
+ * import { ScopedRegistryMixin } from '@lushly-dev/fast-element/scoped.js';
+ *
+ * // Children can be plain custom elements. FASTElement children must be composed
+ * // first (FASTElementDefinition.compose(MyIcon, { name: 'my-icon' })) so the
+ * // registry can reuse their FAST definition; creating an element of an
+ * // undefined FASTElement class throws FAST error 1401.
+ * class MyButton extends HTMLElement {
+ *   // Button implementation
+ * }
+ *
+ * class MyCard extends ScopedRegistryMixin(FASTElement) {
+ *   static elementDefinitions = {
+ *     'my-button': MyButton,
+ *   };
+ * }
+ *
+ * // Attach the scoped registry to the shadow root through getShadowOptions().
+ * // The template's <my-button> is created against it and does not need to be
+ * // (and here is not) defined in the global registry.
+ * await FASTElement.define(MyCard, {
+ *   name: 'my-card',
+ *   template: html`<my-button>Click me</my-button>`,
+ *   shadowOptions: MyCard.getShadowOptions(),
+ * });
+ * ```
+ *
+ * @public
+ */
+export function ScopedRegistryMixin(Base) {
+    return class ScopedRegistryMixinClass extends Base {
+        /**
+         * Gets the scoped registry for this element class.
+         * @remarks
+         * Lazily creates the registry from elementDefinitions on first access.
+         * Returns undefined if no definitions exist or if scoped registries
+         * are not supported (fallback to global).
+         */
+        static get scopedRegistry() {
+            if (!initializedConstructors.has(this)) {
+                initializedConstructors.add(this);
+                if (this.elementDefinitions) {
+                    const keys = Object.keys(this.elementDefinitions);
+                    if (keys.length > 0) {
+                        // Convert { 'tag-name': Ctor } to [Ctor, 'tag-name'] format
+                        const elementDefs = [];
+                        for (let i = 0, len = keys.length; i < len; i++) {
+                            const tagName = keys[i];
+                            const ctor = this.elementDefinitions[tagName];
+                            elementDefs.push([ctor, tagName]);
+                        }
+                        const registry = createRegistry(elementDefs);
+                        scopedRegistries.set(this, registry);
+                        if (isDevMode() && registry) {
+                            console.debug("[fast-af] Created scoped registry for " +
+                                this.name +
+                                " with " +
+                                keys.length +
+                                " element(s)");
+                        }
+                    }
+                }
+            }
+            return scopedRegistries.get(this);
+        }
+        /**
+         * Gets shadow root options with the scoped registry configured.
+         * @remarks
+         * Use this method when defining the element to include the scoped registry.
+         * Returns options with customElementRegistry set if a registry was created.
+         *
+         * @param baseOptions - Optional base shadow root options to extend
+         * @returns Shadow root options with customElementRegistry if applicable
+         *
+         * @example
+         * ```typescript
+         * await FASTElement.define(MyComponent, {
+         *   name: 'my-component',
+         *   template: myTemplate,
+         *   shadowOptions: MyComponent.getShadowOptions({ mode: 'closed' }),
+         * });
+         * ```
+         */
+        static getShadowOptions(baseOptions) {
+            const registry = this.scopedRegistry;
+            const options = Object.assign({ mode: "open" }, baseOptions);
+            if (registry) {
+                options.customElementRegistry = registry;
+                options.registry = registry;
+            }
+            return options;
+        }
+    };
+}

package/dist/esm/scoped/registry.js

@@ -0,0 +1,125 @@
+/**
+ * Registry builder utilities for Scoped Custom Element Registries.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { isDevMode } from "../dev-mode.js";
+import { fastElementRegistry } from "../components/fast-element-registry.js";
+import { ensureScopedRegistrySupport, supportsScopedRegistries } from "./detection.js";
+function defineElements(registry, definitions) {
+    for (const [ctor, tagName] of definitions) {
+        if (registry.get(tagName)) {
+            continue;
+        }
+        const fastDefinition = fastElementRegistry.getByType(ctor);
+        if ((fastDefinition === null || fastDefinition === void 0 ? void 0 : fastDefinition.name) === tagName) {
+            fastDefinition.define(registry);
+        }
+        else {
+            registry.define(tagName, ctor, fastDefinition === null || fastDefinition === void 0 ? void 0 : fastDefinition.elementOptions);
+        }
+    }
+}
+/**
+ * Creates a scoped custom element registry with the provided element definitions.
+ *
+ * @remarks
+ * When scoped registries are supported, creates a new CustomElementRegistry
+ * and defines all provided elements in it. When not supported, falls back to
+ * registering elements on the global `customElements` registry (with a dev warning).
+ *
+ * In strict mode, throws an error if scoped registries are not supported
+ * instead of falling back to the global registry.
+ *
+ * @param definitions - Array of [Constructor, tagName] tuples to register
+ * @param options - Configuration options
+ * @returns The created registry, or undefined if fallback to global occurred
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const registry = createRegistry([
+ *   [MyButton, 'my-button'],
+ *   [MyInput, 'my-input'],
+ * ]);
+ *
+ * if (registry) {
+ *   element.attachShadow({ mode: 'open', customElementRegistry: registry });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Strict mode - throws if not supported
+ * const registry = createRegistry(
+ *   [[MyButton, 'my-button']],
+ *   { strict: true }
+ * );
+ * ```
+ *
+ * @public
+ */
+export function createRegistry(definitions, options) {
+    if (!supportsScopedRegistries()) {
+        if (options === null || options === void 0 ? void 0 : options.strict) {
+            throw new Error("[fast-af] Scoped custom element registries are not supported in this browser");
+        }
+        if (isDevMode()) {
+            console.warn("[fast-af] Scoped registries not supported. Falling back to global registry. " +
+                "Elements will be globally registered which may cause conflicts in MFE scenarios.");
+        }
+        // Fallback: register on global registry
+        defineElements(customElements, definitions);
+        return undefined; // Signal fallback occurred
+    }
+    const registry = new CustomElementRegistry();
+    defineElements(registry, definitions);
+    return registry;
+}
+/**
+ * Creates a scoped custom element registry with automatic polyfill loading.
+ *
+ * @remarks
+ * This async version first ensures scoped registry support is available
+ * (loading the polyfill if necessary), then creates the registry.
+ *
+ * Unlike `createRegistry()`, this function always operates in strict mode
+ * after polyfill loading, as the polyfill should provide support. If the
+ * polyfill fails to load, the underlying `ensureScopedRegistrySupport()`
+ * will throw.
+ *
+ * @param definitions - Array of [Constructor, tagName] tuples to register
+ * @param options - Configuration options (strict is always true after polyfill)
+ * @returns Promise resolving to the created registry
+ *
+ * @throws Error if polyfill loading fails
+ *
+ * @example
+ * ```typescript
+ * // Automatically loads polyfill if needed
+ * const registry = await createRegistryAsync([
+ *   [MyButton, 'my-button'],
+ *   [MyInput, 'my-input'],
+ * ]);
+ *
+ * element.attachShadow({ mode: 'open', customElementRegistry: registry });
+ * ```
+ *
+ * @public
+ */
+export function createRegistryAsync(definitions, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield ensureScopedRegistrySupport();
+        // After polyfill loading, we should have support - use strict mode
+        const registry = createRegistry(definitions, Object.assign(Object.assign({}, options), { strict: true }));
+        // TypeScript knows this won't be undefined because strict: true would throw
+        return registry;
+    });
+}

package/dist/esm/scoped/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Scoped Custom Element Registries.
+ */
+export {};

package/dist/esm/state/exports.js

@@ -0,0 +1,3 @@
+export { reactive } from "./reactive.js";
+export { computedState, ownedState, state, } from "./state.js";
+export { watch } from "./watch.js";

package/dist/esm/state/reactive.js

@@ -0,0 +1,34 @@
+import { noop } from "../interfaces.js";
+import { Observable } from "../observation/observable.js";
+import { visitObject } from "./visitor.js";
+const observed = new WeakSet();
+const makeObserverVisitor = {
+    visitObject: noop,
+    visitArray: noop,
+    visitProperty(object, propertyName, value) {
+        Reflect.defineProperty(object, propertyName, {
+            enumerable: true,
+            get() {
+                Observable.track(object, propertyName);
+                return value;
+            },
+            set(newValue) {
+                if (value !== newValue) {
+                    value = newValue;
+                    Observable.notify(object, propertyName);
+                }
+            },
+        });
+    },
+};
+/**
+ * Converts a plain object to a reactive, observable object.
+ * @param object - The object to make reactive.
+ * @param deep - Indicates whether or not to deeply convert the oject.
+ * @returns The converted object.
+ * @beta
+ */
+export function reactive(object, deep = false) {
+    visitObject(object, deep, makeObserverVisitor, void 0, observed);
+    return object;
+}

package/dist/esm/state/state.js

@@ -0,0 +1,148 @@
+// Inspired by https://www.starbeamjs.com/
+import { isFunction, isString } from "../interfaces.js";
+import { Observable } from "../observation/observable.js";
+import { reactive } from "./reactive.js";
+const defaultStateOptions = {
+    deep: false,
+};
+/**
+ * Creates a reactive state value.
+ * @param value - The initial state value.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns A State instance.
+ * @beta
+ */
+export function state(value, options = defaultStateOptions) {
+    var _a;
+    if (isString(options)) {
+        options = { deep: false, name: options };
+    }
+    const host = reactive({ value }, options.deep);
+    const state = (() => host.value);
+    Object.defineProperty(state, "current", {
+        get: () => host.value,
+        set: (value) => (host.value = value),
+    });
+    Object.defineProperty(state, "name", {
+        value: (_a = options.name) !== null && _a !== void 0 ? _a : "SharedState",
+    });
+    state.set = (value) => (host.value = value);
+    state.asReadonly = () => {
+        const readonlyState = (() => host.value);
+        Object.defineProperty(readonlyState, "current", {
+            get: () => host.value,
+        });
+        Object.defineProperty(readonlyState, "name", {
+            value: `${state.name} (Readonly)`,
+        });
+        return Object.freeze(readonlyState);
+    };
+    return state;
+}
+/**
+ * Creates a reactive state that has its value associated with a specific owner.
+ * @param value - The initial value or a factory that provides an initial value for each owner.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns An OwnedState instance.
+ * @beta
+ */
+export function ownedState(value, options = defaultStateOptions) {
+    var _a;
+    if (isString(options)) {
+        options = { deep: false, name: options };
+    }
+    if (!isFunction(value)) {
+        const v = value;
+        value = () => v;
+    }
+    const storage = new WeakMap();
+    const getHost = (owner) => {
+        let host = storage.get(owner);
+        if (host === void 0) {
+            host = reactive({ value: value() }, options.deep);
+            storage.set(owner, host);
+        }
+        return host;
+    };
+    const state = ((owner) => getHost(owner).value);
+    Object.defineProperty(state, "name", {
+        value: (_a = options.name) !== null && _a !== void 0 ? _a : "OwnedState",
+    });
+    state.set = (owner, value) => (getHost(owner).value = value);
+    state.asReadonly = () => {
+        const readonlyState = ((owner) => getHost(owner).value);
+        Object.defineProperty(readonlyState, "name", {
+            value: `${state.name} (Readonly)`,
+        });
+        return Object.freeze(readonlyState);
+    };
+    return state;
+}
+/**
+ * Creates a ComputedState.
+ * @param initialize - The initialization callback.
+ * @param name - A friendly name for this computation.
+ * @returns A ComputedState
+ * @beta
+ */
+export function computedState(initialize, name = "ComputedState") {
+    let setupCallback = null;
+    const builder = {
+        on: {
+            setup(callback) {
+                setupCallback = callback;
+            },
+        },
+    };
+    const computer = initialize(builder);
+    const host = reactive({ value: null }, false);
+    const output = (() => host.value);
+    Object.defineProperty(output, "current", {
+        get: () => host.value,
+    });
+    Object.defineProperty(output, "name", {
+        value: name,
+    });
+    // eslint-disable-next-line prefer-const
+    let computedNotifier;
+    const computedSubscriber = {
+        handleChange() {
+            host.value = computedNotifier.observe(null);
+        },
+    };
+    computedNotifier = Observable.binding(computer, computedSubscriber);
+    computedNotifier.setMode(false);
+    let cleanup;
+    let setupNotifier;
+    if (setupCallback) {
+        const setupSubscriber = {
+            handleChange() {
+                if (cleanup) {
+                    cleanup();
+                }
+                cleanup = setupNotifier.observe(null);
+                host.value = computer();
+            },
+        };
+        setupNotifier = Observable.binding(setupCallback, setupSubscriber);
+        setupNotifier.setMode(false);
+        cleanup = setupNotifier.observe(null);
+    }
+    host.value = computedNotifier.observe(null);
+    output.dispose = () => {
+        if (cleanup) {
+            cleanup();
+        }
+        if (setupNotifier) {
+            setupNotifier.dispose();
+        }
+        computedNotifier.dispose();
+    };
+    output.subscribe = (subscriber) => {
+        computedNotifier.subscribe(subscriber);
+    };
+    output.unsubscribe = (subscriber) => {
+        computedNotifier.unsubscribe(subscriber);
+    };
+    return output;
+}

package/dist/esm/state/visitor.js

@@ -0,0 +1,28 @@
+function shouldTraverse(value, traversed) {
+    return (value !== null &&
+        value !== void 0 &&
+        typeof value === "object" &&
+        !traversed.has(value));
+}
+export function visitObject(object, deep, visitor, data, traversed) {
+    if (!shouldTraverse(object, traversed)) {
+        return;
+    }
+    traversed.add(object);
+    if (Array.isArray(object)) {
+        visitor.visitArray(object, data);
+        for (const item of object) {
+            visitObject(item, deep, visitor, data, traversed);
+        }
+    }
+    else {
+        visitor.visitObject(object, data);
+        for (const key in object) {
+            const value = object[key];
+            visitor.visitProperty(object, key, value, data);
+            if (deep) {
+                visitObject(value, deep, visitor, data, traversed);
+            }
+        }
+    }
+}

package/dist/esm/state/watch.js

@@ -0,0 +1,36 @@
+import { isFunction, noop } from "../interfaces.js";
+import { ArrayObserver } from "../observation/arrays.js";
+import { Observable } from "../observation/observable.js";
+import { visitObject } from "./visitor.js";
+function watchObject(object, data) {
+    const notifier = Observable.getNotifier(object);
+    notifier.subscribe(data.subscriber);
+    data.notifiers.push(notifier);
+}
+const watchVisitor = {
+    visitProperty: noop,
+    visitObject: watchObject,
+    visitArray: watchObject,
+};
+/**
+ * Deeply subscribes to changes in existing observable objects.
+ * @param object - The observable object to watch.
+ * @param subscriber - The handler to call when changes are made to the object.
+ * @returns A disposable that can be used to unsubscribe from change updates.
+ * @beta
+ */
+export function watch(object, subscriber) {
+    const data = {
+        notifiers: [],
+        subscriber: isFunction(subscriber) ? { handleChange: subscriber } : subscriber,
+    };
+    ArrayObserver.enable();
+    visitObject(object, true, watchVisitor, data, new Set());
+    return {
+        dispose() {
+            for (const n of data.notifiers) {
+                n.unsubscribe(data.subscriber);
+            }
+        },
+    };
+}