@smilodon/core 1.0.0

package/dist/types/src/components/native-select.d.ts

@@ -0,0 +1,41 @@
+import { OptionRenderer, OptionTemplate } from '../renderers/contracts';
+export declare class NativeSelectElement extends HTMLElement {
+    static get observedAttributes(): string[];
+    private _options;
+    private _shadow;
+    private _listRoot;
+    private _items;
+    private _helpers;
+    private _virtualizer?;
+    private _selectedSet;
+    private _selectedItems;
+    private _activeIndex;
+    private _multi;
+    private _typeBuffer;
+    private _typeTimeout?;
+    private _liveRegion?;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    set items(items: unknown[]);
+    get items(): unknown[];
+    set multi(value: boolean);
+    get multi(): boolean;
+    get selectedIndices(): number[];
+    get selectedItems(): unknown[];
+    set optionTemplate(template: OptionTemplate | undefined);
+    set optionRenderer(renderer: OptionRenderer | undefined);
+    render(): void;
+    private _applyOptionAttrs;
+    private _applyAriaToAll;
+    private _emit;
+    private _onSelect;
+    private _onKeydown;
+    private _moveActive;
+    private _setActive;
+    private _scrollToActive;
+    private _onType;
+    private _announce;
+    focus(): void;
+}

package/dist/types/src/components/select-option.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Independent Option Component
+ * High cohesion, low coupling - handles its own selection state and events
+ */
+export interface OptionConfig {
+    /** The data item this option represents */
+    item: unknown;
+    /** The index of this option */
+    index: number;
+    /** Whether this option is selected */
+    selected: boolean;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+    /** Whether this option is focused/active */
+    active?: boolean;
+    /** Custom value accessor */
+    getValue?: (item: unknown) => unknown;
+    /** Custom label accessor */
+    getLabel?: (item: unknown) => string;
+    /** Custom renderer */
+    render?: (item: unknown, index: number) => HTMLElement | string;
+    /** Custom style */
+    style?: Partial<CSSStyleDeclaration>;
+    /** Custom class names */
+    className?: string;
+    /** Show remove button (for multi-select) */
+    showRemoveButton?: boolean;
+}
+export interface OptionEventDetail {
+    item: unknown;
+    index: number;
+    value: unknown;
+    label: string;
+    selected: boolean;
+}
+export declare class SelectOption extends HTMLElement {
+    private _config;
+    private _shadow;
+    private _container;
+    private _removeButton?;
+    constructor(config: OptionConfig);
+    private _initializeStyles;
+    private _render;
+    private _attachEventListeners;
+    private _handleSelect;
+    private _handleRemove;
+    private _getValue;
+    private _getLabel;
+    /**
+     * Update option configuration and re-render
+     */
+    updateConfig(updates: Partial<OptionConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<OptionConfig>;
+    /**
+     * Get option value
+     */
+    getValue(): unknown;
+    /**
+     * Get option label
+     */
+    getLabel(): string;
+    /**
+     * Set selected state
+     */
+    setSelected(selected: boolean): void;
+    /**
+     * Set active state
+     */
+    setActive(active: boolean): void;
+    /**
+     * Set disabled state
+     */
+    setDisabled(disabled: boolean): void;
+}

package/dist/types/src/config/global-config.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Global Configuration System for Select Components
+ * Allows users to define default behaviors that can be overridden at component level
+ */
+export interface ScrollToSelectedConfig {
+    /** Whether to scroll to selected item when dropdown opens/closes */
+    enabled: boolean;
+    /** Which selected item to scroll to in multi-select mode: 'first' | 'last' */
+    multiSelectTarget: 'first' | 'last';
+    /** Scroll behavior */
+    behavior?: ScrollBehavior;
+    /** Scroll block alignment */
+    block?: ScrollLogicalPosition;
+}
+export interface LoadMoreConfig {
+    /** Enable load more functionality */
+    enabled: boolean;
+    /** Number of items to load per increment */
+    itemsPerLoad: number;
+    /** Threshold (in pixels from bottom) to trigger auto-load */
+    threshold?: number;
+    /** Show loading indicator */
+    showLoader?: boolean;
+}
+export interface BusyBucketConfig {
+    /** Enable busy/loading state bucket */
+    enabled: boolean;
+    /** Show spinner in bucket */
+    showSpinner?: boolean;
+    /** Custom loading message */
+    message?: string;
+    /** Minimum display time (ms) to prevent flashing */
+    minDisplayTime?: number;
+}
+export interface SelectionConfig {
+    /** Single or multi-select mode */
+    mode: 'single' | 'multi';
+    /** Allow deselection in single-select mode */
+    allowDeselect?: boolean;
+    /** Maximum selections in multi-select (0 = unlimited) */
+    maxSelections?: number;
+    /** Show remove button on selected options in multi-select */
+    showRemoveButton?: boolean;
+    /** Close dropdown after selection in single-select */
+    closeOnSelect?: boolean;
+}
+export interface StyleConfig {
+    /** Container styles */
+    container?: Partial<CSSStyleDeclaration>;
+    /** Dropdown styles */
+    dropdown?: Partial<CSSStyleDeclaration>;
+    /** Option item styles */
+    option?: Partial<CSSStyleDeclaration>;
+    /** Selected option styles */
+    selectedOption?: Partial<CSSStyleDeclaration>;
+    /** Disabled option styles */
+    disabledOption?: Partial<CSSStyleDeclaration>;
+    /** Hover option styles */
+    hoverOption?: Partial<CSSStyleDeclaration>;
+    /** Input field styles */
+    input?: Partial<CSSStyleDeclaration>;
+    /** Loading indicator styles */
+    loader?: Partial<CSSStyleDeclaration>;
+    /** Custom CSS class names */
+    classNames?: {
+        container?: string;
+        dropdown?: string;
+        option?: string;
+        selectedOption?: string;
+        disabledOption?: string;
+        input?: string;
+        loader?: string;
+        removeButton?: string;
+    };
+}
+export interface ServerSideConfig {
+    /** Enable server-side data management */
+    enabled: boolean;
+    /** Initial selected value(s) from server */
+    initialSelectedValues?: unknown[];
+    /** Initial selected indices from server */
+    initialSelectedIndices?: number[];
+    /** Function to fetch pre-selected items not in current page */
+    fetchSelectedItems?: (values: unknown[]) => Promise<unknown[]>;
+    /** Value accessor function */
+    getValueFromItem?: (item: unknown) => unknown;
+    /** Label accessor function */
+    getLabelFromItem?: (item: unknown) => string;
+}
+export interface InfiniteScrollConfig {
+    /** Enable infinite scroll */
+    enabled: boolean;
+    /** Page size for pagination */
+    pageSize: number;
+    /** Initial page */
+    initialPage?: number;
+    /** Cache loaded pages */
+    cachePages?: boolean;
+    /** Maximum cached pages (LRU eviction) */
+    maxCachedPages?: number;
+    /** Preload adjacent pages */
+    preloadAdjacent?: boolean;
+    /** Scroll restoration strategy for selected items on distant pages */
+    scrollRestoration?: 'auto' | 'manual' | 'disabled';
+}
+export interface CallbackConfig {
+    /** Called when option is selected/deselected */
+    onSelect?: (data: {
+        item: unknown;
+        index: number;
+        value: unknown;
+        label: string;
+        selected: boolean;
+    }) => void;
+    /** Called when dropdown opens */
+    onOpen?: () => void;
+    /** Called when dropdown closes */
+    onClose?: () => void;
+    /** Called when search query changes */
+    onSearch?: (query: string) => void;
+    /** Called when more items are loaded */
+    onLoadMore?: (page: number) => void;
+    /** Called when selection changes */
+    onChange?: (selectedItems: unknown[], selectedValues: unknown[]) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+export interface GlobalSelectConfig {
+    /** Selection behavior */
+    selection: SelectionConfig;
+    /** Scroll to selected configuration */
+    scrollToSelected: ScrollToSelectedConfig;
+    /** Load more configuration */
+    loadMore: LoadMoreConfig;
+    /** Busy bucket configuration */
+    busyBucket: BusyBucketConfig;
+    /** Style customization */
+    styles: StyleConfig;
+    /** Server-side configuration */
+    serverSide: ServerSideConfig;
+    /** Infinite scroll configuration */
+    infiniteScroll: InfiniteScrollConfig;
+    /** Callbacks */
+    callbacks: CallbackConfig;
+    /** Enable/disable entire component */
+    enabled: boolean;
+    /** Enable search/filter */
+    searchable?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Virtualization */
+    virtualize?: boolean;
+    /** Estimated item height for virtualization */
+    estimatedItemHeight?: number;
+}
+/**
+ * Global configuration instance
+ */
+declare class SelectConfigManager {
+    private config;
+    constructor();
+    /**
+     * Get current global configuration
+     */
+    getConfig(): Readonly<GlobalSelectConfig>;
+    /**
+     * Update global configuration (deep merge)
+     */
+    updateConfig(updates: Partial<GlobalSelectConfig>): void;
+    /**
+     * Reset to default configuration
+     */
+    resetConfig(): void;
+    /**
+     * Merge component-level config with global config
+     * Component-level config takes precedence
+     */
+    mergeWithComponentConfig(componentConfig: Partial<GlobalSelectConfig>): GlobalSelectConfig;
+    private deepClone;
+    private deepMerge;
+}
+/**
+ * Singleton instance
+ */
+export declare const selectConfig: SelectConfigManager;
+/**
+ * Helper function to configure select globally
+ */
+export declare function configureSelect(config: Partial<GlobalSelectConfig>): void;
+/**
+ * Helper function to reset select configuration
+ */
+export declare function resetSelectConfig(): void;
+export {};

package/dist/types/src/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './renderers/contracts.js';
+export * from './components/native-select.js';
+export * from './components/enhanced-select.js';
+export * from './components/select-option.js';
+export * from './config/global-config.js';
+export { FenwickTree } from './utils/fenwick-tree.js';
+export { DOMPool } from './utils/dom-pool.js';
+export { WorkerManager, getWorkerManager } from './utils/worker-manager.js';
+export { PerformanceTelemetry, getTelemetry, measureAsync, measureSync } from './utils/telemetry.js';
+export { Virtualizer } from './utils/virtualizer.js';
+export { setHTMLSanitizer, getHTMLSanitizer, sanitizeHTML, createElement, setCSSProperties, CSPFeatures, detectEnvironment, containsSuspiciousPatterns, escapeHTML, escapeAttribute, validateTemplate, createTextNode, setTextContent } from './utils/security.js';
+export { applyClasses, toggleClass, setCustomProperties, getCustomProperty, removeCustomProperty, defaultTheme, applyDefaultTheme, shadowDOMStyles, injectShadowStyles, hasOverflowHiddenAncestor, warnCSPViolation } from './utils/csp-styles.js';
+export type { HTMLSanitizer, EnvironmentCapabilities } from './utils/security.js';

package/dist/types/src/renderers/contracts.d.ts

@@ -0,0 +1,5 @@
+import type { RendererHelpers } from '../types';
+export type OptionTemplate = (item: unknown, index: number) => string;
+export type OptionRenderer = (item: unknown, index: number, helpers: RendererHelpers) => HTMLElement;
+export declare const createRendererHelpers: (onSelect: (item: unknown, index: number) => void) => RendererHelpers;
+export declare function renderTemplate(container: HTMLElement, items: unknown[], optionTemplate: OptionTemplate): void;

package/dist/types/src/themes/importer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Design Token Importer
+ * Convert design tokens from Figma, Adobe XD, and other design tools to CSS variables
+ *
+ * Supports:
+ * - Figma Variables API
+ * - Adobe XD Design Tokens
+ * - Design Tokens Format (W3C Community Group spec)
+ * - Style Dictionary format
+ *
+ * Usage:
+ *   import { importTokens, applyTokens } from '@smilodon/core/themes/importer';
+ *
+ *   const tokens = await importTokens('figma', figmaData);
+ *   applyTokens(selectElement, tokens);
+ */
+/**
+ * Design token types
+ */
+export interface DesignToken {
+    $type?: string;
+    $value: string | number | DesignToken;
+    $description?: string;
+}
+export interface DesignTokens {
+    [key: string]: DesignToken | DesignTokens;
+}
+export interface CSSVariable {
+    name: string;
+    value: string;
+    category?: string;
+    description?: string;
+}
+/**
+ * Import design tokens from various sources
+ */
+export declare function importTokens(source: 'figma' | 'adobe-xd' | 'tokens-studio' | 'style-dictionary' | 'json', data: any): Promise<Map<string, CSSVariable>>;
+/**
+ * Import Figma Variables API format
+ *
+ * Example Figma export:
+ * {
+ *   "colors": {
+ *     "primary": { "$type": "color", "$value": "#007aff" },
+ *     "background": { "$type": "color", "$value": "#ffffff" }
+ *   },
+ *   "spacing": {
+ *     "sm": { "$type": "dimension", "$value": "8px" }
+ *   }
+ * }
+ */
+export declare function importFigmaTokens(data: any): Map<string, CSSVariable>;
+/**
+ * Import Adobe XD design tokens
+ *
+ * Example Adobe XD export:
+ * {
+ *   "colors": [
+ *     { "name": "Primary Blue", "value": "#007aff" }
+ *   ],
+ *   "textStyles": [
+ *     { "name": "Body", "fontSize": 16, "fontFamily": "SF Pro" }
+ *   ]
+ * }
+ */
+export declare function importAdobeXDTokens(data: any): Map<string, CSSVariable>;
+/**
+ * Import Tokens Studio (Figma plugin) format
+ */
+export declare function importTokensStudioTokens(data: any): Map<string, CSSVariable>;
+/**
+ * Import Style Dictionary format
+ *
+ * Example:
+ * {
+ *   "color": {
+ *     "primary": { "value": "#007aff" }
+ *   }
+ * }
+ */
+export declare function importStyleDictionaryTokens(data: any): Map<string, CSSVariable>;
+/**
+ * Import generic JSON token format
+ */
+export declare function importGenericTokens(data: any): Map<string, CSSVariable>;
+/**
+ * Apply CSS variables to an element
+ */
+export declare function applyTokens(element: HTMLElement, tokens: Map<string, CSSVariable>, options?: {
+    prefix?: string;
+    scope?: 'element' | 'root';
+}): void;
+/**
+ * Generate CSS stylesheet from tokens
+ */
+export declare function generateCSS(tokens: Map<string, CSSVariable>, options?: {
+    selector?: string;
+    groupByCategory?: boolean;
+    includeComments?: boolean;
+}): string;
+/**
+ * Export tokens to various formats
+ */
+export declare function exportTokens(tokens: Map<string, CSSVariable>, format: 'css' | 'json' | 'scss' | 'js' | 'ts'): string;
+/**
+ * CLI tool for token conversion
+ *
+ * Usage:
+ *   npx @smilodon/tokens import figma tokens.json --output theme.css
+ *   npx @smilodon/tokens import adobe-xd design.json --output vars.css
+ */
+export declare function cli(args: string[]): Promise<void>;

package/dist/types/src/types.d.ts

@@ -0,0 +1,85 @@
+export type Placement = 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
+export type Strategy = 'fixed' | 'absolute';
+export interface GroupedItem {
+    label: string;
+    options: unknown[];
+}
+export interface RemoteConfig {
+    endpoint: string;
+    pageSize?: number;
+    headers?: Record<string, string>;
+    transformer?: (resp: unknown) => unknown[] | Promise<unknown[]>;
+    cacheTTL?: number;
+}
+export interface SelectEventDetail<T = unknown> {
+    item: T;
+    index: number;
+    value: unknown;
+    label: string;
+    selected: boolean;
+    multi?: boolean;
+}
+export interface OpenEventDetail {
+}
+export interface CloseEventDetail {
+}
+export interface SearchEventDetail {
+    query: string;
+    results?: unknown[];
+    count?: number;
+}
+export interface PageLoadedEventDetail {
+    page: number;
+    count: number;
+}
+export interface ErrorEventDetail {
+    message: string;
+    cause?: unknown;
+}
+export interface ChangeEventDetail {
+    selectedItems: unknown[];
+    selectedValues: unknown[];
+    selectedIndices: number[];
+}
+export interface LoadMoreEventDetail {
+    page: number;
+    items: unknown[];
+}
+export interface RemoveEventDetail {
+    item: unknown;
+    index: number;
+}
+export interface SelectEventsDetailMap {
+    select: SelectEventDetail;
+    open: OpenEventDetail;
+    close: CloseEventDetail;
+    search: SearchEventDetail;
+    pageLoaded: PageLoadedEventDetail;
+    error: ErrorEventDetail;
+    change: ChangeEventDetail;
+    loadMore: LoadMoreEventDetail;
+    remove: RemoveEventDetail;
+}
+export type SelectEventName = keyof SelectEventsDetailMap;
+export interface RendererHelpers {
+    onSelect: (item: unknown, index: number) => void;
+    getIndex: (node: Element | null) => number | null;
+    keyboardFocus: (index: number) => void;
+}
+export interface NativeSelectOptions {
+    placement?: Placement;
+    strategy?: Strategy;
+    portal?: boolean;
+    offset?: [number, number];
+    flip?: boolean;
+    shift?: boolean;
+    boundary?: Element | Document;
+    optionRenderer?: (item: unknown, index: number, helpers: RendererHelpers) => HTMLElement;
+    optionTemplate?: (item: unknown, index: number) => string;
+    remote?: RemoteConfig | null;
+    loadMode?: 'full' | 'lazy';
+    infinite?: boolean;
+    virtualize?: boolean;
+    estimatedItemHeight?: number;
+    bufferSize?: number;
+}

package/dist/types/src/utils/csp-styles.d.ts

@@ -0,0 +1,74 @@
+/**
+ * CSP-compliant styling utilities.
+ * No inline styles or runtime style tag injection.
+ * Uses CSS custom properties and class names only.
+ */
+/**
+ * Apply CSS classes to an element (CSP-safe).
+ */
+export declare function applyClasses(element: HTMLElement, classes: string[]): void;
+/**
+ * Toggle a CSS class (CSP-safe).
+ */
+export declare function toggleClass(element: HTMLElement, className: string, force?: boolean): void;
+/**
+ * Set CSS custom properties (CSP-safe dynamic styling).
+ * All properties must start with -- (CSS variables).
+ *
+ * @example
+ * setCustomProperties(element, {
+ *   '--item-height': '48px',
+ *   '--selected-bg': '#0066cc'
+ * });
+ */
+export declare function setCustomProperties(element: HTMLElement, properties: Record<string, string>): void;
+/**
+ * Get a CSS custom property value.
+ */
+export declare function getCustomProperty(element: HTMLElement, propertyName: string): string;
+/**
+ * Remove a CSS custom property.
+ */
+export declare function removeCustomProperty(element: HTMLElement, propertyName: string): void;
+/**
+ * Predefined theme as CSS custom properties.
+ * Can be overridden by consumers via CSS.
+ */
+export declare const defaultTheme: {
+    '--ns-item-height': string;
+    '--ns-item-padding': string;
+    '--ns-item-bg': string;
+    '--ns-item-hover-bg': string;
+    '--ns-item-selected-bg': string;
+    '--ns-item-active-bg': string;
+    '--ns-item-color': string;
+    '--ns-item-selected-color': string;
+    '--ns-border-color': string;
+    '--ns-border-radius': string;
+    '--ns-focus-outline': string;
+    '--ns-font-size': string;
+    '--ns-font-family': string;
+};
+/**
+ * Apply the default theme to an element.
+ */
+export declare function applyDefaultTheme(element: HTMLElement): void;
+/**
+ * Static CSS for shadow DOM (no runtime injection).
+ * This CSS is CSP-safe because it's defined at build time as a string constant,
+ * not generated at runtime.
+ */
+export declare const shadowDOMStyles = "\n:host {\n  display: block;\n  box-sizing: border-box;\n  font-family: var(--ns-font-family, system-ui, -apple-system, sans-serif);\n  font-size: var(--ns-font-size, 14px);\n}\n\n* {\n  box-sizing: border-box;\n}\n\n.ns-list {\n  position: relative;\n  overflow: auto;\n  max-height: var(--ns-max-height, 300px);\n  border: 1px solid var(--ns-border-color, #ccc);\n  border-radius: var(--ns-border-radius, 4px);\n  background: var(--ns-bg, white);\n  outline: none;\n}\n\n.ns-list:focus {\n  outline: var(--ns-focus-outline, 2px solid #0066cc);\n  outline-offset: -2px;\n}\n\n.ns-item {\n  padding: var(--ns-item-padding, 8px 12px);\n  min-height: var(--ns-item-height, 40px);\n  color: var(--ns-item-color, inherit);\n  background: var(--ns-item-bg, transparent);\n  cursor: pointer;\n  user-select: none;\n  display: flex;\n  align-items: center;\n  transition: background-color 0.15s ease;\n}\n\n.ns-item:hover {\n  background: var(--ns-item-hover-bg, rgba(0, 0, 0, 0.05));\n}\n\n.ns-item[aria-selected=\"true\"] {\n  background: var(--ns-item-selected-bg, rgba(0, 102, 204, 0.1));\n  color: var(--ns-item-selected-color, #0066cc);\n}\n\n.ns-item[data-active=\"true\"] {\n  background: var(--ns-item-active-bg, rgba(0, 102, 204, 0.2));\n}\n\n.ns-item[aria-disabled=\"true\"] {\n  opacity: 0.5;\n  cursor: not-allowed;\n}\n\n.ns-viewport {\n  position: relative;\n  overflow: auto;\n  -webkit-overflow-scrolling: touch;\n}\n\n.ns-spacer {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 1px;\n  pointer-events: none;\n}\n\n/* Screen reader only */\n.ns-sr-only {\n  position: absolute;\n  left: -9999px;\n  width: 1px;\n  height: 1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n}\n\n/* Portal mode (teleported outside shadow DOM) */\n.ns-portal {\n  position: fixed;\n  z-index: var(--ns-portal-z-index, 9999);\n}\n\n/* CSP warning banner (only shown in development) */\n.ns-csp-warning {\n  padding: 8px;\n  background: #fff3cd;\n  border: 1px solid #ffc107;\n  border-radius: 4px;\n  color: #856404;\n  font-size: 12px;\n  margin-bottom: 8px;\n}\n";
+/**
+ * Inject static styles into shadow root (CSP-safe).
+ * Only called once during component initialization.
+ */
+export declare function injectShadowStyles(shadowRoot: ShadowRoot): void;
+/**
+ * Check if element has overflow:hidden ancestors (portal fallback detection).
+ */
+export declare function hasOverflowHiddenAncestor(element: HTMLElement): boolean;
+/**
+ * Runtime warning for CSP violations (development only).
+ */
+export declare function warnCSPViolation(feature: string, fallback: string): void;

package/dist/types/src/utils/data-source.d.ts

@@ -0,0 +1,37 @@
+export type Transformer<T = unknown> = (resp: unknown) => T[] | Promise<T[]>;
+export interface RemoteConfig {
+    endpoint: string;
+    pageSize?: number;
+    headers?: Record<string, string>;
+    transformer?: Transformer;
+    cacheTTL?: number;
+}
+export interface FetchResult<T> {
+    items: T[];
+    fromCache: boolean;
+}
+export declare class TTLCache<T> {
+    private defaultTTL;
+    private store;
+    constructor(defaultTTL?: number);
+    get(key: string): T[] | null;
+    set(key: string, items: T[], ttl?: number): void;
+}
+export declare class LocalSource<T = unknown> {
+    private items;
+    constructor(items: T[]);
+    search(query: string): T[];
+    fetchPage(query: string, page: number, pageSize?: number): Promise<FetchResult<T>>;
+}
+export declare class RemoteSource<T = unknown> {
+    private cfg;
+    private cache;
+    private controller;
+    private pageMap;
+    constructor(cfg: RemoteConfig);
+    private key;
+    fetchPage(query: string, page: number): Promise<FetchResult<T>>;
+    refresh(query: string, page: number): Promise<void>;
+    getPage(page: number): T[] | null;
+}
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, ms: number): (...args: Parameters<T>) => void;