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

package/dist/esm/command/behaviors/confirm-behavior.js

@@ -0,0 +1,225 @@
+/**
+ * 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
+ */
+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 { Observable } from "../../observation/observable.js";
+import { CommandRegistry } from "../registry.js";
+import { failure } from "../types.js";
+/**
+ * Error code for user-cancelled operations.
+ * @public
+ */
+export const USER_CANCELLED = "USER_CANCELLED";
+/**
+ * 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 class ConfirmBehavior {
+    constructor() {
+        /** Pending confirmations, oldest first */
+        this.queue = [];
+        /** Whether this instance is currently connected */
+        this.connected = false;
+    }
+    /**
+     * 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) {
+        if (this.connected) {
+            return;
+        }
+        this.connected = true;
+        const instances = ConfirmBehavior.instances;
+        instances.push(this);
+        if (instances.length === 1) {
+            CommandRegistry.addInterceptor({
+                name: ConfirmBehavior.INTERCEPTOR_NAME,
+                confirms: true,
+                priority: 10, // Run early to block before other interceptors
+                intercept: (command, args, next) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    // Only intercept destructive commands
+                    if (!command.destructive) {
+                        return next();
+                    }
+                    const active = ConfirmBehavior.instances;
+                    const handler = active[active.length - 1];
+                    // Show confirmation and wait for user response; with nobody left
+                    // to ask, fail closed.
+                    const confirmed = handler !== void 0 &&
+                        (yield handler.showConfirmation(command.id, command.label, (_a = command.confirmPrompt) !== null && _a !== void 0 ? _a : "Are you sure you want to proceed?"));
+                    if (!confirmed) {
+                        return failure({
+                            code: USER_CANCELLED,
+                            message: "User cancelled the operation",
+                            retryable: false,
+                        });
+                    }
+                    return next();
+                }),
+            });
+        }
+    }
+    /**
+     * 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) {
+        if (!this.connected) {
+            return;
+        }
+        this.connected = false;
+        // Cancel any pending confirmation
+        this.settleAll(false);
+        const instances = ConfirmBehavior.instances;
+        const index = instances.indexOf(this);
+        if (index !== -1) {
+            instances.splice(index, 1);
+        }
+        // Remove interceptor to prevent memory leaks once nobody can confirm
+        if (instances.length === 0) {
+            CommandRegistry.removeInterceptor(ConfirmBehavior.INTERCEPTOR_NAME);
+        }
+    }
+    /**
+     * 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() {
+        var _a;
+        Observable.track(this, "pendingConfirmation");
+        return (_a = this.queue[0]) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Gets the number of unsettled confirmations, including the current one.
+     * Observable.
+     */
+    get pendingCount() {
+        Observable.track(this, "pendingConfirmation");
+        return this.queue.length;
+    }
+    /**
+     * 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() {
+        this.settleCurrent(true);
+    }
+    /**
+     * 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() {
+        this.settleCurrent(false);
+    }
+    settleCurrent(confirmed) {
+        const current = this.queue.shift();
+        if (current !== void 0) {
+            Observable.notify(this, "pendingConfirmation");
+            current.resolve(confirmed);
+        }
+    }
+    settleAll(confirmed) {
+        const settled = this.queue;
+        if (settled.length > 0) {
+            this.queue = [];
+            Observable.notify(this, "pendingConfirmation");
+            for (const pending of settled) {
+                pending.resolve(confirmed);
+            }
+        }
+    }
+    /**
+     * 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
+     */
+    showConfirmation(commandId, label, prompt) {
+        return new Promise(resolve => {
+            this.queue.push({
+                commandId,
+                label,
+                prompt,
+                resolve,
+            });
+            Observable.notify(this, "pendingConfirmation");
+        });
+    }
+}
+/** Name of the interceptor for registration/removal */
+ConfirmBehavior.INTERCEPTOR_NAME = "confirm";
+/** Connected instances, oldest first. The last one is the active handler. */
+ConfirmBehavior.instances = [];

package/dist/esm/command/behaviors/undo-behavior.js

