@timeax/form-palette 0.0.30 → 0.0.31

package/dist/extra.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import { M as ListerProviderHost, P as PresetMap, N as ListerApi, O as ListerStoreState, Q as ListerRuntimeState, U as ListerSessionId, W as ListerId, X as ListerSearchMode, Y as ListerSearchTarget, Z as ListerSearchPayload, _ as ListerFilterCtx, $ as ListerDefinition, a0 as ListerMode, a1 as ShadcnJsonEditorProps, a2 as JsonEditorIndexHandle } from './variant-BPDyK780.mjs';
-export { a7 as ListerChangeEvent, as as ListerDetails, ah as ListerFilterApply, ag as ListerFilterApplyMode, ai as ListerFilterBindKey, ak as ListerFilterGroupOption, aj as ListerFilterInput, am as ListerFilterInputOption, an as ListerFilterOption, ao as ListerFilterSpec, al as ListerFilterValueOption, a9 as ListerLogCode, aa as ListerLogEntry, a8 as ListerLogLevel, ad as ListerMapping, at as ListerOpenOptions, a3 as ListerOpenReason, au as ListerOpenResult, ac as ListerOption, ar as ListerOptionsForMode, ab as ListerPermissionCtx, aq as ListerRawForMode, af as ListerSearchSpec, az as ListerSessionState, ae as ListerSource, ap as ListerValueForMode, a6 as OpenAnchor, ax as PresetFilters, ay as PresetMeta, av as PresetRaw, aw as PresetValue, a5 as Resolver, a4 as Selector } from './variant-BPDyK780.mjs';
+import { M as ListerDefinition, N as ListerRuntimeState, O as ListerProviderHost, P as PresetMap, Q as ListerStoreState, U as ListerSessionId, W as ListerId, X as ListerSearchMode, Y as ListerSearchTarget, Z as ListerSearchPayload, _ as ListerFilterCtx, $ as ListerFilterOption, a0 as ListerMode, a1 as ListerApi, a2 as ShadcnJsonEditorProps, a3 as JsonEditorIndexHandle } from './variant-jHi2M5Ru.mjs';
+export { a8 as ListerChangeEvent, as as ListerDetails, ai as ListerFilterApply, ah as ListerFilterApplyMode, aj as ListerFilterBindKey, al as ListerFilterGroupOption, ak as ListerFilterInput, an as ListerFilterInputOption, ao as ListerFilterSpec, am as ListerFilterValueOption, aa as ListerLogCode, ab as ListerLogEntry, a9 as ListerLogLevel, ae as ListerMapping, at as ListerOpenOptions, a4 as ListerOpenReason, au as ListerOpenResult, ad as ListerOption, ar as ListerOptionsForMode, ac as ListerPermissionCtx, aq as ListerRawForMode, ag as ListerSearchSpec, az as ListerSessionState, af as ListerSource, ap as ListerValueForMode, a7 as OpenAnchor, ax as PresetFilters, ay as PresetMeta, av as PresetRaw, aw as PresetValue, a6 as Resolver, a5 as Selector } from './variant-jHi2M5Ru.mjs';
 import 'zod';
 import './adapter-CvjXO9Gi.mjs';
 import '@inertiajs/core';
@@ -31,8 +31,81 @@ type AnyDef = ListerDefinition<any, any, any, any>;
 type AnyState = ListerRuntimeState<any, any, any, any, any> & {
     searchSpec?: any;
     searchTarget?: any;
+    searchPayload?: any;
     ownerKey?: string;
 };
