@nivaro/react 0.1.230 → 0.1.231

package/dist/index.d.ts

@@ -17,6 +17,7 @@ import { ReportDateRange } from '@nivaro/sdk';
 import { ReportEntityFilter } from '@nivaro/sdk';
 import { ReportQueryWidgetConfig } from '@nivaro/sdk';
 import { UseMutationResult } from '@tanstack/react-query';
+import { UseQueryResult } from '@tanstack/react-query';
 import { UserScopesInfo } from '@nivaro/sdk';
 
 export declare function AccessDeniedPanel({ collection, itemId, onBack }: {
@@ -268,6 +269,28 @@ export declare function AutolinkedText({ text, plain }: {
     plain?: boolean;
 }): JSX.Element;
 
+/**
+ * Registry bulk actions (GET /bulk-actions/available) rendered as buttons in
+ * a selection bar. Each button opens an anchored popover — what the action
+ * does, how many records, the reason field when the action requires one —
+ * and runs it via POST /bulk-actions/run (DB-defined) or
+ * POST /bulk-actions/:id/execute (extension-registered). Targets may span
+ * collections (queues): one run per collection that offers the action.
+ */
+declare interface AvailableBulkAction {
+    key: string;
+    source: 'db' | 'extension' | 'builtin';
+    collection: string | null;
+    label: string;
+    icon: string | null;
+    variant: 'default' | 'danger';
+    kind: 'update_fields' | 'transition' | 'extension' | 'builtin';
+    require_reason: boolean;
+    confirm_text: string | null;
+    summary: string;
+    surfaces?: Array<'browser' | 'queue'>;
+}
+
 export declare function BaseMap({ pins, bubbles, statusLine, onPinClick, onBubbleClick, minHeight, focus }: {
     pins: BaseMapPin[];
     bubbles?: BaseMapBubble[];
@@ -316,6 +339,33 @@ export declare function BroadcastView({ className }: {
 
 export declare function buildGroups<T extends QueueGroupingRow>(rows: T[], attribute: string): QueueGroup<T>[];
 
+export declare function BulkActionButtons({ targets, enabledKeys, tone, disabled, onDone }: {
+    targets: BulkTarget[];
+    /** Surface allow-list (browser_config.bulk_actions / display_config.bulk_action_keys). */
+    enabledKeys?: string[] | null;
+    /** 'dark' = the collection browser's navy bar; 'light' = the queue pill. */
+    tone?: 'dark' | 'light';
+    disabled?: boolean;
+    onDone?: (result: BulkRunResult & {
+        action: AvailableBulkAction;
+    }) => void;
+}): JSX.Element | null;
+
+declare interface BulkRunResult {
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    errors: Array<{
+        item: string;
+        error: string;
+    }>;
+}
+
+declare interface BulkTarget {
+    collection: string;
+    id: string | number;
+}
+
 export declare function canOpenCatalogItem(collection: string | null | undefined): boolean;
 
 export declare function canOpenChatRoom(): boolean;
@@ -969,6 +1019,9 @@ export declare interface DataTableProps<T = Record<string, unknown>> {
 
 export declare function DateField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
 
+/** Decoder for `?prefill=` (base64 → JSON), tolerant of '+' arriving as ' '. */
+export declare function decodePrefill(raw: string | null | undefined): Record<string, unknown> | null;
+
 /** The admin's route shape — the default when the host supplies no itemUrl. */
 export declare function defaultItemUrl(t: ItemLinkTarget): string;
 
@@ -1077,6 +1130,9 @@ export declare function EmptyState({ icon: Icon, title, detail, action }: {
     action?: ReactNode;
 }): JSX.Element;
 
+/** `?prefill=` payload encoder — base64 of the JSON, URL-encoded. */
+export declare function encodePrefill(values: Record<string, unknown>): string;
+
 export declare function ErpFailureBanner({ collection, itemId }: {
     collection: string;
     itemId: string;
@@ -2002,6 +2058,10 @@ export declare type ItemLinkTarget = {
     itemId: string;
     /** Grouped-layout slug to pin (queue item_layout etc.); null/absent = default. */
     layoutSlug?: string | null;
+    /** New-record seed (itemId 'new'): scalar values plus `__links` (m2m ids
+     *  keyed by staging key). Rides the URL as `?prefill=<base64 JSON>`, the
+     *  shape both hosts already consume. */
+    prefill?: Record<string, unknown> | null;
 };
 
 export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin, onRequestLock, requesting }: {
@@ -3119,7 +3179,7 @@ export declare function QueryWidgetView({ config }: {
     config: QueryWidgetConfig;
 }): JSX.Element;
 
-export declare function QueueBulkBar({ count, states, busy, claimsEnabled, onClaim, onRelease, onTransition, onClear }: {
+export declare function QueueBulkBar({ count, states, busy, claimsEnabled, showClaim, showRelease, showTransition, onClaim, onRelease, onTransition, onClear, children }: {
     count: number;
     states: Array<{
         value: string;
@@ -3127,10 +3187,16 @@ export declare function QueueBulkBar({ count, states, busy, claimsEnabled, onCla
     }>;
     busy: boolean;
     claimsEnabled?: boolean;
+    /** Built-in gates from the bulk-actions registry (useBuiltinGate). */
+    showClaim?: boolean;
+    showRelease?: boolean;
+    showTransition?: boolean;
     onClaim: () => void;
     onRelease: () => void;
     onTransition: (state: string) => void;
     onClear: () => void;
+    /** Registry bulk actions (BulkActionButtons) rendered before Transition. */
+    children?: ReactNode;
 }): JSX.Element | null;
 
 export declare interface QueueGroup<T extends QueueGroupingRow = QueueGroupingRow> {
@@ -3250,6 +3316,55 @@ declare interface QuickFilterDef {
     sort?: string;
 }
 
+export declare function QuickPicker({ collection, itemId, steps, fieldConfig, relations, draft, getM2M, onChange, onM2MChange, fieldLabels, fieldOptionFilters, onCompleteChange, onFinish, finishLabel, finishRequiresComplete, className }: QuickPickerProps): JSX.Element | null;
+
+export declare function QuickPickerDialog({ collection, layoutSlug, open, onOpenChange, onDone, noun, anchorEl }: QuickPickerDialogProps): JSX.Element;
+
+export declare interface QuickPickerDialogProps {
+    collection: string;
+    layoutSlug?: string | null;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called with the picks: scalar values + `__links` (staging key → ids). */
+    onDone: (prefill: Record<string, unknown>) => void;
+    /** Noun for the title + button ("workflow"). */
+    noun?: string;
+    /**
+     * Element to anchor beside (the "+ New" button). With an anchor the picker
+     * is a compact popover next to it; without one it falls back to a dialog.
+     */
+    anchorEl?: HTMLElement | null;
+}
+
+export declare interface QuickPickerProps {
+    collection: string;
+    /** 'new' for an unsaved record. */
+    itemId: string;
+    /** Ordered field keys (the layout's quick_picker). */
+    steps: string[];
+    fieldConfig: CMSField[];
+    relations: CMSRelation[];
+    draft: Record<string, unknown>;
+    /** Effective ids for an M2M alias (committed ± staged); undefined = unknown. */
+    getM2M: (field: string) => string[] | undefined;
+    onChange: (field: string, value: unknown) => void;
+    onM2MChange: (field: string, ids: string[]) => void;
+    /** Layout-effective labels + option filters (ParentDraftContext shape). */
+    fieldLabels?: Record<string, string>;
+    fieldOptionFilters?: Record<string, Record<string, unknown>>;
+    /** Fires whenever completeness changes. */
+    onCompleteChange?: (complete: boolean) => void;
+    /**
+     * Primary action rendered in the Next slot once the chain is complete (or on
+     * the last slide): "Done" in the form, "Create workflow" before a record
+     * exists. Disabled until complete unless `finishRequiresComplete` is false.
+     */
+    onFinish?: () => void;
+    finishLabel?: string;
+    finishRequiresComplete?: boolean;
+    className?: string;
+}
+
 /**
  * Tier a team against a cell's filter values. `out` carries the human
  * mismatches ("doesn't cover BLT"). Filters without a resolvable id don't
@@ -3848,6 +3963,18 @@ export declare type SectionState = {
     expandAll: () => void;
 };
 
+export declare function seedQuickPickerSteps(fieldConfig: Array<{
+    field: string;
+    dependency_config?: unknown;
+    hidden?: boolean;
+}>, relations: Array<{
+    many_collection: string;
+    many_field: string | null;
+    one_collection: string | null;
+    one_field: string | null;
+    junction_field: string | null;
+}>, collection: string): string[];
+
 export declare function SelectField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
 
 /**
@@ -4141,6 +4268,9 @@ export declare function useApiFetchConfig(): {
 
 export declare function useApiUpdate(): ApiVersionInfo | null;
 
+/** Available actions per collection, for the viewer. */
+export declare function useAvailableBulkActions(collections: string[]): UseQueryResult<NoInfer<Record<string, AvailableBulkAction[]>>, Error>;
+
 export declare function useChannelAdmin(channelId: number | null): {
     update: UseMutationResult<unknown, Error, {
     name?: string;
@@ -4439,6 +4569,19 @@ export declare function useOverlayState<T>(key: string): {
 
 export declare function usePeerReadAt(room: string | null): string | null;
 
+/**
+ * The quick picker BEFORE a record exists — the "+ New" menus open it, and on
+ * Create the host navigates to the new-record page with the picks in
+ * `?prefill=` (scalars) plus `__links` (M2M ids keyed by staging key, the key
+ * ItemEditForm's initialLinks resolves). Reads the layout's `quick_picker`
+ * steps itself, so hosts only need the collection (and optional layout slug).
+ */
+export declare function useQuickPickerSteps(collection: string | null | undefined, layoutSlug?: string | null): {
+    steps: string[];
+    layoutId: number | null;
+    loading: boolean;
+};
+
 /**
  * Real profile photo (Microsoft Graph, captured at login) with the caller's
  * initials disc as the fallback. The photo arrives as a small data URI from