@proveanything/smartlinks-utils-ui 0.10.8 → 0.11.0

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

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, ReactNode } from 'react';
-import { FacetRule, MatchedAt, RecordTarget, AppRecord, MatchResult, ResolveAllEntry } from '@proveanything/smartlinks/dist/types/appObjects';
+import { FacetRule, MatchedAt, AppRecord, RecordTarget, MatchResult, ResolveAllEntry } from '@proveanything/smartlinks/dist/types/appObjects';
+import { ReactNode, ComponentType } from 'react';
 import { LucideIcon } from 'lucide-react';
 import * as _tanstack_query_core from '@tanstack/query-core';
 import * as _proveanything_smartlinks from '@proveanything/smartlinks';
@@ -93,6 +93,21 @@ interface RecordSummary<TData = unknown> {
      * browser uses this to render a friendly rule summary as the row subtitle.
      */
     facetRule?: FacetRule | null;
+    /**
+     * Optional visual hint for the leading status icon on the default row
+     * renderer. When set, takes precedence over the status-derived icon
+     * (configured / inherited / empty). Used by lifecycle rail buckets
+     * (success/warning/etc) and any host that wants per-row iconography
+     * without supplying a full `renderListRow`.
+     */
+    iconHint?: ReactNode;
+    /**
+     * Optional semantic tone for the leading status icon. Drives the icon
+     * colour via `ra-status-icon--<tone>` CSS classes. Has no effect unless
+     * `iconHint` is also set (or the tone is one that maps to a built-in
+     * default icon).
+     */
+    toneHint?: 'success' | 'warning' | 'danger' | 'muted' | 'info' | 'default';
 }
 interface ResolvedRecord<TData = unknown> {
     data: TData | null;
@@ -755,6 +770,17 @@ interface ItemColumn<TData = unknown> {
     width?: string;
     /** Right-align the cell (numeric columns). */
     align?: 'left' | 'right' | 'center';
+    /**
+     * When supplied, the column header becomes clickable and toggles
+     * asc → desc → none on the loaded records. The framework sorts
+     * client-side over whatever pages have been fetched; if more pages
+     * exist a small "Sorting first N — Load more for full set" hint is
+     * shown above the table so admins know they're sorting a subset.
+     *
+     * Return a primitive (`string` / `number` / `Date` / `boolean`) — the
+     * framework handles nulls (always sorted last) and stable ordering.
+     */
+    sortBy?: (record: RecordSummary<TData>) => string | number | Date | boolean | null | undefined;
 }
 /**
  * Context passed to right-pane item-view slot renderers.
@@ -993,6 +1019,15 @@ interface RailConfig<TData = unknown> {
     onGroupExpanded?: (key: string) => void;
     /** Visual density. Default `comfortable`. */
     density?: 'comfortable' | 'compact';
+    /**
+     * Page size requested from the SDK for the records-driven rail
+     * (Rules / Global / All tabs). Default 100. Raise for apps that
+     * routinely have hundreds of rule-targeted records and want fewer
+     * "Load more" clicks; lower to reduce initial payload on large
+     * collections. The footer remains visible whenever more pages exist
+     * so admins always have a path to record N+1.
+     */
+    pageSize?: number;
 }
 interface EditorPreviewConfig<TData = unknown> {
     /**
@@ -1048,6 +1083,40 @@ interface ItemsConfig<TData = unknown> {
     cardSize?: 'sm' | 'md' | 'lg';
     /** What the rail shows once an item is open. Default `'siblings'`. */
     railMode?: CollectionRailMode;
+    /**
+     * Optional projector that derives `label` / `subtitle` / `thumbnail`
+     * (and any other `RecordSummary` fields) from a raw record. Runs for
+     * every item in the collection-cardinality right-pane list. The
+     * shell's default tries common keys (`title`, `name`, `label`,
+     * `question`, …) — supply this when your record shape doesn't match
+     * those, or when you want the global / all-items list to read from a
+     * different field.
+     *
+     * `base` already carries the framework-derived fields (id, scope,
+     * status, etc.); return a merged `RecordSummary` (e.g.
+     * `{ ...base, label: rec.data?.headline ?? base.label }`).
+     */
+    toSummary?: (rec: AppRecord, base: RecordSummary<TData>) => RecordSummary<TData>;
+    /**
+     * Page size requested from the SDK for the right-pane item list (and
+     * the sibling rail, since both share `useCollectionItems`). Default
+     * 100. Raise for apps where a single scope routinely holds hundreds
+     * of items (votes, attestations, ledger entries) so admins don't
+     * have to "Load more" on every visit. The footer always renders when
+     * more pages exist — the goal is to never silently truncate.
+     */
+    pageSize?: number;
+    /**
+     * Optional projector returning extra strings to include in the
+     * built-in item-list search match. The framework always searches
+     * `label` + `subtitle`; this hook lets hosts add fields that aren't
+     * on the summary (e.g. body text, tags, internal codes).
+     *
+     * Set `searchable: false` to disable the search box entirely.
+     */
+    searchableFields?: (record: RecordSummary<TData>) => Array<string | undefined | null>;
+    /** Disable the built-in search input. Default `true` (enabled). */
+    searchable?: boolean;
 }
 interface UnsavedConfig<TData = unknown> {
     /**
@@ -1163,6 +1232,8 @@ interface Props$f {
 declare const StatusDot: ({ source, status, className }: Props$f) => react_jsx_runtime.JSX.Element;
 
 type StatusTone = 'own' | 'shared' | 'missing';
+/** Semantic tones used by host-driven iconography (e.g. lifecycle buckets). */
+type SemanticTone = 'success' | 'warning' | 'danger' | 'muted' | 'info' | 'default';
 interface Props$e {
     source?: RecordSource;
     status?: RecordStatus;
@@ -1171,8 +1242,21 @@ interface Props$e {
     size?: string;
     /** Optional accessible label — defaults to the tone name. */
     label?: string;
+    /**
+     * Host-supplied icon override. Either a React element (rendered as-is)
+     * or any ReactNode. When set, takes precedence over the status-derived
+     * icon. Pair with `semanticTone` to drive colour.
+     */
+    iconHint?: ReactNode;
+    /**
+     * Host-supplied semantic tone (success/warning/danger/muted/info). When
+     * set, drives the icon colour AND — if no `iconHint` is supplied —
+     * picks a sensible default lucide icon per tone (CheckCircle2 / Alert /
+     * XCircle / MinusCircle / Info).
+     */
+    semanticTone?: SemanticTone;
 }
-declare const StatusIcon: ({ source, status, className, size, label }: Props$e) => react_jsx_runtime.JSX.Element;
+declare const StatusIcon: ({ source, status, className, size, label, iconHint, semanticTone, }: Props$e) => react_jsx_runtime.JSX.Element;
 /** Short label rendered next to / under the row title. */
 declare const statusToneLabel: (tone: StatusTone) => string;
 
@@ -2038,9 +2122,25 @@ declare const useScopeCounts: (args: UseScopeCountsArgs) => UseScopeCountsResult
 /** React Query key factory for cache invalidation from save/delete sites. */
 declare const scopeCountsQueryKey: (collectionId: string, appId: string, recordType?: string) => (string | null)[];
 
-declare const useIntroDismissed: (SL: SmartLinksSDK, collectionId: string, appId: string, recordType?: string) => {
+/**
+ * Records-admin intro dismiss state. Thin shim over the library-level
+ * `useIntroState` so the shell shares one persistence model with every
+ * other admin app:
+ *
+ *   • Global "show inline help" preference on the user record
+ *     (`SL.userAppData('prefs').showHints`) — flipped once, applies
+ *     everywhere. When `false` the intro is collapsed by default but the
+ *     `?` reopen button is still rendered.
+ *   • Per-browser, per-app temporary dismiss in `localStorage`
+ *     (`sl:intro-dismissed:${appId}[:recordType]`).
+ *
+ * `collectionId` is no longer used (the old per-collection persistence on
+ * `appConfiguration._meta.introDismissed` was removed) but kept in the
+ * signature for back-compat with existing callers.
+ */
+declare const useIntroDismissed: (SL: SmartLinksSDK, _collectionId: string, appId: string, recordType?: string) => {
     dismissed: boolean;
-    dismiss: () => Promise<void>;
+    dismiss: () => void;
     undismiss: () => void;
 };
 
@@ -2400,9 +2500,25 @@ interface Props$5<T> {
         onCopy?: () => void;
         onDuplicate?: () => void;
     } | null;
+    /**
+     * Optional projector returning extra strings to include in the search
+     * match. Framework always searches `label` + `subtitle`.
+     */
+    searchableFields?: (record: RecordSummary<T>) => Array<string | undefined | null>;
+    /** Disable the search box. Default `true`. */
+    searchable?: boolean;
+    /**
+     * Pagination — when the underlying `useCollectionItems` reports more
+     * pages, the list renders a footer with "Showing X of Y · Load more"
+     * so admins always have a path to record N+1.
+     */
+    total?: number;
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    onLoadMore?: () => void;
     i18n: RecordsAdminI18n;
 }
-declare function ItemListView<T>({ items, isLoading, error, ctx, itemNoun, ruleSummary, view, views, onViewChange, renderItemList, renderItemCard, renderItemEmpty, itemColumns, cardSize, rowActions, rowClipboard, i18n, }: Props$5<T>): react_jsx_runtime.JSX.Element;
+declare function ItemListView<T>({ items, isLoading, error, ctx, itemNoun, ruleSummary, view, views, onViewChange, renderItemList, renderItemCard, renderItemEmpty, itemColumns, cardSize, rowActions, rowClipboard, searchableFields, searchable, total, hasNextPage, isFetchingNextPage, onLoadMore, i18n, }: Props$5<T>): react_jsx_runtime.JSX.Element;
 
 interface Props$4 {
     options: ItemView[];
@@ -2412,12 +2528,23 @@ interface Props$4 {
 }
 declare const ItemViewSwitcher: ({ options, value, onChange, i18n }: Props$4) => react_jsx_runtime.JSX.Element | null;
 
+type SortDir = 'asc' | 'desc' | null;
+interface SortState {
+    key: string | null;
+    dir: SortDir;
+}
 interface Props$3<T> {
     items: RecordSummary<T>[];
     columns?: ItemColumn<T>[];
     selectedId?: string;
     onOpen: (itemId: string) => void;
     onDelete: (itemId: string) => void;
+    /** Current sort state (controlled by ItemListView). */
+    sort?: SortState;
+    /** Toggle sort for a given column key (asc → desc → none). */
+    onToggleSort?: (key: string) => void;
+    /** Sort key + direction for the fallback (label / updated) columns. */
+    fallbackSortKey?: 'label' | 'updated';
     /** Host-supplied per-record menu actions for each row's `…` kebab. */
     rowActions?: (record: RecordSummary<T>) => RecordAction[] | null | undefined;
     /** Per-record Copy / Duplicate wiring from the shell clipboard. */
@@ -2427,7 +2554,7 @@ interface Props$3<T> {
     } | null;
     i18n: Pick<RecordsAdminI18n, 'itemColumnLabel' | 'itemColumnUpdated' | 'itemActions' | 'delete'>;
 }
-declare function DefaultItemTable<T>({ items, columns, selectedId, onOpen, onDelete, rowActions, rowClipboard, i18n, }: Props$3<T>): react_jsx_runtime.JSX.Element;
+declare function DefaultItemTable<T>({ items, columns, selectedId, onOpen, onDelete, sort, onToggleSort, rowActions, rowClipboard, i18n, }: Props$3<T>): react_jsx_runtime.JSX.Element;
 
 interface Props$2<T> {
     items: RecordSummary<T>[];
@@ -2504,9 +2631,14 @@ interface Props<T> {
     dirtyKeys?: ReadonlySet<string>;
     /** Subset of `dirtyKeys` whose last save attempt failed. */
     errorKeys?: ReadonlySet<string>;
+    /** Pagination passthrough from `useCollectionItems`. */
+    total?: number;
+    hasNextPage?: boolean;
+    isFetchingNextPage?: boolean;
+    onLoadMore?: () => void;
     i18n: Pick<RecordsAdminI18n, 'backToScopes' | 'siblingsHeading' | 'noItemsTitle' | 'noItemsBody' | 'backToList' | 'newItem'>;
 }
-declare function SiblingRail<T>({ items, selectedItemId, isLoading, error, onBack, onSelect, contextKind, contextSummary, onCreate, itemNoun, dirtyKeys, errorKeys, i18n, }: Props<T>): react_jsx_runtime.JSX.Element;
+declare function SiblingRail<T>({ items, selectedItemId, isLoading, error, onBack, onSelect, contextKind, contextSummary, onCreate, itemNoun, dirtyKeys, errorKeys, i18n, total, hasNextPage, isFetchingNextPage, onLoadMore, }: Props<T>): react_jsx_runtime.JSX.Element;
 
 interface ClipboardEntry<T = unknown> {
     value: T;