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

package/dist/dts/observation/observable.d.ts

@@ -0,0 +1,276 @@
+import { type Disposable } from "../interfaces.js";
+import type { Notifier, Subscriber } from "./notifier.js";
+/**
+ * Represents a getter/setter property accessor on an object.
+ * @public
+ */
+export interface Accessor {
+    /**
+     * The name of the property.
+     */
+    name: string;
+    /**
+     * Gets the value of the property on the source object.
+     * @param source - The source object to access.
+     */
+    getValue(source: any): any;
+    /**
+     * Sets the value of the property on the source object.
+     * @param source - The source object to access.
+     * @param value - The value to set the property to.
+     */
+    setValue(source: any, value: any): void;
+}
+/**
+ * The signature of an arrow function capable of being evaluated
+ * against source data and within an execution context.
+ * @public
+ */
+export type Expression<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
+/**
+ * A record of observable property access.
+ * @public
+ */
+export interface ObservationRecord {
+    /**
+     * The source object with an observable property that was accessed.
+     */
+    propertySource: any;
+    /**
+     * The name of the observable property on {@link ObservationRecord.propertySource} that was accessed.
+     */
+    propertyName: string;
+}
+/**
+ * Describes how the source's lifetime relates to its controller's lifetime.
+ * @public
+ */
+export declare const SourceLifetime: Readonly<{
+    /**
+     * The source to controller lifetime relationship is unknown.
+     */
+    readonly unknown: undefined;
+    /**
+     * The source and controller lifetimes are coupled to one another.
+     * They can/will be GC'd together.
+     */
+    readonly coupled: 1;
+}>;
+/**
+ * Describes how the source's lifetime relates to its controller's lifetime.
+ * @public
+ */
+export type SourceLifetime = (typeof SourceLifetime)[keyof typeof SourceLifetime];
+/**
+ * Controls the lifecycle of an expression and provides relevant context.
+ * @public
+ */
+export interface ExpressionController<TSource = any, TParent = any> {
+    /**
+     * The source the expression is evaluated against.
+     */
+    readonly source: TSource;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime?: SourceLifetime;
+    /**
+     * The context the expression is evaluated against.
+     */
+    readonly context: ExecutionContext<TParent>;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    readonly isBound: boolean;
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ExpressionController<TSource, TParent>): any;
+    }): void;
+}
+/**
+ * Observes an expression for changes.
+ * @public
+ */
+export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any> {
+    /**
+     * Binds the expression to the source.
+     * @param controller - The controller that manages the lifecycle and related
+     * context for the expression.
+     */
+    bind(controller: ExpressionController<TSource, TParent>): TReturn;
+}
+/**
+ * Enables evaluation of and subscription to a binding.
+ * @public
+ */
+export interface ExpressionNotifier<TSource = any, TReturn = any, TParent = any> extends Notifier, ExpressionObserver<TSource, TReturn, TParent>, Disposable {
+    /**
+     * Observes the expression.
+     * @param source - The source for the expression.
+     * @param context - The context for the expression.
+     */
+    observe(source: TSource, context?: ExecutionContext): TReturn;
+    /**
+     * Gets {@link ObservationRecord|ObservationRecords} that the {@link ExpressionNotifier}
+     * is observing.
+     */
+    records(): IterableIterator<ObservationRecord>;
+    /**
+     * Sets the update mode used by the observer.
+     * @param isAsync - Indicates whether updates should be asynchronous.
+     * @remarks
+     * By default, the update mode is asynchronous, since that provides the best
+     * performance for template rendering scenarios. Passing false to setMode will
+     * instead cause the observer to notify subscribers immediately when changes occur.
+     */
+    setMode(isAsync: boolean): void;
+}
+/**
+ * Common Observable APIs.
+ * @public
+ */
+export declare const Observable: Readonly<{
+    /**
+     * @internal
+     * @param factory - The factory used to create array observers.
+     */
+    setArrayObserverFactory(factory: (collection: any[]) => Notifier): void;
+    /**
+     * Gets a notifier for an object or Array.
+     * @param source - The object or Array to get the notifier for.
+     */
+    getNotifier: <T extends Notifier = Notifier>(source: any) => T;
+    /**
+     * Records a property change for a source object.
+     * @param source - The object to record the change against.
+     * @param propertyName - The property to track as changed.
+     */
+    track(source: unknown, propertyName: string): void;
+    /**
+     * Notifies watchers that the currently executing property getter or function is volatile
+     * with respect to its observable dependencies.
+     */
+    trackVolatile(): void;
+    /**
+     * Notifies subscribers of a source object of changes.
+     * @param source - the object to notify of changes.
+     * @param args - The change args to pass to subscribers.
+     */
+    notify(source: unknown, args: any): void;
+    /**
+     * Defines an observable property on an object or prototype.
+     * @param target - The target object to define the observable on.
+     * @param nameOrAccessor - The name of the property to define as observable;
+     * or a custom accessor that specifies the property name and accessor implementation.
+     */
+    defineProperty(target: {}, nameOrAccessor: string | Accessor): void;
+    /**
+     * Finds all the observable accessors defined on the target,
+     * including its prototype chain.
+     * @param target - The target object to search for accessor on.
+     */
+    getAccessors: (target: {}) => Accessor[];
+    /**
+     * Creates a {@link ExpressionNotifier} that can watch the
+     * provided {@link Expression} for changes.
+     * @param expression - The binding to observe.
+     * @param initialSubscriber - An initial subscriber to changes in the binding value.
+     * @param isVolatileBinding - Indicates whether the binding's dependency list must be re-evaluated on every value evaluation.
+     */
+    binding<TSource = any, TReturn = any>(expression: Expression<TSource, TReturn>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): ExpressionNotifier<TSource, TReturn>;
+    /**
+     * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
+     * on every evaluation of the value.
+     * @param expression - The binding to inspect.
+     */
+    isVolatileBinding<TSource = any, TReturn = any>(expression: Expression<TSource, TReturn>): boolean;
+}>;
+/**
+ * Decorator: Defines an observable property on the target.
+ * @param target - The target to define the observable on.
+ * @param nameOrAccessor - The property name or accessor to define the observable as.
+ * @public
+ */
+export declare function observable(target: {}, nameOrAccessor: string | Accessor): void;
+/**
+ * Provides additional contextual information available to behaviors and expressions.
+ * @public
+ */
+export interface ExecutionContext<TParent = any> {
+    /**
+     * The index of the current item within a repeat context.
+     */
+    index: number;
+    /**
+     * The length of the current collection within a repeat context.
+     */
+    length: number;
+    /**
+     * The parent data source within a nested context.
+     */
+    parent: TParent;
+    /**
+     * The parent execution context when in nested context scenarios.
+     */
+    parentContext: ExecutionContext<TParent>;
+    /**
+     * The current event within an event handler.
+     */
+    readonly event: Event;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an even index.
+     */
+    readonly isEven: boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an odd index.
+     */
+    readonly isOdd: boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the first item in the collection.
+     */
+    readonly isFirst: boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is somewhere in the middle of the collection.
+     */
+    readonly isInMiddle: boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the last item in the collection.
+     */
+    readonly isLast: boolean;
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget<TTarget extends EventTarget>(): TTarget;
+}
+/**
+ * Provides additional contextual information available to behaviors and expressions.
+ * @public
+ */
+export declare const ExecutionContext: Readonly<{
+    /**
+     * A default execution context.
+     */
+    default: ExecutionContext;
+    /**
+     * Gets the current event.
+     * @returns An event object.
+     */
+    getEvent(): Event | null;
+    /**
+     * Sets the current event.
+     * @param event - An event object.
+     */
+    setEvent(event: Event | null): void;
+}>;

