@nivaro/react 0.1.116 → 0.1.118

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { ImportParseResponse } from '@nivaro/sdk';
 import { ImportTemplateSummary } from '@nivaro/sdk';
 import { JSX } from 'react';
 import { JSXElementConstructor } from 'react';
+import type { LucideIcon } from 'lucide-react';
 import { NivaroClient } from '@nivaro/sdk';
 import { default as React_2 } from 'react';
 import { ReactElement } from 'react';
@@ -246,6 +247,10 @@ declare type AutoAllocateConfig = {
     };
 };
 
+export declare function AutolinkedText({ text }: {
+    text: string;
+}): JSX.Element;
+
 export declare function BaseMap({ pins, bubbles, statusLine, onPinClick, onBubbleClick, minHeight, focus }: {
     pins: BaseMapPin[];
     bubbles?: BaseMapBubble[];
@@ -264,7 +269,7 @@ export declare function BaseMap({ pins, bubbles, statusLine, onPinClick, onBubbl
     } | null;
 }): JSX.Element;
 
-declare interface BaseMapBubble {
+export declare interface BaseMapBubble {
     id: string;
     lat: number;
     lng: number;
@@ -273,7 +278,7 @@ declare interface BaseMapBubble {
     color?: string;
 }
 
-declare interface BaseMapPin {
+export declare interface BaseMapPin {
     id: string;
     lat: number;
     lng: number;
@@ -764,6 +769,18 @@ export declare function ConformanceView({ className }: {
 
 export declare function createLeaderSocket(key: string, cbs: LeaderCallbacks): LeaderSocketHandle;
 
+export declare function CronBuilder({ value, onChange, disabled }: {
+    value: string;
+    onChange: (cron: string) => void;
+    disabled?: boolean;
+}): JSX.Element;
+
+export declare function CustomActionButtons({ collection, itemId, draft }: {
+    collection: string;
+    itemId: string;
+    draft: Record<string, unknown>;
+}): JSX.Element | null;
+
 export declare function DataTable<T = Record<string, unknown>>({ columns, rows, rowKey, total, page, limit, isLoading, isError, errorMessage, sort, onSortChange, onPageChange, onRowClick, onRowContextMenu, searchValue, onSearchChange, searchPlaceholder, filterDefs, filterValues, onFilterChange, toolbarRight, emptyMessage, minBodyHeight, fillHeight, hideFilterRow, nowrapCells, density, pinFirstColumn, columnPins, onColumnPinChange, columnFilterRow, hScrollProxy, selectedIds, onSelectionChange, rowClassName, rowGroups, collapsedGroups, onToggleGroup }: DataTableProps<T>): React_2.JSX.Element;
 
 export declare interface DataTableProps<T = Record<string, unknown>> {
@@ -845,8 +862,22 @@ export declare function DateField({ field, value, onChange, error, disabled, rea
 /** The admin's route shape — the default when the host supplies no itemUrl. */
 export declare function defaultItemUrl(t: ItemLinkTarget): string;
 
+/**
+ * Definition registry (admin). Master-detail rather than a dialog: an operator
+ * comparing two imports' targets needs both the list and the editor on screen.
+ */
+export declare function DefinitionsPanel({ definitions, runCounts, isLoading }: {
+    definitions: ImportDefinition[];
+    /** Runs per import key — a definition's history is the main thing that makes
+     *  it recognisable, and the reason deactivating beats deleting. */
+    runCounts: Record<string, number>;
+    isLoading?: boolean;
+}): JSX.Element;
+
 export declare function deriveGroupKey<T extends QueueGroupingRow>(row: T, attribute: string): string;
 
+export declare function describeCron(cron: string): string;
+
 declare interface DirectoryChannel {
     id: number;
     key: string;
@@ -900,6 +931,17 @@ export declare function effectiveScopeSeedIds(scopes: {
     restricted: Record<string, Array<string | number>>;
 }, dimName: string): Array<string | number>;
 
+/**
+ * Designed empty state (#322): what this surface is, why it's empty, and the
+ * one right action. Replaces bare "No results" strings on the major surfaces.
+ */
+export declare function EmptyState({ icon: Icon, title, detail, action }: {
+    icon?: LucideIcon;
+    title: string;
+    detail?: string;
+    action?: ReactNode;
+}): JSX.Element;
+
 export declare function ErpFailureBanner({ collection, itemId }: {
     collection: string;
     itemId: string;
@@ -912,6 +954,18 @@ export declare interface ErrorReplayLink {
     offset_ms: number | null;
 }
 
+/**
+ * Error surface family (#324): 403/404/500 as one designed system — a name
+ * for what happened, an honest cause line, and the one right action. The
+ * smart-404 (#219) and AccessDeniedPanel remain the record-scoped variants;
+ * this is the page-level chrome.
+ */
+export declare function ErrorSurface({ variant, detail, action }: {
+    variant: '403' | '404' | '500';
+    detail?: string;
+    action?: ReactNode;
+}): JSX.Element;
+
 /** Boolean convenience — for guards and conditions. */
 export declare function evaluateBoolean(src: string, row: TokenResolver | Record<string, unknown>, opts?: EvaluateOptions): boolean;
 
@@ -1006,6 +1060,9 @@ export declare function ExternalRequestsChip({ collection, itemId }: {
 /** Field paths an expression reads, without evaluating it. */
 export declare function extractExpressionTokens(src: string): string[];
 
+/** Extract the slot key from an assignment field name, or null. */
+export declare function extSlotKey(field: string): string | null;
+
 declare type Fetcher = () => Promise<ApiVersionInfo | null>;
 
 export declare function fetchSchema(client: NivaroClient, collection: string, includeHidden: boolean, layoutId?: number, layoutSlug?: string): Promise<FormSchema>;
@@ -1049,6 +1106,47 @@ export declare function fieldDrilldownConfig(field: {
     _overrides?: Record<string, unknown> | null;
 }): FieldDrilldownConfig | null;
 
+export declare interface FieldInterfaceHandle {
+    update?: (props: FieldInterfaceProps) => void;
+    destroy?: () => void;
+}
+
+export declare interface FieldInterfacePlugin {
+    interface: string;
+    mount: (el: HTMLElement, props: FieldInterfaceProps) => FieldInterfaceHandle | void;
+}
+
+/**
+ * Pluggable field interfaces (#17): extensions register custom field
+ * renderers (map picker, signature pad…) usable in any layout. The contract
+ * is framework-free — a DOM mount function — so extension UI bundles need
+ * nothing beyond the browser:
+ *
+ *   window.__nvrRegisterFieldInterface({
+ *     interface: 'map-picker',
+ *     mount(el, props) {
+ *       // build DOM inside el; call props.onChange(next) on edits
+ *       return { update(next) { … }, destroy() { … } }
+ *     }
+ *   })
+ *
+ * FieldRenderer consults the registry before its built-in dispatch, so a
+ * field whose `interface` matches a registered name renders through the
+ * plugin; unknown interfaces keep falling through to the default renderer.
+ */
+export declare interface FieldInterfaceProps {
+    value: unknown;
+    onChange: (next: unknown) => void;
+    field: {
+        field: string;
+        label?: string | null;
+        options?: unknown;
+    };
+    readOnly: boolean;
+    collection: string;
+    itemId: string | null;
+}
+
 export declare function FieldRenderer({ field, value, onChange, relations, collection, itemId, cascadeFilter, requiredParentLabel, onCountChange, displayOnly, prefillParentId }: {
     field: CMSField;
     value: unknown;
@@ -1136,6 +1234,13 @@ export declare function FirstLoginChecklist({ profileUrl }: {
     profileUrl?: string;
 }): JSX.Element | null;
 
+/** "FY2026-Q1" — the FiscalPeriodField storage format. */
+export declare function fiscalPeriodOf(d: Date, startMonth?: number): string;
+
+export declare function fiscalQuarterOf(d: Date, startMonth?: number): number;
+
+export declare function fiscalYearOf(d: Date, startMonth?: number): number;
+
 export declare function formatDate(date: string | Date, opts?: Intl.DateTimeFormatOptions): string;
 
 export declare function formatDateTime(date: string | Date): string;
@@ -1254,6 +1359,8 @@ export declare type FormStatus = {
     canSubmit: boolean;
 };
 
+export declare function formulaConstant(name: string): number | null;
+
 /**
  * Authoring surface for `{{token}}` formulas.
  *
@@ -1338,6 +1445,12 @@ export declare type FormVisibilityRule = {
 /** The newer API build being served, or null while this tab is current. */
 export declare function getApiUpdate(): ApiVersionInfo | null;
 
+export declare function getFieldInterface(name: string | null | undefined): FieldInterfacePlugin | null;
+
+export declare function getFiscalStartMonth(): number;
+
+export declare function getLayoutSlot(key: string | null | undefined): LayoutSlotPlugin | null;
+
 export declare function getMentionQuery(text: string, cursorPos: number): string | null;
 
 export declare const GridFlushContext: React_2.Context<GridFlushContextValue | null>;
@@ -1851,6 +1964,39 @@ declare interface LayoutGroup {
 
 export declare type LayoutItem = FormGroupDescriptor | '__ungrouped__';
 
+declare interface LayoutSlotHandle {
+    update?: (props: LayoutSlotProps) => void;
+    destroy?: () => void;
+}
+
+declare interface LayoutSlotPlugin {
+    key: string;
+    mount: (el: HTMLElement, props: LayoutSlotProps) => LayoutSlotHandle | void;
+}
+
+/**
+ * Extension layout slots (#425): extensions render whole custom SECTIONS
+ * inside record layouts — the section-level sibling of the field-interface
+ * registry (#17). Same framework-free DOM contract:
+ *
+ *   window.__nvrRegisterLayoutSlot({
+ *     key: 'shipment-tracker',
+ *     mount(el, props) {
+ *       // build DOM inside el; props carries {collection, itemId, draft}
+ *       return { update(props) { … }, destroy() { … } }
+ *     }
+ *   })
+ *
+ * Authoring: a layout assignment whose field is `__ext_<key>__` renders the
+ * registered slot; an unregistered key renders an honest placeholder naming
+ * it, so a missing bundle is visible instead of a silent blank.
+ */
+declare interface LayoutSlotProps {
+    collection: string;
+    itemId: string | null;
+    draft: Record<string, unknown>;
+}
+
 declare interface LeaderCallbacks {
     /** Called when this tab becomes leader — create the real socket, wire onAny → deliver. */
     becomeLeader(deliver: (event: string, payload: any) => void, emit: {
@@ -1880,6 +2026,8 @@ export declare interface LeaderSocketHandle {
     destroy(): void;
 }
 
+export declare function listFieldInterfaces(): string[];
+
 declare interface LockHolder {
     locked_by: string;
     locked_by_name: string | null;
@@ -2072,6 +2220,17 @@ export declare type NavigationContextValue = {
     userUrl?: (userId: string) => string | null;
 };
 
+export declare function networkdaysBetween(a: Date, b: Date): number;
+
+export declare function NewImportDialog({ open, onOpenChange, definitions, runCounts, onQueued }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    definitions: ImportDefinition[];
+    /** All-time run count per import key — drives the "Frequently used" section. */
+    runCounts?: Record<string, number>;
+    onQueued: (id: number) => void;
+}): JSX.Element;
+
 /**
  * Selects and renders the correct field component for a single field based on
  * its normalized fieldType. Override any type via `components`; falls back to
@@ -2179,6 +2338,18 @@ declare interface O2MFieldInfo {
     parentId: string;
 }
 
+/**
+ * Offline banner (#348): connectivity loss shows an honest "offline — changes
+ * paused" strip and clears itself when the connection returns. Uses the
+ * browser online/offline events plus a confirm probe (the events lie on some
+ * networks) against a HEAD to the app's own origin.
+ */
+export declare function OfflineBanner(): JSX.Element | null;
+
+/** Re-render hook support: components subscribe so a late-loading extension
+ *  bundle upgrades already-mounted fields. */
+export declare function onFieldInterfacesChange(cb: () => void): () => void;
+
 /**
  * Called when idleness CHANGES, not on a timer — a host can push the flip
  * straight down its socket so coming back is seen in about a second instead of
@@ -2350,6 +2521,43 @@ export declare function QualityRulesView({ className }: {
     className?: string;
 }): JSX.Element;
 
+declare type QueryRowClick = {
+    picker?: {
+        collection: string;
+        filter?: Record<string, unknown>;
+        title?: string;
+    };
+    drill?: {
+        collection?: string;
+        layout_id?: number;
+        width?: number | string;
+    };
+    matrix?: {
+        config: MatrixEditorConfig;
+        scope_field: string;
+        width?: number | string;
+        title?: string;
+    };
+    /** Open a nested query sheet for the clicked row. */
+    sheet?: QuerySheetDef;
+};
+
+/** A right-hand sheet hosting one (or tabbed) nested query views. Nested
+ *  config `params` values may use '$row.<field>' (clicked row), '$rows.<field>'
+ *  (comma-join over all visible rows — footer/'View All' drills),
+ *  '$param.<name>' (parent widget's effective params) and '$filters.<param>'
+ *  (parent filter selections, comma-joined). Title supports {{field}} tokens
+ *  from the clicked row. */
+declare interface QuerySheetDef {
+    title?: string;
+    width?: number | string;
+    config?: QueryWidgetConfig;
+    tabs?: Array<{
+        label: string;
+        config: QueryWidgetConfig;
+    }>;
+}
+
 export declare function QueryStatStrip({ stats, rows, effectiveParams, loading }: {
     stats: QueryWidgetStat[];
     rows: Array<Record<string, unknown>>;
@@ -2501,6 +2709,45 @@ export declare function QueryWidgetBody({ cfg, dateRange, entityFilters, refetch
     }) => void;
 }): JSX.Element;
 
+declare interface QueryWidgetConfig {
+    query_slug?: string;
+    params?: Record<string, unknown>;
+    table?: QueryTableConfig;
+    row_click?: QueryRowClick;
+    filters?: QueryWidgetFilter[];
+    stats?: QueryWidgetStat[];
+    /** Trailing action buttons per row (and totals row) opening nested sheets. */
+    row_actions?: Array<{
+        label: string;
+        sheet: QuerySheetDef;
+    }>;
+    /** Toolbar action buttons running a (write) custom query — params support
+     *  the same tokens as sheets ('$filters.<param>' / '$param.<name>' /
+     *  '$rows.<field>'); an unresolved param blocks the run with a message.
+     *  EFP 'Run Reforecasting'. */
+    actions?: Array<{
+        label: string;
+        query_slug: string;
+        params?: Record<string, unknown>;
+        confirm?: string;
+        success_message?: string;
+    }>;
+}
+
+declare type QueryWidgetFilter = {
+    param: string;
+    label?: string;
+    collection: string;
+    value_field?: string;
+    label_field?: string;
+    sort?: string;
+    /** Option fetch cap (default 500) — bump for big pick lists (projects). */
+    limit?: number;
+    /** Pre-selected values on load. '$current_year' resolves to the current
+     *  calendar year (EFP default-funding-year behavior). */
+    default_values?: Array<string | number>;
+};
+
 declare interface QueryWidgetStat {
     label: string;
     /** Sum this field over the main query's rows. */
@@ -2537,6 +2784,13 @@ declare interface QueryWidgetStat {
     accent_negative?: string;
 }
 
+/** The full query-widget surface (filters, stats, table, row actions, drill
+ *  sheets) — shared by page renderers and nested drill sheets. A config with
+ *  display:'drawer' renders as a lone trigger button instead. */
+export declare function QueryWidgetView({ config }: {
+    config: QueryWidgetConfig;
+}): JSX.Element;
+
 export declare function QueueBulkBar({ count, states, busy, claimsEnabled, onClaim, onRelease, onTransition, onClear }: {
     count: number;
     states: Array<{
@@ -2781,6 +3035,12 @@ declare interface RecordGridEditorConfig {
     }>;
 }
 
+/** Editable record grid widget — 'drawer' display renders a lone button
+ *  opening the editor in a right sheet (Manage Production Numbers pattern). */
+export declare function RecordGridWidgetBody({ widget }: {
+    widget: PageRendererWidget;
+}): JSX.Element;
+
 export declare function RecordReadView({ collection, itemId, layoutData }: {
     collection: string;
     itemId: string;
@@ -2824,6 +3084,10 @@ export declare function RecordSubscribeButton({ collection, itemId, recordLabel
 /** Register the host's DM opener. Returns an unregister function. */
 export declare function registerDmOpener(fn: DmOpener): () => void;
 
+export declare function registerFieldInterface(plugin: FieldInterfacePlugin): void;
+
+export declare function registerLayoutSlot(plugin: LayoutSlotPlugin): void;
+
 export declare function registerRoomOpener(fn: RoomOpener): () => void;
 
 export declare function RelatedRecordsPanel({ collection, itemId, defaultExpanded }: {
@@ -2928,6 +3192,99 @@ export declare function resolveCollectionIcon(iconName: string | null | undefine
 
 export declare function resolveNotificationTarget(collection: string | null | undefined, item: string | null | undefined, routes: NotificationRouteMap): NotificationTarget;
 
+declare type ReviewListColumnFormat = 'currency' | 'number' | 'date' | 'datetime' | 'flag';
+
+declare interface ReviewListColumnSpec {
+    field: string;
+    label?: string;
+    format?: ReviewListColumnFormat;
+    color?: string;
+}
+
+declare interface ReviewListConfig {
+    host_collection: string;
+    collection: string;
+    path: Array<{
+        kind: 'm2o' | 'm2m';
+        field: string;
+    }>;
+    static_filter?: Array<{
+        field: string;
+        op: 'eq' | 'neq' | 'nnull';
+        value?: unknown;
+    }>;
+    group_by: string;
+    aggregate_sum?: string | null;
+    aggregate_sum_format?: ReviewListColumnFormat | null;
+    group_meta?: Array<string | ReviewListColumnSpec>;
+    line_columns?: Array<string | ReviewListColumnSpec>;
+    status: {
+        field: string;
+        options: ReviewListStatusOption[];
+        empty_label?: string | null;
+        empty_color?: string | null;
+        stamp_user_field?: string | null;
+        stamp_date_field?: string | null;
+        /** POST this endpoint with {ids, status, note, workflow_id} instead of
+         *  per-row PATCHes — lets a deployment route decisions through an
+         *  endpoint that owns stamping, authorization, notes and notifications
+         *  (EFP: /efp/invoice-approvals/decide). */
+        action_endpoint?: string | null;
+    };
+}
+
+declare interface ReviewListResult {
+    rows: ReviewListRow[];
+    columns: {
+        group_meta: Array<{
+            field: string;
+            label: string;
+            format?: ReviewListColumnFormat | null;
+            color?: string | null;
+        }>;
+        line_columns: Array<{
+            field: string;
+            label: string;
+            format?: ReviewListColumnFormat | null;
+            color?: string | null;
+        }>;
+    };
+    truncated: boolean;
+}
+
+declare interface ReviewListRow {
+    id: string | number;
+    group: unknown;
+    values: Record<string, unknown>;
+    status: unknown;
+    stamp_user: {
+        id: string;
+        label: string;
+    } | null;
+    stamp_date: string | null;
+}
+
+declare interface ReviewListStatusOption {
+    value: string;
+    label: string;
+    color: string;
+    /** Picking this option first asks the reviewer for a note (required). */
+    require_note?: boolean;
+}
+
+export declare function ReviewListWidget({ data, config, loading, error, onRefetch, hostRecordId }: ReviewListWidgetProps): JSX.Element;
+
+declare interface ReviewListWidgetProps {
+    data: ReviewListResult | null;
+    config: ReviewListConfig;
+    loading?: boolean;
+    error?: string | null;
+    onRefetch: () => void;
+    /** Host record id (the workflow the widget is slotted on) — forwarded to
+     *  action_endpoint as workflow_id so a rejection note can anchor to it. */
+    hostRecordId?: string | number | null;
+}
+
 export declare function RevisionsPanel({ collection, item, onRollback, triggerClassName, inlineTableFields, open, onOpenChange }: {
     collection: string;
     item: string;
@@ -3077,6 +3434,26 @@ export declare interface SessionRecorderOptions {
     disabled?: boolean;
 }
 
+export declare function setDisplayTimezone(tz: string | null): void;
+
+/**
+ * Fiscal calendar helpers (#343). The instance's fiscal-year start month
+ * lives on nivaro_settings.fiscal_year_start_month; hosts hydrate it via
+ * setFiscalStartMonth (ItemEditForm does this from /settings). Convention:
+ * a fiscal year is NAMED for the calendar year it ends in when the start
+ * month is not January (Oct 2025 with start month 10 → FY2026).
+ */
+export declare function setFiscalStartMonth(m: number | null | undefined): void;
+
+export declare function setFormulaConstants(map: Record<string, number> | null | undefined): void;
+
+export declare function setNumberFormat(opts: {
+    locale?: string;
+    compact?: boolean;
+} | null | undefined): void;
+
+export declare function setTimeDisplay(mode: string | null | undefined): void;
+
 declare interface SheetItem {
     collection: string;
     item_id: string;
@@ -3136,6 +3513,18 @@ export declare function TextareaField({ field, value, onChange, error, disabled,
 
 export declare function TextField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
 
+/**
+ * Number ticker (#320): rolls to a new value with an eased count instead of
+ * snapping. Cosmetic — the true value is always the final frame. Respects
+ * prefers-reduced-motion (snaps), and the FIRST render never animates (a page
+ * load is not a change).
+ */
+export declare function TickerNumber({ value, format, durationMs }: {
+    value: number;
+    format?: (n: number) => string;
+    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;
@@ -3249,6 +3638,13 @@ user_ids: string[];
 name?: string;
 }, unknown>;
 
+/**
+ * Returns a value that trails `value` by `delayMs`. Useful for keeping text
+ * inputs bound to live state while queries key off the debounced copy so a
+ * request doesn't fire per keystroke.
+ */
+export declare function useDebounced<T>(value: T, delayMs?: number): T;
+
 export declare function useDeleteMessage(room: string): UseMutationResult<unknown, Error, number, unknown>;
 
 export declare function useDrilldown(): DrilldownContextValue | null;
@@ -3258,6 +3654,13 @@ messageId: number;
 text: string;
 }, unknown>;
 
+/**
+ * Long-request honesty (#370): after `thresholdMs` of continuous loading,
+ * returns the elapsed seconds so surfaces can say "Still working — 8s" instead
+ * of an eternal spinner. Returns null while under the threshold or idle.
+ */
+export declare function useElapsedLoading(loading: boolean, thresholdMs?: number): number | null;
+
 /**
  * Resolves an entity room ('wf:CR26-76773') to the record's URL, host-routed
  * via cfg.recordUrl. The room-type registry maps the prefix to a collection +
@@ -3272,6 +3675,22 @@ export declare function useFieldArray(form: UseNivaroFormReturn, field: string):
 
 export declare function useFieldState(form: UseNivaroFormReturn, field: string): FieldState;
 
+/**
+ * Dead-file-link awareness for anything rendering file chips/links.
+ *
+ * Batch-verifies the given file ids against the storage provider (POST
+ * /files/verify — persists the verdict on the rows too) and returns a lookup:
+ * `health.isMissing(id)` → true when the physical bytes are gone. Cached 5
+ * minutes per id-set; degrades to "nothing missing" on any failure — a
+ * broken check must never paint healthy files as dead.
+ */
+export declare function useFileHealth(ids: Array<string | null | undefined>): {
+    isMissing: (id: string | null | undefined) => boolean;
+    /** Fresh verdict when the check has run for this id, undefined otherwise —
+     *  lets callers prefer the live answer over a stale stored missing_at. */
+    verdict: (id: string | null | undefined) => boolean | undefined;
+};
+
 export declare function useFormDirty(form: UseNivaroFormReturn, initialValuesOverride?: Record<string, unknown>): FormDirtyState;
 
 /**