import { type OptionFilterRule } from './option-filter';
import type { OptionDisplayData } from './option-display';
export interface ResolvedOption {
    /** Canonical id (server-side primary key). */
    id: string | number;
    /** Same as `id` — preserved for legacy frontend parity. */
    value: string | number;
    /** Display string. */
    label: string;
    /** Same as `label` — preserved for legacy frontend parity. */
    name: string;
    description?: string | null;
    image?: string | null;
    color?: string | null;
    icon?: string | null;
    /**
     * Presentación declarativa resuelta por el kernel (manifest v3
     * `option_display`): título, subtítulo, imagen, métricas a la derecha con
     * tono (precio, stock…) y badges. Ausente en hosts/modelos sin display.
     */
    display?: OptionDisplayData | null;
    /**
     * Campos extra del payload (precio, costo, sku, tasa) que no son decoración.
     * Solo se llena cuando el option trae números o strings además de id/label.
     */
    meta?: Record<string, unknown>;
}
export interface OptionsMeta {
    /** 'static' for inline options, 'dynamic' for FK-resolved lists. */
    type: 'static' | 'dynamic' | string;
    /** Number of options the server returned in this batch. */
    count: number;
}
export interface UseOptionsResolverArgs {
    /**
     * The owning model whose options endpoint is queried. Pass the model
     * key (e.g. 'sales_orders'). Required — passing an empty string puts
     * the hook in idle mode and no fetch fires.
     */
    modelKey: string;
    /**
     * Field on `modelKey` to resolve. Maps to `?field=<fieldKey>`.
     */
    fieldKey: string;
    /**
     * Optional FK target. When set the hook resolves against
     * `/api/options/<ref>?field=id` instead of `/api/options/<modelKey>`.
     * This is the canonical path the kernel auto-derives from
     * `ColumnDef.Ref`. Prefer this over `endpoint`.
     */
    ref?: string;
    /**
     * Free-text query forwarded as `?q=`. Empty values are skipped so the
     * server returns the first page unfiltered.
     */
    query?: string;
    /**
     * Cascade scope forwarded as `?filter_value=`. Set by a dependent picker
     * from the current value of the field it `dependsOn` (e.g. a product
     * picker scoped to the header's `source_warehouse_id`). When empty/undefined
     * the param is omitted (no scope — the picker lists everything). Changing it
     * re-fetches; an empty string is treated as "not set" so a cleared parent
     * does not query for the empty-string scope.
     */
    filterValue?: string;
    /**
     * Server-side pagination cap. Defaults to 50 (kernel
     * DefaultOptionsLimit) if omitted.
     */
    limit?: number;
    /**
     * Toggle to disable fetching entirely (e.g. while a parent row is
     * still loading). Defaults to true.
     */
    enabled?: boolean;
    /**
     * Escape hatch for callers that need a non-canonical URL — e.g.
     * legacy `/options/<custom>?...`. When set it overrides `ref` and
     * `modelKey` for the fetch path. The query string is built from
     * `fieldKey` / `query` / `limit` exactly the same way.
     */
    endpoint?: string;
    /**
     * Client-side rules that hide fetched options (see `option-filter.ts`).
     * Empty/undefined → no filtering (retrocompat).
     */
    optionFilter?: OptionFilterRule[];
    /** Current selection: never hidden by `optionFilter`, so its label survives. */
    keepValue?: unknown;
    /**
     * Picker context for the option display's contributed metrics, sent as
     * `?ctx.<key>=<value>` (e.g. `{ warehouse_id }` of the document being
     * edited → stock in that warehouse). Empty values are dropped.
     */
    context?: Record<string, string | null | undefined>;
}
export interface UseOptionsResolverResult {
    options: ResolvedOption[];
    meta: OptionsMeta | null;
    loading: boolean;
    error: Error | null;
    /** Forces a refetch. Useful after a parent record updates. */
    refetch: () => void;
}
/**
 * Forgets every cached and in-flight options lookup. Called after any write
 * (create, edit, delete), so a picker opened right after creating a record
 * lists it instead of serving the previous 30 s snapshot.
 */
export declare function invalidateOptionsCache(): void;
/** Runs `fn` on every invalidateOptionsCache (id-label lookups drop with it). */
export declare function onOptionsCacheInvalidated(fn: () => void): () => void;
export declare function optionsRequestKey(scope: string, url: string, field: string, query: string, limit: number | undefined, filter: string | undefined, context?: Record<string, string>): string;
/** Normalized picker context: string values only, empty dropped (null when none). */
export declare function normalizeOptionsContext(context: Record<string, string | null | undefined> | undefined): Record<string, string> | undefined;
/** Org + branch of the host session: part of every options cache key. */
export declare function optionsScope(): string;
export declare function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsResolverResult;
export declare function projectOption(raw: any): ResolvedOption;
//# sourceMappingURL=use-options-resolver.d.ts.map