@nivaro/react 0.1.235 → 0.1.237

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ImportTemplateSummary } from '@nivaro/sdk';
 import { JSX } from 'react';
 import { JSXElementConstructor } from 'react';
 import type { LucideIcon } from 'lucide-react';
+import { ManagedUser } from '@nivaro/sdk';
 import { NivaroClient } from '@nivaro/sdk';
 import { default as React_2 } from 'react';
 import { ReactElement } from 'react';
@@ -1037,6 +1038,29 @@ export declare function DefinitionsPanel({ definitions, runCounts, isLoading }:
     isLoading?: boolean;
 }): JSX.Element;
 
+export declare function DelegationCard({ user, onSaved }: {
+    user: ManagedUser;
+    onSaved: () => void;
+}): JSX.Element;
+
+export declare function DelegationConsoleView({ className, onNotice }: DelegationConsoleViewProps): JSX.Element;
+
+export declare interface DelegationConsoleViewProps {
+    className?: string;
+    /** Host toast hook. */
+    onNotice?: (message: string) => void;
+}
+
+export declare function DeliveryChips({ delivery, mailLogUrl, onNavigate, className }: DeliveryChipsProps): JSX.Element;
+
+declare interface DeliveryChipsProps {
+    delivery: NotificationDeliveryRecord | null | undefined;
+    /** Host route for a mail-log row (admin: /mail-log?id=N). Absent = no link. */
+    mailLogUrl?: (mailLogId: number) => string | null;
+    onNavigate?: (path: string) => void;
+    className?: string;
+}
+
 export declare function deriveGroupKey<T extends QueueGroupingRow>(row: T, attribute: string): string;
 
 export declare function describeCron(cron: string): string;
@@ -1879,10 +1903,14 @@ declare interface ImportValidationReport {
     truncated: boolean;
 }
 