package/dist/dts/observation/update-queue.d.ts

@@ -0,0 +1,40 @@
+import type { Callable } from "../interfaces.js";
+/**
+ * A work queue used to synchronize writes to the DOM.
+ * @public
+ */
+export interface UpdateQueue {
+    /**
+     * Schedules DOM update work in the next batch.
+     * @param callable - The callable function or object to queue.
+     */
+    enqueue(callable: Callable): void;
+    /**
+     * Resolves with the next DOM update.
+     */
+    next(): Promise<void>;
+    /**
+     * Immediately processes all work previously scheduled
+     * through enqueue.
+     * @remarks
+     * This also forces next() promises
+     * to resolve.
+     */
+    process(): void;
+    /**
+     * Sets the update mode used by enqueue.
+     * @param isAsync - Indicates whether DOM updates should be asynchronous.
+     * @remarks
+     * By default, the update mode is asynchronous, since that provides the best
+     * performance in the browser. Passing false to setMode will instead cause
+     * the queue to be immediately processed for each call to enqueue. However,
+     * ordering will still be preserved so that nested tasks do not run until
+     * after parent tasks complete.
+     */
+    setMode(isAsync: boolean): void;
+}
+/**
+ * The default UpdateQueue.
+ * @public
+ */
+export declare const Updates: UpdateQueue;

