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

package/dist/dts/trust/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Severity of a {@link Warning}.
+ * @public
+ */
+export type WarningSeverity = "info" | "warning" | "caution";
+/**
+ * A non-fatal issue surfaced alongside an event.
+ *
+ * @remarks
+ * Local stub that mirrors the `Warning` type of AFD's `CommandResult`; it can be
+ * re-exported from `@lushly-dev/afd-core` once that package is a dependency.
+ *
+ * @public
+ */
+export interface Warning {
+    /** Machine-readable warning code. */
+    code: string;
+    /** Human-readable warning message. */
+    message: string;
+    /** Optional severity. Unknown values are dropped when signals are read. */
+    severity?: WarningSeverity;
+    /** Optional structured details. Only plain objects are kept when signals are read. */
+    details?: Record<string, unknown>;
+}
+/**
+ * Trust signals attached to component events.
+ * @public
+ */
+export interface TrustSignals {
+    /** Confidence level 0-1. Higher = more certain. */
+    confidence?: number;
+    /** Human-readable explanation of why this event occurred. */
+    reasoning?: string;
+    /** Non-fatal issues to surface to the user. An empty array is preserved. */
+    warnings?: Warning[];
+}
+/**
+ * Extended emit options with trust signals.
+ * @public
+ */
+export interface TrustEmitOptions extends Omit<CustomEventInit, "detail">, TrustSignals {
+}
+/**
+ * Property key (the string `"__trust"`) under which trust metadata is stored in
+ * event detail.
+ * @public
+ */
+export declare const TRUST_KEY: "__trust";

package/dist/dts/trust/utils.d.ts

@@ -0,0 +1,26 @@
+import type { TrustSignals } from "./types.js";
+/**
+ * Extract trust signals from a CustomEvent.
+ * Returns empty object if no trust signals present.
+ * @public
+ */
+export declare function getTrustSignals(event: CustomEvent): TrustSignals;
+/**
+ * Check if an event has trust signals.
+ * @public
+ */
+export declare function hasTrustSignals(event: CustomEvent): boolean;
+/**
+ * Wrap detail with trust signals.
+ *
+ * @remarks
+ * - Plain objects are copied and the signals are added under {@link TRUST_KEY}.
+ * - Anything else (primitives, arrays, Dates, class instances, ...) is wrapped in a
+ *   `{ value, __trust }` envelope so it is never spread into a different shape.
+ * - A `__trust` key already present on a plain-object detail is caller-supplied
+ *   (often from parsed JSON) and is never kept: it is replaced by the real signals,
+ *   or dropped when there are none, so detail data cannot forge trust signals.
+ *
+ * @internal
+ */
+export declare function wrapDetailWithTrust(detail: unknown, signals?: TrustSignals): unknown;

package/dist/dts/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.60.1"
+    }
+  ]
+}

package/dist/dts/utilities.d.ts

