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

package/dist/dts/command/component-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Component introspection commands for FAST elements.
+ * Pure runtime introspection - no Creator dependencies.
+ *
+ * @remarks
+ * These commands expose FAST component metadata to AI agents and command palettes.
+ * Task 9 will add fast.component.getAPI to this file.
+ */
+import type { ComponentSchema } from "../definition-schema/types.js";
+/**
+ * Component list result item.
+ * @public
+ */
+export interface ComponentInfo {
+    /** The custom element tag name */
+    name: string;
+    /** The constructor function name */
+    constructor: string;
+    /** Whether the element is defined in the platform registry */
+    isDefined: boolean;
+}
+/**
+ * Component API result from fast.component.getAPI.
+ * @public
+ */
+export interface ComponentAPIInfo {
+    /** The custom element tag name */
+    name: string;
+    /** Properties exposed by the component */
+    properties: ComponentSchema["properties"];
+    /** Events emitted by the component */
+    events: ComponentSchema["events"];
+    /** Slots available in the component */
+    slots: ComponentSchema["slots"];
+    /** CSS custom properties (design tokens) */
+    cssProperties: ComponentSchema["cssProperties"];
+    /** Commands exposed by the component */
+    commands?: ComponentSchema["commands"];
+}
+/**
+ * Register fast.component.* commands with the CommandRegistry.
+ * Called during fast-element initialization.
+ *
+ * @remarks
+ * These commands provide runtime introspection of registered FAST elements.
+ * They have no dependencies on Creator or design-to-code packages.
+ *
+ * @public
+ */
+export declare function registerComponentCommands(): void;

package/dist/dts/command/components/confirm-dialog.d.ts

@@ -0,0 +1,117 @@
+/**
+ * ConfirmDialog component for command safety confirmations.
+ * Modal dialog for confirming destructive actions.
+ *
+ * @remarks
+ * Provides an accessible modal dialog with:
+ * - open/prompt attributes for state management
+ * - confirm/cancel events for user response
+ * - Full ARIA support (role, aria-modal, aria-labelledby, aria-describedby)
+ * - Focus trap to keep keyboard navigation within dialog
+ * - Escape key to cancel
+ *
+ * @example
+ * ```html
+ * <fast-af-confirm-dialog
+ *   open
+ *   prompt="Are you sure you want to delete this item?"
+ *   @confirm=${handleConfirm}
+ *   @cancel=${handleCancel}
+ * ></fast-af-confirm-dialog>
+ * ```
+ */
+import { FASTElement } from "../../components/fast-element.js";
+/**
+ * A modal dialog component for confirming destructive actions.
+ *
+ * Events: `confirm` is dispatched when the user confirms; `cancel` is dispatched
+ * when the user cancels, presses Escape, or clicks the overlay.
+ *
+ * Slots: the default slot supplies additional content; `title`, `cancel-text`, and
+ * `confirm-text` replace their corresponding labels.
+ *
+ * CSS parts: `overlay`, `dialog`, `title`, `prompt`, `actions`, `cancel-button`, and
+ * `confirm-button`.
+ *
+ * @internal
+ */
+export declare class ConfirmDialog extends FASTElement {
+    /**
+     * Whether the dialog is open/visible.
+     * @public
+     */
+    open: boolean;
+    /**
+     * The prompt message to display in the dialog.
+     * @public
+     */
+    prompt: string;
+    /**
+     * Reference to the previously focused element for restoring focus on close.
+     * @internal
+     */
+    private previouslyFocused;
+    /**
+     * List of focusable elements within the dialog for focus trapping.
+     * @internal
+     */
+    private focusableElements;
+    /**
+     * Called when the open attribute changes.
+     * Manages focus trap and body scroll lock.
+     * @param oldValue - Previous value
+     * @param newValue - New value
+     */
+    openChanged(oldValue: boolean, newValue: boolean): void;
+    /**
+     * Sets up focus trap within the dialog.
+     * @internal
+     */
+    private trapFocus;
+    /**
+     * Handles keydown events for focus trap and escape key.
+     * @param event - The keyboard event
+     * @internal
+     */
+    handleKeydown(event: KeyboardEvent): void;
+    /**
+     * Handles tab key for focus trapping.
+     * @param event - The keyboard event
+     * @internal
+     */
+    private handleTabKey;
+    /**
+     * Handles overlay click to cancel.
+     * @param event - The mouse event
+     * @internal
+     */
+    handleOverlayClick(event: MouseEvent): void;
+    /**
+     * Handles confirm button click.
+     * Emits 'confirm' event and closes the dialog.
+     * @public
+     */
+    handleConfirm(): void;
+    /**
+     * Handles cancel button click.
+     * Emits 'cancel' event and closes the dialog.
+     * @public
+     */
+    handleCancel(): void;
+}
+/**
+ * The namespaced tag used by the opt-in confirmation dialog.
+ * @public
+ */
+export declare const confirmDialogTagName: "fast-af-confirm-dialog";
+/**
+ * Defines the confirmation dialog in the provided registry.
+ *
+ * @remarks
+ * Registration is explicit so importing the command API remains side-effect free.
+ * Repeated calls for the same registry are safe.
+ *
+ * @param registry - Registry in which to define the dialog.
+ * @public
+ */
+export declare function defineConfirmDialog(registry?: CustomElementRegistry): Promise<void>;

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

