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

package/dist/dts/arrays.d.ts

@@ -0,0 +1,2 @@
+export { type ArrayObserver, type LengthObserver, lengthOf, Sort, type SortObserver, Splice, SpliceStrategy, SpliceStrategySupport, sortedCount, } from "./observation/arrays.js";
+export type { Notifier, Subscriber, SubscriberSet } from "./observation/notifier.js";

package/dist/dts/binding/binding.d.ts

@@ -0,0 +1,59 @@
+import type { DOMAspect } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
+import type { Subscriber } from "../observation/notifier.js";
+import type { Expression, ExpressionObserver } from "../observation/observable.js";
+/**
+ * The directive from which a binding originates.
+ *
+ * @public
+ */
+export interface BindingDirective {
+    /**
+     * The binding.
+     */
+    readonly dataBinding: Binding;
+    /**
+     * The evaluated target aspect.
+     */
+    readonly targetAspect?: string;
+    /**
+     * The type of aspect to target.
+     */
+    readonly aspectType?: DOMAspect;
+}
+/**
+ * Captures a binding expression along with related information and capabilities.
+ *
+ * @public
+ */
+export declare abstract class Binding<TSource = any, TReturn = any, TParent = any> {
+    /**
+     * Options associated with the binding.
+     */
+    options?: any;
+    /**
+     * Evaluates the binding.
+     */
+    evaluate: Expression<TSource, TReturn, TParent>;
+    /**
+     * The security policy to associate with this binding.
+     */
+    policy?: DOMPolicy;
+    /**
+     * Indicates whether the binding is volatile.
+     */
+    isVolatile: boolean;
+    /**
+     * 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: Expression<TSource, TReturn, TParent>, policy?: DOMPolicy, isVolatile?: boolean);
+    /**
+     * Creates an observer capable of notifying a subscriber when the output of a binding changes.
+     * @param subscriber - The subscriber to changes in the binding.
+     * @param directive - The Binding directive to create the observer for.
+     */
+    abstract createObserver(subscriber: Subscriber, directive: BindingDirective): ExpressionObserver<TSource, TReturn, TParent>;
+}

package/dist/dts/binding/exports.d.ts

@@ -0,0 +1,9 @@
+export type { DOMAspect, DOMPolicy } from "../dom.js";
+export type { Subscriber } from "../observation/notifier.js";
+export type { Expression, ExpressionObserver } from "../observation/observable.js";
+export { Binding, type BindingDirective } 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 { type TwoWayBindingOptions, TwoWaySettings, twoWay, } from "./two-way.js";

package/dist/dts/binding/normalize.d.ts

@@ -0,0 +1,9 @@
+import type { Expression } from "../observation/observable.js";
+import { Binding } from "./binding.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 declare function normalizeBinding<TSource = any, TReturn = any, TParent = any>(value: Expression<TSource, TReturn, TParent> | Binding<TSource, TReturn, TParent> | {}): Binding<TSource, TReturn, TParent>;

package/dist/dts/binding/one-time.d.ts