@@ -0,0 +1,76 @@
+import type { HostBehavior } from "./styles/host.js";
+import type { ViewBehavior, ViewBehaviorFactory, ViewController } from "./templating/html-directive.js";
+/**
+ * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
+ * When the parent of a node is a shadow-root, it will return the host
+ * element of the shadow root. Otherwise it will return the parent node or null if
+ * no parent node exists.
+ * @param element - The element for which to retrieve the composed parent
+ *
+ * @public
+ */
+export declare function composedParent<T extends HTMLElement>(element: T): HTMLElement | null;
+/**
+ * Determines if the reference element contains the test element in a "composed" DOM tree that
+ * ignores shadow DOM boundaries.
+ *
+ * Returns true of the test element is a descendent of the reference, or exists in
+ * a shadow DOM that is a logical descendent of the reference. Otherwise returns false.
+ * @param reference - The element to test for containment against.
+ * @param test - The element being tested for containment.
+ *
+ * @public
+ */
+export declare function composedContains(reference: HTMLElement, test: HTMLElement): boolean;
+/**
+ * An extension of MutationObserver that supports unobserving nodes.
+ * @internal
+ */
+export declare class UnobservableMutationObserver extends MutationObserver {
+    private readonly callback;
+    private observedNodes;
+    /**
+     * Creates an instance of UnobservableMutationObserver.
+     * @param callback - The callback to invoke when observed nodes are changed.
+     */
+    constructor(callback: MutationCallback);
+    observe(target: Node, options?: MutationObserverInit | undefined): void;
+    unobserve(target: Node): void;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export interface ViewBehaviorOrchestrator<TSource = any, TParent = any> extends ViewController<TSource, TParent>, HostBehavior<TSource> {
+    /**
+     *
+     * @param nodeId - The structural id of the DOM node to which a behavior will apply.
+     * @param target - The DOM node associated with the id.
+     */
+    addTarget(nodeId: string, target: Node): void;
+    /**
+     * Adds a behavior.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: ViewBehavior): void;
+    /**
+     * Adds a behavior factory.
+     * @param factory - The behavior factory to add.
+     * @param target - The target the factory will create behaviors for.
+     */
+    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export declare const ViewBehaviorOrchestrator: Readonly<{
+    /**
+     * Creates a ViewBehaviorOrchestrator.
+     * @param source - The source to to associate behaviors with.
+     * @returns A ViewBehaviorOrchestrator.
+     */
+    create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
+}>;

package/dist/esm/arrays.js

@@ -0,0 +1 @@
+export { lengthOf, Sort, Splice, SpliceStrategy, SpliceStrategySupport, sortedCount, } from "./observation/arrays.js";

package/dist/esm/binding/binding.js

@@ -0,0 +1,18 @@
+/**
+ * Captures a binding expression along with related information and capabilities.
+ *
+ * @public
+ */
+export class Binding {
+    /**
+     * Creates a binding.
+     * @param evaluate - Evaluates the binding.
+     * @param policy - The security policy to associate with this binding.
+     * @param isVolatile - Indicates whether the binding is volatile.
+     */
+    constructor(evaluate, policy, isVolatile = false) {
+        this.evaluate = evaluate;
+        this.policy = policy;
+        this.isVolatile = isVolatile;
+    }
+}

package/dist/esm/binding/exports.js

@@ -0,0 +1,6 @@
+export { Binding } from "./binding.js";
+export { normalizeBinding } from "./normalize.js";
+export { oneTime } from "./one-time.js";
+export { listener, oneWay } from "./one-way.js";
+export { Signal, signal } from "./signal.js";
+export { TwoWaySettings, twoWay, } from "./two-way.js";

package/dist/esm/binding/normalize.js

@@ -0,0 +1,17 @@
+import { isFunction } from "../interfaces.js";
+import { Binding } from "./binding.js";
+import { oneTime } from "./one-time.js";
+import { oneWay } from "./one-way.js";
+/**
+ * Normalizes the input value into a binding.
+ * @param value - The value to create the default binding for.
+ * @returns A binding configuration for the provided value.
+ * @public
+ */
+export function normalizeBinding(value) {
+    return isFunction(value)
+        ? oneWay(value)
+        : value instanceof Binding
+            ? value
+            : oneTime(() => value);
+}

package/dist/esm/binding/one-time.js

@@ -0,0 +1,21 @@
+import { makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
+class OneTimeBinding extends Binding {
+    createObserver() {
+        return this;
+    }
+    bind(controller) {
+        return this.evaluate(controller.source, controller.context);
+    }
+}
+makeSerializationNoop(OneTimeBinding);
+/**
+ * Creates a one time binding
+ * @param expression - The binding to refresh when signaled.
+ * @param policy - The security policy to associate with th binding.
+ * @returns A binding configuration.
+ * @public
+ */
+export function oneTime(expression, policy) {
+    return new OneTimeBinding(expression, policy);
+}

package/dist/esm/binding/one-way.js

@@ -0,0 +1,30 @@
+import { Observable, } from "../observation/observable.js";
+import { Binding } from "./binding.js";
+class OneWayBinding extends Binding {
+    createObserver(subscriber) {
+        return Observable.binding(this.evaluate, subscriber, this.isVolatile);
+    }
+}
+/**
+ * Creates an standard binding.
+ * @param expression - The binding to refresh when changed.
+ * @param policy - The security policy to associate with th binding.
+ * @param isVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding configuration.
+ * @public
+ */
+export function oneWay(expression, policy, isVolatile = Observable.isVolatileBinding(expression)) {
+    return new OneWayBinding(expression, policy, isVolatile);
+}
+/**
+ * Creates an event listener binding.
+ * @param expression - The binding to invoke when the event is raised.
+ * @param options - Event listener options.
+ * @returns A binding configuration.
+ * @public
+ */
+export function listener(expression, options) {
+    const config = new OneWayBinding(expression);
+    config.options = options;
+    return config;
+}

package/dist/esm/binding/signal.js

@@ -0,0 +1,99 @@
+import { isString } from "../interfaces.js";
+import { makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
+const subscribers = Object.create(null);
+/**
+ * The gateway to signal APIs.
+ * @public
+ */
+export const Signal = Object.freeze({
+    /**
+     * Subscribes to a signal.
+     * @param signal - The signal to subscribe to.
+     * @param subscriber - The subscriber.
+     */
+    subscribe(signal, subscriber) {
+        const found = subscribers[signal];
+        if (found) {
+            found instanceof Set
+                ? found.add(subscriber)
+                : (subscribers[signal] = new Set([found, subscriber]));
+        }
+        else {
+            subscribers[signal] = subscriber;
+        }
+    },
+    /**
+     * Unsubscribes from the signal.
+     * @param signal - The signal to unsubscribe from.
+     * @param subscriber - The subscriber.
+     */
+    unsubscribe(signal, subscriber) {
+        const found = subscribers[signal];
+        if (found && found instanceof Set) {
+            found.delete(subscriber);
+        }
+        else {
+            subscribers[signal] = void 0;
+        }
+    },
+    /**
+     * Sends the specified signal to subscribers.
+     * @param signal - The signal to send.
+     */
+    send(signal) {
+        const found = subscribers[signal];
+        if (found) {
+            found instanceof Set
+                ? found.forEach(x => x.handleChange(found, signal))
+                : found.handleChange(this, signal);
+        }
+    },
+});
+class SignalObserver {
+    constructor(dataBinding, subscriber) {
+        this.dataBinding = dataBinding;
+        this.subscriber = subscriber;
+        this.isNotBound = true;
+    }
+    bind(controller) {
+        if (this.isNotBound) {
+            Signal.subscribe(this.getSignal(controller), this);
+            controller.onUnbind(this);
+            this.isNotBound = false;
+        }
+        return this.dataBinding.evaluate(controller.source, controller.context);
+    }
+    unbind(controller) {
+        this.isNotBound = true;
+        Signal.unsubscribe(this.getSignal(controller), this);
+    }
+    handleChange() {
+        this.subscriber.handleChange(this.dataBinding.evaluate, this);
+    }
+    getSignal(controller) {
+        const options = this.dataBinding.options;
+        return isString(options)
+            ? options
+            : options(controller.source, controller.context);
+    }
+}
+makeSerializationNoop(SignalObserver);
+class SignalBinding extends Binding {
+    createObserver(subscriber) {
+        return new SignalObserver(this, subscriber);
+    }
+}
+/**
+ * Creates a signal binding configuration with the supplied options.
+ * @param expression - The binding to refresh when signaled.
+ * @param options - The signal name or a binding to use to retrieve the signal name.
+ * @param policy - The security policy to associate with th binding.
+ * @returns A binding configuration.
+ * @public
+ */
+export function signal(expression, options, policy) {
+    const binding = new SignalBinding(expression, policy);
+    binding.options = options;
+    return binding;
+}

package/dist/esm/binding/two-way.js

@@ -0,0 +1,109 @@
+import { isString, Message } from "../interfaces.js";
+import { Observable, } from "../observation/observable.js";
+import { FAST, makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
+const defaultOptions = {
+    fromView: v => v,
+};
+let twoWaySettings = {
+    determineChangeEvent() {
+        return "change";
+    },
+};
+/**
+ * Enables configuring two-way binding settings.
+ * @public
+ */
+export const TwoWaySettings = Object.freeze({
+    /**
+     * Configures two-way binding.
+     * @param settings - The settings to use for the two-way binding system.
+     */
+    configure(settings) {
+        twoWaySettings = settings;
+    },
+});
+class TwoWayObserver {
+    constructor(directive, subscriber, dataBinding) {
+        this.directive = directive;
+        this.subscriber = subscriber;
+        this.dataBinding = dataBinding;
+        this.isNotBound = true;
+        this.notifier = Observable.binding(dataBinding.evaluate, this, dataBinding.isVolatile);
+    }
+    bind(controller) {
+        var _a;
+        if (!this.changeEvent) {
+            this.changeEvent = (_a = this.dataBinding.options.changeEvent) !== null && _a !== void 0 ? _a : twoWaySettings.determineChangeEvent(this.directive, this.target);
+        }
+        if (this.isNotBound) {
+            this.target.addEventListener(this.changeEvent, this);
+            controller.onUnbind(this);
+            this.isNotBound = false;
+        }
+        return this.notifier.bind(controller);
+    }
+    unbind(controller) {
+        this.isNotBound = true;
+        this.target.removeEventListener(this.changeEvent, this);
+    }
+    handleChange(subject, args) {
+        this.subscriber.handleChange(this.dataBinding.evaluate, this);
+    }
+    handleEvent(event) {
+        const bindingSource = this.directive;
+        const target = event.currentTarget;
+        const notifier = this.notifier;
+        const last = notifier.last; // using internal API!!!
+        if (!last) {
+            FAST.warn(Message.twoWayBindingRequiresObservables);
+            return;
+        }
+        let value;
+        switch (bindingSource.aspectType) {
+            case 1:
+                value = target.getAttribute(bindingSource.targetAspect);
+                break;
+            case 2:
+                value = target.hasAttribute(bindingSource.targetAspect);
+                break;
+            case 4:
+                value = target.innerText;
+                break;
+            default:
+                value = target[bindingSource.targetAspect];
+                break;
+        }
+        last.propertySource[last.propertyName] =
+            this.dataBinding.options.fromView(value);
+    }
+}
+makeSerializationNoop(TwoWayObserver);
+class TwoWayBinding extends Binding {
+    createObserver(subscriber, bindingSource) {
+        return new TwoWayObserver(bindingSource, subscriber, this);
+    }
+}
+/**
+ * Creates a default binding.
+ * @param expression - The binding to refresh when changed.
+ * @param optionsOrChangeEvent - The binding options or the name of the change event to use.
+ * @param policy - The security policy to associate with the binding.
+ * @param isBindingVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding.
+ * @public
+ */
+export function twoWay(expression, optionsOrChangeEvent, policy, isBindingVolatile = Observable.isVolatileBinding(expression)) {
+    if (isString(optionsOrChangeEvent)) {
+        optionsOrChangeEvent = { changeEvent: optionsOrChangeEvent };
+    }
+    if (!optionsOrChangeEvent) {
+        optionsOrChangeEvent = defaultOptions;
+    }
+    else if (!optionsOrChangeEvent.fromView) {
+        optionsOrChangeEvent.fromView = defaultOptions.fromView;
+    }
+    const binding = new TwoWayBinding(expression, policy, isBindingVolatile);
+    binding.options = optionsOrChangeEvent;
+    return binding;
+}

package/dist/esm/command/behavior.js

@@ -0,0 +1,155 @@
+/**
+ * CommandBehavior - Lifecycle management for `command`-decorated methods.
+ * Bridges `command` decorator metadata to the CommandRegistry.
+ *
+ * @remarks
+ * Implements the FAST host-behavior lifecycle structurally.
+ * Commands are discovered in addedCallback, registered on connect, and
+ * unregistered on disconnect.
+ *
+ * Uses Observable.track() for reactive canExecute and when getters,
+ * allowing UI to reactively update when command availability changes.
+ *
+ * @example
+ * ```typescript
+ * // Behavior is automatically added when an element has command decorators
+ * class MyEditor extends FASTElement {
+ *   @observable
+ *   hasChanges = false;
+ *
+ *   // Reactive canExecute getter
+ *   get saveCanExecute(): boolean {
+ *     return this.hasChanges;
+ *   }
+ *
+ *   @command('editor.save', { label: 'Save' })
+ *   save(): CommandResult {
+ *     return success({ saved: true });
+ *   }
+ * }
+ * ```
+ */
+import { Observable } from "../observation/observable.js";
+import { getCommandMetadata } from "./command.js";
+import { CommandRegistry } from "./registry.js";
+import { createWeakReference } from "./weak-ref.js";
+/**
+ * Behavior that manages command lifecycle for FASTElement components.
+ *
+ * @remarks
+ * - Discovers `command`-decorated methods via getCommandMetadata
+ * - Registers commands with CommandRegistry on connect
+ * - Unregisters commands on disconnect
+ * - Provides reactive canExecute/when getters via Observable.track()
+ *
+ * @public
+ */
+export class CommandBehavior {
+    constructor() {
+        /**
+         * Map of command IDs to their registry entries.
+         * Populated in addedCallback, used in connect/disconnect.
+         */
+        this.commands = new Map();
+        /**
+         * Reference to the host element.
+         * Set in addedCallback for use in discoverCommands.
+         */
+        this.host = null;
+    }
+    /**
+     * Called when the behavior is first attached to a controller.
+     * Discovers all `command`-decorated methods on the host element.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    addedCallback(controller) {
+        this.host = controller.source;
+        this.discoverCommands();
+    }
+    /**
+     * Called when the host element connects to the DOM.
+     * Registers all discovered commands with the CommandRegistry.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    connectedCallback(controller) {
+        this.commands.forEach((cmd, id) => {
+            CommandRegistry.register(id, cmd);
+        });
+    }
+    /**
+     * Called when the host element disconnects from the DOM.
+     * Unregisters all commands from the CommandRegistry.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    disconnectedCallback(controller) {
+        this.commands.forEach((command, id) => {
+            CommandRegistry.unregister(id, command);
+        });
+    }
+    /**
+     * Discovers all `command`-decorated methods on the host element
+     * and creates CommandEntry objects for each.
+     *
+     * @remarks
+     * For each command:
+     * - Binds the method to the host element
+     * - Creates reactive canExecute getter checking for `${methodName}CanExecute`
+     * - Creates reactive when getter checking for `${methodName}When`
+     * - Stores WeakRef to host for garbage collection safety
+     */
+    discoverCommands() {
+        var _a;
+        if (!this.host)
+            return;
+        const metadata = getCommandMetadata(this.host.constructor);
+        const host = this.host;
+        for (const meta of metadata) {
+            const entry = {
+                id: meta.id,
+                methodName: meta.methodName,
+                label: (_a = meta.label) !== null && _a !== void 0 ? _a : meta.methodName,
+                icon: meta.icon,
+                description: meta.description,
+                category: meta.category,
+                keybinding: meta.keybinding,
+                parameters: meta.parameters,
+                hidden: meta.hidden,
+                destructive: meta.destructive,
+                confirmPrompt: meta.confirmPrompt,
+                expose: meta.expose,
+                execute: host[meta.methodName].bind(host),
+                source: createWeakReference(host),
+                /**
+                 * Reactive getter for command executability.
+                 * Checks for a `${methodName}CanExecute` property on the host.
+                 * Uses Observable.track() to enable reactive updates.
+                 */
+                get canExecute() {
+                    const getter = `${meta.methodName}CanExecute`;
+                    if (getter in host) {
+                        Observable.track(host, getter);
+                        return host[getter];
+                    }
+                    return true;
+                },
+                /**
+                 * Reactive getter for command visibility.
+                 * Checks for a `${methodName}When` property on the host.
+                 * Uses Observable.track() to enable reactive updates.
+                 */
+                get when() {
+                    const getter = `${meta.methodName}When`;
+                    if (getter in host) {
+                        Observable.track(host, getter);
+                        return host[getter];
+                    }
+                    return true;
+                },
+            };
+            this.commands.set(meta.id, entry);
+        }
+    }
+}