@@ -0,0 +1,21 @@
+/**
+ * Public API for the `command` decorator system.
+ * Enables AI agents to interact with FASTElement components through structured commands.
+ */
+export type { ResultMetadata, CommandError, CommandResult, CommandId, CommandMetadata, CommandOptions, CommandEntry, Action, InterfaceType, ExposeConfig, ActionFilter, JSONSchema, } from "./types.js";
+export { ErrorCodes, success, failure, isSuccess, isFailure, createError, DEFAULT_EXPOSE_CONFIG, } from "./types.js";
+export { command, getCommandMetadata } from "./command.js";
+export { CommandBehavior } from "./behavior.js";
+export type { CommandHostController } from "./behavior.js";
+export { ConfirmBehavior, USER_CANCELLED } from "./behaviors/confirm-behavior.js";
+export type { PendingConfirmation } from "./behaviors/confirm-behavior.js";
+export { UndoBehavior } from "./behaviors/undo-behavior.js";
+export type { UndoEntry, UndoBehaviorOptions } from "./behaviors/undo-behavior.js";
+export { CommandRegistry } from "./registry.js";
+export type { CommandRegistryAPI, CommandListener, TelemetryHandler, InvokeOptions, Interceptor, PostHook, } from "./registry.js";
+export { confirmDialogTagName, defineConfirmDialog, } from "./components/confirm-dialog.js";
+export { registerComponentCommands } from "./component-registry.js";
+export type { ComponentInfo, ComponentAPIInfo } from "./component-registry.js";
+export type { AriaHint, CommandSchema, ComponentSchema, CSSPropertySchema, EventSchema, JSONSchema as DefinitionJSONSchema, PropertySchema, PropertyType, SlotSchema, } from "../definition-schema/types.js";
+export { registerValidationCommands } from "./validation.js";
+export type { LintSeverity, LintIssue, LintCounts, LintPlanStep, LintResult, WcagLevel, A11yImpact, A11yViolation, A11yAuditResult, } from "./validation.js";

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