@@ -0,0 +1,11 @@
+import type { DOMPolicy } from "../dom-policy.js";
+import type { Expression } from "../observation/observable.js";
+import { Binding } from "./binding.js";
+/**
+ * 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 declare function oneTime<T = any>(expression: Expression<T>, policy?: DOMPolicy): Binding<T>;

package/dist/dts/binding/one-way.d.ts

@@ -0,0 +1,20 @@
+import type { DOMPolicy } from "../dom-policy.js";
+import { type Expression } from "../observation/observable.js";
+import { Binding } from "./binding.js";
+/**
+ * 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 declare function oneWay<T = any>(expression: Expression<T>, policy?: DOMPolicy, isVolatile?: boolean): Binding<T>;
+/**
+ * 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 declare function listener<T = any>(expression: Expression<T>, options?: AddEventListenerOptions): Binding<T>;

package/dist/dts/binding/signal.d.ts

@@ -0,0 +1,36 @@
+import type { DOMPolicy } from "../dom-policy.js";
+import type { Subscriber } from "../observation/notifier.js";
+import type { Expression } from "../observation/observable.js";
+import { Binding } from "./binding.js";
+/**
+ * The gateway to signal APIs.
+ * @public
+ */
+export declare const Signal: Readonly<{
+    /**
+     * Subscribes to a signal.
+     * @param signal - The signal to subscribe to.
+     * @param subscriber - The subscriber.
+     */
+    subscribe(signal: string, subscriber: Subscriber): void;
+    /**
+     * Unsubscribes from the signal.
+     * @param signal - The signal to unsubscribe from.
+     * @param subscriber - The subscriber.
+     */
+    unsubscribe(signal: string, subscriber: Subscriber): void;
+    /**
+     * Sends the specified signal to subscribers.
+     * @param signal - The signal to send.
+     */
+    send(signal: string): void;
+}>;
+/**
+ * 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 declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>, policy?: DOMPolicy): Binding<T>;

package/dist/dts/binding/two-way.d.ts

@@ -0,0 +1,44 @@
+import type { DOMPolicy } from "../dom-policy.js";
+import { type Expression } from "../observation/observable.js";
+import { Binding, type BindingDirective } from "./binding.js";
+/**
+ * The twoWay binding options.
+ * @public
+ */
+export type TwoWayBindingOptions = {
+    changeEvent?: string;
+    fromView?: (value: any) => any;
+};
+/**
+ * The settings required to enable two-way binding.
+ * @public
+ */
+export interface TwoWaySettings {
+    /**
+     * Determines which event to listen to, to detect changes in the view.
+     * @param bindingSource - The directive to determine the change event for.
+     * @param target - The target element to determine the change event for.
+     */
+    determineChangeEvent(bindingSource: BindingDirective, target: HTMLElement): string;
+}
+/**
+ * Enables configuring two-way binding settings.
+ * @public
+ */
+export declare const TwoWaySettings: Readonly<{
+    /**
+     * Configures two-way binding.
+     * @param settings - The settings to use for the two-way binding system.
+     */
+    configure(settings: TwoWaySettings): void;
+}>;
+/**
+ * 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 declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, policy?: DOMPolicy, isBindingVolatile?: boolean): Binding<T>;

package/dist/dts/command/behavior.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 });
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Minimal controller contract required by command behaviors.
+ * @public
+ */
+export interface CommandHostController {
+    readonly source: HTMLElement;
+}
+/**
+ * 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 declare class CommandBehavior {
+    /**
+     * Map of command IDs to their registry entries.
+     * Populated in addedCallback, used in connect/disconnect.
+     */
+    private commands;
+    /**
+     * Reference to the host element.
+     * Set in addedCallback for use in discoverCommands.
+     */
+    private host;
+    /**
+     * 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: CommandHostController): void;
+    /**
+     * 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: CommandHostController): void;
+    /**
+     * 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: CommandHostController): void;
+    /**
+     * 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
+     */
+    private discoverCommands;
+}

package/dist/dts/command/behaviors/confirm-behavior.d.ts

