@proveanything/smartlinks-utils-ui 0.10.9 → 0.11.0

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

@@ -770,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.
@@ -1008,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> {
     /**
@@ -1077,6 +1097,26 @@ interface ItemsConfig<TData = unknown> {
      * `{ ...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> {
     /**
@@ -2082,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;
 };
 
@@ -2444,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[];
@@ -2456,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. */
@@ -2471,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>[];
@@ -2548,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;