@@ -0,0 +1,201 @@
+/**
+ * CommandRegistry singleton for managing command lifecycle.
+ * Enables AI agents and command palettes to discover and execute commands.
+ *
+ * @remarks
+ * - SSR-safe: Guards against document access in Node.js
+ * - The `cmd-exec` document event bridge is opt-in (`enableEventBridge()`)
+ * - Uses AFD's failure() helper for error results
+ *
+ * @example
+ * ```typescript
+ * import { CommandRegistry } from '@lushly-dev/fast-element/command.js';
+ *
+ * // Execute a command
+ * const result = await CommandRegistry.execute('editor.save');
+ * if (result.success) {
+ *   console.log('Saved:', result.data);
+ * } else {
+ *   console.error('Failed:', result.error.message);
+ * }
+ *
+ * // Get actions for command palette
+ * const actions = CommandRegistry.getActions();
+ *
+ * // Subscribe to changes
+ * const unsubscribe = CommandRegistry.onChange((added, removed) => {
+ *   console.log('Commands changed:', { added, removed });
+ * });
+ * ```
+ */
+import type { Action, ActionFilter, CommandEntry, CommandResult, InterfaceType } from "./types.js";
+/**
+ * Interceptor for command execution.
+ * Interceptors can modify, block, or wrap command execution.
+ *
+ * @remarks
+ * Interceptors run in priority order (lower priority runs first).
+ * Each interceptor must call `next()` to continue the chain.
+ *
+ * @example
+ * ```typescript
+ * CommandRegistry.addInterceptor({
+ *   name: 'confirm',
+ *   priority: 10,
+ *   intercept: async (command, args, next) => {
+ *     if (command.destructive) {
+ *       const confirmed = await showConfirm('Are you sure?');
+ *       if (!confirmed) return { success: false, error: { code: 'USER_CANCELLED', message: 'Cancelled' } };
+ *     }
+ *     return next();
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+export interface Interceptor {
+    /** Unique name for the interceptor (used for removal) */
+    name: string;
+    /** Priority order (lower runs first, default: 100) */
+    priority?: number;
+    /**
+     * Marks the interceptor as one that asks for user confirmation of destructive
+     * commands.
+     *
+     * @remarks
+     * Externally-originated invocations (see {@link CommandRegistryAPI.invoke}) of
+     * `destructive` commands fail closed with `CONFIRMATION_REQUIRED` unless an
+     * interceptor with this flag, or one named `confirm`, is installed.
+     */
+    confirms?: boolean;
+    /**
+     * Intercept the command execution.
+     * @param command - The command entry being executed
+     * @param args - Arguments passed to the command
+     * @param next - Call to continue to next interceptor or execute the command
+     * @returns The command result
+     */
+    intercept(command: CommandEntry, args: unknown[], next: () => Promise<CommandResult>): Promise<CommandResult>;
+}
+/**
+ * PostHook for observing command execution results.
+ * PostHooks run after command execution completes (success or failure).
+ *
+ * @remarks
+ * Unlike interceptors, post-hooks cannot modify the result.
+ * They are useful for:
+ * - Logging and analytics
+ * - Building undo stacks
+ * - Triggering side effects
+ *
+ * @example
+ * ```typescript
+ * CommandRegistry.addPostHook({
+ *   name: 'undo',
+ *   afterExecute: (command, args, result) => {
+ *     if (result.success && command.undoable) {
+ *       undoStack.push({ command, args, result });
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+export interface PostHook {
+    /** Unique name for the post-hook (used for removal) */
+    name: string;
+    /**
+     * Called after command execution completes.
+     * @param command - The command entry that was executed
+     * @param args - Arguments that were passed to the command
+     * @param result - The result of command execution
+     */
+    afterExecute(command: CommandEntry, args: unknown[], result: CommandResult): void;
+}
+/**
+ * Listener function signature for command registry changes.
+ * @param added - Array of newly registered command IDs
+ * @param removed - Array of unregistered command IDs
+ * @public
+ */
+export type CommandListener = (added: string[], removed: string[]) => void;
+/**
+ * Telemetry handler function signature.
+ * @param event - Event name (e.g., "command.registered", "command.executed")
+ * @param data - Event data
+ * @public
+ */
+export type TelemetryHandler = (event: string, data: Record<string, unknown>) => void;
+/**
+ * Describes who is invoking a command from outside the component's own code.
+ * @public
+ */
+export interface InvokeOptions {
+    /**
+     * The interface the invocation arrives through (`agent`, `mcp`, `cli` or
+     * `palette`). The command's `expose` configuration must enable it.
+     */
+    origin: InterfaceType;
+}
+/**
+ * Public contract for the global command registry.
+ * @public
+ */
+export interface CommandRegistryAPI {
+    register(id: string, command: CommandEntry): void;
+    unregister(id: string, expected?: CommandEntry): void;
+    get(id: string): CommandEntry | undefined;
+    execute(id: string, ...args: unknown[]): Promise<CommandResult>;
+    invoke(id: string, args: unknown[], options: InvokeOptions): Promise<CommandResult>;
+    enableEventBridge(): () => void;
+    getActions(filter?: ActionFilter): Action[];
+    onChange(listener: CommandListener): () => void;
+    clear(): void;
+    forScope(shadowRoot: ShadowRoot): CommandRegistryAPI;
+    setTelemetryHandler(handler?: TelemetryHandler): void;
+    addInterceptor(interceptor: Interceptor): void;
+    removeInterceptor(name: string): void;
+    addPostHook(hook: PostHook): void;
+    removePostHook(name: string): void;
+}
+/**
+ * Global CommandRegistry singleton.
+ *
+ * @remarks
+ * The CommandRegistry is the central hub for command management.
+ * Commands are registered automatically when FASTElement components
+ * with \@command decorators connect to the DOM.
+ *
+ * Key features:
+ * - SSR-safe with lazy initialization
+ * - Reactive: subscribe to changes via onChange()
+ * - Command palette integration via getActions()
+ * - Telemetry hooks for analytics
+ *
+ * @example
+ * ```typescript
+ * import { CommandRegistry, success, failure } from '\@lushly-dev/fast-element/command.js';
+ *
+ * // Manual command registration (usually done automatically)
+ * CommandRegistry.register('custom.action', \{
+ *   id: 'custom.action',
+ *   label: 'Custom Action',
+ *   execute: () => success(\{ done: true \}),
+ *   canExecute: true,
+ *   when: true,
+ *   source: new WeakRef(document.body),
+ * \});
+ *
+ * // Execute command
+ * const result = await CommandRegistry.execute('custom.action');
+ *
+ * // Command palette integration
+ * const actions = CommandRegistry.getActions();
+ * ninjaKeys.data = actions;
+ * ```
+ *
+ * @public
+ */
+export declare const CommandRegistry: CommandRegistryAPI;