@@ -0,0 +1,139 @@
+/**
+ * ConfirmBehavior - Intercepts destructive commands and prompts for confirmation.
+ *
+ * @remarks
+ * Uses the CommandRegistry interceptor API to intercept commands marked with
+ * `destructive: true`. Exposes pending confirmation state for UI rendering.
+ *
+ * @example
+ * ```typescript
+ * import { ConfirmBehavior } from '@lushly-dev/fast-element/command.js';
+ *
+ * class MyApp extends FASTElement {
+ *   private confirmBehavior = new ConfirmBehavior();
+ *
+ *   connectedCallback() {
+ *     super.connectedCallback();
+ *     this.$fastController.addBehavior(this.confirmBehavior);
+ *   }
+ *
+ *   // In template (pendingConfirmation is observable, so the template updates):
+ *   // <fast-af-confirm-dialog
+ *   //   :open="${x => x.confirmBehavior.pendingConfirmation !== null}"
+ *   //   :prompt="${x => x.confirmBehavior.pendingConfirmation?.prompt}"
+ *   //   @confirm="${x => x.confirmBehavior.executeConfirmed()}"
+ *   //   @cancel="${x => x.confirmBehavior.cancelPending()}">
+ *   // </fast-af-confirm-dialog>
+ * }
+ * ```
+ *
+ * @public
+ */
+import type { CommandHostController } from "../behavior.js";
+/**
+ * Error code for user-cancelled operations.
+ * @public
+ */
+export declare const USER_CANCELLED = "USER_CANCELLED";
+/**
+ * Pending confirmation state.
+ * @public
+ */
+export interface PendingConfirmation {
+    /** The command ID being confirmed */
+    commandId: string;
+    /** The command label for display */
+    label: string;
+    /** The confirmation prompt to show */
+    prompt: string;
+    /** Internal resolver - do not use directly */
+    resolve: (confirmed: boolean) => void;
+}
+/**
+ * Behavior that intercepts destructive commands and prompts for user confirmation.
+ *
+ * @remarks
+ * - Installs a shared `confirm` interceptor with the CommandRegistry while at
+ *   least one instance is connected (reference counted: the interceptor is added
+ *   by the first instance and removed when the last one disconnects)
+ * - Intercepts commands where `destructive: true`
+ * - When several instances are connected, the most recently connected one handles
+ *   confirmations; if it disconnects, the previous one takes over
+ * - Concurrent confirmations are queued: `pendingConfirmation` is the oldest
+ *   unsettled one, and each `executeConfirmed()`/`cancelPending()` settles it and
+ *   exposes the next
+ * - `pendingConfirmation` is observable, so templates binding to it update
+ * - Cancels any pending confirmation on disconnect
+ *
+ * @public
+ */
+export declare class ConfirmBehavior {
+    /** Pending confirmations, oldest first */
+    private queue;
+    /** Whether this instance is currently connected */
+    private connected;
+    /** Name of the interceptor for registration/removal */
+    private static readonly INTERCEPTOR_NAME;
+    /** Connected instances, oldest first. The last one is the active handler. */
+    private static readonly instances;
+    /**
+     * Called when the host element connects to the DOM.
+     * Registers this instance and, for the first one, the shared interceptor.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    connectedCallback(controller: CommandHostController): void;
+    /**
+     * Called when the host element disconnects from the DOM.
+     * Cancels pending confirmations, and removes the shared interceptor when this
+     * was the last connected instance.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    disconnectedCallback(controller: CommandHostController): void;
+    /**
+     * Gets the oldest pending confirmation, if any.
+     *
+     * @remarks
+     * Observable: use this in templates to show a confirmation dialog and to get the
+     * prompt text. When several confirmations are queued, the next one becomes
+     * current after the present one is settled.
+     *
+     * @returns The pending confirmation or null
+     */
+    get pendingConfirmation(): PendingConfirmation | null;
+    /**
+     * Gets the number of unsettled confirmations, including the current one.
+     * Observable.
+     */
+    get pendingCount(): number;
+    /**
+     * Confirms the current pending operation and allows it to proceed.
+     *
+     * @remarks
+     * Call this when the user clicks "Confirm" in your confirmation UI.
+     * The intercepted command will then execute normally.
+     */
+    executeConfirmed(): void;
+    /**
+     * Cancels the current pending operation.
+     *
+     * @remarks
+     * Call this when the user clicks "Cancel" in your confirmation UI.
+     * The intercepted command will return a USER_CANCELLED error.
+     */
+    cancelPending(): void;
+    private settleCurrent;
+    private settleAll;
+    /**
+     * Queues a confirmation prompt and waits for user response.
+     *
+     * @param commandId - The command ID being confirmed
+     * @param label - The command label for display
+     * @param prompt - The confirmation prompt text
+     * @returns Promise that resolves to true if confirmed, false if cancelled
+     *
+     * @internal
+     */
+    private showConfirmation;
+}

package/dist/dts/command/behaviors/undo-behavior.d.ts

