@nivaro/react 0.1.251 → 0.1.253

package/dist/index.d.ts

@@ -131,7 +131,7 @@ export declare function AlertRuleDrawer({ open, definitions, editRule, preselect
 declare type AlertUnit = 'percent' | 'dollar' | 'count' | 'days';
 
 declare type AllocateDrawerConfig = {
-    /** Option collection browsed in the drawer (e.g. workflow_line_items). */
+    /** Option collection browsed in the drawer (e.g. request_lines). */
     collection: string;
     /** Grid FK column that receives the picked option's id. */
     target_field: string;
@@ -151,7 +151,7 @@ declare type AllocateDrawerConfig = {
         width?: number;
     }>;
     /** Group option rows under collapsible headers by this (dotted) path —
-     *  EFP grouped allocation lines by workflow. Groups start collapsed;
+     *  e.g. allocation lines grouped by their parent record. Groups start collapsed;
      *  groups containing an existing allocation start expanded. */
     group_by?: string;
     /** Per-row allocation ceiling formula (same tokens as column formulas incl.
@@ -421,7 +421,7 @@ declare type CascadeRule = {
  *  the `replace` columns from the parent's defaults (same entry shape as
  *  pinned_options — `when` gates read parent fields only). The swap runs the
  *  grid's row rules with the child field as the changed field, so every
- *  downstream derivation (category type, oracle category, task…) follows. */
+ *  downstream derivation (category type, ERP category, task…) follows. */
 declare type CascadeSwapConfig = {
     keep?: string[];
     replace: Record<string, PinnedCfg[]>;
@@ -527,7 +527,7 @@ export declare interface ChatConfig {
     /** Label for a non-global, non-dm room key (null = uppercased key). */
     roomLabel?: (room: string) => string | null;
     /** Host route for a resolved record (entity rooms' "Open record" action) —
-     *  admin passes /collections/:c/:id, efp-new /records/:c/:id. Absent = the
+     *  admin passes /collections/:c/:id, a portal its own record route. Absent = the
      *  admin shape; return null = hide the action. */
     recordUrl?: (collection: string, id: string | number) => string | null;
     /** Host route for a session replay (the online list's admin-only "watch
@@ -635,7 +635,7 @@ export declare interface ChatProviderProps {
  * which is per-user by nature. Live delivery comes from a host-provided
  * realtime adapter, with polling fallbacks baked into every query.
  *
- * Ported from the EFP implementation with its semantics preserved:
+ * Ported from the original host implementation with its semantics preserved:
  * - DM room keys are 'dm:<A>:<B>' with UPPERCASED sorted uuids (MSSQL returns
  *   uuids uppercased — a casing mismatch forks a second room).
  * - Read watermarks are serialized per room (markInFlight) because the reads
@@ -831,7 +831,7 @@ export declare function CollectionImportPanel({ initialJobId, onJobOpen }: {
 }): JSX.Element;
 
 /**
- * Realtime sprint client contract. A HOST (admin, efp-new) owns the actual
+ * Realtime sprint client contract. A HOST (admin, a portal app) owns the actual
  * Socket.io connection and provides this to shared components; components
  * that render without it degrade to polling exactly as before — the context
  * is always optional.
@@ -1711,14 +1711,28 @@ export declare type GridFlushContextValue = {
     unregister: (key: string) => void;
 };
 
+/** Row-editor action: spread a remaining amount across a row's empty fields
+ *  (a forecast year's open months). `remaining` is a grid-token expression —
+ *  `{{$parent.amount}} - {{$sum.total}}` — evaluated with the row
+ *  being edited included in the sums, so spreading once lands the balance on
+ *  the target fields and a second click has nothing left. */
+declare interface GridSpreadConfig {
+    fields: string[];
+    remaining: string;
+    label?: string;
+    /** Fill only empty/zero targets (default true); false = overwrite all. */
+    only_empty?: boolean;
+    format?: 'currency' | 'number';
+}
+
 /**
  * A one-click rewrite of every row in the grid, driven by an aggregate of a
  * related collection.
  *
- * EFP's "Close Out Lines" is one instance of this shape: for each REQ line,
- * sum `open_unbilled_amount` across the PO lines pointing at it and, where the
- * line covers that remainder, subtract it. Expressed as config rather than
- * EFP code so any collection can do the same:
+ * A "Close Out Lines" action is one instance of this shape: for each request
+ * line, sum `open_unbilled_amount` across the PO lines pointing at it and, where
+ * the line covers that remainder, subtract it. Expressed as config rather than
+ * host code so any collection can do the same:
  *
  *   {label:'Close Out Lines', relation:'po_line_items',
  *    aggregate:{field:'open_unbilled_amount', op:'sum'},
@@ -1735,7 +1749,7 @@ export declare type GridFlushContextValue = {
  */
 declare interface GridStatConfig {
     label: string;
-    /** Expression — `{{$parent.requisition_amount}} - {{$sum.total}}`. */
+    /** Expression — `{{$parent.amount}} - {{$sum.total}}`. */
     value: string;
     format?: 'currency' | 'number';
     /** 'danger' paints a negative result red (the "over" state). */
@@ -1745,7 +1759,7 @@ declare interface GridStatConfig {
 declare interface GridSumCapConfig {
     /** Column summed over the grid (write-computed columns are derived per row). */
     field: string;
-    /** Expression for the ceiling — `{{$parent.requisition_amount}}`. */
+    /** Expression for the ceiling — `{{$parent.amount}}`. */
     cap: string;
     format?: 'currency' | 'number';
     label?: string;
@@ -1970,7 +1984,7 @@ declare interface ImportValidationReport {
 /**
  * Inbound integrations — every caller that is not a person's browser session,
  * as cards, plus the request log scoped to the picked one. This is the
- * dedicated "external API logs" view: MWF's file pushes, LinX/Nuvolo GraphQL
+ * dedicated "external API logs" view: partner file pushes, legacy GraphQL
  * writes, named API keys — who called, how often, what failed, and the exact
  * response body the caller got back.
  */
@@ -1978,7 +1992,7 @@ export declare function InboundCallersView({ hours: initialHours }: {
     hours?: number;
 }): JSX.Element;
 
-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, stats, sumCap, submissionErrors, prefillParentId, parentFieldKey, readOnly, emptyLabel, editorMode }: {
+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, stats, sumCap, spreadRemaining, submissionErrors, prefillParentId, parentFieldKey, readOnly, emptyLabel, editorMode }: {
     relatedCollection: string;
     manyField: string;
     parentId: string;
@@ -2021,12 +2035,12 @@ export declare function InlineTableField({ relatedCollection, manyField, parentI
     rowFilter?: Record<string, unknown>;
     /** Values seeded onto every NEW row created from this grid (e.g. {is_osp: true}). */
     rowDefaults?: Record<string, unknown>;
-    /** EFP-style allocate drawer: browse all eligible options, type amounts. */
+    /** Allocate drawer: browse all eligible options, type amounts. */
     allocateDrawer?: AllocateDrawerConfig;
     autoAllocate?: AutoAllocateConfig;
     /** Toolbar buttons that rewrite EVERY row in one go from an aggregate of a
-     *  related collection — the generic form of EFP's "Close Out Lines" (reduce
-     *  each REQ line by the open unbilled amount across its PO lines). */
+     *  related collection — the generic form of a "Close Out Lines" action (reduce
+     *  each request line by the open unbilled amount across its PO lines). */
     rowBulkActions?: RowBulkActionConfig[];
     /** Import template NAME — renders that template's upload button in this
      *  grid's toolbar (existing records; wired to ItemEditForm's reimport flow). */
@@ -2051,6 +2065,7 @@ export declare function InlineTableField({ relatedCollection, manyField, parentI
      *  grid (this row's draft included) would exceed `cap` (same tokens as
      *  stats). The client twin of the server's sum_cap validation rule. */
     sumCap?: GridSumCapConfig | null;
+    spreadRemaining?: GridSpreadConfig | null;
     /** Flag rows a failed ERP push rejected (options.submission_errors) — the
      *  latest failed nivaro_erp_submissions row for the PARENT record is parsed
      *  for "LineNumber N: reason" entries and matching rows tint red with the
@@ -2478,8 +2493,8 @@ declare interface MatrixEditorConfig {
     value_label?: string;
     value_format?: 'currency' | 'number';
     /** Scope pickers. `filter` narrows a picker's options; '$scope.<field>'
-     *  tokens resolve from the other scope values (EFP: sub types limited to the
-     *  chosen project's linked sub types) — unresolved tokens drop the filter. */
+     *  tokens resolve from the other scope values (e.g. a child picker limited to
+     *  the chosen parent's linked options) — unresolved tokens drop the filter. */
     scope_fields: Array<{
         field: string;
         collection: string;
@@ -2487,8 +2502,8 @@ declare interface MatrixEditorConfig {
         filter?: Record<string, unknown>;
     }>;
     /** Third level: sub-group options WITHIN a group section by a template over
-     *  the option record (EFP region → core category → Labor/Materials/Equipment:
-     *  label_template '{{core_category.name}}', row_label_template
+     *  the option record (e.g. group → parent category → sub-category rows:
+     *  label_template '{{parent_category.name}}', row_label_template
      *  '{{sub_category.name}}'). Sub-headers aggregate their children and
      *  collapse independently. */
     option_section?: {
@@ -2507,7 +2522,7 @@ declare interface MatrixEditorConfig {
      *  and use [n] (e.g. '$project.funding_years[0].funding_year'). */
     scope_seeds?: Record<string, string>;
     /** Auto-fill a scope picker from another scope record when empty, e.g.
-     *  {project_sub_type: '$project.default_sub_type'} (EFP default sub type). */
+     *  {sub_type: '$parent.default_sub_type'} (a parent record's default). */
     scope_defaults?: Record<string, string>;
     /** Seeds copied from the GROUP record onto rows created in that section,
      *  {targetField: groupField} — e.g. {division: 'division'} (allocation rows
@@ -3340,7 +3355,7 @@ declare interface QueryTableColumn {
      *  the formula over the summed values — weighted, not averaged). */
     sum?: boolean;
     /** 'progress' renders the value with a bar underneath, filled to
-     *  value / progress_max (EFP PUB'd-vs-budget style). Over 100% turns red. */
+     *  value / progress_max (spend-vs-budget style). Over 100% turns red. */
     display?: 'progress';
     /** Denominator for display 'progress': a row field name or a {{col}} formula. */
     progress_max?: string;
@@ -3348,7 +3363,7 @@ declare interface QueryTableColumn {
      *  rows — group cells spanning their children ('Jan' over Fcst/Act) — and
      *  alternating groups get a faint band so wide grids stay scannable. */
     group?: string;
-    /** Cell text color (any CSS color) — EFP forecast/actual column tinting.
+    /** Cell text color (any CSS color) — e.g. forecast/actual column tinting.
      *  color_dark overrides in dark mode (defaults to color). Either may be a
      *  role name — accent | ink | muted | positive | negative | warning | info —
      *  instead of a hex; roles follow the host theme (see COLOR_ROLES). */
@@ -3358,7 +3373,7 @@ declare interface QueryTableColumn {
      *  negative — a Remaining Budget column reads green until it goes red. */
     color_negative?: string;
     /** Second field rendered as a stacked line under the main value in the SAME
-     *  cell (EFP month cells: Fcst over Act — halves the column count). Toggles
+     *  cell (e.g. month cells: Fcst over Act — halves the column count). Toggles
      *  hide individual lines; the column collapses when both lines hide. */
     stack?: string;
     stack_color?: string;
@@ -3397,14 +3412,14 @@ declare interface QueryTableConfig {
     tree_strip_section_prefix?: boolean;
     /** Per-row numeric format override: name of a row field holding
      *  'currency' | 'number' — lets unit-count rows sit alongside dollar rows
-     *  (EFP forecasting grid). Falls back to the column format. */
+     *  (forecasting-style grids). Falls back to the column format. */
     row_format_field?: string;
     /** Pin the first column and the header row while the grid scrolls — wide
      *  month grids keep their row labels in view. */
     sticky?: boolean;
     /** Render zeroes as an em dash — de-noises mostly-empty month grids. */
     zero_dash?: boolean;
-    /** Column show/hide toggle pills above the table (EFP Actuals / Forecasts /
+    /** Column show/hide toggle pills above the table (e.g. Actuals / Forecasts /
      *  Calendar Year). A toggle turned OFF hides columns matched by exact
      *  `fields` or a field-name `suffix` — unless `hide_when_on` inverts it
      *  (Calendar Year ON hides the Prior/Carryover columns). */
@@ -3423,7 +3438,7 @@ declare interface QueryTableConfig {
      *  year — highlight_group is dropped unless it equals the current year. */
     highlight_year_param?: string;
     /** Tiny colored line-name legend under stacked-column headers, e.g.
-     *  ['Fcst', 'Act'] (EFP listHeaderSubLabel). */
+     *  ['Fcst', 'Act']. */
     stack_legend?: [string, string];
     /** Pivot long rows into month columns BEFORE rendering. Rows sharing the
      *  same key fields merge into one row with Jan…Dec (+ optional
@@ -3440,7 +3455,7 @@ declare interface QueryTableConfig {
         year_param?: string;
         /** Add a Total column summing every pivoted cell. */
         total?: boolean;
-        /** Render a Months/Quarters toggle above the table (EFP quarterly view).
+        /** Render a Months/Quarters toggle above the table (quarterly view).
          *  Quarter columns sum their three months — same drill/total math. */
         quarter_toggle?: boolean;
         /** Colour role/hex for the generated period + year columns, an optional
@@ -3481,8 +3496,8 @@ declare interface QueryWidgetConfig {
     }>;
     /** 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'. */
+     *  '$rows.<field>'); an unresolved param blocks the run with a message
+     *  (e.g. a "recalculate" stored-procedure button). */
     actions?: Array<{
         label: string;
         query_slug: string;
@@ -3502,7 +3517,7 @@ declare type QueryWidgetFilter = {
     /** 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). */
+     *  calendar year (default-year behavior). */
     default_values?: Array<string | number>;
 };
 
@@ -3529,13 +3544,13 @@ declare interface QueryWidgetStat {
     };
     /** Card tint (any CSS color, e.g. '#f9fbd1'). */
     bg?: string;
-    /** Only sum rows matching these field values (equality AND) — EFP
-     *  forecasting stats scope to the Workflow Forecast section. */
+    /** Only sum rows matching these field values (equality AND) — e.g. scope a
+     *  stat to one tree section of the table. */
     row_match?: Record<string, unknown>;
     /** Delta stat: value = sum(field) − sum(field_subtract); positive values
      *  render with a leading '+'. */
     field_subtract?: string;
-    /** EFP stat-card accent: colored top border + value (accent_dark in dark
+    /** Stat-card accent: colored top border + value (accent_dark in dark
      *  mode; accent_negative when a delta goes negative). Each may be a role name
      *  — accent | positive | negative | info … — see QueryTable COLOR_ROLES. */
     accent?: string;
@@ -3864,7 +3879,7 @@ declare interface RecordGridEditorConfig {
         query_slug: string;
         params?: Record<string, unknown>;
     };
-    /** Nested map editors opened from toolbar buttons (EFP Manage Cost Tables) —
+    /** Nested map editors opened from toolbar buttons (e.g. cost tables) —
      *  receive the current scope; enabled once `require_scope` fields are set. */
     toolbar_editors?: Array<{
         button_label: string;
@@ -3880,7 +3895,7 @@ export declare function RecordGridWidgetBody({ widget }: {
     widget: PageRendererWidget;
 }): JSX.Element;
 
-export declare function RecordReadView({ collection, itemId, layoutData, flush, renderSlot, integrityMarks, renderGrid, gridCounts }: {
+export declare function RecordReadView({ collection, itemId, layoutData, flush, renderSlot, integrityMarks, renderGrid, onEditSection, gridCounts }: {
     collection: string;
     itemId: string;
     layoutData: ReadViewLayout;
@@ -3889,11 +3904,15 @@ export declare function RecordReadView({ collection, itemId, layoutData, flush,
     /**
      * Page-slot sentinels (`__comments__`, `__tasks__`, …) the host wants to
      * keep LIVE inside the read view — Summary mode is read-only for the
-     * record's fields, but notes and tasks stay editable (Rob). Return null to
+     * record's fields, but notes and tasks stay editable. Return null to
      * skip a slot. A slot placed in a section renders inside that card; the
      * rest render full-width under the cards, in layout order.
      */
     renderSlot?: (key: string, assignment: LayoutAssignment) => ReactNode;
+    /** Summary-mode hosts: a pencil on every section header that hands back the
+     *  group key + its first field so the host can flip to Edit and land there
+     *  (whole-form flip + scroll was the only way in). */
+    onEditSection?: (groupKey: string, firstField: string | null) => void;
     /**
      * Summary mode hides the data-integrity banner but must not hide the
      * problem: with this on, every field (or child grid) that carries a
@@ -3974,7 +3993,7 @@ export declare function RelationCombobox({ collection, value, onChange, disabled
     value: unknown;
     onChange: (v: unknown) => void;
     /** A "floating" option shown FIRST regardless of search or sort — the
-     *  project's default CIFA for a materials line, say. Label = the option's
+     *  parent's default item for a materials line, say. Label = the option's
      *  own display label; `tag` is the small badge beside it ("Default"). */
     pinned?: {
         id: unknown;
@@ -4129,7 +4148,7 @@ declare interface ReviewListConfig {
         /** 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). */
+         *  (e.g. an extension's /decide route). */
         action_endpoint?: string | null;
     };
 }
@@ -4267,8 +4286,8 @@ declare interface RowLint {
  * "Which related record is this row matched to, and if none, why not?"
  *
  * Config-driven (`options.row_match_panel` on an inline-table field): the
- * O2M alias on the child that points at the matched records (a workflow
- * line's `po_line_items`), the columns to show for a match, and — for the
+ * O2M alias on the child that points at the matched records (a request
+ * line's PO lines), the columns to show for a match, and — for the
  * unmatched case — how to find the nearest candidate among a filtered set
  * (the record's linked purchase orders) and which keys the match rule
  * compares. `useRowMatches` resolves this ONCE for every saved row of a
@@ -4276,7 +4295,7 @@ declare interface RowLint {
  * full panel with the reason a match fails.
  */
 declare interface RowMatchPanelConfig {
-    /** O2M alias on the child collection (e.g. workflow_line_items.po_line_items). */
+    /** O2M alias on the child collection (e.g. request_lines.po_lines). */
     relation: string;
     /** Panel heading. Default "Match". */
     title?: string;
@@ -4792,7 +4811,7 @@ text: string;
 export declare function useElapsedLoading(loading: boolean, thresholdMs?: number): number | null;
 
 /**
- * Resolves an entity room ('wf:CR26-76773') to the record's URL, host-routed
+ * Resolves an entity room ('<prefix>:<token>') to the record's URL, host-routed
  * via cfg.recordUrl. The room-type registry maps the prefix to a collection +
  * match field; when the match field isn't the PK the record is looked up by
  * it (readable by construction — room visibility already required record