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

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

@@ -0,0 +1,332 @@
+/**
+ * Type definitions for the `command` decorator system.
+ * Enables AI agents to interact with FASTElement components through structured commands.
+ *
+ * @remarks
+ * This module contains types only - no runtime code.
+ * Re-exports AFD core types for ecosystem alignment.
+ * FAST-AF is an "agent runtime for Web Components".
+ */
+/**
+ * Metadata attached to command results for tracing and analytics.
+ * @public
+ */
+export interface ResultMetadata {
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Trace ID for distributed tracing */
+    traceId?: string;
+    /** Additional custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Structured error information for failed commands.
+ * @public
+ */
+export interface CommandError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Suggestion for how to resolve the error */
+    suggestion?: string;
+    /** Whether the operation can be retried */
+    retryable?: boolean;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Result type for command execution.
+ * Discriminated union based on success field.
+ * @public
+ */
+export type CommandResult<T = unknown> = {
+    success: true;
+    data: T;
+    metadata?: ResultMetadata;
+} | {
+    success: false;
+    error: CommandError;
+    metadata?: ResultMetadata;
+};
+/**
+ * Standard error codes for command failures.
+ * @public
+ */
+export declare const ErrorCodes: {
+    /** Command ID not found in registry */
+    readonly COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND";
+    /** Command is currently disabled */
+    readonly COMMAND_DISABLED: "COMMAND_DISABLED";
+    /** Command is not exposed to the interface that invoked it */
+    readonly COMMAND_NOT_EXPOSED: "COMMAND_NOT_EXPOSED";
+    /** Invalid parameters provided */
+    readonly INVALID_PARAMETERS: "INVALID_PARAMETERS";
+    /** Destructive command requires confirmation but no confirmation handler is installed */
+    readonly CONFIRMATION_REQUIRED: "CONFIRMATION_REQUIRED";
+    /** Command execution failed */
+    readonly EXECUTION_FAILED: "EXECUTION_FAILED";
+    /** Operation timed out */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Generic internal error */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+/**
+ * Create a successful command result.
+ * @param data - The result data
+ * @param metadata - Optional metadata
+ * @public
+ */
+export declare function success<T>(data: T, metadata?: ResultMetadata): CommandResult<T>;
+/**
+ * Create a failed command result.
+ * @param error - The error information
+ * @param metadata - Optional metadata
+ * @public
+ */
+export declare function failure(error: CommandError, metadata?: ResultMetadata): CommandResult<never>;
+/**
+ * Type guard for successful results.
+ * @param result - The result to check
+ * @public
+ */
+export declare function isSuccess<T>(result: CommandResult<T>): result is {
+    success: true;
+    data: T;
+    metadata?: ResultMetadata;
+};
+/**
+ * Type guard for failed results.
+ * @param result - The result to check
+ * @public
+ */
+export declare function isFailure<T>(result: CommandResult<T>): result is {
+    success: false;
+    error: CommandError;
+    metadata?: ResultMetadata;
+};
+/**
+ * Create a CommandError object.
+ * @param code - Error code
+ * @param message - Error message
+ * @param options - Additional error options
+ * @public
+ */
+export declare function createError(code: string, message: string, options?: Omit<CommandError, "code" | "message">): CommandError;
+/**
+ * Namespace-prefixed command ID.
+ * TypeScript template literal enforces at compile time.
+ *
+ * @remarks
+ * Commands must include a namespace prefix to avoid collisions.
+ * Format: "namespace.action" or "\@scope/namespace.action"
+ *
+ * @example
+ * ```typescript
+ * // Valid IDs:
+ * const id1: CommandId = "editor.save";
+ * const id2: CommandId = "app.settings.toggle";
+ * const id3: CommandId = "@myorg/editor.format";
+ *
+ * // Invalid (compile error):
+ * const bad: CommandId = "save"; // Missing namespace
+ * ```
+ *
+ * @public
+ */
+export type CommandId = `${string}.${string}` | `@${string}/${string}.${string}`;
+/**
+ * JSONSchema type for parameter validation.
+ * Flexible until formal JSON Schema type is added.
+ *
+ * @public
+ */
+export type JSONSchema = Record<string, unknown>;
+/**
+ * Decorator metadata stored via createMetadataLocator.
+ * Represents the compile-time configuration of a command.
+ *
+ * @public
+ */
+export interface CommandMetadata {
+    /** Namespace-prefixed command identifier */
+    id: CommandId;
+    /** Name of the decorated method on the component class */
+    methodName: string;
+    /** Human-readable label for UI display */
+    label?: string;
+    /** Icon identifier (e.g., "save", "fluent:save-24-regular") */
+    icon?: string;
+    /** Extended description for command palettes and documentation */
+    description?: string;
+    /** Grouping category for organization in UI */
+    category?: string;
+    /** Keyboard shortcut (e.g., "Ctrl+S", "Cmd+Shift+P") */
+    keybinding?: string;
+    /** JSON Schema for runtime parameter validation */
+    parameters?: JSONSchema;
+    /** Context expression for conditional visibility (e.g., "editorFocus") */
+    when?: string;
+    /** If true, command is registered but hidden from UI */
+    hidden?: boolean;
+    /** If true, command requires user confirmation before execution */
+    destructive?: boolean;
+    /** Custom confirmation prompt (default: "Are you sure?") */
+    confirmPrompt?: string;
+    /** Interface exposure configuration */
+    expose?: ExposeConfig;
+}
+/**
+ * Options passed to the `command` decorator.
+ * All fields except id are optional.
+ *
+ * @public
+ */
+export interface CommandOptions {
+    /** Human-readable label for UI display */
+    label?: string;
+    /** Icon identifier (e.g., "save", "fluent:save-24-regular") */
+    icon?: string;
+    /** Extended description for command palettes and documentation */
+    description?: string;
+    /** Grouping category for organization in UI */
+    category?: string;
+    /** Keyboard shortcut (e.g., "Ctrl+S", "Cmd+Shift+P") */
+    keybinding?: string;
+    /** JSON Schema for runtime parameter validation */
+    parameters?: JSONSchema;
+    /** Context expression for conditional visibility (e.g., "editorFocus") */
+    when?: string;
+    /** If true, command is registered but hidden from UI */
+    hidden?: boolean;
+    /** If true, command requires user confirmation before execution */
+    destructive?: boolean;
+    /** Custom confirmation prompt (default: "Are you sure?") */
+    confirmPrompt?: string;
+    /** Interface exposure configuration */
+    expose?: ExposeConfig;
+}
+/**
+ * Runtime command entry in the CommandRegistry.
+ * Uses AFD's CommandResult for full ecosystem alignment.
+ *
+ * @remarks
+ * Created at connect-time by CommandBehavior from CommandMetadata.
+ * The source WeakRef allows garbage collection of disconnected elements.
+ *
+ * @public
+ */
+export interface CommandEntry {
+    /** Namespace-prefixed command identifier */
+    id: CommandId;
+    /**
+     * Name of the method on the source element that implements the command.
+     * Set by CommandBehavior; used for conventions such as `${methodName}Undo()`.
+     */
+    methodName?: string;
+    /** Human-readable label for UI display */
+    label: string;
+    /** Icon identifier (e.g., "save", "fluent:save-24-regular") */
+    icon?: string;
+    /** Extended description for command palettes and documentation */
+    description?: string;
+    /** Grouping category for organization in UI */
+    category?: string;
+    /** Keyboard shortcut (e.g., "Ctrl+S", "Cmd+Shift+P") */
+    keybinding?: string;
+    /** JSON Schema for runtime parameter validation */
+    parameters?: JSONSchema;
+    /** If true, command stays registered and executable but is omitted from `getActions()` */
+    hidden?: boolean;
+    /** If true, command requires user confirmation before execution */
+    destructive?: boolean;
+    /** Custom confirmation prompt (default: "Are you sure?") */
+    confirmPrompt?: string;
+    /** Interface exposure configuration */
+    expose?: ExposeConfig;
+    /**
+     * Execute the command with optional arguments.
+     * Returns AFD CommandResult for consistent error handling.
+     */
+    execute: (...args: unknown[]) => CommandResult | Promise<CommandResult>;
+    /**
+     * Whether the command can currently be executed.
+     * Reactive via Observable.track() on the source element.
+     */
+    readonly canExecute: boolean;
+    /**
+     * Whether the command should be visible in UI.
+     * Reactive via Observable.track() on the source element.
+     */
+    readonly when: boolean;
+    /**
+     * WeakRef to the source element.
+     * Allows garbage collection of disconnected elements.
+     */
+    source: {
+        deref(): HTMLElement | undefined;
+    };
+}
+/**
+ * Action format for command palette integration.
+ * Compatible with ninja-keys and similar libraries.
+ *
+ * @public
+ */
+export interface Action {
+    /** Unique action identifier */
+    id: string;
+    /** Display title for the action */
+    title: string;
+    /** Icon identifier */
+    icon?: string;
+    /** Section/category for grouping */
+    section?: string;
+    /** Keyboard shortcut string */
+    hotkey?: string;
+    /** Whether the action is currently disabled */
+    disabled?: boolean;
+    /** Handler function to execute the action */
+    handler: () => void;
+}
+/**
+ * Interface types for command exposure filtering.
+ * @public
+ */
+export type InterfaceType = "palette" | "agent" | "mcp" | "cli";
+/**
+ * Configuration for which interfaces a command is exposed to.
+ * Secure defaults: palette and agent are opt-out, mcp and cli are opt-in.
+ *
+ * @remarks
+ * - palette: Command palette UI (ninja-keys, etc.)
+ * - agent: AI agents interacting with the component
+ * - mcp: Model Context Protocol servers
+ * - cli: Command-line interface tools
+ *
+ * @public
+ */
+export interface ExposeConfig {
+    /** Expose to command palette UI (default: true) */
+    palette?: boolean;
+    /** Expose to AI agents (default: true) */
+    agent?: boolean;
+    /** Expose to MCP servers (default: false - opt-in for security) */
+    mcp?: boolean;
+    /** Expose to CLI tools (default: false - opt-in for security) */
+    cli?: boolean;
+}
+/**
+ * Default expose configuration.
+ * Secure defaults: palette and agent are enabled, mcp and cli require opt-in.
+ * @public
+ */
+export declare const DEFAULT_EXPOSE_CONFIG: Required<ExposeConfig>;
+/**
+ * Filter options for getActions().
+ * @public
+ */
+export interface ActionFilter {
+    /** Filter by interface type */
+    interface?: InterfaceType;
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Validation commands for FAST elements.
+ * Provides linting and accessibility auditing capabilities.
+ *
+ * @remarks
+ * Task 10: Implements fast.lint.check for code validation against FAST best practices.
+ * Task 11: Implements fast.a11y.audit for accessibility auditing.
+ */
+/**
+ * Severity level for lint issues.
+ * @public
+ */
+export type LintSeverity = "error" | "warning" | "info";
+/**
+ * A single lint issue found in code.
+ * @public
+ */
+export interface LintIssue {
+    /** Rule ID that triggered the issue */
+    rule: string;
+    /** Issue severity */
+    severity: LintSeverity;
+    /** Human-readable message describing the issue */
+    message: string;
+    /** Line number where the issue occurs (1-indexed) */
+    line: number;
+    /** Column number where the issue occurs (1-indexed) */
+    column: number;
+    /** Suggested fix for the issue */
+    fix?: string;
+    /** Confidence level for the suggested fix (0-1) */
+    fixConfidence?: number;
+}
+/**
+ * Issue counts by severity level.
+ * @public
+ */
+export interface LintCounts {
+    error: number;
+    warning: number;
+    info: number;
+}
+/**
+ * A plan step for fixing a lint issue.
+ * @public
+ */
+export interface LintPlanStep {
+    /** Step number (1-indexed) */
+    step: number;
+    /** Action to take to fix the issue */
+    action: string;
+    /** Confidence level for this fix (0-1) */
+    confidence: number;
+}
+/**
+ * Result of a lint check operation.
+ * @public
+ */
+export interface LintResult {
+    /** Array of lint issues found */
+    issues: LintIssue[];
+    /** Issue counts by severity */
+    counts: LintCounts;
+}
+/**
+ * WCAG conformance level.
+ * @public
+ */
+export type WcagLevel = "A" | "AA" | "AAA";
+/**
+ * Impact severity for accessibility violations.
+ * @public
+ */
+export type A11yImpact = "minor" | "moderate" | "serious" | "critical";
+/**
+ * A single accessibility violation found during audit.
+ * @public
+ */
+export interface A11yViolation {
+    /** WCAG rule ID that was violated (e.g., "color-contrast", "aria-label") */
+    rule: string;
+    /** Impact severity of the violation */
+    impact: A11yImpact;
+    /** CSS selector identifying the violating element */
+    selector: string;
+    /** WCAG level this rule applies to */
+    wcagLevel: WcagLevel;
+    /** Human-readable description of the violation */
+    message: string;
+    /** WCAG success criterion reference (e.g., "1.4.3") */
+    wcagCriterion?: string;
+}
+/**
+ * Result of an accessibility audit operation.
+ * @public
+ */
+export interface A11yAuditResult {
+    /** Array of accessibility violations found */
+    violations: A11yViolation[];
+    /** WCAG level used for the audit */
+    level: WcagLevel;
+    /** Target element selector that was audited */
+    target: string;
+}
+/**
+ * Register fast.lint.* and fast.a11y.* commands with the CommandRegistry.
+ * Called during fast-element initialization.
+ *
+ * @remarks
+ * These commands provide code validation and accessibility auditing:
+ * - fast.lint.check: Validates code against FAST best practices
+ * - fast.a11y.audit: Runs WCAG accessibility audit on DOM elements
+ *
+ * @public
+ */
+export declare function registerValidationCommands(): void;

package/dist/dts/command/weak-ref.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal WeakRef surface used by command entries without requiring the
+ * ES2021.WeakRef TypeScript library in FAST Element's compilation target.
+ * @internal
+ */
+interface WeakReference<T extends object> {
+    deref(): T | undefined;
+}
+/** @internal */
+export declare function createWeakReference<T extends object>(target: T): WeakReference<T>;
+export {};

package/dist/dts/components/attributes.d.ts

@@ -0,0 +1,153 @@
+import { type Accessor } from "../observation/observable.js";
+/**
+ * Represents objects that can convert values to and from
+ * view or model representations.
+ * @public
+ */
+export interface ValueConverter {
+    /**
+     * Converts a value from its representation in the model, to a representation for the view.
+     * @param value - The value to convert to a view representation.
+     */
+    toView(value: any): any;
+    /**
+     * Converts a value from its representation in the view, to a representation for the model.
+     * @param value - The value to convert to a model representation.
+     */
+    fromView(value: any): any;
+}
+/**
+ * The mode that specifies the runtime behavior of the attribute.
+ * @remarks
+ * By default, attributes run in `reflect` mode, propagating their property
+ * values to the DOM and DOM values to the property. The `boolean` mode also
+ * reflects values, but uses the HTML standard boolean attribute behavior,
+ * interpreting the presence of the attribute as `true` and the absence as
+ * `false`. The `fromView` behavior only updates the  property value based on
+ * changes in the DOM, but does not reflect property changes back.
+ * @public
+ */
+export type AttributeMode = "reflect" | "boolean" | "fromView";
+/**
+ * Metadata used to configure a custom attribute's behavior.
+ * @public
+ */
+export type AttributeConfiguration = {
+    property: string;
+    attribute?: string;
+    mode?: AttributeMode;
+    converter?: ValueConverter;
+};
+/**
+ * Metadata used to configure a custom attribute's behavior.
+ * @public
+ */
+export declare const AttributeConfiguration: Readonly<{
+    /**
+     * Locates all attribute configurations associated with a type.
+     */
+    locate: (target: {}) => AttributeConfiguration[];
+}>;
+/**
+ * Metadata used to configure a custom attribute's behavior through a decorator.
+ * @public
+ */
+export type DecoratorAttributeConfiguration = Omit<AttributeConfiguration, "property">;
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values.
+ * @remarks
+ * Used automatically when the `boolean` {@link AttributeMode} is selected.
+ * @public
+ */
+export declare const booleanConverter: ValueConverter;
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values. `null`, `undefined`, `""`,
+ * and `void` values are converted to `null`.
+ * @public
+ */
+export declare const nullableBooleanConverter: ValueConverter;
+/**
+ * A {@link ValueConverter} that converts to and from `number` values.
+ * @remarks
+ * This converter allows for nullable numbers, returning `null` if the
+ * input was `null`, `undefined`, or `NaN`.
+ * @public
+ */
+export declare const nullableNumberConverter: ValueConverter;
+/**
+ * An implementation of {@link Accessor} that supports reactivity,
+ * change callbacks, attribute reflection, and type conversion for
+ * custom elements.
+ * @public
+ */
+export declare class AttributeDefinition implements Accessor {
+    private readonly fieldName;
+    private readonly callbackName;
+    private readonly hasCallback;
+    private readonly guards;
+    /**
+     * The class constructor that owns this attribute.
+     */
+    readonly Owner: Function;
+    /**
+     * The name of the property associated with the attribute.
+     */
+    readonly name: string;
+    /**
+     * The name of the attribute in HTML.
+     */
+    readonly attribute: string;
+    /**
+     * The {@link AttributeMode} that describes the behavior of this attribute.
+     */
+    readonly mode: AttributeMode;
+    /**
+     * A {@link ValueConverter} that integrates with the property getter/setter
+     * to convert values to and from a DOM string.
+     */
+    readonly converter?: ValueConverter;
+    /**
+     * Creates an instance of AttributeDefinition.
+     * @param Owner - The class constructor that owns this attribute.
+     * @param name - The name of the property associated with the attribute.
+     * @param attribute - The name of the attribute in HTML.
+     * @param mode - The {@link AttributeMode} that describes the behavior of this attribute.
+     * @param converter - A {@link ValueConverter} that integrates with the property getter/setter
+     * to convert values to and from a DOM string.
+     */
+    constructor(Owner: Function, name: string, attribute?: string, mode?: AttributeMode, converter?: ValueConverter);
+    /**
+     * Sets the value of the attribute/property on the source element.
+     * @param source - The source element to access.
+     * @param newValue - The value to set the attribute/property to.
+     */
+    setValue(source: HTMLElement, newValue: any): void;
+    /**
+     * Gets the value of the attribute/property on the source element.
+     * @param source - The source element to access.
+     */
+    getValue(source: HTMLElement): any;
+    /** @internal */
+    onAttributeChangedCallback(element: HTMLElement, value: any): void;
+    private tryReflectToAttribute;
+    /**
+     * Collects all attribute definitions associated with the owner.
+     * @param Owner - The class constructor to collect attribute for.
+     * @param attributeLists - Any existing attributes to collect and merge with those associated with the owner.
+     * @internal
+     */
+    static collect(Owner: Function, ...attributeLists: (ReadonlyArray<string | AttributeConfiguration> | undefined)[]): ReadonlyArray<AttributeDefinition>;
+}
+/**
+ * Decorator: Specifies an HTML attribute.
+ * @param config - The configuration for the attribute.
+ * @public
+ */
+export declare function attr(config?: DecoratorAttributeConfiguration): (target: {}, property: string) => void;
+/**
+ * Decorator:  Specifies an HTML attribute.
+ * @param target - The class to define the attribute on.
+ * @param prop - The property name to be associated with the attribute.
+ * @public
+ */
+export declare function attr(target: {}, prop: string): void;

package/dist/dts/components/definition-schema-transforms.d.ts

@@ -0,0 +1,9 @@
+import type { FASTElementDefinition } from "../components/fast-definitions.js";
+import type { Schema } from "./schema.js";
+export interface DeclarativeSchemaTransformContext {
+    definition: FASTElementDefinition;
+    schema: Schema;
+}
+export type DeclarativeSchemaTransform = (context: DeclarativeSchemaTransformContext) => void;
+export declare function setDefinitionSchemaTransform(definition: FASTElementDefinition, key: string, transform: DeclarativeSchemaTransform, priority: number): void;
+export declare function getDefinitionSchemaTransforms(definition?: FASTElementDefinition): readonly DeclarativeSchemaTransform[];