@@ -0,0 +1,178 @@
+/**
+ * UndoBehavior - Manages an undo stack for undoable commands.
+ *
+ * @remarks
+ * Uses the CommandRegistry PostHook API to observe command execution and
+ * capture undo functions. Provides keyboard shortcut support (Ctrl+Z).
+ *
+ * Commands are undoable if the source element has a matching `${methodName}Undo()`
+ * method that returns a function to reverse the operation. `methodName` is the name
+ * of the `@command`-decorated method (not the last segment of the command ID).
+ *
+ * @example
+ * ```typescript
+ * import { UndoBehavior } from '@lushly-dev/fast-element/command.js';
+ *
+ * class MyApp extends FASTElement {
+ *   private undoBehavior = new UndoBehavior({ limit: 20 });
+ *
+ *   connectedCallback() {
+ *     super.connectedCallback();
+ *     this.$fastController.addBehavior(this.undoBehavior);
+ *   }
+ *
+ *   // Command with undo support
+ *   @command("editor.delete")
+ *   delete() { ... }
+ *
+ *   // Undo function - returns the reverse operation
+ *   deleteUndo() {
+ *     return () => { ... restore deleted content ... };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+import type { CommandHostController } from "../behavior.js";
+/**
+ * Entry in the undo stack.
+ * @public
+ */
+export interface UndoEntry {
+    /** The command ID that was executed */
+    commandId: string;
+    /** The command label for display */
+    label: string;
+    /** Arguments that were passed to the command */
+    args: unknown[];
+    /** The undo function to reverse the operation */
+    undoFn: () => void | Promise<void>;
+    /** Timestamp when the command was executed */
+    timestamp: number;
+}
+/**
+ * Options for configuring UndoBehavior.
+ * @public
+ */
+export interface UndoBehaviorOptions {
+    /** Maximum number of undo entries to keep (default: 10) */
+    limit?: number;
+    /** Whether to register Ctrl+Z keyboard shortcut (default: true) */
+    enableKeyboardShortcut?: boolean;
+}
+/**
+ * Behavior that manages an undo stack for undoable commands.
+ *
+ * @remarks
+ * - Installs a shared PostHook with the CommandRegistry while at least one instance
+ *   is connected (reference counted: added by the first instance, removed when the
+ *   last one disconnects)
+ * - When several instances are connected, the most recently connected one records
+ *   undo entries and handles the keyboard shortcut
+ * - Captures undo functions from `${methodName}Undo()` convention
+ * - Maintains a limited stack of undo entries
+ * - Provides `undo()` method and Ctrl/Cmd+Z keyboard shortcut; the shortcut is left
+ *   to the browser when the event target is an editable element
+ * - Cleans up on disconnect
+ *
+ * @public
+ */
+export declare class UndoBehavior {
+    /** Undo stack (most recent at the end) */
+    private stack;
+    /** Maximum stack size */
+    private readonly limit;
+    /** Whether keyboard shortcut is enabled */
+    private readonly enableKeyboardShortcut;
+    /** Bound keyboard handler for cleanup */
+    private boundKeydownHandler;
+    /** Name of the post-hook for registration/removal */
+    private static readonly POST_HOOK_NAME;
+    /** Connected instances, oldest first. The last one is the active handler. */
+    private static readonly instances;
+    /** Whether this instance is currently connected */
+    private connected;
+    /**
+     * Creates a new UndoBehavior instance.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: UndoBehaviorOptions);
+    /**
+     * Called when the host element connects to the DOM.
+     * Registers the undo post-hook with CommandRegistry.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    connectedCallback(controller: CommandHostController): void;
+    /**
+     * Called when the host element disconnects from the DOM.
+     * Removes the post-hook (when this was the last instance) and cleans up state.
+     *
+     * @param controller - The host controller managing this behavior
+     */
+    disconnectedCallback(controller: CommandHostController): void;
+    /**
+     * Gets the current undo stack.
+     *
+     * @remarks
+     * Returns a copy of the stack to prevent external mutation.
+     *
+     * @returns Array of undo entries (most recent last)
+     */
+    getStack(): readonly UndoEntry[];
+    /**
+     * Gets the number of entries in the undo stack.
+     *
+     * @returns The stack size
+     */
+    get stackSize(): number;
+    /**
+     * Whether there are any operations to undo.
+     *
+     * @returns True if the stack is not empty
+     */
+    get canUndo(): boolean;
+    /**
+     * Gets the most recent undo entry without removing it.
+     *
+     * @returns The most recent entry, or undefined if stack is empty
+     */
+    peek(): UndoEntry | undefined;
+    /**
+     * Undoes the most recent operation.
+     *
+     * @remarks
+     * Pops the most recent entry from the stack and executes its undo function.
+     * If the undo function is async, this returns a Promise.
+     *
+     * @returns Promise that resolves when the undo is complete
+     */
+    undo(): Promise<boolean>;
+    /**
+     * Clears the entire undo stack.
+     */
+    clear(): void;
+    /**
+     * Handles a command execution and potentially adds to the undo stack.
+     *
+     * @internal
+     */
+    private handleCommandExecuted;
+    /**
+     * Extracts the method name from a command ID.
+     *
+     * @param commandId - The command ID (e.g., "editor.save")
+     * @returns The method name (e.g., "save")
+     *
+     * @internal
+     */
+    private extractMethodName;
+    /**
+     * Handles keyboard events for Ctrl+Z shortcut.
+     *
+     * @internal
+     */
+    private handleKeydown;
+}

