@proveanything/smartlinks-utils-ui 0.1.13 → 0.3.0

package/dist/components/RecordsAdmin/index.d.ts

@@ -0,0 +1,1083 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import * as _tanstack_query_core from '@tanstack/query-core';
+import { RecordScope, AppRecord, RecordTarget, MatchResult } from '@proveanything/smartlinks/dist/types/appObjects';
+
+type ScopeKind = 'product' | 'facet' | 'variant' | 'batch';
+/** Parsed `ref` string — see `data/refs.ts`. Format: `kind:id` or chain. */
+interface ParsedRef {
+    /** Most-specific scope this ref points at. */
+    kind: ScopeKind | 'collection';
+    /** Raw ref string, e.g. `product:abc123` or `facet:gluten-free/variant:500ml`. */
+    raw: string;
+    collectionId?: string;
+    productId?: string;
+    facetId?: string;
+    facetValue?: string;
+    variantId?: string;
+    batchId?: string;
+    proofId?: string;
+}
+
+type RecordSource = 'self' | 'inherited' | 'empty';
+type RecordStatus = 'configured' | 'partial' | 'empty';
+/** Optional badge displayed on a record card or row. */
+interface RecordBadge {
+    label: string;
+    /** Semantic tone — apps may map to their own colour vocabulary. */
+    tone?: 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+}
+interface RecordSummary<TData = unknown> {
+    id: string | null;
+    ref: string;
+    scope: ParsedRef;
+    data: TData | null;
+    status: RecordStatus;
+    /** Display label for the list row. */
+    label: string;
+    /** Optional subtitle (e.g. SKU, GTIN). */
+    subtitle?: string;
+    updatedAt?: string;
+    /**
+     * Optional thumbnail URL used by card / gallery presentations. Apps that
+     * don't supply one fall back to a coloured tile with the label initials.
+     */
+    thumbnail?: string;
+    /** Optional small badges (e.g. "Draft", "12 items"). */
+    badges?: RecordBadge[];
+    /**
+     * For `collection` cardinality record types: the per-item identifier within
+     * a scope. The full ref is `{scopeRef}/item:{itemId}`. Singleton records
+     * leave this undefined.
+     */
+    itemId?: string;
+}
+interface ResolvedRecord<TData = unknown> {
+    data: TData | null;
+    source: RecordSource;
+    /** Where the resolved value came from (own scope or parent ref). */
+    sourceRef?: string;
+    /** The parent value that would be inherited if this scope cleared its override. */
+    parentValue?: TData | null;
+}
+
+interface EditorContext<TData = unknown> {
+    value: TData;
+    onChange: (next: TData) => void;
+    source: RecordSource;
+    parentValue?: TData | null;
+    scope: ParsedRef;
+    isDirty: boolean;
+    save: () => Promise<void>;
+    /** Discard local changes (reverts to last saved/inherited value). */
+    reset: () => void;
+    /** Permanently delete this record's own override (when `source === 'self'`). */
+    remove: () => Promise<void>;
+    /** True when a saved-own record exists that can be removed. */
+    canRemove: boolean;
+    /** True while an optimistic save is in flight (request not yet acknowledged). */
+    isSaving?: boolean;
+    /** Last save error, if any. Cleared when the next save attempt starts. */
+    saveError?: unknown | null;
+}
+
+interface CsvSchemaColumn<TData> {
+    key: string;
+    header: string;
+    toCell: (v: TData) => string;
+    fromCell: (s: string) => unknown;
+}
+interface CsvSchema<TData> {
+    columns: Array<CsvSchemaColumn<TData>>;
+    validate?: (row: Record<string, unknown>) => string | null;
+}
+
+/**
+ * How records are laid out in the browse rail / panel.
+ * - `list`     → dense rows with status dot + label + subtitle (default).
+ * - `grid`     → square cards with thumbnail + label.
+ * - `gallery`  → larger 16:9 cards with thumbnail + label + subtitle.
+ * - `compact`  → minimal one-line rows (no subtitle, no status dot).
+ */
+type RecordPresentation = 'list' | 'grid' | 'gallery' | 'compact';
+declare const ALL_PRESENTATIONS: RecordPresentation[];
+/**
+ * Whether each scope holds at most one record of this type, or many.
+ * - `singleton`  → one record per scope (e.g. washing instructions). Default.
+ * - `collection` → many records per scope (e.g. FAQs, recipes, SOPs).
+ */
+type RecordCardinality = 'singleton' | 'collection';
+/**
+ * How `useCollectedRecords` orders the aggregated chain.
+ * - `specificity` → most-specific scope first (default).
+ * - `field`       → use a numeric/string `data.<field>` to sort.
+ */
+type CollectedSort = {
+    kind: 'specificity';
+    direction?: 'asc' | 'desc';
+} | {
+    kind: 'field';
+    field: string;
+    direction?: 'asc' | 'desc';
+};
+
+type TelemetryEvent = {
+    type: 'record.save';
+    recordType: string;
+    ref: string;
+    isCreate: boolean;
+} | {
+    type: 'record.delete';
+    recordType: string;
+    ref: string;
+} | {
+    type: 'scope.change';
+    recordType: string;
+    from: ScopeKind;
+    to: ScopeKind;
+} | {
+    type: 'intro.dismiss';
+    recordType: string;
+} | {
+    type: 'csv.import';
+    recordType: string;
+    rows: number;
+    errors: number;
+} | {
+    type: 'csv.export';
+    recordType: string;
+    rows: number;
+} | {
+    type: 'bulk.apply';
+    recordType: string;
+    targetCount: number;
+} | {
+    type: 'presentation.change';
+    recordType: string;
+    from: RecordPresentation;
+    to: RecordPresentation;
+} | {
+    type: 'item.create';
+    recordType: string;
+    scopeRef: string;
+};
+
+interface RecordsAdminI18n {
+    emptyTitle: string;
+    emptyBody: string;
+    noResults: string;
+    searchPlaceholder: string;
+    filterAll: string;
+    filterConfigured: string;
+    filterPartial: string;
+    filterEmpty: string;
+    save: string;
+    discard: string;
+    delete: string;
+    /** Save button label while a save is in flight. */
+    saving: string;
+    /** Inline error label shown next to the Save button when a save fails. */
+    saveError: string;
+    inherited: string;
+    override: string;
+    reset: string;
+    bulkActions: string;
+    applyToMany: string;
+    copyFrom: string;
+    clear: string;
+    importCsv: string;
+    exportCsv: string;
+    preview: string;
+    editor: string;
+    closePreview: string;
+    openPreview: string;
+    previewAs: string;
+    previewAsDefault: string;
+    confirmDelete: string;
+    unsavedBadge: string;
+    unsavedPromptTitle: string;
+    unsavedPromptBody: string;
+    unsavedPromptDiscard: string;
+    unsavedPromptCancel: string;
+    unsavedPromptSave: string;
+    /** Presentation mode switcher labels. */
+    presentationList: string;
+    presentationGrid: string;
+    presentationGallery: string;
+    presentationCompact: string;
+    /** Collection cardinality affordances. */
+    newItem: string;
+    noItemsTitle: string;
+    noItemsBody: string;
+}
+declare const DEFAULT_I18N: RecordsAdminI18n;
+
+/** Minimal SDK shape consumed by the shell. */
+type SmartLinksSDK = any;
+/** Slot context passed to renderCard / renderListRow. */
+interface RecordSlotContext {
+    selected: boolean;
+    onSelect: () => void;
+    isDirty?: boolean;
+}
+interface RecordsAdminShellProps<TData = unknown> {
+    SL: SmartLinksSDK;
+    appId: string;
+    collectionId: string;
+    recordType: string;
+    label: string;
+    scopes: ScopeKind[];
+    defaultScope?: ScopeKind;
+    /**
+     * Context from the host URL (productId/variantId/batchId).
+     * When provided, the browser is constrained to that subtree:
+     * — `batchId` set → editing one batch (no list / variants pinned)
+     * — `variantId` set → list of batches under that variant
+     * — `productId` set → list of variants/batches/the product itself
+     * — none set → full collection-level browser (current behaviour)
+     */
+    contextScope?: {
+        productId?: string;
+        variantId?: string;
+        batchId?: string;
+    };
+    renderEditor: (ctx: EditorContext<TData>) => ReactNode;
+    /**
+     * Render the preview surface. Receives the editor's current value so the
+     * preview tracks unsaved edits. When `previewScope` differs from the
+     * editing scope (because the user picked something in `<PreviewScopePicker>`),
+     * `previewScope` reflects the chosen target — apps can use it to load
+     * resolved/collected/merged data for that scope instead of `resolved`.
+     */
+    renderPreview?: (ctx: {
+        resolved: TData | null;
+        previewScope: ParsedRef;
+    }) => ReactNode;
+    /**
+     * How the preview surface attaches to the editor pane.
+     * - `inline` (default): rendered below the form (current behaviour).
+     * - `side`:   resizable right pane next to the editor.
+     * - `tab`:    Editor / Preview siblings inside the right pane.
+     * - `drawer`: slide-out from the right, toggled by a button.
+     */
+    previewMode?: 'inline' | 'side' | 'tab' | 'drawer';
+    /**
+     * When true, render a `<PreviewScopePicker>` in the preview chrome so admins
+     * can preview as a different product/variant/batch than they're editing.
+     * Default false.
+     */
+    previewScopePicker?: boolean;
+    /**
+     * How to handle unsaved edits when the user navigates to a different
+     * record/scope/tab.
+     * - `prompt` (default): show a confirm dialog (Discard / Cancel / Save).
+     * - `autosave`: silently save before navigating away.
+     * - `keep`: hold edits in memory keyed by ref; coming back restores them.
+     */
+    dirtyStrategy?: 'prompt' | 'autosave' | 'keep';
+    /**
+     * Pre-delete hook. Return `false` to abort. Lets apps run app-specific
+     * confirms (e.g. "this batch has 12k linked proofs"). When omitted the
+     * inline two-step confirm is the only safeguard.
+     */
+    onBeforeDelete?: (scope: ParsedRef) => boolean | Promise<boolean>;
+    /**
+     * Disable the browser-level `beforeunload` prompt. Default false.
+     * Set true when the host platform handles unload guarding itself.
+     */
+    disableBeforeUnload?: boolean;
+    intro?: {
+        title: string;
+        body: ReactNode;
+    };
+    csvSchema?: CsvSchema<TData>;
+    classify?: (record: RecordSummary<TData>) => RecordStatus;
+    defaultData?: () => TData;
+    /**
+     * Which layouts the rail offers. Default `['list']`. When more than one is
+     * supplied, a switcher appears above the list and the choice persists
+     * per-app/recordType.
+     */
+    presentations?: RecordPresentation[];
+    /** Initial presentation when nothing is persisted. Default first of `presentations`. */
+    defaultPresentation?: RecordPresentation;
+    /**
+     * Optional custom card renderer used by `grid` / `gallery` presentations.
+     * If omitted the shell uses `<DefaultRecordCard>`.
+     */
+    renderCard?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
+    /**
+     * Optional custom list-row renderer used by `list` / `compact` presentations.
+     * If omitted the shell uses `<DefaultRecordRow>`.
+     */
+    renderListRow?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
+    /**
+     * Optional custom empty-state renderer for the rail. If omitted the shell
+     * uses the default `<EmptyState>` with `i18n.emptyTitle` / `i18n.emptyBody`.
+     */
+    renderEmpty?: (ctx: {
+        scope: ParsedRef | null;
+    }) => ReactNode;
+    /**
+     * Whether each scope holds at most one record (`singleton`, default) or
+     * many (`collection`, e.g. FAQs / recipes / SOPs). In collection mode the
+     * shell treats scopes as folders containing items, exposes a "+ New" action,
+     * and the `RecordEditor` works on individual items via `itemId`-suffixed refs.
+     */
+    cardinality?: RecordCardinality;
+    /** Display name for an item in collection mode (defaults to `'item'`). */
+    itemNoun?: string;
+    /**
+     * Generate a per-item id when "+ New" is clicked. Defaults to a ULID-like
+     * timestamp+random string.
+     */
+    generateItemId?: () => string;
+    i18n?: Partial<RecordsAdminI18n>;
+    onTelemetry?: (event: TelemetryEvent) => void;
+    className?: string;
+}
+
+declare function RecordsAdminShell<TData = unknown>(props: RecordsAdminShellProps<TData>): react_jsx_runtime.JSX.Element;
+
+interface RecordBrowserProps {
+    scopes: ScopeKind[];
+    activeScope: ScopeKind;
+    onActiveScopeChange: (s: ScopeKind) => void;
+    selectedRef?: string;
+    onSelectRef: (item: RecordSummary) => void;
+    items: RecordSummary[];
+    counts: {
+        all: number;
+        configured: number;
+        partial: number;
+        empty: number;
+    };
+    isLoading: boolean;
+    error: Error | null;
+    filter: 'all' | RecordStatus;
+    onFilterChange: (v: 'all' | RecordStatus) => void;
+    search: string;
+    onSearchChange: (v: string) => void;
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    onLoadMore?: () => void;
+    scopesLoading?: boolean;
+    i18n: RecordsAdminI18n;
+}
+declare const RecordBrowser: ({ scopes, activeScope, onActiveScopeChange, selectedRef, onSelectRef, items, counts, isLoading, error, filter, onFilterChange, search, onSearchChange, hasNextPage, isFetchingNextPage, onLoadMore, scopesLoading, i18n, }: RecordBrowserProps) => react_jsx_runtime.JSX.Element;
+
+interface Props$9 {
+    scopes: ScopeKind[];
+    active: ScopeKind;
+    onChange: (s: ScopeKind) => void;
+    /** When true, tabs render disabled (used while collection flags are loading). */
+    loading?: boolean;
+}
+declare const ScopeTabs: ({ scopes, active, onChange, loading }: Props$9) => react_jsx_runtime.JSX.Element;
+
+interface Props$8 {
+    source?: RecordSource;
+    status?: RecordStatus;
+    className?: string;
+}
+/** Emerald = own data, amber = inherited, muted = empty */
+declare const StatusDot: ({ source, status, className }: Props$8) => react_jsx_runtime.JSX.Element;
+
+interface Props$7 {
+    value: 'all' | RecordStatus;
+    onChange: (v: 'all' | RecordStatus) => void;
+    counts: {
+        all: number;
+        configured: number;
+        partial: number;
+        empty: number;
+    };
+    i18n: RecordsAdminI18n;
+}
+declare const StatusFilterPills: ({ value, onChange, counts, i18n }: Props$7) => react_jsx_runtime.JSX.Element;
+
+interface Props$6 {
+    items: RecordSummary[];
+    selectedRef?: string;
+    onSelect: (item: RecordSummary) => void;
+    /** When set, the matching row gets a small "unsaved" indicator. */
+    dirtyRef?: string;
+    /** Layout. Defaults to `list` for full back-compat. */
+    presentation?: RecordPresentation;
+    /** Optional override for `list` / `compact` rows. */
+    renderListRow?: (record: RecordSummary, ctx: RecordSlotContext) => ReactNode;
+    /** Optional override for `grid` / `gallery` cards. */
+    renderCard?: (record: RecordSummary, ctx: RecordSlotContext) => ReactNode;
+}
+declare const RecordList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, }: Props$6) => react_jsx_runtime.JSX.Element;
+declare const ProductList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, }: Props$6) => react_jsx_runtime.JSX.Element;
+declare const FacetList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, }: Props$6) => react_jsx_runtime.JSX.Element;
+declare const VariantList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, }: Props$6) => react_jsx_runtime.JSX.Element;
+declare const BatchList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, }: Props$6) => react_jsx_runtime.JSX.Element;
+
+interface DefaultRecordRowProps {
+    record: RecordSummary;
+    ctx: RecordSlotContext;
+    /** Drop the status dot + subtitle (used by the `compact` preset). */
+    compact?: boolean;
+}
+declare const DefaultRecordRow: ({ record, ctx, compact }: DefaultRecordRowProps) => react_jsx_runtime.JSX.Element;
+
+interface DefaultRecordCardProps {
+    record: RecordSummary;
+    ctx: RecordSlotContext;
+    /** `grid` → 1:1, `gallery` → 16:9 with denser meta. Default `grid`. */
+    variant?: 'grid' | 'gallery';
+}
+declare const DefaultRecordCard: ({ record, ctx, variant }: DefaultRecordCardProps) => react_jsx_runtime.JSX.Element;
+
+interface PresentationSwitcherProps {
+    options: RecordPresentation[];
+    value: RecordPresentation;
+    onChange: (next: RecordPresentation) => void;
+    i18n: RecordsAdminI18n;
+}
+declare const PresentationSwitcher: ({ options, value, onChange, i18n }: PresentationSwitcherProps) => react_jsx_runtime.JSX.Element | null;
+
+declare const EmptyState: ({ title, body, action }: {
+    title: string;
+    body?: ReactNode;
+    action?: ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+declare const LoadingState: () => react_jsx_runtime.JSX.Element;
+declare const ErrorState: ({ error }: {
+    error: Error;
+}) => react_jsx_runtime.JSX.Element;
+
+interface Props$5 {
+    i18n: RecordsAdminI18n;
+    onApplyToMany?: () => void;
+    onCopyFrom?: () => void;
+    onClearMany?: () => void;
+    onImportCsv?: () => void;
+    onExportCsv?: () => void;
+}
+declare const BulkActionsMenu: ({ i18n, onApplyToMany, onCopyFrom, onClearMany, onImportCsv, onExportCsv, }: Props$5) => react_jsx_runtime.JSX.Element | null;
+
+interface Props$4<T> {
+    ctx: EditorContext<T>;
+    i18n: RecordsAdminI18n;
+    children: ReactNode;
+    preview?: ReactNode;
+    bulkActions?: React.ComponentProps<typeof BulkActionsMenu>;
+    /** Extra slot rendered in the footer between the danger actions and Save. */
+    footerExtra?: ReactNode;
+    /** Optional pre-delete hook (see DeleteButton). */
+    onBeforeDelete?: () => boolean | Promise<boolean>;
+}
+declare function RecordEditor<T>({ ctx, i18n, children, preview, bulkActions, footerExtra, onBeforeDelete, }: Props$4<T>): react_jsx_runtime.JSX.Element;
+
+interface InheritanceCtx {
+    parentValue?: Record<string, unknown> | null;
+    ownValue?: Record<string, unknown> | null;
+    onResetField?: (field: string) => void;
+}
+declare const InheritanceProvider: ({ parentValue, ownValue, onResetField, children, }: InheritanceCtx & {
+    children: ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+interface MarkerProps {
+    field: string;
+    inheritedValue?: unknown;
+    value?: unknown;
+    children: ReactNode;
+}
+declare const InheritanceMarker: ({ field, inheritedValue, value, children }: MarkerProps) => react_jsx_runtime.JSX.Element;
+
+interface Props$3 {
+    children: ReactNode;
+}
+declare const ResolvedPreview: ({ children }: Props$3) => react_jsx_runtime.JSX.Element;
+
+interface ProductChildItem {
+    /** Variant or batch id (the `<id>` part of `variant:<id>` / `batch:<id>`). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Optional subtitle (sku, expiry, etc.). */
+    subtitle?: string;
+}
+interface UseProductChildrenArgs {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    productId: string | undefined;
+    /** Which child kind to fetch. Hooks only fire when both productId and kind are set. */
+    kind: 'variant' | 'batch' | null;
+    enabled?: boolean;
+}
+/**
+ * Lazy children loader. When `kind` is `null` or `productId` is missing the
+ * underlying query is disabled, so opening the shell at collection level never
+ * touches `variant.list` / `batch.list`.
+ */
+declare const useProductChildren: (args: UseProductChildrenArgs) => {
+    items: ProductChildItem[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+
+type DrillTab = 'product' | 'variant' | 'batch';
+interface Props$2 {
+    productLabel: string;
+    /** Which child types are available on the collection. */
+    showVariants: boolean;
+    showBatches: boolean;
+    active: DrillTab;
+    onChange: (tab: DrillTab) => void;
+    /** Currently selected child id (variant or batch), if any. */
+    selectedChildId?: string;
+    onSelectChild: (id: string) => void;
+    variants: ProductChildItem[];
+    batches: ProductChildItem[];
+    variantsLoading: boolean;
+    batchesLoading: boolean;
+    /** Editor body rendered to the right of the picker. */
+    children: ReactNode;
+}
+declare const ProductDrillDown: ({ productLabel, showVariants, showBatches, active, onChange, selectedChildId, onSelectChild, variants, batches, variantsLoading, batchesLoading, children, }: Props$2) => react_jsx_runtime.JSX.Element;
+
+type PreviewMode = 'inline' | 'side' | 'tab' | 'drawer';
+interface CommonProps {
+    /** App-rendered preview body. */
+    children: ReactNode;
+    /** Optional scope picker rendered in the chrome header. */
+    scopePicker?: ReactNode;
+    /** Header label (defaults to "Preview"). */
+    label?: string;
+}
+declare const InlinePreview: ({ children, scopePicker, label }: CommonProps) => react_jsx_runtime.JSX.Element;
+declare const SidePreview: ({ children, scopePicker, label }: CommonProps) => react_jsx_runtime.JSX.Element;
+interface TabbedPreviewProps {
+    editor: ReactNode;
+    preview: ReactNode;
+    scopePicker?: ReactNode;
+    /** Initial active tab (default `editor`). */
+    defaultTab?: 'editor' | 'preview';
+    i18n?: {
+        editor?: string;
+        preview?: string;
+    };
+}
+declare const TabbedPreview: ({ editor, preview, scopePicker, defaultTab, i18n, }: TabbedPreviewProps) => react_jsx_runtime.JSX.Element;
+interface DrawerPreviewProps extends CommonProps {
+    open: boolean;
+    onClose: () => void;
+    /** Drawer width (default 420). */
+    width?: number;
+}
+declare const DrawerPreview: ({ open, onClose, children, scopePicker, label, width, }: DrawerPreviewProps) => react_jsx_runtime.JSX.Element | null;
+declare const PreviewToggleButton: ({ onClick, label, }: {
+    onClick: () => void;
+    label?: string;
+}) => react_jsx_runtime.JSX.Element;
+
+interface PreviewScopePickerProps {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    /** The scope currently being edited — used as the "Same as edited" default. */
+    editingScope: ParsedRef;
+    /** The current preview scope. */
+    value: ParsedRef;
+    onChange: (next: ParsedRef) => void;
+    /** Are variants/batches available for drill-down. */
+    showVariants: boolean;
+    showBatches: boolean;
+    /** i18n strings (uses defaults if omitted). */
+    i18n?: {
+        previewAs?: string;
+        previewAsDefault?: string;
+    };
+}
+declare const PreviewScopePicker: ({ SL, collectionId, editingScope, value, onChange, showVariants, showBatches, i18n, }: PreviewScopePickerProps) => react_jsx_runtime.JSX.Element;
+
+declare const ScopeBreadcrumb: ({ scope }: {
+    scope: ParsedRef;
+}) => react_jsx_runtime.JSX.Element | null;
+
+interface Props$1 {
+    title: string;
+    body: ReactNode;
+    onDismiss: () => void;
+}
+declare const IntroCard: ({ title, body, onDismiss }: Props$1) => react_jsx_runtime.JSX.Element;
+
+interface Props {
+    label: string;
+    recordType: string;
+    introHidden: boolean;
+    onShowIntro?: () => void;
+}
+declare const UtilityRow: ({ label, recordType, introHidden, onShowIntro }: Props) => react_jsx_runtime.JSX.Element;
+
+interface RecordsCtx {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    appId: string;
+    recordType: string;
+}
+/** Shape of a single record write — uses the SDK's structured `scope`. */
+interface RecordWrite<T = unknown> {
+    /** Logical key. The server canonicalises this from `scope` if omitted. */
+    ref?: string;
+    /** Structured scope; required for specificity / `match()` to work. */
+    scope: RecordScope;
+    data: T;
+    visibility?: 'public' | 'owner' | 'admin';
+    productId?: string;
+    status?: string;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    customId?: string;
+    sourceSystem?: string;
+}
+declare const listRecords: (ctx: RecordsCtx, params?: {
+    ref?: string;
+    refPrefix?: string;
+    q?: string;
+    limit?: number;
+    offset?: number;
+    sort?: string;
+}) => Promise<{
+    data: AppRecord[];
+    total: number;
+    hasMore: boolean;
+}>;
+/** Look up a single record by its canonical ref. */
+declare const getRecordByRef: (ctx: RecordsCtx, ref: string) => Promise<AppRecord | null>;
+/**
+ * Atomic upsert via the SDK. Always sends `scope` so the server can compute
+ * `specificity` and derive `ref` deterministically.
+ */
+declare const upsertRecord: <T>(ctx: RecordsCtx, write: RecordWrite<T>) => Promise<{
+    record: AppRecord;
+    isCreate: boolean;
+}>;
+declare const deleteRecord: (ctx: RecordsCtx, ref: string) => Promise<boolean>;
+/** Restore a soft-deleted record by ID (admin only). */
+declare const restoreRecord: (ctx: RecordsCtx, recordId: string) => Promise<AppRecord>;
+/**
+ * Server-side match — single round trip that returns every record whose
+ * `scope` is satisfied by `target`, ordered by descending `specificity`.
+ * Replaces the per-scope N+1 chain walk we used pre-1.9.
+ */
+declare const matchRecords: (ctx: RecordsCtx, target: RecordTarget, opts?: {
+    strategy?: "all" | "best";
+    at?: string;
+    includeScheduled?: boolean;
+    includeExpired?: boolean;
+    limit?: number;
+}) => Promise<MatchResult>;
+/**
+ * Server-side bulk upsert. Up to 500 rows per call; any leftover is chunked.
+ * Each row is error-isolated by the server.
+ */
+declare const bulkUpsert: <T>(ctx: RecordsCtx, entries: Array<{
+    ref?: string;
+    scope: RecordScope;
+    data: T;
+    status?: string;
+}>) => Promise<{
+    saved: number;
+    failed: number;
+}>;
+/**
+ * Server-side bulk delete. Accepts an explicit ref list (max 1000 per call,
+ * chunked here) or a scope anchor (single call).
+ */
+declare const bulkDelete: (ctx: RecordsCtx, input: {
+    refs: string[];
+} | {
+    scope: Omit<RecordScope, "facets">;
+}) => Promise<{
+    removed: number;
+}>;
+
+interface UseRecordListArgs {
+    ctx: RecordsCtx;
+    scopeKind: ScopeKind;
+    search?: string;
+    filter?: 'all' | RecordStatus;
+    classify?: (record: RecordSummary) => RecordStatus;
+    enabled?: boolean;
+    scaffolder?: (existing: RecordSummary[]) => Promise<RecordSummary[]> | RecordSummary[];
+    /**
+     * Constrain the list to a subtree (e.g. a specific product when the host URL
+     * pins one). Records whose ParsedRef does not match every set field are dropped.
+     */
+    contextScope?: {
+        productId?: string;
+        variantId?: string;
+        batchId?: string;
+    };
+    /** Page size requested from the SDK (default 100). */
+    pageSize?: number;
+}
+declare const useRecordList: (args: UseRecordListArgs) => {
+    items: RecordSummary<unknown>[];
+    total: number;
+    counts: {
+        all: number;
+        configured: number;
+        partial: number;
+        empty: number;
+    };
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<{
+        data: AppRecord[];
+        total: number;
+        hasMore: boolean;
+        nextOffset: number;
+    }, unknown>, Error>>;
+};
+
+interface UseRecordEditorArgs<T> {
+    ctx: RecordsCtx;
+    scope: ParsedRef;
+    resolved: ResolvedRecord<T>;
+    defaultData?: () => T;
+    onSaved?: () => void;
+    onDeleted?: () => void;
+    /** Fired after a save fails and local state has been rolled back. */
+    onSaveError?: (err: unknown) => void;
+    /**
+     * Controls how the editor reseeds its local value when the resolved
+     * record changes. Default `'always'` matches legacy behaviour.
+     * `'preserve-dirty'` keeps unsaved local edits across resolve refreshes
+     * (used by the shell when `dirtyStrategy === 'keep'`).
+     */
+    reseed?: 'always' | 'preserve-dirty';
+}
+declare function useRecordEditor<T>(args: UseRecordEditorArgs<T>): EditorContext<T>;
+
+interface UseResolvedRecordArgs {
+    SL: SmartLinksSDK;
+    appId: string;
+    recordType: string;
+    collectionId: string;
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    facetId?: string;
+    facetValue?: string;
+    proofId?: string;
+    supportedScopes?: ScopeKind[];
+    enabled?: boolean;
+    withParent?: boolean;
+}
+declare function useResolvedRecord<T = unknown>(args: UseResolvedRecordArgs): {
+    isLoading: boolean;
+    error: Error | null;
+    data: T | null;
+    source: RecordSource;
+    sourceRef?: string;
+    parentValue?: T | null | undefined;
+};
+
+interface UseScopeProbeArgs {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    /** Force admin endpoint when fetching the collection (default true). */
+    admin?: boolean;
+    enabled?: boolean;
+}
+/**
+ * Reports whether a collection has variants/batches enabled.
+ *
+ * Uses the canonical `Collection.variants` / `Collection.batches` boolean flags
+ * from `SL.collection.get(collectionId)` (SDK ≥ 1.9). No more guessing by
+ * probing list endpoints.
+ */
+declare const useScopeProbe: ({ SL, collectionId, admin, enabled }: UseScopeProbeArgs) => {
+    hasVariants: boolean;
+    hasBatches: boolean;
+    isLoading: boolean;
+    error: Error | null;
+};
+
+declare const useIntroDismissed: (SL: SmartLinksSDK, collectionId: string, appId: string, recordType: string) => {
+    dismissed: boolean;
+    dismiss: () => Promise<void>;
+    undismiss: () => void;
+};
+
+interface ProductBrowseItem {
+    /** Product id (used in refs as `product:<id>`). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Optional subtitle. */
+    sku?: string | null;
+    /** Optional ordering hint. */
+    sortOrder?: number | null;
+}
+interface UseProductBrowseArgs {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    search?: string;
+    /** Soft cap per page (default 50). */
+    pageSize?: number;
+    enabled?: boolean;
+    /** Override admin flag if needed (default true). */
+    admin?: boolean;
+}
+/**
+ * Cursor-paginated product list backed by `SL.product.query`. When the SDK
+ * returns a `nextCursor`, we use it; otherwise we fall back to offset-based
+ * paging so the hook works against older SDKs or in-memory adapters too.
+ */
+declare const useProductBrowse: (args: UseProductBrowseArgs) => {
+    items: any[];
+    total: any;
+    isLoading: boolean;
+    error: Error | null;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<{
+        items: any;
+        nextOffset: any;
+        nextCursor: any;
+        hasMore: any;
+        total: any;
+    }, unknown>, Error>>;
+    refetch: () => Promise<void>;
+};
+
+interface CollectedRecord<T = unknown> {
+    /** The ref this record was loaded from. */
+    ref: string;
+    /** Parsed scope of the ref (gives you `productId`, `facetId`, etc.). */
+    scope: ParsedRef;
+    /** Domain payload. */
+    data: T;
+    /** Index in the resolution chain (0 = most-specific). */
+    depth: number;
+}
+interface UseCollectedRecordsArgs {
+    SL: SmartLinksSDK;
+    appId: string;
+    recordType: string;
+    collectionId: string;
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    facetId?: string;
+    facetValue?: string;
+    /** Scopes to walk. Defaults to all four. */
+    supportedScopes?: ScopeKind[];
+    /** Drop scopes that don't have a record (default true). */
+    filterEmpty?: boolean;
+    /**
+     * Ordering applied to the result. Defaults to specificity-descending
+     * (most-specific scope first), matching the previous behaviour and aligning
+     * with the future `match()` API.
+     */
+    sort?: CollectedSort;
+    enabled?: boolean;
+}
+declare function useCollectedRecords<T = unknown>(args: UseCollectedRecordsArgs): {
+    items: CollectedRecord<T>[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<CollectedRecord<T>[], Error>>;
+};
+
+type MergeStrategy = 'deep' | 'shallow';
+interface MergedRecord<T = unknown> {
+    /** The merged result. */
+    data: T | null;
+    /**
+     * For each top-level key, the ref of the record that contributed its
+     * winning value. Useful for "Inherited from facet:gluten-free" hints.
+     */
+    provenance: Record<string, string>;
+    /** Refs that contributed something to the merge, deepest-first. */
+    layers: string[];
+}
+interface UseMergedRecordArgs<T> {
+    SL: SmartLinksSDK;
+    appId: string;
+    recordType: string;
+    collectionId: string;
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    facetId?: string;
+    facetValue?: string;
+    supportedScopes?: ScopeKind[];
+    /**
+     * Merge strategy. `deep` recursively merges plain objects; arrays are
+     * replaced wholesale. `shallow` does Object.assign at the top level.
+     * Default `deep`.
+     */
+    strategy?: MergeStrategy;
+    /** Custom merge fn. Receives `(parent, child)` and returns the winner. */
+    merge?: (parent: T | null, child: T) => T;
+    enabled?: boolean;
+}
+declare function useMergedRecord<T = unknown>(args: UseMergedRecordArgs<T>): {
+    isLoading: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_query_core.RefetchOptions) => Promise<_tanstack_query_core.QueryObserverResult<MergedRecord<T>, Error>>;
+    /** The merged result. */
+    data: T | null;
+    /**
+     * For each top-level key, the ref of the record that contributed its
+     * winning value. Useful for "Inherited from facet:gluten-free" hints.
+     */
+    provenance: Record<string, string>;
+    /** Refs that contributed something to the merge, deepest-first. */
+    layers: string[];
+};
+
+interface UseUnsavedGuardArgs {
+    /** Whether there are unsaved edits right now. */
+    isDirty: boolean;
+    /**
+     * Optional human-friendly label (e.g. recordType). Posted to the parent
+     * frame so the host can describe what's unsaved.
+     */
+    label?: string;
+    /**
+     * Optional async confirm impl. Defaults to `window.confirm`. Apps can pass
+     * a custom dialog (e.g. a shadcn AlertDialog promise wrapper).
+     */
+    confirm?: (message: string) => boolean | Promise<boolean>;
+    /**
+     * Disable the browser-level `beforeunload` listener (e.g. when running
+     * inside a host that handles it already). Default false.
+     */
+    disableBeforeUnload?: boolean;
+    /**
+     * Disable the parent-frame `postMessage` notification. Default false.
+     */
+    disableParentMessage?: boolean;
+}
+/**
+ * Tracks unsaved state and wires up the browser/iframe guards. Returns a
+ * `confirmDiscard` helper apps can `await` from their own navigation code.
+ */
+declare function useUnsavedGuard({ isDirty, label, confirm, disableBeforeUnload, disableParentMessage, }: UseUnsavedGuardArgs): {
+    confirmDiscard: (message?: string) => Promise<boolean>;
+};
+
+type DirtyStrategy = 'prompt' | 'autosave' | 'keep';
+interface UseDirtyNavigationArgs {
+    strategy: DirtyStrategy;
+    isDirty: boolean;
+    /** Persist current edits. Resolves when the SDK call completes. */
+    save: () => void | Promise<void>;
+    /** Discard local edits to the saved snapshot. */
+    reset: () => void;
+    /**
+     * Confirm impl: returns `'save' | 'discard' | 'cancel'`. Defaults to a
+     * `window.confirm` fallback (Save = OK, Discard = Cancel, no Cancel option).
+     */
+    confirm?: (i18n?: NavConfirmI18n) => Promise<'save' | 'discard' | 'cancel'>;
+    i18n?: NavConfirmI18n;
+}
+interface NavConfirmI18n {
+    title?: string;
+    body?: string;
+    save?: string;
+    discard?: string;
+    cancel?: string;
+}
+/**
+ * Returns `runWithGuard(action)` — call it instead of executing the
+ * navigation directly. The guard handles dirty-state policy and only calls
+ * `action()` when it's safe to proceed.
+ */
+declare const useDirtyNavigation: ({ strategy, isDirty, save, reset, confirm, i18n, }: UseDirtyNavigationArgs) => {
+    runWithGuard: (action: () => void) => Promise<boolean>;
+};
+
+declare function usePresentationPref(args: {
+    appId: string;
+    recordType: string;
+    options: RecordPresentation[];
+    defaultValue: RecordPresentation;
+}): [RecordPresentation, (next: RecordPresentation) => void];
+
+interface DeleteButtonProps {
+    /** Performs the delete. Should resolve when the SDK call completes. */
+    onConfirm: () => void | Promise<void>;
+    /**
+     * Optional async pre-check — return false to abort BEFORE the inline
+     * confirm flips. Lets apps run their own modal for high-stakes deletes.
+     */
+    onBeforeDelete?: () => boolean | Promise<boolean>;
+    /** Default label (idle state). */
+    label?: string;
+    /** Confirm-state label. */
+    confirmLabel?: string;
+    /** Auto-revert timeout in ms (default 3000). */
+    revertMs?: number;
+    disabled?: boolean;
+}
+declare const DeleteButton: ({ onConfirm, onBeforeDelete, label, confirmLabel, revertMs, disabled, }: DeleteButtonProps) => react_jsx_runtime.JSX.Element;
+
+declare const parseRef: (raw: string) => ParsedRef;
+interface BuildRefArgs {
+    collectionId?: string;
+    productId?: string;
+    facetId?: string;
+    facetValue?: string;
+    variantId?: string;
+    batchId?: string;
+    proofId?: string;
+}
+declare const buildRef: (a: BuildRefArgs) => string;
+/**
+ * Build the resolution chain for a target ref, from most specific → least specific.
+ * `supportedScopes` prunes scopes the app doesn't care about.
+ */
+declare const resolutionChain: (target: ParsedRef, supportedScopes: ScopeKind[]) => string[];
+
+interface ResolveArgs {
+    ctx: RecordsCtx;
+    target: ParsedRef;
+    /**
+     * Ignored — kept for API compatibility. The server determines the
+     * resolution chain from the structured scope.
+     */
+    supportedScopes?: ScopeKind[];
+    /** When true, also returns the parent value (next-best after self). */
+    withParent?: boolean;
+    admin?: boolean;
+}
+declare const resolveRecord: <T>(args: ResolveArgs) => Promise<ResolvedRecord<T>>;
+
+declare const parsedRefToScope: (ref: ParsedRef) => RecordScope;
+declare const parsedRefToTarget: (ref: ParsedRef) => RecordTarget;
+/**
+ * Compare a winning record's scope against the editing scope.
+ * Returns true when they refer to the same node — used to decide
+ * "self" vs "inherited" when consuming `match()` results.
+ */
+declare const scopesEqual: (a: RecordScope, b: RecordScope) => boolean;
+
+interface ImportReport {
+    total: number;
+    saved: number;
+    failed: number;
+    errorRows: Array<{
+        row: number;
+        error: string;
+    }>;
+    /** Annotated CSV ready for download (input + `error` column). */
+    annotatedCsv: string;
+}
+declare const exportCsv: <T>(records: RecordSummary<T>[], schema: CsvSchema<T>) => Blob;
+declare const importCsv: <T>(file: File, schema: CsvSchema<T>, ctx: RecordsCtx) => Promise<ImportReport>;
+declare const downloadBlob: (blob: Blob, filename: string) => void;
+
+export { ALL_PRESENTATIONS, BatchList, BulkActionsMenu, type CollectedRecord, type CollectedSort, type CsvSchema, type CsvSchemaColumn, DEFAULT_I18N, DefaultRecordCard, DefaultRecordRow, DeleteButton, type DirtyStrategy, DrawerPreview, type EditorContext, EmptyState, ErrorState, FacetList, InheritanceMarker, InheritanceProvider, InlinePreview, IntroCard, LoadingState, type MergeStrategy, type MergedRecord, type NavConfirmI18n, type ParsedRef, PresentationSwitcher, type PreviewMode, PreviewScopePicker, PreviewToggleButton, type ProductBrowseItem, type ProductChildItem, ProductDrillDown, ProductList, type RecordBadge, RecordBrowser, type RecordCardinality, RecordEditor, RecordList, type RecordPresentation, type RecordSlotContext, type RecordSource, type RecordStatus, type RecordSummary, type RecordsAdminI18n, RecordsAdminShell, type RecordsAdminShellProps, ResolvedPreview, type ResolvedRecord, ScopeBreadcrumb, type ScopeKind, ScopeTabs, SidePreview, type SmartLinksSDK, StatusDot, StatusFilterPills, TabbedPreview, type TelemetryEvent, UtilityRow, VariantList, buildRef, bulkDelete, bulkUpsert, deleteRecord, downloadBlob, exportCsv, getRecordByRef, importCsv, listRecords, matchRecords, parseRef, parsedRefToScope, parsedRefToTarget, resolutionChain, resolveRecord, restoreRecord, scopesEqual, upsertRecord, useCollectedRecords, useDirtyNavigation, useIntroDismissed, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordEditor, useRecordList, useResolvedRecord, useScopeProbe, useUnsavedGuard };