package/dist/dts/observation/volatile.d.ts

@@ -0,0 +1,9 @@
+import { type Accessor } from "./observable.js";
+/**
+ * Decorator: Marks a property getter as having volatile observable dependencies.
+ * @param target - The target that the property is defined on.
+ * @param name - The property name.
+ * @param descriptor - The existing descriptor.
+ * @public
+ */
+export declare function volatile(target: {}, name: string | Accessor, descriptor: PropertyDescriptor): PropertyDescriptor;

package/dist/dts/platform.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The FAST messaging API for warnings and errors.
+ * @public
+ */
+export declare const FAST: {
+    /**
+     * Sends a warning to the developer.
+     * @param code - The warning code to send.
+     * @param values - Values relevant for the warning message.
+     */
+    warn(_code: number, _values?: Record<string, any>): void;
+    /**
+     * Creates an error from a code.
+     * @param code - The error code.
+     * @param values - Values relevant for the error message.
+     */
+    error(code: number, _values?: Record<string, any>): Error;
+    /**
+     * Adds debug messages for errors and warnings.
+     * @param messages - The message dictionary to add.
+     */
+    addMessages(messages: Record<number, string>): void;
+};
+/**
+ * Gets the shared debug message lookup.
+ * @internal
+ */
+export declare function getDebugMessageLookup(): Record<number, string>;
+/**
+ * A readonly, empty array.
+ * @remarks
+ * Typically returned by APIs that return arrays when there are
+ * no actual items to return.
+ * @public
+ */
+export declare const emptyArray: readonly never[];
+/**
+ * A type that can be registered with a `TypeRegistry`.
+ * @public
+ */
+export interface TypeDefinition {
+    /**
+     * The registered type constructor.
+     */
+    type: Function;
+}
+/**
+ * A registry that stores definitions by type.
+ * @public
+ */
+export interface TypeRegistry<TDefinition extends TypeDefinition> {
+    /**
+     * Registers a type definition.
+     * @param definition - The type definition to register.
+     * @returns `true` when the definition was registered, otherwise `false`.
+     */
+    register(definition: TDefinition): boolean;
+    /**
+     * Gets a definition by type.
+     * @param key - The type to retrieve the definition for.
+     */
+    getByType(key: Function): TDefinition | undefined;
+    /**
+     * Gets a definition by instance.
+     * @param object - The instance to retrieve the definition for.
+     */
+    getForInstance(object: any): TDefinition | undefined;
+}
+/**
+ * Do not change. Part of shared kernel contract.
+ * @internal
+ */
+export declare function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRegistry<TDefinition>;
+/**
+ * Creates a function capable of locating metadata associated with a type.
+ * @returns A metadata locator function.
+ * @internal
+ */
+export declare function createMetadataLocator<TMetadata>(): (target: {}) => TMetadata[];
+/**
+ * Makes a type noop for JSON serialization.
+ * @param type - The type to make noop for JSON serialization.
+ * @internal
+ */
+export declare function makeSerializationNoop(type: {
+    readonly prototype: any;
+}): void;

package/dist/dts/registry.d.ts

@@ -0,0 +1,2 @@
+export { FASTElementDefinition, type TypeDefinition, type TypeRegistry, } from "./components/fast-definitions.js";
+export { type FASTElementRegistry, fastElementRegistry, } from "./components/fast-element-registry.js";