@@ -0,0 +1,313 @@
+/**
+ * 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
+ */
+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 { CommandRegistry } from "../registry.js";
+/**
+ * Whether a keyboard event originates from an element whose own undo history the
+ * browser manages (inputs, textareas, selects, contenteditable).
+ * @internal
+ */
+function isEditableTarget(event) {
+    var _a;
+    var _b;
+    // composedPath()[0] sees through shadow roots, where event.target is retargeted
+    const target = ((_b = (_a = event.composedPath) === null || _a === void 0 ? void 0 : _a.call(event)[0]) !== null && _b !== void 0 ? _b : event.target);
+    if (!target || typeof target.tagName !== "string") {
+        return false;
+    }
+    const tag = target.tagName;
+    return (tag === "INPUT" ||
+        tag === "TEXTAREA" ||
+        tag === "SELECT" ||
+        target.isContentEditable === true);
+}
+/**
+ * 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 class UndoBehavior {
+    /**
+     * Creates a new UndoBehavior instance.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        var _a, _b;
+        /** Undo stack (most recent at the end) */
+        this.stack = [];
+        /** Bound keyboard handler for cleanup */
+        this.boundKeydownHandler = null;
+        /** Whether this instance is currently connected */
+        this.connected = false;
+        this.limit = (_a = options.limit) !== null && _a !== void 0 ? _a : 10;
+        this.enableKeyboardShortcut = (_b = options.enableKeyboardShortcut) !== null && _b !== void 0 ? _b : true;
+    }
+    /**
+     * 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) {
+        if (this.connected) {
+            return;
+        }
+        this.connected = true;
+        const instances = UndoBehavior.instances;
+        instances.push(this);
+        // Register the shared post-hook to capture undo functions
+        if (instances.length === 1) {
+            CommandRegistry.addPostHook({
+                name: UndoBehavior.POST_HOOK_NAME,
+                afterExecute: (command, args, result) => {
+                    var _a;
+                    const active = UndoBehavior.instances;
+                    (_a = active[active.length - 1]) === null || _a === void 0 ? void 0 : _a.handleCommandExecuted(command, args, result);
+                },
+            });
+        }
+        // Register keyboard shortcut
+        if (this.enableKeyboardShortcut && typeof document !== "undefined") {
+            const handler = this.handleKeydown.bind(this);
+            this.boundKeydownHandler = handler;
+            document.addEventListener("keydown", handler);
+        }
+    }
+    /**
+     * 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) {
+        if (!this.connected) {
+            return;
+        }
+        this.connected = false;
+        const instances = UndoBehavior.instances;
+        const index = instances.indexOf(this);
+        if (index !== -1) {
+            instances.splice(index, 1);
+        }
+        // Remove post-hook once no instance needs it
+        if (instances.length === 0) {
+            CommandRegistry.removePostHook(UndoBehavior.POST_HOOK_NAME);
+        }
+        // Remove keyboard handler
+        const handler = this.boundKeydownHandler;
+        if (typeof document !== "undefined" && handler !== null) {
+            document.removeEventListener("keydown", handler);
+            this.boundKeydownHandler = null;
+        }
+        // Clear state
+        this.stack = [];
+    }
+    /**
+     * 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() {
+        return [...this.stack];
+    }
+    /**
+     * Gets the number of entries in the undo stack.
+     *
+     * @returns The stack size
+     */
+    get stackSize() {
+        return this.stack.length;
+    }
+    /**
+     * Whether there are any operations to undo.
+     *
+     * @returns True if the stack is not empty
+     */
+    get canUndo() {
+        return this.stack.length > 0;
+    }
+    /**
+     * Gets the most recent undo entry without removing it.
+     *
+     * @returns The most recent entry, or undefined if stack is empty
+     */
+    peek() {
+        return this.stack[this.stack.length - 1];
+    }
+    /**
+     * 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() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entry = this.stack.pop();
+            if (!entry) {
+                return false;
+            }
+            try {
+                yield entry.undoFn();
+                return true;
+            }
+            catch (error) {
+                // Re-push on failure so user can retry
+                this.stack.push(entry);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Clears the entire undo stack.
+     */
+    clear() {
+        this.stack = [];
+    }
+    /**
+     * Handles a command execution and potentially adds to the undo stack.
+     *
+     * @internal
+     */
+    handleCommandExecuted(command, args, result) {
+        var _a;
+        // Only capture successful commands
+        if (!result.success) {
+            return;
+        }
+        // Get the source element
+        const source = command.source.deref();
+        if (!source) {
+            return;
+        }
+        // Prefer the decorated method's name; fall back to the last segment of the
+        // command ID (e.g., "editor.save" -> "save") for hand-registered entries.
+        const methodName = (_a = command.methodName) !== null && _a !== void 0 ? _a : this.extractMethodName(command.id);
+        if (!methodName) {
+            return;
+        }
+        // Look for ${methodName}Undo() convention
+        const undoMethodName = `${methodName}Undo`;
+        const undoMethod = source[undoMethodName];
+        if (typeof undoMethod !== "function") {
+            return;
+        }
+        // Call the undo method to get the undo function
+        // The undo method should return a function that reverses the operation
+        const undoFn = undoMethod.call(source);
+        if (typeof undoFn !== "function") {
+            return;
+        }
+        // Add to stack
+        this.stack.push({
+            commandId: command.id,
+            label: command.label,
+            args,
+            undoFn,
+            timestamp: Date.now(),
+        });
+        // Trim to limit
+        while (this.stack.length > this.limit) {
+            this.stack.shift();
+        }
+    }
+    /**
+     * 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
+     */
+    extractMethodName(commandId) {
+        // Command IDs are in format "namespace.method" or "@scope/namespace.method"
+        const lastDotIndex = commandId.lastIndexOf(".");
+        if (lastDotIndex === -1) {
+            return null;
+        }
+        return commandId.slice(lastDotIndex + 1);
+    }
+    /**
+     * Handles keyboard events for Ctrl+Z shortcut.
+     *
+     * @internal
+     */
+    handleKeydown(event) {
+        // Check for Ctrl+Z (Windows/Linux) or Cmd+Z (Mac)
+        const isUndo = (event.ctrlKey || event.metaKey) && event.key === "z" && !event.shiftKey;
+        if (isUndo &&
+            this.canUndo &&
+            UndoBehavior.instances[UndoBehavior.instances.length - 1] === this &&
+            !event.defaultPrevented &&
+            !isEditableTarget(event)) {
+            event.preventDefault();
+            this.undo().catch(error => {
+                console.error("[fast-af] Undo failed:", error);
+            });
+        }
+    }
+}
+/** Name of the post-hook for registration/removal */
+UndoBehavior.POST_HOOK_NAME = "undo";
+/** Connected instances, oldest first. The last one is the active handler. */
+UndoBehavior.instances = [];

