@flxgde/gigamenu 0.2.0 → 0.5.0

package/types/flxgde-gigamenu.d.ts

@@ -1,8 +1,23 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { Router, Routes } from '@angular/router';
+import * as _flxgde_gigamenu from '@flxgde/gigamenu';
 
 type GigamenuItemCategory = 'page' | 'command';
+/**
+ * Autocomplete option for parameter suggestions.
+ * label: Display text shown in the autocomplete dropdown
+ * value: Actual value that gets passed to the action
+ */
+interface AutocompleteOption {
+    label: string;
+    value: string;
+}
+/**
+ * Provider for autocomplete suggestions.
+ * Can be either a static array of options or an async function that returns options.
+ */
+type ParamProvider = AutocompleteOption[] | ((query: string) => Promise<AutocompleteOption[]> | AutocompleteOption[]);
 interface GigamenuItem {
     id: string;
     label: string;
@@ -17,6 +32,39 @@ interface GigamenuItem {
     action: (args?: string) => void;
     /** Required parameter names for this item (e.g., ['id', 'commentId']) */
     params?: string[];
+    /**
+     * Autocomplete providers for parameters.
+     * Key: parameter name (must match a name in params array)
+     * Value: ParamProvider (static array or async function)
+     */
+    paramProviders?: Record<string, ParamProvider>;
+    /**
+     * Optional section/group label. Items supplied by dynamic providers typically
+     * set this so the UI can render them under a heading (e.g. "Recipes").
+     */
+    group?: string;
+    /** Provider id when produced by a dynamic provider. Set automatically. */
+    providerId?: string;
+}
+/**
+ * A dynamic provider returns items that depend on the current query, e.g. results
+ * fetched from a server. Returned items skip the built-in fuzzy filter.
+ */
+type GigamenuProvider = (query: string) => Promise<GigamenuProviderItem[]> | GigamenuProviderItem[];
+/**
+ * Items returned from a provider. Same shape as GigamenuItem but `category` is
+ * optional — it defaults to 'command'. Providers typically omit it.
+ */
+type GigamenuProviderItem = Omit<GigamenuItem, 'category'> & {
+    category?: GigamenuItemCategory;
+};
+interface GigamenuProviderOptions {
+    /** Minimum query length before the provider is invoked. Default: 2. */
+    minQueryLength?: number;
+    /** Debounce window in ms before invoking the provider. Default: 200. */
+    debounceMs?: number;
+    /** Optional group label applied to all items from this provider. */
+    group?: string;
 }
 /** Colors for parameter highlighting */
 declare const PARAM_COLORS: readonly ["text-blue-500 dark:text-blue-400", "text-green-500 dark:text-green-400", "text-orange-500 dark:text-orange-400", "text-pink-500 dark:text-pink-400", "text-cyan-500 dark:text-cyan-400"];
@@ -32,6 +80,12 @@ interface GigamenuConfig {
     autoDiscoverRoutes?: boolean;
     /** Separator between search query and arguments (default: ' ') */
     argSeparator?: string;
+    /** CSS class name for dark mode (default: 'dark') */
+    darkModeClass?: string;
+    /** Tab behavior for autocomplete: 'cycle' always cycles, 'accept-first' accepts on first tab (default: 'cycle') */
+    autocompleteTabBehavior?: 'cycle' | 'accept-first';
+    /** When to dismiss autocomplete overlay: 'on-type' hides on any keystroke, 'manual' only on Escape/selection (default: 'on-type') */
+    autocompleteDismiss?: 'on-type' | 'manual';
 }
 declare const DEFAULT_CONFIG: GigamenuConfig;
 /**
@@ -89,12 +143,18 @@ interface DiscoverRoutesOptions {
     map?: RouteMapper;
 }
 
+interface RegisteredProvider {
+    provider: GigamenuProvider;
+    options: Required<GigamenuProviderOptions>;
+}
 declare class GigamenuService {
     private _router?;
     private readonly _items;
+    private readonly _providers;
     private readonly _isOpen;
     private readonly _config;
     readonly items: _angular_core.Signal<GigamenuItem[]>;
+    readonly providers: _angular_core.Signal<Map<string, RegisteredProvider>>;
     readonly isOpen: _angular_core.Signal<boolean>;
     readonly config: _angular_core.Signal<GigamenuConfig>;
     /**
@@ -106,8 +166,16 @@ declare class GigamenuService {
     open(): void;
     close(): void;
     toggle(): void;
+    toggleDarkMode(): void;
     registerItem(item: GigamenuItem): void;
     unregisterItem(id: string): void;
+    /**
+     * Register a dynamic item provider. The provider is invoked when the user
+     * types in the menu (in action-selection mode) and its results are merged
+     * into the displayed items alongside statically registered items.
+     */
+    registerProvider(id: string, provider: GigamenuProvider, options?: GigamenuProviderOptions): void;
+    unregisterProvider(id: string): void;
     registerCommand(command: GigamenuCommand): void;
     registerPage(page: GigamenuPage): void;
     private extractParamNames;
@@ -168,20 +236,26 @@ interface GigamenuEmptyContext {
  * Context provided to the header template.
  */
 interface GigamenuHeaderContext {
-    /** The current full query */
+    /** The current query value */
     $implicit: string;
-    /** The search term (before separator) */
-    searchTerm: string;
-    /** The arguments (after separator) */
-    args: string;
-    /** Whether the query contains a separator */
-    hasSeparator: boolean;
+    /** The current query value */
+    query: string;
+    /** The locked action (if in parameter mode) */
+    lockedAction: GigamenuItem | null;
+    /** Array of filled parameter values */
+    paramValues: string[];
+    /** Name of the current parameter being edited */
+    currentParamName: string | null;
+    /** Placeholder text */
+    placeholder: string;
     /** Callback to update the query */
     onQueryChange: (value: string) => void;
     /** Callback for keydown events */
     onKeydown: (event: KeyboardEvent) => void;
-    /** Placeholder text */
-    placeholder: string;
+    /** Callback to unlock the action (go back to action selection) */
+    onUnlockAction: () => void;
+    /** Callback to go back to a specific parameter */
+    onGoToParam: (index: number) => void;
 }
 /**
  * Context provided to the footer template.
@@ -278,28 +352,28 @@ declare class GigamenuFooterTemplate {
  * ```
  */
 interface GigamenuPanelContext {
-    /** Filtered items to display */
+    /** Items to display (actions or autocomplete suggestions) */
     $implicit: GigamenuItem[];
-    /** Current full query */
+    /** Items to display (actions or autocomplete suggestions) */
+    items: GigamenuItem[];
+    /** Current query value */
     query: string;
-    /** The search term (before separator) */
-    searchTerm: string;
-    /** The arguments (after separator) */
-    args: string;
-    /** Whether the query contains a separator */
-    hasSeparator: boolean;
+    /** The locked action (if in parameter mode) */
+    lockedAction: GigamenuItem | null;
+    /** Array of filled parameter values */
+    paramValues: string[];
     /** Currently selected index */
     selectedIndex: number;
-    /** Callback to execute an item */
-    executeItem: (item: GigamenuItem) => void;
+    /** Placeholder text from config */
+    placeholder: string;
+    /** Callback when item is clicked */
+    onItemClick: (item: GigamenuItem, index: number) => void;
     /** Callback to update selection */
-    setSelectedIndex: (index: number) => void;
+    onSelectIndex: (index: number) => void;
     /** Callback to update query */
-    setQuery: (query: string) => void;
+    onQueryChange: (query: string) => void;
     /** Callback to close the menu */
-    close: () => void;
-    /** Placeholder text from config */
-    placeholder: string;
+    onClose: () => void;
 }
 declare class GigamenuPanelTemplate {
     readonly template: TemplateRef<GigamenuPanelContext>;
@@ -307,6 +381,24 @@ declare class GigamenuPanelTemplate {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GigamenuPanelTemplate, "[gmPanel]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Represents the different states of the gigamenu input.
+ * New paradigm: input handles ONE thing at a time.
+ */
+declare enum InputState {
+    /** Menu is closed */
+    Closed = "closed",
+    /** User is searching/selecting an action (page or command) */
+    ActionSelection = "actionSelection",
+    /** User is inputting a parameter value */
+    ParameterInput = "parameterInput"
+}
+
+/**
+ * Get color class for a parameter index.
+ */
+declare function getParamColor(index: number): string;
+
 declare class GigamenuComponent {
     protected readonly service: GigamenuService;
     private readonly frecency;
@@ -320,40 +412,75 @@ declare class GigamenuComponent {
     protected readonly panelTemplate: _angular_core.Signal<GigamenuPanelTemplate>;
     protected readonly query: _angular_core.WritableSignal<string>;
     protected readonly selectedIndex: _angular_core.WritableSignal<number>;
-    /** Parsed search term (before first separator) */
-    protected readonly searchTerm: _angular_core.Signal<string>;
-    /** Parsed arguments (after first separator) */
-    protected readonly args: _angular_core.Signal<string>;
-    /** Whether the query contains a separator (for display purposes) */
-    protected readonly hasSeparator: _angular_core.Signal<boolean>;
-    /** Parsed arguments as array */
-    protected readonly argsArray: _angular_core.Signal<string[]>;
-    /** Currently selected item */
+    protected readonly lockedAction: _angular_core.WritableSignal<GigamenuItem>;
+    protected readonly paramValues: _angular_core.WritableSignal<string[]>;
+    protected readonly autocompleteSuggestions: _angular_core.WritableSignal<AutocompleteOption[]>;
+    private autocompleteCache;
+    private readonly selectedParamOptions;
+    private readonly providerResults;
+    private providerTimers;
+    private providerGeneration;
+    private readonly queryParser;
     protected readonly selectedItem: _angular_core.Signal<GigamenuItem>;
-    /** Whether the selected item can be executed (has all required params) */
-    protected readonly canExecute: _angular_core.Signal<boolean>;
-    /** Get color class for a parameter index */
-    protected getParamColor(index: number): string;
+    protected readonly currentParamIndex: _angular_core.Signal<number>;
+    protected readonly currentParamName: _angular_core.Signal<string>;
+    protected readonly hasAutocomplete: _angular_core.Signal<boolean>;
+    protected readonly currentState: _angular_core.Signal<InputState>;
     protected readonly filteredItems: _angular_core.Signal<GigamenuItem[]>;
+    protected readonly displayItems: _angular_core.Signal<GigamenuItem[]>;
+    protected getParamColor: typeof getParamColor;
     constructor(service: GigamenuService, frecency: FrecencyService, platformId: object);
     onGlobalKeydown(event: KeyboardEvent): void;
     protected onInputKeydown(event: KeyboardEvent): void;
-    private scrollSelectedIntoView;
+    private getActionsForState;
+    private dispatchAction;
     protected onQueryChange(event: Event): void;
     protected onBackdropClick(event: MouseEvent): void;
-    protected executeItem(item: GigamenuItem): void;
-    protected getItemContext(item: GigamenuItem, index: number): GigamenuItemContext;
-    protected getEmptyContext(): GigamenuEmptyContext;
-    protected getHeaderContext(): GigamenuHeaderContext;
-    protected getFooterContext(): GigamenuFooterContext;
-    protected getPanelContext(): GigamenuPanelContext;
+    protected onItemClick(item: GigamenuItem, index: number): void;
+    private executeItemWithArgs;
+    private selectSuggestion;
+    /**
+     * Build args array using values from selectedParamOptions when available.
+     * For each param, if a suggestion was selected, use its value; otherwise use the typed text.
+     */
+    private buildArgsWithValues;
+    protected getItemContext(item: GigamenuItem, index: number): _flxgde_gigamenu.GigamenuItemContext;
+    protected getEmptyContext(): _flxgde_gigamenu.GigamenuEmptyContext;
+    protected getFooterContext(): _flxgde_gigamenu.GigamenuFooterContext;
+    protected getHeaderContext(): {
+        $implicit: string;
+        query: string;
+        lockedAction: GigamenuItem;
+        paramValues: string[];
+        currentParamName: string;
+        placeholder: string;
+        onQueryChange: (value: string) => void;
+        onKeydown: (event: KeyboardEvent) => void;
+        onUnlockAction: () => void;
+        onGoToParam: (index: number) => void;
+    };
+    protected getPanelContext(): {
+        $implicit: GigamenuItem[];
+        items: GigamenuItem[];
+        query: string;
+        lockedAction: GigamenuItem;
+        paramValues: string[];
+        selectedIndex: number;
+        placeholder: string;
+        onItemClick: (item: GigamenuItem, index: number) => void;
+        onSelectIndex: (index: number) => void;
+        onQueryChange: (query: string) => void;
+        onClose: () => void;
+    };
+    private fetchSuggestions;
     private close;
-    private sortByFrecency;
-    private matchesQuery;
-    private isInputFocused;
+    private clearProviderResults;
+    private normalizeProviderItems;
+    protected unlockActionFromUI(): void;
+    protected goToParam(index: number): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GigamenuComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<GigamenuComponent, "gm-gigamenu", never, {}, {}, ["itemTemplate", "emptyTemplate", "headerTemplate", "footerTemplate", "panelTemplate"], never, true, never>;
 }
 
 export { DEFAULT_CONFIG, FrecencyService, GigamenuComponent, GigamenuEmptyTemplate, GigamenuFooterTemplate, GigamenuHeaderTemplate, GigamenuItemTemplate, GigamenuPanelTemplate, GigamenuService, PARAM_COLORS, defineCommand };
-export type { CommandDefinition, DiscoverRoutesOptions, GigamenuCommand, GigamenuConfig, GigamenuEmptyContext, GigamenuFooterContext, GigamenuHeaderContext, GigamenuItem, GigamenuItemCategory, GigamenuItemContext, GigamenuPage, GigamenuPanelContext, MappedPage, RouteFilter, RouteInfo, RouteMapper };
+export type { AutocompleteOption, CommandDefinition, DiscoverRoutesOptions, GigamenuCommand, GigamenuConfig, GigamenuEmptyContext, GigamenuFooterContext, GigamenuHeaderContext, GigamenuItem, GigamenuItemCategory, GigamenuItemContext, GigamenuPage, GigamenuPanelContext, GigamenuProvider, GigamenuProviderItem, GigamenuProviderOptions, MappedPage, ParamProvider, RouteFilter, RouteInfo, RouteMapper };