@ai-matrx/records-ui 0.90.1 → 0.92.0

package/dist/index.d.cts

@@ -1192,6 +1192,10 @@ interface PersonPickerProps {
     disabled?: boolean | undefined;
     id?: string | undefined;
     className?: string | undefined;
+    /** A grid cell's picker opens at once (`FieldEditorControlProps.autoOpen`). */
+    autoOpen?: boolean | undefined;
+    /** The list closed: the cell commits who is picked. */
+    onClose?: (() => void) | undefined;
 }
 /** A Person record in the kernel Table, as this picker needs to read it. */
 interface PersonRecord {
@@ -1213,7 +1217,7 @@ declare function personRecordForMember(client: RecordsClient, personTableId: Uui
     ok: false;
     error: RecordsError;
 }>;
-declare function PersonPicker({ field, value, onChange, disabled, id, className }: PersonPickerProps): react.JSX.Element;
+declare function PersonPicker({ field, value, onChange, disabled, id, className, autoOpen, onClose }: PersonPickerProps): react.JSX.Element;
 
 /** Which cell is open. A grid opens exactly one at a time, like every other grid. */
 interface CellAddress {
@@ -1246,14 +1250,16 @@ interface GridEditing {
      * exactly that, replacing the value, as every spreadsheet does; a picker column opens as usual.
      */
     begin: (address: CellAddress, seed?: string | null) => void;
-    cancel: () => void;
+    /** `via`: a key (Escape) or a pointer (the picker's own close) — how the grid gets its keys back. */
+    cancel: (via?: EditVia) => void;
     /**
      * Commit the open cell — whatever is in `draft`. `move` opens the
      * next/previous editable cell after it. It takes NO value: a caller that
      * passed one would be a second copy of the typed value, which is the defect
      * this file's header describes.
      */
-    commit: (move?: "next" | "previous" | null) => void;
+    /** Answers `false` when the cell stayed open: typed words that are not a value (editors.tsx). */
+    commit: (move?: "next" | "previous" | null, via?: EditVia) => boolean | void;
     /**
      * WRITE ONE CELL OUTRIGHT, with no editor ever opening.
      *
@@ -1330,8 +1336,18 @@ interface Options {
         before: unknown;
         after: unknown;
     }) => void) | undefined;
+    /**
+     * THE GRID GETS ITS KEYS BACK (merged-grid review 2026-09-26, A1). Bound, an editor that closes
+     * by a key or a pick says so — Enter `down`, Tab `right` (Shift-Tab `left`), Escape and a pick
+     * `stay` — and Tab no longer opens the next cell's editor: it commits and the CURSOR moves right,
+     * as in Sheets and Airtable. A blur (a click elsewhere) says nothing: the click has the focus.
+     * Unbound (the classic grid), Tab chains editors as before.
+     */
+    onEnded?: ((exit: "down" | "right" | "left" | "stay", from: CellAddress, how: "keyboard" | "pointer") => void) | undefined;
 }
-declare function useGridEditing({ tableId, fields, rows, reload, canWrite, mayWriteRow, onWritten }: Options): GridEditing;
+/** How an open cell was closed: a key (Enter, Tab, Escape), the picker's own close, or a blur. */
+type EditVia = "key" | "pick" | "blur";
+declare function useGridEditing({ tableId, fields, rows, reload, canWrite, mayWriteRow, onWritten, onEnded }: Options): GridEditing;
 /**
  * ONE CELL. Read, until somebody asks to change it; then the Field's own
  * editor, in place, with the keys a person expects from a grid.
@@ -1805,8 +1821,14 @@ interface GridProps {
      * the store compiles both into the one WHERE clause.
      */
     filter?: StoreFilter$1 | undefined;
-    /** Opened when a row is clicked. A host that has a record page passes its own. */
+    /** Opened from a row's handle, Space or the row menu. A host that has a record page passes its own. */
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
+    /**
+     * THE RECORD THE HOST HAS OPEN BESIDE THE GRID, if any (merged grid). While one is open the panel
+     * FOLLOWS the cursor: arrowing to another row opens that row (Airtable's expanded record walks
+     * with the arrows), so the panel always shows the row the person is on.
+     */
+    openRecordId?: Uuid | null | undefined;
     /** SCR-2. Called when an admin clicks the "+" at the end of the headers. */
     onAddField?: (() => void) | undefined;
     /**
@@ -1867,7 +1889,7 @@ interface GridProps {
     footer?: FooterPlacement | undefined;
     className?: string | undefined;
 }
-declare function Grid({ tableId, pageSize, filter, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, viewOrder, footer, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
+declare function Grid({ tableId, pageSize, filter, onOpenRecord, openRecordId, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, viewOrder, footer, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
 
 /** Answers "what is the record with this id called", for one Field's values. */
 type LabelLookup = (field: Field$1, id: string) => string | null;
@@ -2354,6 +2376,14 @@ interface FieldEditorControlProps {
     onChange: (value: unknown) => void;
     disabled?: boolean | undefined;
     id?: string | undefined;
+    /**
+     * A GRID CELL'S PICKER OPENS AT ONCE (merged-grid review 2026-09-26, A2). One click on a selected
+     * choice, multi-choice or person cell opens its list directly — no inline Save/Cancel form that
+     * grows the row. Honoured by the choice and person pickers; every other control ignores it.
+     */
+    autoOpen?: boolean | undefined;
+    /** The picker's list closed (a pick, Escape, a click away): the cell commits what is chosen. */
+    onClose?: (() => void) | undefined;
 }
 /** The label row every editor shares: one line, the label, the unit, the required mark. */
 declare function FieldLabel({ field, htmlFor, children }: {
@@ -2361,7 +2391,7 @@ declare function FieldLabel({ field, htmlFor, children }: {
     htmlFor: string;
     children?: ReactNode;
 }): react.JSX.Element;
-declare function FieldControl({ field, value, onChange, disabled, id }: FieldEditorControlProps): string | number | bigint | true | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element;
+declare function FieldControl({ field, value, onChange, disabled, id, autoOpen, onClose }: FieldEditorControlProps): string | number | bigint | true | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element;
 /** The chip a picked record shows as — REC-2's "a record is a chip" in one place. */
 declare function RecordChip({ title, onRemove, className, }: {
     title: string;
@@ -2711,6 +2741,8 @@ interface ViewSwitcherProps {
      */
     onViewChange?: ((patch: Partial<SavedViewSpec>) => void) | undefined;
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
+    /** The record the host has open beside a grid, which the grid's panel then follows (`Grid.openRecordId`). */
+    openRecordId?: Uuid | null | undefined;
     /**
      * Called after a card moves between columns, so the host re-reads the rows it owns. A
      * board that moved a card and left the row list alone would show the card in two places
@@ -2794,7 +2826,7 @@ declare function useViewRecords(view: SavedViewSpec, pageSize?: number, filter?:
      */
     membership: string;
 };
-declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, titleField, filter, hostLayout, onHostLayoutChange, chooser, openExport, viewId, onOrderPlaced, footer, className, }: ViewSwitcherProps): react.JSX.Element;
+declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, openRecordId, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, titleField, filter, hostLayout, onHostLayoutChange, chooser, openExport, viewId, onOrderPlaced, footer, className, }: ViewSwitcherProps): react.JSX.Element;
 
 /** What the screen says above the list, so nobody has to be told twice that nothing was destroyed. */
 declare const ARCHIVE_MEANS = "Archiving never destroys anything. A record you remove from the grid waits here until somebody brings it back.";

package/dist/index.d.ts

@@ -1192,6 +1192,10 @@ interface PersonPickerProps {
     disabled?: boolean | undefined;
     id?: string | undefined;
     className?: string | undefined;
+    /** A grid cell's picker opens at once (`FieldEditorControlProps.autoOpen`). */
+    autoOpen?: boolean | undefined;
+    /** The list closed: the cell commits who is picked. */
+    onClose?: (() => void) | undefined;
 }
 /** A Person record in the kernel Table, as this picker needs to read it. */
 interface PersonRecord {
@@ -1213,7 +1217,7 @@ declare function personRecordForMember(client: RecordsClient, personTableId: Uui
     ok: false;
     error: RecordsError;
 }>;
-declare function PersonPicker({ field, value, onChange, disabled, id, className }: PersonPickerProps): react.JSX.Element;
+declare function PersonPicker({ field, value, onChange, disabled, id, className, autoOpen, onClose }: PersonPickerProps): react.JSX.Element;
 
 /** Which cell is open. A grid opens exactly one at a time, like every other grid. */
 interface CellAddress {
@@ -1246,14 +1250,16 @@ interface GridEditing {
      * exactly that, replacing the value, as every spreadsheet does; a picker column opens as usual.
      */
     begin: (address: CellAddress, seed?: string | null) => void;
-    cancel: () => void;
+    /** `via`: a key (Escape) or a pointer (the picker's own close) — how the grid gets its keys back. */
+    cancel: (via?: EditVia) => void;
     /**
      * Commit the open cell — whatever is in `draft`. `move` opens the
      * next/previous editable cell after it. It takes NO value: a caller that
      * passed one would be a second copy of the typed value, which is the defect
      * this file's header describes.
      */
-    commit: (move?: "next" | "previous" | null) => void;
+    /** Answers `false` when the cell stayed open: typed words that are not a value (editors.tsx). */
+    commit: (move?: "next" | "previous" | null, via?: EditVia) => boolean | void;
     /**
      * WRITE ONE CELL OUTRIGHT, with no editor ever opening.
      *
@@ -1330,8 +1336,18 @@ interface Options {
         before: unknown;
         after: unknown;
     }) => void) | undefined;
+    /**
+     * THE GRID GETS ITS KEYS BACK (merged-grid review 2026-09-26, A1). Bound, an editor that closes
+     * by a key or a pick says so — Enter `down`, Tab `right` (Shift-Tab `left`), Escape and a pick
+     * `stay` — and Tab no longer opens the next cell's editor: it commits and the CURSOR moves right,
+     * as in Sheets and Airtable. A blur (a click elsewhere) says nothing: the click has the focus.
+     * Unbound (the classic grid), Tab chains editors as before.
+     */
+    onEnded?: ((exit: "down" | "right" | "left" | "stay", from: CellAddress, how: "keyboard" | "pointer") => void) | undefined;
 }
-declare function useGridEditing({ tableId, fields, rows, reload, canWrite, mayWriteRow, onWritten }: Options): GridEditing;
+/** How an open cell was closed: a key (Enter, Tab, Escape), the picker's own close, or a blur. */
+type EditVia = "key" | "pick" | "blur";
+declare function useGridEditing({ tableId, fields, rows, reload, canWrite, mayWriteRow, onWritten, onEnded }: Options): GridEditing;
 /**
  * ONE CELL. Read, until somebody asks to change it; then the Field's own
  * editor, in place, with the keys a person expects from a grid.
@@ -1805,8 +1821,14 @@ interface GridProps {
      * the store compiles both into the one WHERE clause.
      */
     filter?: StoreFilter$1 | undefined;
-    /** Opened when a row is clicked. A host that has a record page passes its own. */
+    /** Opened from a row's handle, Space or the row menu. A host that has a record page passes its own. */
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
+    /**
+     * THE RECORD THE HOST HAS OPEN BESIDE THE GRID, if any (merged grid). While one is open the panel
+     * FOLLOWS the cursor: arrowing to another row opens that row (Airtable's expanded record walks
+     * with the arrows), so the panel always shows the row the person is on.
+     */
+    openRecordId?: Uuid | null | undefined;
     /** SCR-2. Called when an admin clicks the "+" at the end of the headers. */
     onAddField?: (() => void) | undefined;
     /**
@@ -1867,7 +1889,7 @@ interface GridProps {
     footer?: FooterPlacement | undefined;
     className?: string | undefined;
 }
-declare function Grid({ tableId, pageSize, filter, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, viewOrder, footer, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
+declare function Grid({ tableId, pageSize, filter, onOpenRecord, openRecordId, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, viewOrder, footer, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
 
 /** Answers "what is the record with this id called", for one Field's values. */
 type LabelLookup = (field: Field$1, id: string) => string | null;
@@ -2354,6 +2376,14 @@ interface FieldEditorControlProps {
     onChange: (value: unknown) => void;
     disabled?: boolean | undefined;
     id?: string | undefined;
+    /**
+     * A GRID CELL'S PICKER OPENS AT ONCE (merged-grid review 2026-09-26, A2). One click on a selected
+     * choice, multi-choice or person cell opens its list directly — no inline Save/Cancel form that
+     * grows the row. Honoured by the choice and person pickers; every other control ignores it.
+     */
+    autoOpen?: boolean | undefined;
+    /** The picker's list closed (a pick, Escape, a click away): the cell commits what is chosen. */
+    onClose?: (() => void) | undefined;
 }
 /** The label row every editor shares: one line, the label, the unit, the required mark. */
 declare function FieldLabel({ field, htmlFor, children }: {
@@ -2361,7 +2391,7 @@ declare function FieldLabel({ field, htmlFor, children }: {
     htmlFor: string;
     children?: ReactNode;
 }): react.JSX.Element;
-declare function FieldControl({ field, value, onChange, disabled, id }: FieldEditorControlProps): string | number | bigint | true | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element;
+declare function FieldControl({ field, value, onChange, disabled, id, autoOpen, onClose }: FieldEditorControlProps): string | number | bigint | true | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element;
 /** The chip a picked record shows as — REC-2's "a record is a chip" in one place. */
 declare function RecordChip({ title, onRemove, className, }: {
     title: string;
@@ -2711,6 +2741,8 @@ interface ViewSwitcherProps {
      */
     onViewChange?: ((patch: Partial<SavedViewSpec>) => void) | undefined;
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
+    /** The record the host has open beside a grid, which the grid's panel then follows (`Grid.openRecordId`). */
+    openRecordId?: Uuid | null | undefined;
     /**
      * Called after a card moves between columns, so the host re-reads the rows it owns. A
      * board that moved a card and left the row list alone would show the card in two places
@@ -2794,7 +2826,7 @@ declare function useViewRecords(view: SavedViewSpec, pageSize?: number, filter?:
      */
     membership: string;
 };
-declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, titleField, filter, hostLayout, onHostLayoutChange, chooser, openExport, viewId, onOrderPlaced, footer, className, }: ViewSwitcherProps): react.JSX.Element;
+declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, openRecordId, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, titleField, filter, hostLayout, onHostLayoutChange, chooser, openExport, viewId, onOrderPlaced, footer, className, }: ViewSwitcherProps): react.JSX.Element;
 
 /** What the screen says above the list, so nobody has to be told twice that nothing was destroyed. */
 declare const ARCHIVE_MEANS = "Archiving never destroys anything. A record you remove from the grid waits here until somebody brings it back.";