package/dist/dts/render.d.ts

@@ -0,0 +1,7 @@
+export type { Binding, BindingDirective } from "./binding/binding.js";
+export type { Subscriber } from "./observation/notifier.js";
+export type { Expression, ExpressionObserver } from "./observation/observable.js";
+export type { ContentTemplate } from "./templating/html-binding-directive.js";
+export type { AddViewBehaviorFactory, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewController, } from "./templating/html-directive.js";
+export { RenderBehavior, RenderDirective, render } from "./templating/render.js";
+export type { CaptureType } from "./templating/template.js";

package/dist/dts/schema.d.ts

@@ -0,0 +1 @@
+export { type AccessCachedPath, type CachedPath, type CachedPathCommon, type CachedPathMap, type ChildrenMap, type DefaultCachedPath, type EventCachedPath, type JSONSchema, type JSONSchemaCommon, type JSONSchemaDefinition, type RegisterPathConfig, type RepeatCachedPath, Schema, schemaRegistry, } from "./components/schema.js";

package/dist/dts/scoped/detection.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Detection and polyfill loading for Scoped Custom Element Registries.
+ */
+declare global {
+    interface GlobalThis {
+        __scopedRegistryPolyfillApplied?: boolean;
+        __scopedRegistryPolyfillPromise?: Promise<void>;
+    }
+}
+/**
+ * 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 declare function supportsScopedRegistries(): boolean;
+/**
+ * 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 declare function ensureScopedRegistrySupport(): Promise<void>;

package/dist/dts/scoped/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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
+ */
+export type { ScopedShadowRootInit, ElementDefinition, CreateRegistryOptions, } from "./types.js";
+export { supportsScopedRegistries, ensureScopedRegistrySupport } from "./detection.js";
+export { createRegistry, createRegistryAsync } from "./registry.js";
+export { ScopedRegistryMixin } from "./mixin.js";
+export type { ElementDefinitionMap, ScopedRegistryHost, ScopedRegistryHostConstructor, } from "./mixin.js";

package/dist/dts/scoped/mixin.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 type { ScopedShadowRootInit } from "./types.js";
+/**
+ * Map of element definitions: tag-name to constructor.
+ *
+ * @remarks
+ * Used with ScopedRegistryMixin to define child elements that should
+ * be registered in the component's scoped registry.
+ *
+ * @example
+ * ```typescript
+ * static elementDefinitions: ElementDefinitionMap = {
+ *   'my-button': MyButton,
+ *   'my-input': MyInput,
+ * };
+ * ```
+ *
+ * @public
+ */
+export type ElementDefinitionMap = Record<string, CustomElementConstructor>;
+/**
+ * Interface for classes that host a scoped registry.
+ *
+ * @remarks
+ * Implemented by classes using the ScopedRegistryMixin.
+ *
+ * @public
+ */
+export interface ScopedRegistryHost {
+    /**
+     * Static element definitions for the scoped registry.
+     */
+    elementDefinitions?: ElementDefinitionMap;
+    /**
+     * The scoped registry created from elementDefinitions.
+     * @remarks
+     * Lazily created on first access.
+     */
+    scopedRegistry: CustomElementRegistry | undefined;
+}
+/**
+ * Static interface for ScopedRegistryMixin classes.
+ * @public
+ */
+export interface ScopedRegistryHostConstructor {
+    /**
+     * Static element definitions for the scoped registry.
+     */
+    elementDefinitions?: ElementDefinitionMap;
+    /**
+     * The scoped registry created from elementDefinitions.
+     */
+    readonly scopedRegistry: CustomElementRegistry | undefined;
+    /**
+     * Gets shadow root options with the scoped registry configured.
+     * @param baseOptions - Optional base shadow root options to extend
+     * @returns Shadow root options with customElementRegistry if applicable
+     */
+    getShadowOptions(baseOptions?: ScopedShadowRootInit): ScopedShadowRootInit;
+}
+/**
+ * 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 declare function ScopedRegistryMixin<T extends CustomElementConstructor>(Base: T): T & ScopedRegistryHostConstructor;