@cdevhub/ngx-tw 0.2.0

package/types/cdevhub-ngx-tw-command-palette.d.ts

@@ -0,0 +1,215 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, TemplateRef } from '@angular/core';
+import { TwSize } from '@cdevhub/ngx-tw/core';
+
+/** A single command palette entry. */
+interface CommandPaletteItem {
+    /** Stable identifier used as the DOM id and for selection payloads. */
+    id: string;
+    /** Visible label used for rendering and default filtering. */
+    label: string;
+    /** Additional search keywords that match the query but are not rendered. */
+    keywords?: readonly string[];
+    /** Group header name. Items sharing a group render under one section. */
+    group?: string;
+    /** Disabled items render but cannot be activated. */
+    disabled?: boolean;
+    /** Shortcut hint to render on the right edge. */
+    shortcut?: string | readonly string[];
+    /** Secondary description text rendered under the label. */
+    description?: string;
+    /** Optional icon name (consumers decide how to render). */
+    icon?: string;
+    /** Activation callback invoked before `itemSelected` is emitted. */
+    run?: () => void;
+}
+/** Filter signature. Receives the merged item list plus the current query; returns the filtered/reordered list. */
+type CommandPaletteFilterFn = (items: readonly CommandPaletteItem[], query: string) => readonly CommandPaletteItem[];
+/** Control handle exposed inside the palette overlay (for future component-based content). */
+interface CommandPaletteRef {
+    /** Closes the palette. */
+    close(): void;
+    /** Updates the search query programmatically. */
+    setQuery(query: string): void;
+}
+/** Injection token providing a `CommandPaletteRef` to palette overlay content. */
+declare const COMMAND_PALETTE_REF: InjectionToken<CommandPaletteRef>;
+
+/** Resolved item shape used internally — merges declarative directive refs with data entries. */
+interface ResolvedItem {
+    readonly data: CommandPaletteItem;
+    readonly directive?: CommandPaletteItemDirective;
+    readonly template?: TemplateRef<unknown>;
+    readonly shortcutKeys: readonly string[];
+}
+/** A rendered group in the filtered view. */
+interface ResolvedGroup {
+    readonly id: string;
+    readonly label?: string;
+    readonly items: readonly ResolvedItem[];
+}
+/** Optional explicit grouping wrapper. Items placed inside inherit its label. */
+declare class CommandPaletteGroupDirective {
+    /** Group heading text shown above the items. Required. */
+    readonly label: _angular_core.InputSignal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteGroupDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CommandPaletteGroupDirective, "[twCommandPaletteGroup]", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** A declarative palette item. Consumers project its rendered content as children. */
+declare class CommandPaletteItemDirective {
+    /** Stable identifier for the item. Used as DOM id and in selection payloads. Required. */
+    readonly id: _angular_core.InputSignal<string>;
+    /** Plain-text label used for filtering and default rendering. Defaults to `''`. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Additional search keywords that match the query but are not rendered. Defaults to `[]`. */
+    readonly keywords: _angular_core.InputSignal<readonly string[]>;
+    /** Explicit group name. Overrides any enclosing `twCommandPaletteGroup`. Defaults to `undefined`. */
+    readonly group: _angular_core.InputSignal<string | undefined>;
+    /** Whether the item is disabled. Disabled items render but cannot be activated. Defaults to `false`. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /** Keyboard shortcut hint. A string renders as one kbd; an array renders each key separately. Defaults to `undefined`. */
+    readonly shortcut: _angular_core.InputSignal<string | readonly string[] | undefined>;
+    /** Secondary description text rendered under the label. Defaults to `''`. */
+    readonly description: _angular_core.InputSignal<string>;
+    /** Callback run before `activated` emits. Defaults to `undefined`. */
+    readonly run: _angular_core.InputSignal<(() => void) | undefined>;
+    /** Fires when this specific item is activated (Enter or click). */
+    readonly activated: _angular_core.OutputEmitterRef<void>;
+    /** Projected template used by the palette overlay to render this item's content. */
+    readonly contentTemplate: Signal<TemplateRef<unknown> | undefined>;
+    private readonly parentGroup;
+    /** Resolved CommandPaletteItem data derived from inputs + parent group. */
+    readonly data: Signal<CommandPaletteItem>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteItemDirective, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CommandPaletteItemDirective, "tw-command-palette-item", never, { "id": { "alias": "id"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "keywords": { "alias": "keywords"; "required": false; "isSignal": true; }; "group": { "alias": "group"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "shortcut": { "alias": "shortcut"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "run": { "alias": "run"; "required": false; "isSignal": true; }; }, { "activated": "activated"; }, never, ["*"], true, never>;
+}
+/** Styles a leading icon inside a palette item. */
+declare class CommandPaletteItemIconDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteItemIconDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CommandPaletteItemIconDirective, "[twCommandPaletteItemIcon]", never, {}, {}, never, never, true, never>;
+}
+/** Styles secondary description text inside a palette item. */
+declare class CommandPaletteItemDescriptionDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteItemDescriptionDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CommandPaletteItemDescriptionDirective, "[twCommandPaletteItemDescription]", never, {}, {}, never, never, true, never>;
+}
+/** Structural directive — consumer template rendered when no items match the query. */
+declare class CommandPaletteEmptyDirective {
+    readonly template: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteEmptyDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CommandPaletteEmptyDirective, "[twCommandPaletteEmpty]", never, {}, {}, never, never, true, never>;
+}
+/** Structural directive — consumer template rendered as a sticky footer inside the palette. */
+declare class CommandPaletteFooterDirective {
+    readonly template: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteFooterDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CommandPaletteFooterDirective, "[twCommandPaletteFooter]", never, {}, {}, never, never, true, never>;
+}
+declare class CommandPaletteComponent {
+    /** Controls item density and padding across the palette. Defaults to `'md'`. */
+    readonly size: _angular_core.InputSignal<TwSize>;
+    /** Placeholder text shown inside the search input. Defaults to `'Type a command or search…'`. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Two-way bindable search query. Reads or resets the current filter. Defaults to `''`. */
+    readonly query: _angular_core.ModelSignal<string>;
+    /** Two-way bindable open state. Setting to `true` opens the palette; closing updates it to `false`. Defaults to `false`. */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    /** Data-driven command list. Merged with projected items and filtered by `query`. Defaults to `[]`. */
+    readonly commands: _angular_core.InputSignal<readonly CommandPaletteItem[]>;
+    /** Custom filter function. Receives the merged item list and current query, returns the filtered result. Defaults to `undefined` (case-insensitive substring match). */
+    readonly filterFn: _angular_core.InputSignal<CommandPaletteFilterFn | undefined>;
+    /** Whether the palette closes automatically after an item is activated. Defaults to `true` — a command palette is a fire-and-dismiss surface; the special case is a "run many" launcher that opts out. */
+    readonly closeOnSelect: _angular_core.InputSignal<boolean>;
+    /** Whether Escape closes the palette. Defaults to `true` — Escape is the universal dismiss key for modal surfaces; the special case is a non-dismissible palette. */
+    readonly closeOnEscape: _angular_core.InputSignal<boolean>;
+    /** Whether clicking the backdrop closes the palette. Defaults to `true` — clicking outside a modal is the expected dismiss gesture; the special case is enforcing an explicit choice. */
+    readonly closeOnBackdropClick: _angular_core.InputSignal<boolean>;
+    /** Whether the search input is auto-focused when the palette opens. Defaults to `true` — without auto-focus the user must click into the input before typing, defeating the keyboard-first design. */
+    readonly autoFocus: _angular_core.InputSignal<boolean>;
+    /** Accessible label used for the dialog role. Defaults to `'Command palette'`. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Accessible label applied to the search input (`role="combobox"`). Defaults to `'Search commands'`. */
+    readonly searchAriaLabel: _angular_core.InputSignal<string>;
+    /** Additional classes appended to the overlay panel for consumer customization. Defaults to `''`. */
+    readonly panelClass: _angular_core.InputSignal<string | string[]>;
+    /** Fires when a command is activated (via click or Enter). Payload is the resolved `CommandPaletteItem`. */
+    readonly itemSelected: _angular_core.OutputEmitterRef<CommandPaletteItem>;
+    /** Fires after the palette becomes fully visible. */
+    readonly opened: _angular_core.OutputEmitterRef<void>;
+    /** Fires after the palette is fully removed from the DOM. */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    private readonly overlay;
+    private readonly viewContainerRef;
+    private readonly injector;
+    private readonly destroyRef;
+    private readonly focusTrapFactory;
+    private readonly announcer;
+    private readonly declarativeItems;
+    private readonly emptyDirective;
+    private readonly footerDirective;
+    private overlayRef;
+    private overlayInstance;
+    private focusTrap;
+    private perOpenSubs;
+    private previousFocus;
+    private closing;
+    private closeTimer;
+    private announceTimer;
+    private readonly isAttached;
+    /** Merged (declarative + data-array) items keyed by id — declarative wins on collision. */
+    private readonly allItems;
+    /** Items after applying the filter function. */
+    readonly filteredItems: Signal<readonly ResolvedItem[]>;
+    /** Filtered items grouped by their `group` field. */
+    readonly grouped: Signal<readonly ResolvedGroup[]>;
+    /**
+     * Active item index, auto-resets to the first enabled item when the filtered
+     * *id set* changes. Keyed off the id sequence (not the array reference) so a
+     * re-emission of `filteredItems` with identical ids preserves the user's
+     * keyboard selection; only when ids actually shift do we recompute. When the
+     * previously-active id is still present in the new sequence its index is
+     * carried over; otherwise we fall back to the first enabled item.
+     */
+    readonly activeIndex: _angular_core.WritableSignal<number>;
+    /** Id of the currently active item (for `aria-activedescendant`). */
+    readonly activeItemId: Signal<string | null>;
+    /** Template-ref of the projected empty state (if any). */
+    readonly emptyTemplate: Signal<TemplateRef<{
+        $implicit: string;
+    }> | null>;
+    /** Template-ref of the projected footer (if any). */
+    readonly footerTemplate: Signal<TemplateRef<void> | null>;
+    /** Resolved panel-class string (array merged into a single string). */
+    readonly panelClassResolved: Signal<string>;
+    constructor();
+    /** Open the palette programmatically. */
+    show(): void;
+    /** Close the palette programmatically. */
+    hide(): void;
+    /** Toggle the current open state. */
+    toggle(): void;
+    /** Force the palette to reapply focus to the search input. */
+    focusSearch(): void;
+    /** Activate an item: run callbacks, emit events, optionally close. */
+    selectItem(item: ResolvedItem): void;
+    /** Move the active descendant to the given item (used on hover). */
+    setActiveItem(item: ResolvedItem): void;
+    private openPalette;
+    private closePalette;
+    private ensureOverlay;
+    private attachContent;
+    private subscribePerOpen;
+    private handleOverlayKeydown;
+    private moveActive;
+    private activateActive;
+    private setupFocusTrap;
+    private destroyFocusTrap;
+    private disposeOverlay;
+    private clearCloseTimer;
+    private clearAnnounceTimer;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CommandPaletteComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CommandPaletteComponent, "tw-command-palette", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "query": { "alias": "query"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; "commands": { "alias": "commands"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "closeOnBackdropClick": { "alias": "closeOnBackdropClick"; "required": false; "isSignal": true; }; "autoFocus": { "alias": "autoFocus"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "searchAriaLabel": { "alias": "searchAriaLabel"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; }, { "query": "queryChange"; "open": "openChange"; "itemSelected": "itemSelected"; "opened": "opened"; "closed": "closed"; }, ["declarativeItems", "emptyDirective", "footerDirective"], ["*"], true, never>;
+}
+
+export { COMMAND_PALETTE_REF, CommandPaletteComponent, CommandPaletteEmptyDirective, CommandPaletteFooterDirective, CommandPaletteGroupDirective, CommandPaletteItemDescriptionDirective, CommandPaletteItemDirective, CommandPaletteItemIconDirective };
+export type { CommandPaletteFilterFn, CommandPaletteItem, CommandPaletteRef };