@tocdk-oss/ng-spotlight 0.0.0-stage → 21.0.1

package/types/tocdk-oss-ng-spotlight.d.ts

@@ -0,0 +1,416 @@
+import * as i0 from '@angular/core';
+import { Injector, Signal, EnvironmentProviders, InjectionToken, Type } from '@angular/core';
+import { Observable } from 'rxjs';
+import { Route, Routes } from '@angular/router';
+
+/** Visual tone of a badge. The renderer maps it to its own colours. */
+type SpotlightBadgeTone = 'info' | 'success' | 'warn' | 'danger';
+interface SpotlightBadge {
+    label: string;
+    tone?: SpotlightBadgeTone;
+}
+/** What happens when an item is selected. */
+type SpotlightAction = {
+    route: unknown[] | string;
+} | {
+    url: string;
+    newTab?: boolean;
+} | {
+    run: () => void | Promise<void>;
+};
+interface SpotlightItem {
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** The renderer decides the meaning (CSS class name, image URL, …). */
+    icon?: string;
+    group: string;
+    keywords?: string[];
+    badges?: SpotlightBadge[];
+    /** Shown on an empty query. */
+    suggested?: boolean;
+    /** Free payload for custom templates. */
+    data?: unknown;
+    action: SpotlightAction;
+    /** Reserved for nested pages (v1.x). Must be absent in v1: items that set it are dropped. */
+    children?: never;
+}
+/** An item as written for staticSource(): `group` falls back to the source's group. */
+type SpotlightItemInput = Omit<SpotlightItem, 'group'> & {
+    group?: string;
+};
+interface SpotlightGroup {
+    id: string;
+    label: string;
+    total?: number;
+    items: SpotlightItem[];
+}
+interface SpotlightResponse {
+    groups: SpotlightGroup[];
+}
+type SpotlightResult = SpotlightItem[] | SpotlightResponse;
+interface SpotlightContext {
+    /** Aborted when the next keystroke supersedes this search. */
+    signal: AbortSignal;
+    /** Group id of the active chip, or null for "All". */
+    chip: string | null;
+    /** Environment injector of the provideSpotlight() call that registered the source. */
+    injector: Injector;
+}
+interface SpotlightSource {
+    id: string;
+    /** Default group for items that do not set one. */
+    group?: string;
+    /** e.g. '#', '@'. When the query starts with it, only this source runs. */
+    prefix?: string;
+    /** Default 0 (httpSource: 2). */
+    minLength?: number;
+    /** Default 0 (httpSource: 150). */
+    debounceMs?: number;
+    /** Default 5000. */
+    timeoutMs?: number;
+    /** Group order; lower comes first. Default: registration order. */
+    priority?: number;
+    /** true: the library ranks and filters the results. false (default): keep the source's order. */
+    local?: boolean;
+    search(query: string, ctx: SpotlightContext): Observable<SpotlightResult> | Promise<SpotlightResult> | SpotlightResult;
+}
+type SpotlightTextValue = string | Signal<string> | Observable<string>;
+interface SpotlightTexts {
+    placeholder: SpotlightTextValue;
+    all: SpotlightTextValue;
+    recent: SpotlightTextValue;
+    noResults: SpotlightTextValue;
+    loading: SpotlightTextValue;
+    error: SpotlightTextValue;
+    retry: SpotlightTextValue;
+    /** Called inside a computed: reading signals here makes the announcement reactive. */
+    resultsAnnouncement: (count: number) => string;
+    hintNavigate: SpotlightTextValue;
+    hintOpen: SpotlightTextValue;
+    hintClose: SpotlightTextValue;
+}
+interface SpotlightHttpRequest {
+    method?: string;
+    params?: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
+    headers?: Record<string, string | string[]>;
+    body?: unknown;
+}
+interface SpotlightHttpOptions {
+    request?: (query: string, ctx: SpotlightContext) => SpotlightHttpRequest;
+    map?: (response: unknown, query: string) => SpotlightResult;
+}
+/** The serialisable subset of SpotlightAction. */
+type SpotlightStoredAction = {
+    route: unknown[] | string;
+} | {
+    url: string;
+    newTab?: boolean;
+};
+interface SpotlightRecentEntry {
+    id: string;
+    title: string;
+    group: string;
+    sourceId: string;
+    subtitle?: string;
+    icon?: string;
+    badges?: SpotlightBadge[];
+    /** Absent for run() items: those are resolved through their source by id. */
+    action?: SpotlightStoredAction;
+}
+interface SpotlightRecentStorage {
+    load(): Promise<SpotlightRecentEntry[]>;
+    save(items: SpotlightRecentEntry[]): Promise<void>;
+}
+/**
+ * Configuration of one provideSpotlight() call. `hotkeys`, `texts`, `recent`, `theme` and `onError`
+ * belong to the palette and are read only from the first call (the root or an `isolated` one); a
+ * non-isolated child call only adds its `sources` and `http` defaults.
+ */
+interface SpotlightConfig {
+    /** Default ['ctrl.space', 'mod.k']. 'mod' = Cmd on macOS, Ctrl elsewhere. */
+    hotkeys?: string[];
+    texts?: Partial<SpotlightTexts>;
+    recent?: {
+        max?: number;
+        storage?: SpotlightRecentStorage;
+    };
+    /** Global defaults for every httpSource registered by this call (inherited by child calls). */
+    http?: SpotlightHttpOptions;
+    theme?: 'default' | 'none';
+    onError?: (error: unknown, source: SpotlightSource) => void;
+    sources?: SpotlightSource[];
+    /** true: create a separate palette instead of adding sources to the parent injector's one. */
+    isolated?: boolean;
+}
+
+/**
+ * Recent items in localStorage under `ng-spotlight:recent:<key>`. Every access is wrapped
+ * in try/catch, so the palette still works when storage is blocked, full or corrupted.
+ */
+declare function localStorageRecent(key: string): SpotlightRecentStorage;
+
+interface StaticSourceOptions {
+    /** Default `static:<group>`. */
+    id?: string;
+    group: string;
+    items: SpotlightItemInput[];
+    prefix?: string;
+    priority?: number;
+}
+/** Fixed commands. Results are local: the library ranks and filters them. */
+declare function staticSource(options: StaticSourceOptions): SpotlightSource;
+
+interface RouteSourceOptions {
+    /** Default 'routes'. */
+    id?: string;
+    /** Default 'Pages'. */
+    group?: string;
+    prefix?: string;
+    priority?: number;
+    /** Return false to hide a route, e.g. to apply the app's role gates. */
+    filter?: (route: Route, url: string) => boolean;
+}
+/**
+ * Every labelled static route that is a page, including lazy children once loaded. A labelled
+ * parent that renders nothing at its own URL (no component, no empty-path child) is skipped;
+ * its labelled children still appear. A deeper route with the same URL (an empty-path child)
+ * wins over its parent. Results are local.
+ */
+declare function routeSource(options?: RouteSourceOptions): SpotlightSource;
+
+/** The shape of `route.data.spotlight` (or `false` to opt the route out). */
+interface SpotlightRouteData {
+    label?: string;
+    keywords?: string[];
+    suggested?: boolean;
+    /** Not used by the library; apps use it in their own nav-coverage tests. */
+    hiddenFromNav?: boolean;
+}
+
+interface SpotlightRouteAuditEntry {
+    path: string;
+    reason: 'missing-label';
+}
+interface SpotlightRouteAuditOptions {
+    /** Return true to skip a route. */
+    ignore?: (route: Route, url: string) => boolean;
+}
+/**
+ * Static pages that have no label (title, data.spotlight.label or data.breadcrumb) and are not
+ * opted out with data.spotlight: false. Synchronous: `loadChildren` is not followed, so pass
+ * lazy route arrays in directly. A page whose URL a labelled parent already covers passes.
+ *
+ *     expect(spotlightRouteAudit(adminRoutes)).toEqual([]);
+ */
+declare function spotlightRouteAudit(routes: Routes, options?: SpotlightRouteAuditOptions): SpotlightRouteAuditEntry[];
+
+interface HttpSourceOptions extends Partial<Omit<SpotlightSource, 'search'>>, SpotlightHttpOptions {
+    url: string;
+}
+/**
+ * Remote results in the server's order. Default request: GET {url}?q={query}[&chip={groupId}].
+ * Default response: SpotlightResponse or SpotlightItem[]. Per-source request/map win over
+ * provideSpotlight({ http }), which wins over the defaults.
+ */
+declare function httpSource(options: HttpSourceOptions): SpotlightSource;
+
+/**
+ * Sets up a palette. Call it once in the app config; call it again in a child injector (for
+ * example a lazy route's `providers`) to add sources there. A child call only contributes
+ * `sources` and `http` defaults: its `texts`, `hotkeys`, `recent`, `theme` and `onError` are
+ * ignored (dev mode warns), since the first call owns the palette. Pass `isolated: true` for a
+ * separate palette with its own settings. Pass a factory to build the config in an injection
+ * context, e.g. `provideSpotlight(() => ({ texts: { placeholder: inject(I18n).t$('Search…') } }))`.
+ */
+declare function provideSpotlight(config?: SpotlightConfig | (() => SpotlightConfig)): EnvironmentProviders;
+
+/**
+ * State and behaviour of one palette. Provided by provideSpotlight(); never providedIn root.
+ * Deliberately has no ngOnDestroy: a child injector re-provides the parent's instance and
+ * must not destroy it. Cleanup runs through the creating injector's DestroyRef.
+ */
+declare class SpotlightService {
+    private readonly document;
+    private readonly router;
+    private readonly regs;
+    private registrationOrder;
+    private configured;
+    /** Token of the select() whose action is still running; null when none is. */
+    private selecting;
+    /** Incremented on every open(), so a late action never closes a palette opened after it. */
+    private session;
+    private _settings;
+    private readonly _texts;
+    private readonly _isOpen;
+    readonly isOpen: i0.Signal<boolean>;
+    private readonly _query;
+    private readonly _chip;
+    private readonly _results;
+    private readonly _recent;
+    private readonly _resolvedRuns;
+    private readonly _activeKey;
+    private readonly _chipGroups;
+    private readonly selectedSubject;
+    readonly selected: Observable<SpotlightItem>;
+    private input$;
+    private readonly retry$;
+    private engine;
+    /** Group labels learned from answers; outlives the engine, which restarts on every open(). */
+    private readonly learnedGroups;
+    private readonly recentItems;
+    constructor();
+    open(query?: string): void;
+    close(): void;
+    private runAction;
+    private remember;
+    private loadRecent;
+    /** run() entries are stored without an action; look them up in their source by id. */
+    private resolveRunEntries;
+    private restartEngine;
+    private report;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SpotlightService>;
+}
+
+/** Context of the `input` part. The part must copy every ARIA field onto its <input>. */
+interface SpotlightInputContext {
+    id: string;
+    value: string;
+    placeholder: string;
+    label: string;
+    expanded: boolean;
+    controls: string;
+    activeDescendant: string | null;
+    onInput: (value: string) => void;
+    onKeydown: (event: KeyboardEvent) => void;
+}
+/** Context of the `chips` part (rendered once per chip, inside a host-owned <button>). */
+interface SpotlightChipContext {
+    label: string;
+    active: boolean;
+}
+interface SpotlightGroupHeaderContext {
+    label: string;
+    total: number | undefined;
+    loading: boolean;
+    /** Visually hidden text read after the label while loading; empty when the label already says it. */
+    loadingText: string;
+}
+/** Context of the `row` part (rendered inside a host-owned role="option" element). */
+interface SpotlightRowContext {
+    item: SpotlightItem;
+    active: boolean;
+    query: string;
+    /** The badge part to render badges with (NgComponentOutlet, input `ctx: SpotlightBadgeContext`). */
+    badge: Type<unknown>;
+}
+interface SpotlightBadgeContext {
+    badge: SpotlightBadge;
+}
+/**
+ * Markup for each part of the palette. Every component takes one `ctx` input with the
+ * part's context. Parts left out fall back to the core parts. `dialog` adds classes to the
+ * overlay pane and backdrop (the core always owns the CDK overlay itself).
+ */
+interface SpotlightRenderer {
+    dialog?: {
+        panelClass: string;
+        backdropClass?: string;
+    };
+    input?: Type<unknown>;
+    chips?: Type<unknown>;
+    groupHeader?: Type<unknown>;
+    row?: Type<unknown>;
+    badge?: Type<unknown>;
+}
+declare const SPOTLIGHT_RENDERER: InjectionToken<SpotlightRenderer>;
+
+declare class SpotlightDefaultInput {
+    readonly ctx: i0.InputSignal<SpotlightInputContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightDefaultInput, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightDefaultInput, "spotlight-default-input", never, { "ctx": { "alias": "ctx"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+declare class SpotlightDefaultChip {
+    readonly ctx: i0.InputSignal<SpotlightChipContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightDefaultChip, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightDefaultChip, "spotlight-default-chip", never, { "ctx": { "alias": "ctx"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+declare class SpotlightDefaultGroupHeader {
+    readonly ctx: i0.InputSignal<SpotlightGroupHeaderContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightDefaultGroupHeader, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightDefaultGroupHeader, "spotlight-default-group-header", never, { "ctx": { "alias": "ctx"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+declare class SpotlightDefaultBadge {
+    readonly ctx: i0.InputSignal<SpotlightBadgeContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightDefaultBadge, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightDefaultBadge, "spotlight-default-badge", never, { "ctx": { "alias": "ctx"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+declare class SpotlightDefaultRow {
+    readonly ctx: i0.InputSignal<SpotlightRowContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightDefaultRow, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightDefaultRow, "spotlight-default-row", never, { "ctx": { "alias": "ctx"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** The palette. Place it once in the app shell. */
+declare class SpotlightHost {
+    private readonly overlay;
+    private readonly focusTrapFactory;
+    private readonly breakpoints;
+    private readonly viewContainerRef;
+    private readonly injector;
+    private readonly document;
+    private readonly arbiter;
+    private readonly hotkeyClient;
+    private readonly panel;
+    private readonly itemTemplates;
+    private overlayRef;
+    private focusTrap;
+    private restoreFocus;
+    private readonly handleInput;
+    private readonly handleKeydown;
+    constructor();
+    private onInputKeydown;
+    private attach;
+    private detach;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightHost, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightHost, "spotlight-host", never, {}, {}, ["itemTemplates", "emptyTemplate", "footerTemplate"], never, true, never>;
+}
+
+interface SpotlightItemTemplateContext {
+    $implicit: SpotlightItem;
+    active: boolean;
+    query: string;
+}
+interface SpotlightEmptyTemplateContext {
+    /** The current query. */
+    $implicit: string;
+}
+/** `<ng-template spotlightItem="customers" let-item>`: row for one group; without a value: for every group. */
+declare class SpotlightItemTemplate {
+    readonly spotlightItem: i0.InputSignal<string>;
+    static ngTemplateContextGuard(_dir: SpotlightItemTemplate, _ctx: unknown): _ctx is SpotlightItemTemplateContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightItemTemplate, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SpotlightItemTemplate, "[spotlightItem]", never, { "spotlightItem": { "alias": "spotlightItem"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** `<ng-template spotlightEmpty let-query>`: shown when a non-empty query has no results. */
+declare class SpotlightEmptyTemplate {
+    static ngTemplateContextGuard(_dir: SpotlightEmptyTemplate, _ctx: unknown): _ctx is SpotlightEmptyTemplateContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightEmptyTemplate, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SpotlightEmptyTemplate, "[spotlightEmpty]", never, {}, {}, never, never, true, never>;
+}
+/** `<ng-template spotlightFooter>`: replaces the default key hints. */
+declare class SpotlightFooterTemplate {
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightFooterTemplate, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SpotlightFooterTemplate, "[spotlightFooter]", never, {}, {}, never, never, true, never>;
+}
+/** Opens the palette on click. `spotlightTrigger="#"` opens it with an initial query. */
+declare class SpotlightTrigger {
+    private readonly svc;
+    readonly spotlightTrigger: i0.InputSignal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightTrigger, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SpotlightTrigger, "[spotlightTrigger]", never, { "spotlightTrigger": { "alias": "spotlightTrigger"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { SPOTLIGHT_RENDERER, SpotlightDefaultBadge, SpotlightDefaultChip, SpotlightDefaultGroupHeader, SpotlightDefaultInput, SpotlightDefaultRow, SpotlightEmptyTemplate, SpotlightFooterTemplate, SpotlightHost, SpotlightItemTemplate, SpotlightService, SpotlightTrigger, httpSource, localStorageRecent, provideSpotlight, routeSource, spotlightRouteAudit, staticSource };
+export type { HttpSourceOptions, RouteSourceOptions, SpotlightAction, SpotlightBadge, SpotlightBadgeContext, SpotlightBadgeTone, SpotlightChipContext, SpotlightConfig, SpotlightContext, SpotlightEmptyTemplateContext, SpotlightGroup, SpotlightGroupHeaderContext, SpotlightHttpOptions, SpotlightHttpRequest, SpotlightInputContext, SpotlightItem, SpotlightItemInput, SpotlightItemTemplateContext, SpotlightRecentEntry, SpotlightRecentStorage, SpotlightRenderer, SpotlightResponse, SpotlightResult, SpotlightRouteAuditEntry, SpotlightRouteAuditOptions, SpotlightRouteData, SpotlightRowContext, SpotlightSource, SpotlightStoredAction, SpotlightTextValue, SpotlightTexts, StaticSourceOptions };