@nivaro/react 0.1.302 → 0.1.303

package/dist/index.d.ts

@@ -292,6 +292,46 @@ export declare interface ApiVersionInfo {
 
 export declare function applyValidationRule(rule: FormValidationRule_2, value: unknown, label: string, record?: Record<string, unknown>): string | null;
 
+/**
+ * "Fill from a document" — a person drops a statement of work, a quote, a
+ * spreadsheet on a NEW record and reviews what the model read out of it
+ * before any of it lands in the form. Server contract: POST /ai/extract-record
+ * (background=1) answers a proposal id; GET /ai/extract-record/result/:id
+ * carries the DocumentProposal (values + confidence + the sentence each came
+ * from) once the run lands. This dialog is the review. Nothing is written
+ * until Apply, and Apply only stages — the record still needs Create.
+ *
+ * The run always goes through the background path so the same proposal id
+ * serves three doors: this button, a list's "New from document…" (which
+ * opens the form on `?autofill=<id>`), and "tell me when it's ready" (the
+ * notification opens the same form on the same id).
+ */
+declare type AskInput = AskRelationInput | {
+    type: 'choices';
+    choices: Array<{
+        value: string;
+        text: string;
+    }>;
+} | {
+    type: 'boolean';
+} | {
+    type: 'number';
+} | {
+    type: 'date';
+} | {
+    type: 'text';
+};
+
+/** What a relation ask in the document-autofill review carries from the
+ *  field's own picker configuration. */
+declare type AskRelationInput = {
+    type: 'relation';
+    collection: string;
+    template: string | null;
+    cascades?: CascadeRule[] | null;
+    option_filter?: Record<string, unknown> | null;
+};
+
 declare type AutoAllocateConfig = {
     /** Button label; defaults to 'Auto allocate'. */
     label?: string;
@@ -317,6 +357,35 @@ declare type AutoAllocateConfig = {
     };
 };
 
+export declare type AutofillRun = {
+    id: string;
+    collection: string;
+    /** What the person picked, or what the server says once it answers. */
+    documentName: string;
+    layoutId?: number | null;
+    status: AutofillRunStatus;
+    proposal: unknown | null;
+    error: string | null;
+    startedAt: number;
+    /** A form is showing this run's dialog right now — the shell chip hides it. */
+    presented: boolean;
+};
+
+/**
+ * The document-autofill runs the app is watching, as small chips in the
+ * corner of EVERY page — mount once in the app shell. A reading run shows
+ * its progress; a landed one becomes a Review button; a failed one says so.
+ * Clicking hands the run to the host, which opens the new-record form on
+ * `?autofill=<id>` (the form then shows the run's dialog and this chip
+ * steps aside). Portals to <body>: a `fixed` element under an animated page
+ * wrapper anchors to the wrapper, not the viewport.
+ */
+export declare function AutofillRunsChip({ onOpen }: {
+    onOpen: (run: AutofillRun) => void;
+}): ReactPortal | null;
+
+declare type AutofillRunStatus = 'reading' | 'ready' | 'failed';
+
 export declare function AutolinkedText({ text, plain }: {
     text: string;
     plain?: boolean;
@@ -477,6 +546,30 @@ export declare function captureErrorClip(): Promise<ErrorReplayLink | null>;
 export { CascadeFilterRule }
 
 declare type CascadeRule = {
+    parent_field: string;
+    /** Column on the picker's target collection — may be a dotted relation path
+     *  ('regions.region'); the first hop is wrapped in _some when filter_via_many. */
+    filter_column: string;
+    filter_is_m2m?: boolean;
+    /** Dotted filter_column's first hop is a to-many alias (O2M/M2M) — wrap in _some. */
+    filter_via_many?: boolean;
+    /** Derive the filter value(s) from the parent's value instead of using it
+     *  directly: {parentValue: filterValue | filterValue[]}. Missing keys fall
+     *  back to value_map_default, then the raw parent value. Arrays become _in.
+     *  (e.g. a parent-type hierarchy: tier A → tier B ids, tier B → tier C id, …) */
+    value_map?: Record<string, unknown>;
+    value_map_default?: unknown;
+    clear_on_parent_change?: boolean;
+    clear_on_unavailable?: boolean;
+    /** Reverse the cascade on PICK: choosing this field resolves filter_column
+     *  on the picked record and fills parent_field from it (a Region pick fills
+     *  its Zone). Scalar parents fill only when exactly one value resolves;
+     *  alias parents stage every resolved link (additive). */
+    upstream?: boolean;
+    show_all_if_no_parent?: boolean;
+};
+
+declare type CascadeRule_2 = {
     parent_field: string;
     child_field: string;
     on_unavailable?: CascadeSwapConfig;
@@ -637,6 +730,8 @@ export declare interface ChatMessage {
     deleted_at?: string | null;
     attachments?: string[];
     reactions?: ChatReaction[];
+    /** The admin who was masquerading as the sender when it was sent. */
+    masquerade_admin_name?: string | null;
 }
 
 export declare interface ChatOnlineUser {
@@ -1295,6 +1390,9 @@ declare interface DirectoryChannel {
     members: number;
 }
 
+/** Forget a run: stops watching it (the server run continues on its own). */
+export declare function dismissAutofillRun(id: string): void;
+
 export declare function DisplayPrefsCard(): JSX.Element;
 
 declare type DmOpener = (userId: string, displayName?: string) => void;
@@ -1312,24 +1410,27 @@ declare type DocumentApplySelection = {
     file_id: string | null;
     summary: string;
     document_name: string;
+    proposal_id: string;
 };
 
-export declare function DocumentAutofillButton({ collection, onApply, className }: {
+export declare function DocumentAutofillButton({ collection, onApply, className, layoutId, initialProposalId, label, onProposalConsumed }: {
     collection: string;
     onApply: (selection: DocumentApplySelection, proposal: DocumentProposal) => void | Promise<void>;
     className?: string;
+    /** Restrict the proposal to this layout's fields (an addendum layout). */
+    layoutId?: number | null;
+    /** Open straight onto a stored proposal (`?autofill=<id>` from a list or a notification). */
+    initialProposalId?: string | null;
+    label?: string;
+    /** The initial proposal was shown — the host can drop `?autofill=` from the URL. */
+    onProposalConsumed?: () => void;
 }): JSX.Element | null;
 
-/**
- * "Fill from a document" — a person drops a statement of work, a quote, a
- * spreadsheet on a NEW record and reviews what the model read out of it
- * before any of it lands in the form. Server contract: POST /ai/extract-record
- * returns a DocumentProposal (values + confidence + the sentence each came
- * from); this dialog is the review. Nothing is written until Apply, and Apply
- * only stages — the record still needs Create.
- */
 declare type DocumentProposal = {
+    id: string;
+    request_id?: string | null;
     collection: string;
+    layout_id?: number | null;
     summary: string;
     fields: Array<{
         field: string;
@@ -1338,6 +1439,10 @@ declare type DocumentProposal = {
         display: string | null;
         confidence: number;
         source: string | null;
+        derived?: {
+            by: 'field_rule' | 'cross_record_defaults';
+            from: string;
+        } | null;
     }>;
     children: Array<{
         alias: string;
@@ -1363,6 +1468,13 @@ declare type DocumentProposal = {
         field: string;
         label: string;
         reason: string;
+        candidate?: {
+            value: unknown;
+            display: string | null;
+            confidence: number;
+            source: string | null;
+        } | null;
+        input?: AskInput | null;
     }>;
     warnings: string[];
     prefill: {
@@ -1372,6 +1484,8 @@ declare type DocumentProposal = {
         }>>;
         m2m: Record<string, Array<string | number>>;
         file_id: string | null;
+        /** Every stored document, in the order given (the first is `file_id`). */
+        file_ids?: string[];
         attach_alias: string | null;
     };
     document: {
@@ -1380,9 +1494,24 @@ declare type DocumentProposal = {
         pages: number | null;
         truncated: boolean;
         chars: number;
+        /** One entry per document when several were read together. */
+        documents?: Array<{
+            name: string;
+            method: string;
+            pages: number | null;
+            truncated: boolean;
+            chars: number;
+            file_id: string | null;
+        }>;
     };
     model: string;
     rounds: number;
+    latency_ms?: number;
+    condensed?: {
+        chunks: number;
+        excerpt_chars: number;
+    } | null;
+    hints_used?: string[];
 };
 
 /** One dot per partner, worst outcome winning — a red dot must never be
@@ -1643,6 +1772,12 @@ 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 FetchCfg = {
+    apiBase: string;
+    authHeaders: Record<string, string>;
+    credentials: RequestCredentials;
+};
+
 declare type Fetcher = () => Promise<ApiVersionInfo | null>;
 
 export declare function fetchSchema(client: NivaroClient, collection: string, includeHidden: boolean, layoutId?: number, layoutSlug?: string): Promise<FormSchema>;
@@ -2087,6 +2222,8 @@ export declare interface GatedClient extends NivaroClient {
 /** The newer API build being served, or null while this tab is current. */
 export declare function getApiUpdate(): ApiVersionInfo | null;
 
+export declare function getAutofillRuns(): AutofillRun[];
+
 export declare function getFieldInterface(name: string | null | undefined): FieldInterfacePlugin | null;
 
 export declare function getFiscalStartMonth(): number;
@@ -2564,7 +2701,7 @@ export declare function InlineTableField({ relatedCollection, manyField, parentI
     saveMode?: 'immediate' | 'pending';
     showLineNumbers?: boolean;
     enableReorder?: boolean;
-    parentCascades?: CascadeRule[];
+    parentCascades?: CascadeRule_2[];
     rowRules?: RowRule[];
     columnPresets?: ColumnPreset[];
     /** Initial view before the user picks one: a preset name or '__all__'. */
@@ -2973,7 +3110,7 @@ export declare type ItemEditAuthContextValue = {
     userId: string;
 };
 
-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 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, autofillProposalId, onAutofillConsumed, initialImportResult, initialValues, initialLinks, initialRows }: ItemEditFormProps): JSX.Element;
 
 export declare interface ItemEditFormProps {
     collection: string;
@@ -3035,6 +3172,11 @@ export declare interface ItemEditFormProps {
     extraTopContent?: ReactNode;
     extraBottomContent?: ReactNode;
     onHeaderWidgets?: (widgets: HeaderWidgetInfo[]) => void;
+    /** Open the new-record form on a stored document proposal (`?autofill=<id>`
+     *  from a list's "New from document…" or the ready notification). */
+    autofillProposalId?: string | null;
+    /** The proposal was picked up — the host may drop `?autofill=` from the URL. */
+    onAutofillConsumed?: () => void;
     /** Consumed once, on mount, when `isNew` — prefills the draft + stages O2M
      *  lines from an already-parsed import result (e.g. handed off by a caller
      *  that ran the file picker before this form existed). */
@@ -3067,6 +3209,8 @@ export declare type ItemLinkTarget = {
      *  keyed by staging key). Rides the URL as `?prefill=<base64 JSON>`, the
      *  shape both hosts already consume. */
     prefill?: Record<string, unknown> | null;
+    /** Extra query parameters the target page reads (`autofill=<proposal id>`). */
+    query?: Record<string, string> | null;
 };
 
 export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin, onRequestLock, requesting, queue, myPosition, onJoinQueue, onLeaveQueue, joining }: {
@@ -4412,6 +4556,15 @@ export declare function PipelineTransitionButtons({ collection, item, onBeforeTr
 /** Play the configured notification sound. No-op for 'off'/unknown/unavailable audio. */
 export declare function playNotificationSound(kind: NotificationSound | string | null | undefined): void;
 
+declare function pollProposal(opts: {
+    fetchResult: () => Promise<ProposalPollAnswer>;
+    onRunning?: (documentName?: string) => void;
+    onDone: (data: any) => void;
+    onError: (message: string) => void;
+    onSettled: () => void;
+    intervalMs?: number;
+}): () => void;
+
 /**
  * How many decimal places a numeric field wants, from its `precision` option.
  *
@@ -4476,6 +4629,21 @@ export declare function ProfileView({ userId, className, initialTab, extra }: {
     extra?: React.ReactNode;
 }): JSX.Element;
 
+/**
+ * Polls a running document-autofill proposal until it lands or fails.
+ *
+ * The API answers 202 while the run is still going, 200 with the proposal
+ * once it has landed, and a 4xx/5xx when it failed. `onSettled` fires exactly
+ * once, after `onDone` or `onError` — never on a 202, which only keeps the
+ * loop (and the caller's waiting state) alive. Returns a stop function; after
+ * it is called no callback fires again.
+ */
+declare type ProposalPollAnswer = {
+    status: number;
+    ok: boolean;
+    json: any;
+};
+
 export declare function QualityRulesView({ className }: {
     className?: string;
 }): JSX.Element;
@@ -4724,6 +4892,11 @@ declare type QueryWidgetFilter = {
     /** Pre-selected values on load. '$current_year' resolves to the current
      *  calendar year (default-year behavior). */
     default_values?: Array<string | number>;
+    /** Query-string key that pre-selects this filter when the page URL carries
+     *  it (`?fy=2026`, a comma list for several values, compared on
+     *  value_field). Beats default_values and the user-scope seeding; when the
+     *  URL lacks it, those apply as before. */
+    url_param?: string;
 };
 
 declare interface QueryWidgetStat {
@@ -5860,6 +6033,20 @@ declare type SpreadPreset = 'even' | 'front' | 'back' | 'shape';
  */
 export declare function startApiVersionWatch(fetchVersion: Fetcher): void;
 
+/**
+ * Start watching a run (idempotent — a known id is left alone). Polls until
+ * the proposal lands or fails; the run stays in the store until it is
+ * dismissed or its proposal is consumed by a form.
+ */
+export declare function startAutofillRun(cfg: FetchCfg, run: {
+    id: string;
+    collection: string;
+    documentName?: string;
+    layoutId?: number | null;
+}, deps?: {
+    poll?: typeof pollProposal;
+}): AutofillRun;
+
 export declare function startRum(opts?: {
     app?: string;
     routePattern?: (path: string) => string;
@@ -6058,6 +6245,9 @@ export declare function useApiFetchConfig(): {
 
 export declare function useApiUpdate(): ApiVersionInfo | null;
 
+/** Every run the shell should show or a form may pick up. */
+export declare function useAutofillRuns(): AutofillRun[];
+
 /** Available actions per collection, for the viewer. */
 export declare function useAvailableBulkActions(collections: string[]): UseQueryResult<NoInfer<Record<string, AvailableBulkAction[]>>, Error>;