package/dist/esm/command/command.js

@@ -0,0 +1,104 @@
+/**
+ * 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 { registerElementControllerBehaviorFactory } from "../components/element-controller.js";
+import { createMetadataLocator } from "../platform.js";
+import { CommandBehavior } from "./behavior.js";
+/**
+ * Locates command metadata associated with a class.
+ * @remarks
+ * Uses FAST's createMetadataLocator pattern with WeakMap storage.
+ * Traverses prototype chain for inherited commands.
+ * @internal
+ */
+const commandMetadata = createMetadataLocator();
+registerElementControllerBehaviorFactory(element => getCommandMetadata(element.constructor).length > 0 ? new CommandBehavior() : void 0);
+/**
+ * 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 function getCommandMetadata(target) {
+    return commandMetadata(target);
+}
+/**
+ * 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 function command(id, options) {
+    return function (target, propertyKey, descriptor) {
+        // Runtime validation for namespace prefix
+        if (!id.includes(".")) {
+            console.warn(`[fast-af] Command "${id}" missing namespace prefix. ` +
+                `Use format: "namespace.action" (e.g., "editor.save")`);
+        }
+        // Store metadata using FAST's push() pattern
+        // target is the prototype, target.constructor is the class
+        commandMetadata(target.constructor).push(Object.assign({ id, methodName: propertyKey }, options));
+        return descriptor;
+    };
+}