+type InternalContextValue = {
+    host: ListerProviderHost;
+    http: ListerHttpClient;
+    presetsRef: React.RefObject<PresetMap>;
+    store: ListerStoreState;
+    apiFetchAny: (kindOrDef: string | AnyDef, filters?: any, opts?: any) => Promise<any>;
+    apiOpenAny: (kindOrDef: string | AnyDef, filters?: any, opts?: any) => Promise<any>;
+    focus(id: ListerSessionId): void;
+    dispose(id: ListerSessionId): void;
+    apply(id: ListerSessionId): void;
+    cancel(id: ListerSessionId): void;
+    close(id: ListerSessionId): void;
+    toggle(id: ListerSessionId, value: ListerId): void;
+    select(id: ListerSessionId, value: ListerId): void;
+    deselect(id: ListerSessionId, value: ListerId): void;
+    clear(id: ListerSessionId): void;
+    setQuery(id: ListerSessionId, q: string): void;
+    setSearchMode(id: ListerSessionId, mode: ListerSearchMode): void;
+    /**
+     * Persist the user's current search target (subject/all/only)
+     * so all searches (local/remote/hybrid) can include it.
+     */
+    setSearchTarget(id: ListerSessionId, target: ListerSearchTarget): void;
+    /**
+     * Backwards compatible signatures:
+     * - existing calls still work: searchRemote(id, q)
+     * - new calls can optionally override payload: searchRemote(id, q, payload)
+     *
+     * If payload is omitted, implementation should read from session.searchTarget.
+     */
+    searchLocal: {
+        (id: ListerSessionId, q: string): void;
+        (id: ListerSessionId, q: string, payload?: ListerSearchPayload): void;
+    };
+    searchRemote: {
+        (id: ListerSessionId, q: string): void;
+        (id: ListerSessionId, q: string, payload?: ListerSearchPayload): void;
+    };
+    refresh(id: ListerSessionId): void;
+    setPosition(id: ListerSessionId, pos: {
+        x: number;
+        y: number;
+    } | null): void;
+    /** Filters (non-UI logic; per session) */
+    getFilterCtx<TFilters>(id: ListerSessionId): ListerFilterCtx<TFilters>;
+    /**
+     * NEW semantics:
+     * - `optionId` is the UI identifier of the filter option (NOT the db value)
+     * - `selectedFilterValues` tracks selected option ids (for UI checkmarks/badge)
+     */
+    applyFilterOption(id: ListerSessionId, optionId: string | number): void;
+    registerPreset(kind: string, def: AnyDef): void;
+    getPreset(kind: string): AnyDef | undefined;
+    /** Derived list for UI later (local/hybrid filtering) */
+    getVisibleOptions(id: ListerSessionId): any[];
+};
+declare const Ctx: React.Context<InternalContextValue | null>;
+type ResolvedFilterNode<TFilters> = {
+    option: ListerFilterOption<TFilters>;
+    id: string;
+    kind?: string;
+    disabled?: boolean;
+    bindKey?: string;
+    dbValue?: any;
+    apply?: {
+        key?: string;
+        mode?: "replace" | "merge" | "unset";
+        toggleable?: boolean;
+        value?: any;
+    };
+};
+declare function buildSearchPayloadFromTarget(target?: ListerSearchTarget | null): ListerSearchPayload | undefined;
 declare function ListerProvider(props: {
     host: ListerProviderHost;
     presets?: PresetMap;
@@ -41,6 +114,48 @@ declare function ListerProvider(props: {
     remoteDebounceMs?: number;
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
+
+/**
+ * Search bar + trailing controls:
+ * - Search target (all/subject/only) popover (leading control)
+ * - Search mode toggle (remote/local/hybrid)
+ * - Filters UI (custom popover button)
+ *
+ * Notes:
+ * - Search mode is bound to session.searchMode via actions.setSearchMode(id, mode)
+ * - Search target is bound to session.searchTarget via actions.setSearchTarget(id, target)
+ * - Filters live in session.filtersSpec?.options and session.selectedFilterValues
+ */
+declare function SearchBar(props: {
+    id: ListerSessionId;
+    store: ListerStoreState;
+}): react_jsx_runtime.JSX.Element;
+
+declare function ListerUI(): react_jsx_runtime.JSX.Element | null;
+declare function HeaderBar(props: {
+    id: ListerSessionId;
+    title: string;
+    loading: boolean;
+    refreshing: boolean;
+    showRefresh: boolean;
+    draggable: boolean;
+    onRefresh(): void;
+    onClose(): void;
+}): react_jsx_runtime.JSX.Element;
+
+declare function OptionList(props: {
+    id: ListerSessionId;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function FooterBar(props: {
+    id: ListerSessionId;
+    mode: ListerMode;
+    confirm: boolean;
+    onClear(): void;
+    onCancel(): void;
+    onApply(): void;
+}): react_jsx_runtime.JSX.Element;
+
 declare function useLister<P extends PresetMap>(): {
     api: ListerApi<P>;
     store: ListerStoreState;
@@ -82,46 +197,104 @@ declare function useLister<P extends PresetMap>(): {
 };
 
 /**
- * Search bar + trailing controls:
- * - Search target (all/subject/only) popover (leading control)
- * - Search mode toggle (remote/local/hybrid)
- * - Filters UI (custom popover button)
- *
- * Notes:
- * - Search mode is bound to session.searchMode via actions.setSearchMode(id, mode)
- * - Search target is bound to session.searchTarget via actions.setSearchTarget(id, target)
- * - Filters live in session.filtersSpec?.options and session.selectedFilterValues
+ * Minimal selector contract (matches extractArray contract used by lister)
+ * - function: (body) => array
+ * - string: path selector
  */
-declare function SearchBar(props: {
-    id: ListerSessionId;
-    store: ListerStoreState;
-}): react_jsx_runtime.JSX.Element;
-
-declare function ListerUI(): react_jsx_runtime.JSX.Element | null;
-declare function HeaderBar(props: {
-    id: ListerSessionId;
-    title: string;
+type DataSelector<T> = any;
+type DataSearchConfig = {
+    default?: string;
+};
+type DataBuildRequestCtx<TFilters> = {
+    filters?: TFilters;
+    query: string;
+    cursor: any;
+};
+type DataBuildRequestResult = {
+    params?: any;
+    body?: any;
+    headers?: any;
+};
+type DataKey = string | number;
+type DataSelectionMode = "none" | "single" | "multiple";
+type DataSelectionKey<TItem> = keyof TItem | string | ((item: TItem) => DataKey | null | undefined);
+type DataSelectionConfig<TItem> = {
+    mode?: Exclude<DataSelectionMode, "none">;
+    /**
+     * How to resolve the ID for an item.
+     * - string/ keyof: item[key]
+     * - function: (item) => id
+     * Defaults to: item.id ?? item.value
+     */
+    key?: DataSelectionKey<TItem>;
+    /**
+     * If "missing", selection IDs that don't exist in the *latest fetched list* are removed.
+     * Default: "never" (recommended; avoids wiping selection on remote searches).
+     */
+    prune?: "never" | "missing";
+};
+type UseDataOptions<TItem = any, TFilters = Record<string, any>> = {
+    id?: string;
+    endpoint: string;
+    method?: "GET" | "POST";
+    selector?: DataSelector<TItem>;
+    /**
+     * Passed through into the inline def source.buildRequest (same signature as provider)
+     */
+    buildRequest?: (ctx: DataBuildRequestCtx<TFilters>) => DataBuildRequestResult;
+    /**
+     * Minimal search config (default subject column).
+     */
+    search?: DataSearchConfig;
+    /**
+     * Raw filters object
+     */
+    filters?: TFilters;
+    initial?: TItem[];
+    enabled?: boolean;
+    fetchOnMount?: boolean;
+    searchMode?: ListerSearchMode;
+    debounceMs?: number;
+    autoFetchOnFilterChange?: boolean;
+    /**
+     * Optional selection support (by stable item key)
+     */
+    selection?: DataSelectionConfig<TItem>;
+};
+type UseDataResult<TItem = any, TFilters = Record<string, any>> = {
+    id?: string;
+    data: TItem[];
+    visible: TItem[];
     loading: boolean;
-    refreshing: boolean;
-    showRefresh: boolean;
-    draggable: boolean;
-    onRefresh(): void;
-    onClose(): void;
-}): react_jsx_runtime.JSX.Element;
-
-declare function OptionList(props: {
-    id: ListerSessionId;
-    className?: string;
-}): react_jsx_runtime.JSX.Element;
-declare function FooterBar(props: {
-    id: ListerSessionId;
-    mode: ListerMode;
-    confirm: boolean;
-    onClear(): void;
-    onCancel(): void;
-    onApply(): void;
-}): react_jsx_runtime.JSX.Element;
+    error: any;
+    query: string;
+    setQuery: (q: string) => void;
+    searchMode: ListerSearchMode;
+    setSearchMode: (m: ListerSearchMode) => void;
+    searchTarget?: ListerSearchTarget;
+    setSearchTarget: (t: ListerSearchTarget) => void;
+    filters?: TFilters;
+    setFilters: (next: TFilters | undefined) => void;
+    patchFilters: (patch: Partial<TFilters>) => void;
+    clearFilters: () => void;
+    selectionMode: DataSelectionMode;
+    selectedIds: DataKey | DataKey[] | null;
+    selected: TItem | TItem[] | null;
+    select: (id: DataKey | DataKey[]) => void;
+    deselect: (id: DataKey | DataKey[]) => void;
+    toggle: (id: DataKey) => void;
+    clearSelection: () => void;
+    isSelected: (id: DataKey) => boolean;
+    getSelection: () => TItem | TItem[] | null;
+    refresh: () => void;
+    fetch: (override?: {
+        query?: string;
+        filters?: TFilters;
+        searchTarget?: ListerSearchTarget;
+    }) => Promise<TItem[]>;
+};
+declare function useData<TItem = any, TFilters = Record<string, any>>(opts: UseDataOptions<TItem, TFilters>): UseDataResult<TItem, TFilters>;
 
 declare const ShadcnJsonEditorVariant: React.ForwardRefExoticComponent<ShadcnJsonEditorProps & React.RefAttributes<JsonEditorIndexHandle>>;
 
-export { FooterBar, HeaderBar, ShadcnJsonEditorVariant as JsonEditor, ListerApi, ListerDefinition, ListerFilterCtx, ListerId, ListerMode, ListerProvider, ListerProviderHost, ListerRuntimeState, ListerSearchMode, ListerSearchPayload, ListerSearchTarget, ListerSessionId, ListerStoreState, ListerUI, OptionList, PresetMap, SearchBar, useLister };
+export { type AnyDef, type AnyState, Ctx, type DataBuildRequestCtx, type DataBuildRequestResult, type DataKey, type DataSearchConfig, type DataSelectionConfig, type DataSelectionKey, type DataSelectionMode, type DataSelector, FooterBar, HeaderBar, type InternalContextValue, ShadcnJsonEditorVariant as JsonEditor, ListerApi, ListerDefinition, ListerFilterCtx, ListerFilterOption, ListerId, ListerMode, ListerProvider, ListerProviderHost, ListerRuntimeState, ListerSearchMode, ListerSearchPayload, ListerSearchTarget, ListerSessionId, ListerStoreState, ListerUI, OptionList, PresetMap, type ResolvedFilterNode, SearchBar, type UseDataOptions, type UseDataResult, buildSearchPayloadFromTarget, useData, useLister };

package/dist/extra.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import { M as ListerProviderHost, P as PresetMap, N as ListerApi, O as ListerStoreState, Q as ListerRuntimeState, U as ListerSessionId, W as ListerId, X as ListerSearchMode, Y as ListerSearchTarget, Z as ListerSearchPayload, _ as ListerFilterCtx, $ as ListerDefinition, a0 as ListerMode, a1 as ShadcnJsonEditorProps, a2 as JsonEditorIndexHandle } from './variant-v0LBdshU.js';
-export { a7 as ListerChangeEvent, as as ListerDetails, ah as ListerFilterApply, ag as ListerFilterApplyMode, ai as ListerFilterBindKey, ak as ListerFilterGroupOption, aj as ListerFilterInput, am as ListerFilterInputOption, an as ListerFilterOption, ao as ListerFilterSpec, al as ListerFilterValueOption, a9 as ListerLogCode, aa as ListerLogEntry, a8 as ListerLogLevel, ad as ListerMapping, at as ListerOpenOptions, a3 as ListerOpenReason, au as ListerOpenResult, ac as ListerOption, ar as ListerOptionsForMode, ab as ListerPermissionCtx, aq as ListerRawForMode, af as ListerSearchSpec, az as ListerSessionState, ae as ListerSource, ap as ListerValueForMode, a6 as OpenAnchor, ax as PresetFilters, ay as PresetMeta, av as PresetRaw, aw as PresetValue, a5 as Resolver, a4 as Selector } from './variant-v0LBdshU.js';
+import { M as ListerDefinition, N as ListerRuntimeState, O as ListerProviderHost, P as PresetMap, Q as ListerStoreState, U as ListerSessionId, W as ListerId, X as ListerSearchMode, Y as ListerSearchTarget, Z as ListerSearchPayload, _ as ListerFilterCtx, $ as ListerFilterOption, a0 as ListerMode, a1 as ListerApi, a2 as ShadcnJsonEditorProps, a3 as JsonEditorIndexHandle } from './variant-BhsBO5Yr.js';
+export { a8 as ListerChangeEvent, as as ListerDetails, ai as ListerFilterApply, ah as ListerFilterApplyMode, aj as ListerFilterBindKey, al as ListerFilterGroupOption, ak as ListerFilterInput, an as ListerFilterInputOption, ao as ListerFilterSpec, am as ListerFilterValueOption, aa as ListerLogCode, ab as ListerLogEntry, a9 as ListerLogLevel, ae as ListerMapping, at as ListerOpenOptions, a4 as ListerOpenReason, au as ListerOpenResult, ad as ListerOption, ar as ListerOptionsForMode, ac as ListerPermissionCtx, aq as ListerRawForMode, ag as ListerSearchSpec, az as ListerSessionState, af as ListerSource, ap as ListerValueForMode, a7 as OpenAnchor, ax as PresetFilters, ay as PresetMeta, av as PresetRaw, aw as PresetValue, a6 as Resolver, a5 as Selector } from './variant-BhsBO5Yr.js';
 import 'zod';
 import './adapter-CvjXO9Gi.js';
 import '@inertiajs/core';
@@ -31,8 +31,81 @@ type AnyDef = ListerDefinition<any, any, any, any>;
 type AnyState = ListerRuntimeState<any, any, any, any, any> & {
     searchSpec?: any;
     searchTarget?: any;
+    searchPayload?: any;
     ownerKey?: string;
 };
+type InternalContextValue = {
+    host: ListerProviderHost;
+    http: ListerHttpClient;
+    presetsRef: React.RefObject<PresetMap>;
+    store: ListerStoreState;
+    apiFetchAny: (kindOrDef: string | AnyDef, filters?: any, opts?: any) => Promise<any>;
+    apiOpenAny: (kindOrDef: string | AnyDef, filters?: any, opts?: any) => Promise<any>;
+    focus(id: ListerSessionId): void;
+    dispose(id: ListerSessionId): void;
+    apply(id: ListerSessionId): void;
+    cancel(id: ListerSessionId): void;
+    close(id: ListerSessionId): void;
+    toggle(id: ListerSessionId, value: ListerId): void;
+    select(id: ListerSessionId, value: ListerId): void;
+    deselect(id: ListerSessionId, value: ListerId): void;
+    clear(id: ListerSessionId): void;
+    setQuery(id: ListerSessionId, q: string): void;
+    setSearchMode(id: ListerSessionId, mode: ListerSearchMode): void;
+    /**
+     * Persist the user's current search target (subject/all/only)
+     * so all searches (local/remote/hybrid) can include it.
+     */
+    setSearchTarget(id: ListerSessionId, target: ListerSearchTarget): void;
+    /**
+     * Backwards compatible signatures:
+     * - existing calls still work: searchRemote(id, q)
+     * - new calls can optionally override payload: searchRemote(id, q, payload)
+     *
+     * If payload is omitted, implementation should read from session.searchTarget.
+     */
+    searchLocal: {
+        (id: ListerSessionId, q: string): void;
+        (id: ListerSessionId, q: string, payload?: ListerSearchPayload): void;
+    };
+    searchRemote: {
+        (id: ListerSessionId, q: string): void;
+        (id: ListerSessionId, q: string, payload?: ListerSearchPayload): void;
+    };
+    refresh(id: ListerSessionId): void;
+    setPosition(id: ListerSessionId, pos: {
+        x: number;
+        y: number;
+    } | null): void;
+    /** Filters (non-UI logic; per session) */
+    getFilterCtx<TFilters>(id: ListerSessionId): ListerFilterCtx<TFilters>;
+    /**
+     * NEW semantics:
+     * - `optionId` is the UI identifier of the filter option (NOT the db value)
+     * - `selectedFilterValues` tracks selected option ids (for UI checkmarks/badge)
+     */
+    applyFilterOption(id: ListerSessionId, optionId: string | number): void;
+    registerPreset(kind: string, def: AnyDef): void;
+    getPreset(kind: string): AnyDef | undefined;
+    /** Derived list for UI later (local/hybrid filtering) */
+    getVisibleOptions(id: ListerSessionId): any[];
+};
+declare const Ctx: React.Context<InternalContextValue | null>;
+type ResolvedFilterNode<TFilters> = {
+    option: ListerFilterOption<TFilters>;
+    id: string;
+    kind?: string;
+    disabled?: boolean;
+    bindKey?: string;
+    dbValue?: any;
+    apply?: {
+        key?: string;
+        mode?: "replace" | "merge" | "unset";
+        toggleable?: boolean;
+        value?: any;
+    };
+};
+declare function buildSearchPayloadFromTarget(target?: ListerSearchTarget | null): ListerSearchPayload | undefined;
 declare function ListerProvider(props: {
     host: ListerProviderHost;
     presets?: PresetMap;
@@ -41,6 +114,48 @@ declare function ListerProvider(props: {
     remoteDebounceMs?: number;
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
+
+/**
+ * Search bar + trailing controls:
+ * - Search target (all/subject/only) popover (leading control)
+ * - Search mode toggle (remote/local/hybrid)
+ * - Filters UI (custom popover button)
+ *
+ * Notes:
+ * - Search mode is bound to session.searchMode via actions.setSearchMode(id, mode)
+ * - Search target is bound to session.searchTarget via actions.setSearchTarget(id, target)
+ * - Filters live in session.filtersSpec?.options and session.selectedFilterValues
+ */
+declare function SearchBar(props: {
+    id: ListerSessionId;
+    store: ListerStoreState;
+}): react_jsx_runtime.JSX.Element;
+
+declare function ListerUI(): react_jsx_runtime.JSX.Element | null;
+declare function HeaderBar(props: {
+    id: ListerSessionId;
+    title: string;
+    loading: boolean;
+    refreshing: boolean;
+    showRefresh: boolean;
+    draggable: boolean;
+    onRefresh(): void;
+    onClose(): void;
+}): react_jsx_runtime.JSX.Element;
+
+declare function OptionList(props: {
+    id: ListerSessionId;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function FooterBar(props: {
+    id: ListerSessionId;
+    mode: ListerMode;
+    confirm: boolean;
+    onClear(): void;
+    onCancel(): void;
+    onApply(): void;
+}): react_jsx_runtime.JSX.Element;
+
 declare function useLister<P extends PresetMap>(): {
     api: ListerApi<P>;
     store: ListerStoreState;
@@ -82,46 +197,104 @@ declare function useLister<P extends PresetMap>(): {
 };
 
 /**
- * Search bar + trailing controls:
- * - Search target (all/subject/only) popover (leading control)
- * - Search mode toggle (remote/local/hybrid)
- * - Filters UI (custom popover button)
- *
- * Notes:
- * - Search mode is bound to session.searchMode via actions.setSearchMode(id, mode)
- * - Search target is bound to session.searchTarget via actions.setSearchTarget(id, target)
- * - Filters live in session.filtersSpec?.options and session.selectedFilterValues
+ * Minimal selector contract (matches extractArray contract used by lister)
+ * - function: (body) => array
+ * - string: path selector
  */
-declare function SearchBar(props: {
-    id: ListerSessionId;
-    store: ListerStoreState;
-}): react_jsx_runtime.JSX.Element;
-
-declare function ListerUI(): react_jsx_runtime.JSX.Element | null;
-declare function HeaderBar(props: {
-    id: ListerSessionId;
-    title: string;
+type DataSelector<T> = any;
+type DataSearchConfig = {
+    default?: string;
+};
+type DataBuildRequestCtx<TFilters> = {
+    filters?: TFilters;
+    query: string;
+    cursor: any;
+};
+type DataBuildRequestResult = {
+    params?: any;
+    body?: any;
+    headers?: any;
+};
+type DataKey = string | number;
+type DataSelectionMode = "none" | "single" | "multiple";
+type DataSelectionKey<TItem> = keyof TItem | string | ((item: TItem) => DataKey | null | undefined);
+type DataSelectionConfig<TItem> = {
+    mode?: Exclude<DataSelectionMode, "none">;
+    /**
+     * How to resolve the ID for an item.
+     * - string/ keyof: item[key]
+     * - function: (item) => id
+     * Defaults to: item.id ?? item.value
+     */
+    key?: DataSelectionKey<TItem>;
+    /**
+     * If "missing", selection IDs that don't exist in the *latest fetched list* are removed.
+     * Default: "never" (recommended; avoids wiping selection on remote searches).
+     */
+    prune?: "never" | "missing";
+};
+type UseDataOptions<TItem = any, TFilters = Record<string, any>> = {
+    id?: string;
+    endpoint: string;
+    method?: "GET" | "POST";
+    selector?: DataSelector<TItem>;
+    /**
+     * Passed through into the inline def source.buildRequest (same signature as provider)
+     */
+    buildRequest?: (ctx: DataBuildRequestCtx<TFilters>) => DataBuildRequestResult;
+    /**
+     * Minimal search config (default subject column).
+     */
+    search?: DataSearchConfig;
+    /**
+     * Raw filters object
+     */
+    filters?: TFilters;
+    initial?: TItem[];
+    enabled?: boolean;
+    fetchOnMount?: boolean;
+    searchMode?: ListerSearchMode;
+    debounceMs?: number;
+    autoFetchOnFilterChange?: boolean;
+    /**
+     * Optional selection support (by stable item key)
+     */
+    selection?: DataSelectionConfig<TItem>;
+};
+type UseDataResult<TItem = any, TFilters = Record<string, any>> = {
+    id?: string;
+    data: TItem[];
+    visible: TItem[];
     loading: boolean;
-    refreshing: boolean;
-    showRefresh: boolean;
-    draggable: boolean;
-    onRefresh(): void;
-    onClose(): void;
-}): react_jsx_runtime.JSX.Element;
-
-declare function OptionList(props: {
-    id: ListerSessionId;
-    className?: string;
-}): react_jsx_runtime.JSX.Element;
-declare function FooterBar(props: {
-    id: ListerSessionId;
-    mode: ListerMode;
-    confirm: boolean;
-    onClear(): void;
-    onCancel(): void;
-    onApply(): void;
-}): react_jsx_runtime.JSX.Element;
+    error: any;
+    query: string;
+    setQuery: (q: string) => void;
+    searchMode: ListerSearchMode;
+    setSearchMode: (m: ListerSearchMode) => void;
+    searchTarget?: ListerSearchTarget;
+    setSearchTarget: (t: ListerSearchTarget) => void;
+    filters?: TFilters;
+    setFilters: (next: TFilters | undefined) => void;
+    patchFilters: (patch: Partial<TFilters>) => void;
+    clearFilters: () => void;
+    selectionMode: DataSelectionMode;
+    selectedIds: DataKey | DataKey[] | null;
+    selected: TItem | TItem[] | null;
+    select: (id: DataKey | DataKey[]) => void;
+    deselect: (id: DataKey | DataKey[]) => void;
+    toggle: (id: DataKey) => void;
+    clearSelection: () => void;
+    isSelected: (id: DataKey) => boolean;
+    getSelection: () => TItem | TItem[] | null;
+    refresh: () => void;
+    fetch: (override?: {
+        query?: string;
+        filters?: TFilters;
+        searchTarget?: ListerSearchTarget;
+    }) => Promise<TItem[]>;
+};
+declare function useData<TItem = any, TFilters = Record<string, any>>(opts: UseDataOptions<TItem, TFilters>): UseDataResult<TItem, TFilters>;
 
 declare const ShadcnJsonEditorVariant: React.ForwardRefExoticComponent<ShadcnJsonEditorProps & React.RefAttributes<JsonEditorIndexHandle>>;
 
-export { FooterBar, HeaderBar, ShadcnJsonEditorVariant as JsonEditor, ListerApi, ListerDefinition, ListerFilterCtx, ListerId, ListerMode, ListerProvider, ListerProviderHost, ListerRuntimeState, ListerSearchMode, ListerSearchPayload, ListerSearchTarget, ListerSessionId, ListerStoreState, ListerUI, OptionList, PresetMap, SearchBar, useLister };
+export { type AnyDef, type AnyState, Ctx, type DataBuildRequestCtx, type DataBuildRequestResult, type DataKey, type DataSearchConfig, type DataSelectionConfig, type DataSelectionKey, type DataSelectionMode, type DataSelector, FooterBar, HeaderBar, type InternalContextValue, ShadcnJsonEditorVariant as JsonEditor, ListerApi, ListerDefinition, ListerFilterCtx, ListerFilterOption, ListerId, ListerMode, ListerProvider, ListerProviderHost, ListerRuntimeState, ListerSearchMode, ListerSearchPayload, ListerSearchTarget, ListerSessionId, ListerStoreState, ListerUI, OptionList, PresetMap, type ResolvedFilterNode, SearchBar, type UseDataOptions, type UseDataResult, buildSearchPayloadFromTarget, useData, useLister };