@proveanything/smartlinks-utils-ui 0.3.1 → 0.3.4

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

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
+import * as _proveanything_smartlinks_dist_types_appObjects from '@proveanything/smartlinks/dist/types/appObjects';
+import { MatchedAt, FacetRule, RecordScope, AppRecord, RecordTarget, MatchResult, MatchEntry } from '@proveanything/smartlinks/dist/types/appObjects';
 import { LucideIcon } from 'lucide-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. */
@@ -60,6 +61,14 @@ interface ResolvedRecord<TData = unknown> {
     sourceRef?: string;
     /** The parent value that would be inherited if this scope cleared its override. */
     parentValue?: TData | null;
+    /**
+     * Which resolution tier the SDK reported caused the match.
+     * Use this for badges like "Inherited from product" / "Matched by rule".
+     * Present when the resolver ran via SDK 1.10 `match()`/`resolveAll()`.
+     */
+    matchedAt?: MatchedAt;
+    /** The rule that fired. Present only when `matchedAt === 'rule'`. */
+    matchedRule?: FacetRule;
 }
 
 interface EditorContext<TData = unknown> {
@@ -124,42 +133,42 @@ type CollectedSort = {
 
 type TelemetryEvent = {
     type: 'record.save';
-    recordType: string;
+    recordType?: string;
     ref: string;
     isCreate: boolean;
 } | {
     type: 'record.delete';
-    recordType: string;
+    recordType?: string;
     ref: string;
 } | {
     type: 'scope.change';
-    recordType: string;
+    recordType?: string;
     from: ScopeKind;
     to: ScopeKind;
 } | {
     type: 'intro.dismiss';
-    recordType: string;
+    recordType?: string;
 } | {
     type: 'csv.import';
-    recordType: string;
+    recordType?: string;
     rows: number;
     errors: number;
 } | {
     type: 'csv.export';
-    recordType: string;
+    recordType?: string;
     rows: number;
 } | {
     type: 'bulk.apply';
-    recordType: string;
+    recordType?: string;
     targetCount: number;
 } | {
     type: 'presentation.change';
-    recordType: string;
+    recordType?: string;
     from: RecordPresentation;
     to: RecordPresentation;
 } | {
     type: 'item.create';
-    recordType: string;
+    recordType?: string;
     scopeRef: string;
 };
 
@@ -257,7 +266,7 @@ declare const DEFAULT_ICONS: RecordsAdminIcons;
 declare function mergeIcons(override?: Partial<RecordsAdminIcons>): RecordsAdminIcons;
 /** Look up the right header icon based on prop precedence:
  *  explicit `headerIcon` > `icons.header.byRecordType[type]` > `icons.header.default`. */
-declare function pickHeaderIcon(icons: RecordsAdminIcons, recordType: string): LucideIcon;
+declare function pickHeaderIcon(icons: RecordsAdminIcons, recordType?: string): LucideIcon;
 
 /** Minimal SDK shape consumed by the shell. */
 type SmartLinksSDK = any;
@@ -271,7 +280,10 @@ interface RecordsAdminShellProps<TData = unknown> {
     SL: SmartLinksSDK;
     appId: string;
     collectionId: string;
-    recordType: string;
+    /** Logical record type for this app. Optional — when omitted, records are
+     *  saved against the app id alone (no type qualifier). Set this only when an
+     *  app stores multiple distinct record types and needs to query by type. */
+    recordType?: string;
     label: string;
     scopes: ScopeKind[];
     defaultScope?: ScopeKind;
@@ -388,8 +400,19 @@ interface RecordsAdminShellProps<TData = unknown> {
     headerIcon?: ReactNode;
     /** Right-aligned header content — typically a primary "+ New" button + secondary controls. */
     headerActions?: ReactNode;
-    /** Show the per-scope counts strip in the header (Products · Facets · …). Default true. */
+    /** Show a counts strip in the header (e.g. Shared · Products). Off by default —
+     *  most apps don't need it. When `true`, the shell renders built-in counts unless
+     *  `statsItems` is also provided. */
     showStats?: boolean;
+    /** Show the contextual icon to the left of the header title. Default true.
+     *  Set to `false` if the recordType icon (database, etc.) feels off-brand. */
+    showHeaderIcon?: boolean;
+    /** Fully custom stats strip content. When provided, replaces the built-in
+     *  Shared/Products counts. Each item renders as a value + uppercase label. */
+    statsItems?: Array<{
+        label: string;
+        value: string | number;
+    }>;
     /** Override the default Lucide icons used by the shell (scope tabs, statuses,
      *  empty states, action menus, etc.). Deep-merged onto `DEFAULT_ICONS`. */
     icons?: Partial<RecordsAdminIcons>;
@@ -713,7 +736,10 @@ interface RecordsCtx {
     SL: SmartLinksSDK;
     collectionId: string;
     appId: string;
-    recordType: string;
+    /** Optional — when omitted, records are stored against the app id alone
+     *  (no type qualifier). Set this only when an app uses multiple record types
+     *  and needs to query/scope by type. */
+    recordType?: string;
 }
 /** Shape of a single record write — uses the SDK's structured `scope`. */
 interface RecordWrite<T = unknown> {
@@ -856,7 +882,8 @@ declare function useRecordEditor<T>(args: UseRecordEditorArgs<T>): EditorContext
 interface UseResolvedRecordArgs {
     SL: SmartLinksSDK;
     appId: string;
-    recordType: string;
+    /** Optional — see `RecordsAdminShellProps.recordType`. */
+    recordType?: string;
     collectionId: string;
     productId?: string;
     variantId?: string;
@@ -875,8 +902,76 @@ declare function useResolvedRecord<T = unknown>(args: UseResolvedRecordArgs): {
     source: RecordSource;
     sourceRef?: string;
     parentValue?: T | null | undefined;
+    matchedAt?: _proveanything_smartlinks_dist_types_appObjects.MatchedAt;
+    matchedRule?: _proveanything_smartlinks_dist_types_appObjects.FacetRule;
 };
 
+interface UseResolveAllRecordsArgs {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    appId: string;
+    /** Limit to a single record type. Omit to return every type. */
+    recordType?: string;
+    /** Product context — at minimum a productId in most apps. */
+    context: {
+        productId?: string;
+        variantId?: string;
+        batchId?: string;
+        proofId?: string;
+        /**
+         * Facet assignments for the product. Used for both legacy facet refs
+         * and `facetRule` evaluation server-side.
+         * e.g. `{ brand: 'samsung', type: ['tv', 'laptop'] }`
+         */
+        facets?: Record<string, string | string[]>;
+    };
+    /** Restrict to specific tiers (e.g. only `['rule', 'product']`). */
+    tiers?: MatchedAt[];
+    /** Safety cap. Default 500, max 5000. */
+    limit?: number;
+    /** Point-in-time evaluation for scheduled records. ISO 8601. */
+    at?: string;
+    includeScheduled?: boolean;
+    includeExpired?: boolean;
+    /**
+     * `false` to use the public (visibility-filtered) endpoint.
+     * Defaults to `false` so this hook is safe to call from public surfaces.
+     */
+    admin?: boolean;
+    enabled?: boolean;
+    staleTime?: number;
+}
+interface UseResolveAllResult {
+    /** All matching records, sorted most-specific first. Each appears once. */
+    records: MatchEntry[];
+    /** True when the result hit the `limit` safety cap. */
+    truncated: boolean;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+declare function useResolveAllRecords(args: UseResolveAllRecordsArgs): UseResolveAllResult;
+
+interface UseRulePreviewArgs {
+    SL: SmartLinksSDK;
+    collectionId: string;
+    appId: string;
+    rule: FacetRule | null;
+    /** Sample size. Default 20, max 200. */
+    limit?: number;
+    /** Debounce window in ms while the admin types. Default 350ms. */
+    debounceMs?: number;
+    enabled?: boolean;
+}
+interface UseRulePreviewResult {
+    totalMatches: number | null;
+    sampleProductIds: string[];
+    isLoading: boolean;
+    isStale: boolean;
+    error: Error | null;
+}
+declare function useRulePreview(args: UseRulePreviewArgs): UseRulePreviewResult;
+
 interface UseScopeProbeArgs {
     SL: SmartLinksSDK;
     collectionId: string;
@@ -898,7 +993,7 @@ declare const useScopeProbe: ({ SL, collectionId, admin, enabled }: UseScopeProb
     error: Error | null;
 };
 
-declare const useIntroDismissed: (SL: SmartLinksSDK, collectionId: string, appId: string, recordType: string) => {
+declare const useIntroDismissed: (SL: SmartLinksSDK, collectionId: string, appId: string, recordType?: string) => {
     dismissed: boolean;
     dismiss: () => Promise<void>;
     undismiss: () => void;
@@ -959,7 +1054,7 @@ interface CollectedRecord<T = unknown> {
 interface UseCollectedRecordsArgs {
     SL: SmartLinksSDK;
     appId: string;
-    recordType: string;
+    recordType?: string;
     collectionId: string;
     productId?: string;
     variantId?: string;
@@ -1000,7 +1095,7 @@ interface MergedRecord<T = unknown> {
 interface UseMergedRecordArgs<T> {
     SL: SmartLinksSDK;
     appId: string;
-    recordType: string;
+    recordType?: string;
     collectionId: string;
     productId?: string;
     variantId?: string;
@@ -1097,7 +1192,7 @@ declare const useDirtyNavigation: ({ strategy, isDirty, save, reset, confirm, i1
 
 declare function usePresentationPref(args: {
     appId: string;
-    recordType: string;
+    recordType?: string;
     options: RecordPresentation[];
     defaultValue: RecordPresentation;
 }): [RecordPresentation, (next: RecordPresentation) => void];
@@ -1175,4 +1270,4 @@ declare const exportCsv: <T>(records: RecordSummary<T>[], schema: CsvSchema<T>)
 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, DEFAULT_ICONS, 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, type RecordsAdminIcons, 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, mergeIcons, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, resolutionChain, resolveRecord, restoreRecord, scopesEqual, upsertRecord, useCollectedRecords, useDirtyNavigation, useIntroDismissed, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordEditor, useRecordList, useResolvedRecord, useScopeProbe, useUnsavedGuard };
+export { ALL_PRESENTATIONS, BatchList, BulkActionsMenu, type CollectedRecord, type CollectedSort, type CsvSchema, type CsvSchemaColumn, DEFAULT_I18N, DEFAULT_ICONS, 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, type RecordsAdminIcons, RecordsAdminShell, type RecordsAdminShellProps, ResolvedPreview, type ResolvedRecord, ScopeBreadcrumb, type ScopeKind, ScopeTabs, SidePreview, type SmartLinksSDK, StatusDot, StatusFilterPills, TabbedPreview, type TelemetryEvent, type UseResolveAllRecordsArgs, type UseResolveAllResult, type UseRulePreviewArgs, type UseRulePreviewResult, UtilityRow, VariantList, buildRef, bulkDelete, bulkUpsert, deleteRecord, downloadBlob, exportCsv, getRecordByRef, importCsv, listRecords, matchRecords, mergeIcons, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, resolutionChain, resolveRecord, restoreRecord, scopesEqual, upsertRecord, useCollectedRecords, useDirtyNavigation, useIntroDismissed, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordEditor, useRecordList, useResolveAllRecords, useResolvedRecord, useRulePreview, useScopeProbe, useUnsavedGuard };