package/dist/dts/command/command.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The `command` decorator for FASTElement methods.
+ * Binds methods to the Command Registry for AI agent interaction.
+ *
+ * @remarks
+ * Uses FAST's createMetadataLocator with push() pattern for metadata storage.
+ * Metadata is discovered at connect-time by CommandBehavior.
+ *
+ * @example
+ * ```typescript
+ * import { FASTElement } from '@lushly-dev/fast-element';
+ * import { command, success } from '@lushly-dev/fast-element/command.js';
+ *
+ * class MyEditor extends FASTElement {
+ *   @command('editor.save', { label: 'Save', keybinding: 'Ctrl+S' })
+ *   save(): CommandResult {
+ *     // Save logic here
+ *     return success({ saved: true });
+ *   }
+ * }
+ * ```
+ */
+import type { CommandId, CommandMetadata, CommandOptions } from "./types.js";
+/**
+ * Retrieves all command metadata for a given class.
+ *
+ * @param target - The class constructor to retrieve metadata for
+ * @returns Array of CommandMetadata for all `command` decorators on the class
+ *
+ * @example
+ * ```typescript
+ * const metadata = getCommandMetadata(MyEditor);
+ * console.log(metadata); // [{ id: 'editor.save', methodName: 'save', ... }]
+ * ```
+ *
+ * @public
+ */
+export declare function getCommandMetadata(target: Function): readonly CommandMetadata[];
+/**
+ * Decorator that registers a method as a command.
+ * Commands are discoverable by AI agents and command palettes.
+ *
+ * @param id - Namespace-prefixed command identifier (e.g., "editor.save")
+ * @param options - Optional command configuration
+ * @returns A method decorator
+ *
+ * @remarks
+ * - Command IDs must include a namespace prefix (e.g., "app.action")
+ * - Runtime warning is emitted if namespace is missing
+ * - Metadata is stored using FAST's push() pattern
+ * - Commands are registered with CommandRegistry when element connects
+ *
+ * @example
+ * ```typescript
+ * class TextEditor extends FASTElement {
+ *   // Basic command
+ *   @command('editor.selectAll')
+ *   selectAll(): CommandResult {
+ *     return success({ selected: true });
+ *   }
+ *
+ *   // Command with full options
+ *   @command('editor.save', {
+ *     label: 'Save Document',
+ *     icon: 'save',
+ *     description: 'Save the current document',
+ *     category: 'File',
+ *     keybinding: 'Ctrl+S',
+ *     when: 'editorFocus'
+ *   })
+ *   save(): CommandResult {
+ *     return success({ saved: true });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function command(id: CommandId, options?: CommandOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;