-export declare function InlineTableField({ relatedCollection, manyField, parentId, parentCollection, layoutId, showRowRevisions, rowComments, allowRevisionRestore, saveMode, showLineNumbers, enableReorder, parentCascades, rowRules, columnPresets, defaultPreset, drawerRelations, parentContextFields, uniqueBy, sortField, sortDir, sectionGroupBy, freezeFirstColumn, rowFilter, rowDefaults, allocateDrawer, autoAllocate, rowBulkActions, uploadTemplate, rowMatchPanel, lineSla, rowLints, submissionErrors, prefillParentId, parentFieldKey, readOnly, emptyLabel }: {
+export declare function InlineTableField({ relatedCollection, manyField, parentId, parentCollection, layoutId, showRowRevisions, rowComments, allowRevisionRestore, saveMode, showLineNumbers, enableReorder, parentCascades, rowRules, columnPresets, defaultPreset, drawerRelations, parentContextFields, uniqueBy, sortField, sortDir, sectionGroupBy, freezeFirstColumn, rowFilter, rowDefaults, allocateDrawer, autoAllocate, rowBulkActions, uploadTemplate, rowMatchPanel, lineSla, rowLints, submissionErrors, prefillParentId, parentFieldKey, readOnly, emptyLabel, editorMode }: {
     relatedCollection: string;
     manyField: string;
     parentId: string;
+    /** options.editor_mode — where a row's editor renders: 'drawer' (under the
+     *  row, the default) or 'split' (docked below the table, arrow keys walk the
+     *  rows). A per-user toolbar toggle (localStorage) wins over this. */
+    editorMode?: 'drawer' | 'split';
     /** Same table display, but no editing: hides the Add toolbar, + Add row,
      *  row delete/undo, and blocks cell edit entry. */
     readOnly?: boolean;
@@ -1969,7 +1997,7 @@ export declare type ItemEditAuthContextValue = {
     userId: string;
 };
 
-export declare function ItemEditForm({ collection, itemId: itemIdProp, layoutSlug, initialAddendumViewId, onAddendumViewChange, onBack, onSaved, onDeleted, showHeader, headerExtra, focusField, showItemActions, onDirtyChange, documentTitle, registerSaveHandler, onDuplicate, showRevisions, showClone, showPipeline, showWorkflow, showComments, showTasks, showLockBanner, className, headerClassName, renderField, extraTopContent, extraBottomContent, onHeaderWidgets, initialImportResult, initialValues, initialLinks, initialRows }: ItemEditFormProps): JSX.Element;
+export declare function ItemEditForm({ collection, itemId: itemIdProp, layoutSlug: layoutSlugProp, initialAddendumViewId, onAddendumViewChange, onBack, onSaved, onDeleted, showHeader, headerExtra, focusField, showItemActions, onDirtyChange, documentTitle, registerSaveHandler, onDuplicate, showRevisions, showClone, showPipeline, showWorkflow, showComments, showTasks, showLockBanner, className, headerClassName, renderField, extraTopContent, extraBottomContent, onHeaderWidgets, initialImportResult, initialValues, initialLinks, initialRows }: ItemEditFormProps): JSX.Element;
 
 export declare interface ItemEditFormProps {
     collection: string;
@@ -2004,7 +2032,8 @@ export declare interface ItemEditFormProps {
      */
     /** Fires whenever the form's dirty state flips — lets a host (workspace
      *  tabs, close guards) track unsaved edits without reaching inside. */
-    onDirtyChange?: (dirty: boolean) => void;
+    /** Dirty flag plus a breakdown of what is unsaved (fields, staged lines, links) — hosts render their own leave-page prompt from it. */
+    onDirtyChange?: (dirty: boolean, summary?: UnsavedSummary) => void;
     /** false = skip the document.title side effect — a workspace-tab host keeps
      *  several forms mounted and only the ACTIVE one may own the browser tab. */
     documentTitle?: boolean;
@@ -2064,13 +2093,18 @@ export declare type ItemLinkTarget = {
     prefill?: Record<string, unknown> | null;
 };
 
-export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin, onRequestLock, requesting }: {
+export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin, onRequestLock, requesting, queue, myPosition, onJoinQueue, onLeaveQueue, joining }: {
     lockHolder: LockHolder | null;
     onTakeOver: () => void;
     takingOver: boolean;
     isAdmin?: boolean;
     onRequestLock?: () => void;
     requesting?: boolean;
+    queue?: LockQueueEntry[];
+    myPosition?: number | null;
+    onJoinQueue?: () => void;
+    onLeaveQueue?: () => void;
+    joining?: boolean;
 }): JSX.Element | null;
 
 export declare function JsonMapEditor({ config, scope }: {
@@ -2211,6 +2245,10 @@ declare interface LayoutGroup {
     label: string;
     type: string | null;
     sort: number;
+    id?: number;
+    container_id?: number | null;
+    is_collapsed?: boolean | number | null;
+    visibility_mode?: string | null;
 }
 
 export declare type LayoutItem = FormGroupDescriptor | '__ungrouped__';
@@ -2282,6 +2320,14 @@ export declare function listFieldInterfaces(): string[];
 declare interface LockHolder {
     locked_by: string;
     locked_by_name: string | null;
+    /** The holder's intent note (#10) — "editing lines ~15 min". */
+    note?: string | null;
+}
+
+declare interface LockQueueEntry {
+    user: string;
+    name: string | null;
+    requested_at: string;
 }
 
 export declare interface M2MStagingCtx {
@@ -2579,6 +2625,159 @@ export declare function NivaroProvider({ client, children }: {
  */
 export declare function normalizeFieldType(rawType: string, iface: string | null, relation: FormFieldDescriptor['relation']): FormFieldType;
 
+export declare function NotificationActions({ actions, notificationId, onDone, onError, size, className }: NotificationActionsProps): JSX.Element | null;
+
+/** An inline action the server says is safe to fire from a click. */
+export declare interface NotificationActionSpec {
+    key: string;
+    label: string;
+    method: 'POST' | 'PATCH';
+    endpoint: string;
+    body?: Record<string, unknown>;
+    mark_read?: boolean;
+    /** The action takes a line of text (a reply, a note): render an input and
+     *  send its value as body[field]. */
+    input?: {
+        field: string;
+        placeholder: string;
+        submit_label?: string;
+    };
+}
+
+/**
+ * The inline action pills a notification row offers (server-described:
+ * endpoint + body, domain-blind). One-click actions fire straight away;
+ * actions carrying `input` (Reply, Comment on this) open an inline text box
+ * under the row and send its value as body[field]. Marks the row read when
+ * the action says so, then invalidates the notification queries.
+ */
+declare interface NotificationActionsProps {
+    actions: NotificationActionSpec[];
+    notificationId: number;
+    /** Called after any successful action (hosts refresh their own lists). */
+    onDone?: () => void;
+    onError?: (message: string) => void;
+    size?: 'sm' | 'xs';
+    className?: string;
+}
+
+export declare function NotificationAnalyticsView({ className }: {
+    className?: string;
+}): JSX.Element;
+
+/**
+ * The Nivaro notification bell — the same setup the admin uses: badge that
+ * counts what NEEDS YOU (Critical + Needs-you lanes, never FYI), lane tabs,
+ * rows grouped by record (five updates on one workflow read as one story),
+ * group-level open + mark-read, inline server-approved actions including
+ * reply boxes, per-row delivery chips (where did this go?), and
+ * click-through routing via the shared notification-target resolver. Needs
+ * `<NivaroProvider>`.
+ */
+export declare function NotificationBell({ routes, onNavigate, app, subscribe, buttonClassName, panelClassName, beforeList, extraBadge, mailLogUrl, renderTrigger, allPath, onActionError, panelPlacement }: NotificationBellProps): JSX.Element;
+
+export declare interface NotificationBellProps {
+    /** Where each notification kind lands in the host app. */
+    routes: NotificationRouteMap;
+    /** Host router push — the bell never imports a router itself. */
+    onNavigate: (path: string) => void;
+    /** Which app's routes the server should resolve fallback urls for (?app=…). */
+    app?: 'portal' | 'admin';
+    /**
+     * Realtime hookup: invoke the callback whenever a notification arrives and
+     * return an unsubscribe. The bell refreshes its queries; anything else
+     * (sounds, toasts) stays in the host's handler.
+     */
+    subscribe?: (onNew: () => void) => () => void;
+    /** Extra classes for the trigger button (host header styling). */
+    buttonClassName?: string;
+    /** Extra classes for the popup panel (position/size overrides). */
+    panelClassName?: string;
+    /** Rendered above the tab strip inside the panel (host strips such as
+     *  "3 access requests waiting on an admin"). */
+    beforeList?: ReactNode;
+    /** Added to the badge count (host-side items the inbox does not hold). */
+    extraBadge?: number;
+    /** Host route for a mail-log row — turns the email delivery chip into a
+     *  link. Absent = chips are plain. */
+    mailLogUrl?: (mailLogId: number) => string | null;
+    /** Replace the trigger button entirely (the popup still positions against
+     *  the wrapper). */
+    renderTrigger?: (state: {
+        open: boolean;
+        badge: number;
+        toggle: () => void;
+    }) => ReactNode;
+    /** Path of the full notifications page — renders a "See all" footer link. */
+    allPath?: string | null;
+    /** Called with an error message when an inline action fails. */
+    onActionError?: (message: string) => void;
+    /** Where the panel opens relative to the trigger. 'below' (default) keeps
+     *  it inside the trigger's tree; 'right' portals it to document.body and
+     *  positions it beside the trigger — for a sidebar rail whose overflow
+     *  would clip an inline panel. */
+    panelPlacement?: 'below' | 'right';
+}
+
+export declare function NotificationCenterView({ routes, onNavigate, app, mailLogUrl, onNotice, onError, className }: NotificationCenterViewProps): JSX.Element;
+
+export declare interface NotificationCenterViewProps {
+    routes: NotificationRouteMap;
+    onNavigate: (path: string) => void;
+    app?: 'portal' | 'admin';
+    mailLogUrl?: (mailLogId: number) => string | null;
+    /** Toast hooks — hosts wire their own toaster. */
+    onNotice?: (message: string) => void;
+    onError?: (message: string) => void;
+    className?: string;
+}
+
+/** Per-channel delivery outcome recorded on the row (GET /notifications
+ *  `delivery`). Rows from before delivery tracking carry only in-app. */
+export declare interface NotificationDeliveryRecord {
+    inapp?: {
+        status: 'delivered' | 'skipped';
+        reason?: string;
+    };
+    push?: {
+        status: 'sent' | 'no_subscription' | 'skipped' | 'failed';
+        reason?: string;
+        at?: string;
+    };
+    email?: {
+        status: 'sent' | 'deferred' | 'dropped' | 'failed' | 'off' | 'not_requested' | 'no_address' | 'unconfigured';
+        reason?: string;
+        mail_log_id?: number | null;
+        at?: string;
+    };
+    sms?: {
+        status: 'sent' | 'failed' | 'skipped' | 'not_requested';
+        reason?: string;
+    };
+    escalation?: {
+        push_at?: string;
+        email_at?: string;
+        email_log_id?: number | null;
+    };
+}
+
+/** Inbox lane — Critical and Needs-you are what the badge counts. */
+export declare type NotificationLane = 'critical' | 'needs_you' | 'fyi';
+
+/** The notification row shape every surface receives (GET /notifications). */
+export declare interface NotificationLike {
+    collection?: string | null;
+    item?: string | null;
+    target?: NotificationTargetSpec | null;
+    /** Server-resolved URL for the recipient's app — the fallback when this
+     *  host has no route for the kind (opens in a new tab when foreign). */
+    url?: string | null;
+    actions?: NotificationActionSpec[] | null;
+    lane?: NotificationLane | null;
+    category?: string | null;
+    delivery?: NotificationDeliveryRecord | null;
+}
+
 /**
  * Every in-app notification must land somewhere meaningful — this is the ONE
  * resolver both bells, the notifications page, and My Work use to decide what
@@ -2603,6 +2802,11 @@ export declare interface NotificationRouteMap {
     alerts?: () => string | null;
     imports?: () => string | null;
     issues?: () => string | null;
+    /** Task list (a task-kind row); hosts without one fall back to my_work / url. */
+    tasks?: (id?: string | null) => string | null;
+    approvals?: () => string | null;
+    access_requests?: () => string | null;
+    my_work?: () => string | null;
 }
 
 export declare function NotificationRulesCard(): JSX.Element;
@@ -2644,8 +2848,37 @@ export declare type NotificationTarget = {
 } | {
     type: 'chat';
     room: string;
+} | {
+    type: 'external';
+    url: string;
 } | null;
 
+/** Server-side target spec (services/notification-target.ts) — what the
+ *  notification is about and what a click should offer. */
+export declare interface NotificationTargetSpec {
+    kind: 'record' | 'task' | 'approval' | 'access_request' | 'sla' | 'chat' | 'queue' | 'report' | 'alerts' | 'issue' | 'import' | 'dashboard' | 'my_work' | 'home' | 'external';
+    collection?: string | null;
+    id?: string | number | null;
+    room?: string | null;
+    query?: string | null;
+    focus?: string | null;
+    tab?: string | null;
+    url?: string | null;
+    action?: 'open' | 'complete' | 'acknowledge' | 'review' | 'approve' | 'reply';
+    task_id?: string | number | null;
+    instance_id?: string | number | null;
+}
+
+export declare function NotificationTemplatesView({ onNotice, onError, className, embedded }: NotificationTemplatesViewProps): JSX.Element;
+
+declare interface NotificationTemplatesViewProps {
+    onNotice?: (message: string) => void;
+    onError?: (message: string) => void;
+    className?: string;
+    /** Embedded inside another page (no page header). */
+    embedded?: boolean;
+}
+
 export declare function NumberField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
 
 /** Intl options for a numeric field, honoring its configured precision. */
@@ -2847,12 +3080,14 @@ declare type PipelineOwnerDimension = {
     cascade?: DimensionCascadeRule[] | null;
 };
 
-export declare function PipelinePanel({ collection, item, defaultExpanded, title, showApprovalChain, hideActionsCollapsed, hideActionsExpanded, onBeforeTransition, addendumPending, addendumView }: {
+export declare function PipelinePanel({ collection, item, defaultExpanded, title, showApprovalChain, hideActionsCollapsed, hideActionsExpanded, onBeforeTransition, addendumPending, addendumView, asRole }: {
     collection: string;
     item: string;
     defaultExpanded?: boolean;
     title?: string;
     showApprovalChain?: boolean;
+    /** Admin "view as role" (#8): evaluate available transitions for this role instead of the caller. */
+    asRole?: string | null;
     /** Layout-configurable: suppress the transition buttons inside the slot
      * (collapsed header row / expanded body) — redundant when the record header
      * already renders PipelineTransitionButtons. */
@@ -3450,9 +3685,11 @@ export declare interface RealtimeAdapter {
 
 export declare const RealtimeContext: Context<RealtimeAdapter | null>;
 
-export declare function RecordChatActions({ collection, itemDraft }: {
+export declare function RecordChatActions({ collection, itemDraft, compact }: {
     collection: string;
     itemDraft: Record<string, unknown>;
+    /** Icon-only, borderless — for the record header's tool group. */
+    compact?: boolean;
 }): JSX.Element | null;
 
 export declare function RecordDrilldownSheet({ collection, itemId, layoutId, rootLayoutSlug, width, title, stack: controlledStack, onPush, onPop, onClose }: {
@@ -3554,10 +3791,12 @@ export declare function RecordGridWidgetBody({ widget }: {
     widget: PageRendererWidget;
 }): JSX.Element;
 
-export declare function RecordReadView({ collection, itemId, layoutData }: {
+export declare function RecordReadView({ collection, itemId, layoutData, flush }: {
     collection: string;
     itemId: string;
     layoutData: ReadViewLayout;
+    /** Host already pads and scrolls the body (the record form's read mode). */
+    flush?: boolean;
 }): JSX.Element;
 
 /**
@@ -3588,10 +3827,12 @@ export declare function RecordRecapStrip({ collection, itemId }: {
  * Transitions never fire the items-service update hook (state mirrors are raw
  * writes), so the two rows can't double-notify.
  */
-export declare function RecordSubscribeButton({ collection, itemId, recordLabel }: {
+export declare function RecordSubscribeButton({ collection, itemId, recordLabel, compact }: {
     collection: string;
     itemId: string;
     recordLabel?: string;
+    /** Icon-only, borderless — for the record header's tool group. */
+    compact?: boolean;
 }): JSX.Element;
 
 /** Register a detail opener for a catalog collection. Returns an unregister
@@ -3726,6 +3967,15 @@ export declare function resolveCollectionIcon(iconName: string | null | undefine
 
 export declare function resolveNotificationTarget(collection: string | null | undefined, item: string | null | undefined, routes: NotificationRouteMap): NotificationTarget;
 
+/**
+ * Structured resolution: the server's target spec mapped onto THIS host's
+ * routes (kind by kind), falling back to the server-resolved `url` — same
+ * origin → in-app path, foreign origin → external (new tab) — and finally to
+ * the legacy collection + item resolution. A row still resolving to null
+ * renders as plain text.
+ */
+export declare function resolveNotificationTargetFor(n: NotificationLike, routes: NotificationRouteMap): NotificationTarget;
+
 declare type ReviewListColumnFormat = 'currency' | 'number' | 'date' | 'datetime' | 'flag';
 
 declare interface ReviewListColumnSpec {
@@ -3825,11 +4075,13 @@ declare interface ReviewListWidgetProps {
     emptyLabel?: string;
 }
 
-export declare function RevisionsPanel({ collection, item, onRollback, triggerClassName, inlineTableFields, open, onOpenChange }: {
+export declare function RevisionsPanel({ collection, item, onRollback, triggerClassName, inlineTableFields, open, onOpenChange, compact }: {
     collection: string;
     item: string;
     onRollback?: () => void;
     triggerClassName?: string;
+    /** Icon-only, borderless trigger — for the record header's tool group. */
+    compact?: boolean;
     inlineTableFields?: O2MFieldInfo[];
     /** Controlled mode (no trigger button) — open the sheet programmatically,
      *  e.g. from a row Actions menu. */
@@ -4010,7 +4262,8 @@ declare interface RowRule {
 /** Route-change timing: from the navigation to a settled double-rAF frame. */
 export declare function rumRouteChange(pathname: string): void;
 
-/** Convenience: run a resolved target (navigate or open the chat room). */
+/** Convenience: run a resolved target (navigate, open the chat room, or open
+ *  a foreign-app URL in a new tab). */
 export declare function runNotificationTarget(target: NotificationTarget, navigate: (path: string) => void): boolean;
 
 declare interface ScopeDimensionLite {
@@ -4294,8 +4547,6 @@ export declare function TickerNumber({ value, format, durationMs }: {
     durationMs?: number;
 }): JSX.Element;
 
-/** Timezone preference (#31): applied to every datetime the shared
- *  formatters render. Defaults to the browser's zone. */
 export declare function TimezoneCard(): JSX.Element;
 
 export declare function TipLayer(): ReactPortal | null;
@@ -4318,6 +4569,20 @@ export declare function translateScopeValues(client: {
     target_collection: string;
 }, ids: Array<string | number>, valueField?: string): Promise<Array<string | number>>;
 
+/** What is unsaved right now — the leave-page prompt, the changes tray and
+ *  the host's own dirty indicator all read this one breakdown. */
+declare interface UnsavedSummary {
+    fields: string[];
+    rows: number;
+    edits: number;
+    deletes: number;
+    links: number;
+    unlinks: number;
+    total: number;
+    /** "2 fields, 3 lines, 1 link" — empty when clean. */
+    text: string;
+}
+
 /**
  * Base URL + auth for the few raw `fetch` calls (widgets, PDF blobs) that
  * can't go through `client.request`. Derives everything from the ambient
@@ -4510,6 +4775,13 @@ export declare function useItemLock(collection: string | undefined, item: string
     isAdmin: boolean;
     requestLock: () => Promise<void>;
     requesting: boolean;
+    queue: LockQueueEntry[];
+    myPosition: number | null;
+    joinQueue: () => Promise<void>;
+    leaveQueue: () => Promise<void>;
+    joining: boolean;
+    myNote: string;
+    saveNote: (note: string) => Promise<void>;
 };
 
 /** Resolved item-link helpers honoring the host's itemUrl/openItem overrides. */