package/dist/dts/command/schema-validation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A small, dependency-free JSON Schema validator for command `parameters`.
+ *
+ * @remarks
+ * Deliberately limited to the keywords agents and command palettes actually
+ * rely on: `type`, `enum`, `const`, `required`, `properties`,
+ * `additionalProperties`, `items`, `minimum`/`maximum` (plus the numeric
+ * exclusive forms), `minLength`/`maxLength` and `minItems`/`maxItems`.
+ * Unknown keywords (including `pattern`, `$ref`, `oneOf`, ...) are ignored, so a
+ * schema that uses them is validated on a best-effort basis rather than rejected.
+ *
+ * @internal
+ */
+/**
+ * A single validation problem.
+ * @internal
+ */
+export interface SchemaIssue {
+    /** JSON-pointer-like location of the problem (e.g. `$.items[0].id`). */
+    path: string;
+    /** Human-readable description. */
+    message: string;
+}
+/**
+ * Validates a value against a (basic) JSON Schema.
+ * @param value - The value to validate.
+ * @param schema - The JSON Schema.
+ * @returns The list of problems; empty when the value is valid.
+ * @internal
+ */
+export declare function validateSchema(value: unknown, schema: Record<string, unknown>): SchemaIssue[];
+/**
+ * Validates the arguments of a command invocation against the command's
+ * `parameters` schema.
+ *
+ * @remarks
+ * Command arguments are positional (`execute(...args)`), but the `parameters`
+ * schema describes a single structured argument, which is how every built-in
+ * command (and agent tool call) consumes input. The schema is therefore applied to
+ * `args[0]`. When no argument is supplied and the schema describes an object,
+ * an empty object is validated so `required` still fires.
+ *
+ * @internal
+ */
+export declare function validateCommandArguments(args: unknown[], schema: Record<string, unknown>): SchemaIssue[];