@dxos/react-ui-table 0.10.0 → 0.11.1

package/src/hooks/useTableModel.ts

@@ -3,10 +3,10 @@
 //
 
 import { RegistryContext } from '@effect-atom/atom-react';
-import { useContext, useEffect, useMemo, useState } from 'react';
+import { useContext, useEffect, useRef, useState } from 'react';
 
 import { type Database, Obj } from '@dxos/echo';
-import { useSelection, useSelectionActions, useViewStateManagerOptional } from '@dxos/react-ui-attention';
+import { useManagerOptional, useSelection, useSelectionActions } from '@dxos/react-ui-attention';
 import { type ProjectionModel } from '@dxos/schema';
 
 import {
@@ -24,6 +24,13 @@ export type UseTableModelProps<T extends TableRow = TableRow> = {
   db?: Database.Database;
   rows?: T[];
   rowActions?: TableRowAction[];
+  /**
+   * Rows to select when the model is built. Overrides the selection read from the view state for
+   * the table object — pass this when the surrounding container owns the selection under a
+   * different context id (e.g. a type article keyed by the type's URI), so switching into the
+   * table preserves what was already selected.
+   */
+  selection?: readonly string[];
   onSelectionChanged?: (selection: string[]) => void;
   onRowAction?: (actionId: string, data: T) => void;
 } & Pick<
@@ -38,14 +45,19 @@ export const useTableModel = <T extends TableRow = TableRow>({
   rows,
   rowActions,
   features,
+  selection,
   onSelectionChanged,
   onRowAction,
   ...props
 }: UseTableModelProps<T>): TableModel<T> | undefined => {
   const registry = useContext(RegistryContext);
-  const viewState = useViewStateManagerOptional();
+  const viewState = useManagerOptional();
   const selected = useSelection(object && Obj.getURI(object), 'multi');
-  const initialSelection = useMemo(() => selected, [object]);
+  // Read at construction time, not frozen into the effect's deps. The model is rebuilt whenever any
+  // of its inputs change identity, and each rebuild re-seeds from here — a frozen snapshot would
+  // reset the selection to whatever it was when the table mounted, discarding the user's clicks.
+  const initialSelection = useRef<readonly string[]>(selection ?? selected);
+  initialSelection.current = selection ?? selected;
 
   const [model, setModel] = useState<TableModel<T>>();
   useEffect(() => {
@@ -64,7 +76,7 @@ export const useTableModel = <T extends TableRow = TableRow>({
         change: createEchoChangeCallback<T>(object),
         features,
         rowActions,
-        initialSelection,
+        initialSelection: [...initialSelection.current],
         onRowAction,
         ...props,
       });
@@ -77,7 +89,7 @@ export const useTableModel = <T extends TableRow = TableRow>({
       void model?.close();
     };
     // TODO(burdon): Trigger if callbacks change?
-  }, [registry, viewState, object, projection, features, rowActions, initialSelection]);
+  }, [registry, viewState, object, projection, features, rowActions]);
 
   // Update data when rows change.
   useEffect(() => {

package/src/model/modal-controller.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
+import { Atom, type Registry } from '@effect-atom/atom';
 import { type MutableRefObject, type RefObject } from 'react';
 
 export type ColumnSettingsMode = { type: 'create' } | { type: 'edit'; fieldId: string };

package/src/model/selection-model.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
+import { Atom, type Registry } from '@effect-atom/atom';
 
 import { Resource } from '@dxos/context';
 

package/src/model/table-model.test.ts

@@ -2,13 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Registry } from '@effect-atom/atom-react';
+import { Registry } from '@effect-atom/atom';
 import * as Schema from 'effect/Schema';
 import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
 import { DXN, Filter, JsonSchema, Query, Type } from '@dxos/echo';
 import { createEchoSchema } from '@dxos/echo/testing';
-import { LocalBackend, MemoryBackend, ViewStateManager } from '@dxos/react-ui-attention';
+import { LocalBackend, MemoryBackend, ViewState } from '@dxos/react-ui-attention';
 import { ProjectionModel, ViewModel, createDirectChangeCallback } from '@dxos/schema';
 
 import { Table } from '../types';
@@ -137,7 +137,7 @@ describe('TableModel sort view state', () => {
       const registry = Registry.make();
       const local = new LocalBackend({ registry, storage });
       disposables.push(local);
-      const viewState = new ViewStateManager({ registry, backends: { memory: new MemoryBackend(), local } });
+      const viewState = new ViewState.Manager({ registry, backends: { memory: new MemoryBackend(), local } });
       const projection = new ProjectionModel({
         registry,
         view,

package/src/model/table-model.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
+import { Atom, type Registry } from '@effect-atom/atom';
 
 import { Resource } from '@dxos/context';
 import { type Database, Format, Obj, Order, Query, type QueryAST, Ref, Type, type View } from '@dxos/echo';
@@ -12,14 +12,16 @@ import { SchemaEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { EntityId } from '@dxos/keys';
 import { type Label } from '@dxos/react-ui';
-import { type ViewStateManager } from '@dxos/react-ui-attention';
-import { formatForEditing, parseValue } from '@dxos/react-ui-form';
+import { ViewState } from '@dxos/react-ui-attention';
+import { parseValue } from '@dxos/react-ui-form';
 import {
   type DxGridAxisMeta,
+  type DxGridPlane,
   type DxGridPlanePosition,
   type DxGridPlaneRange,
   type DxGridPosition,
 } from '@dxos/react-ui-grid';
+import { formatForEditing } from '@dxos/schema';
 import { type ProjectionModel, type PropertyType, type ValidationError, validateSchema } from '@dxos/schema';
 
 import { type Table } from '../types';
@@ -88,12 +90,18 @@ export type TableFeatures = {
   selection: { enabled: boolean; mode?: SelectionMode };
   dataEditable: boolean;
   schemaEditable: boolean;
+  /**
+   * Number of leading data columns to pin (freeze) so they remain visible while the remaining
+   * columns scroll horizontally. Pinned columns are rendered in the grid's frozen-column planes.
+   */
+  pinColumns: number;
 };
 
 const defaultFeatures: TableFeatures = {
   selection: { enabled: true, mode: 'multiple' },
   dataEditable: false,
   schemaEditable: false,
+  pinColumns: 0,
 };
 
 export type InsertRowResult = 'draft' | 'final';
@@ -108,7 +116,7 @@ export type TableModelProps<T extends TableRow = TableRow> = {
    * stored in the `tableSortAspect` view state keyed by the table URI; otherwise it falls back to an
    * ephemeral atom (e.g. isolated stories/tests with no `ViewStateProvider`).
    */
-  viewState?: ViewStateManager;
+  viewState?: ViewState.Manager;
   /**
    * Callbacks to wrap mutations in Obj.update().
    * Use createEchoChangeCallback() for ECHO-backed objects or createDirectChangeCallback() for plain objects.
@@ -148,9 +156,9 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
   private readonly _rows: Atom.Writable<T[]>;
   private readonly _draftRows: Atom.Writable<DraftRow<T>[]>;
   // Optional per-context UI state manager; when present the column sort is view-state-backed.
-  private readonly _viewState?: ViewStateManager;
+  private readonly _viewState?: ViewState.Manager;
   // Per-user sort state - backed by the `tableSortAspect` view state (keyed by table URI) when a
-  // ViewStateManager is provided, else an ephemeral atom. Changes are local until saved to the view.
+  // ViewState.Manager is provided, else an ephemeral atom. Changes are local until saved to the view.
   private readonly _inMemorySort: Atom.Writable<FieldSortType | undefined>;
   // Derived atom for persisted sort from view.query.ast.
   private readonly _persistedSort: Atom.Atom<FieldSortType | undefined>;
@@ -210,7 +218,7 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
     this._rows = Atom.make<T[]>([]);
     this._draftRows = Atom.make<DraftRow<T>[]>([]);
     // View-state-backed atom survives remount/reload (local backend, keyed by table URI); the
-    // ephemeral fallback preserves prior behaviour when no ViewStateManager is supplied.
+    // ephemeral fallback preserves prior behaviour when no ViewState.Manager is supplied.
     this._inMemorySort = this._viewState
       ? this._viewState.atom(tableSortAspect, this.id)
       : Atom.make<FieldSortType | undefined>(undefined);
@@ -353,6 +361,24 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
     return this._cellUpdateCounter;
   }
 
+  /**
+   * Reports the grid's currently-visible cell range (called by the presentation from `getCells`). Drives the
+   * per-row subscriptions that keep cells reactive to external mutations, so it must be wired for the grid to
+   * reflect edits made outside it. Guarded so identical ranges don't churn the subscriptions.
+   */
+  public setVisibleRange(range: DxGridPlaneRange): void {
+    const current = this._registry.get(this._visibleRange);
+    if (
+      current.start.row === range.start.row &&
+      current.end.row === range.end.row &&
+      current.start.col === range.start.col &&
+      current.end.col === range.end.col
+    ) {
+      return;
+    }
+    this._registry.set(this._visibleRange, range);
+  }
+
   /**
    * Change a row using the configured change callback.
    * Use this instead of directly mutating to ensure consistent mutation handling.
@@ -365,6 +391,57 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
     return this._features;
   }
 
+  /**
+   * Number of leading data columns pinned (frozen), clamped to the available field count.
+   */
+  public get pinColumns(): number {
+    const fieldCount = this.getColumnCount();
+    return Math.max(0, Math.min(this._features.pinColumns, fieldCount));
+  }
+
+  /**
+   * Number of frozen-start columns preceding the pinned data columns (the selection column, if enabled).
+   */
+  public get selectionColumns(): number {
+    return this._features.selection.enabled ? 1 : 0;
+  }
+
+  /**
+   * Total number of columns rendered in the `frozenColsStart` plane: the selection column (if enabled)
+   * plus the pinned data columns. Single source of truth for the frozen-start boundary.
+   */
+  public get frozenColsStart(): number {
+    return this.selectionColumns + this.pinColumns;
+  }
+
+  /**
+   * Maps a plane-local column index to a field index for the data-bearing planes.
+   * Returns undefined for non-data columns (e.g. the selection or action columns).
+   *
+   * Column layout across planes:
+   * - `frozenColsStart`: [selection?] then the first `pinColumns` data fields.
+   * - `grid` / `frozenRowsStart` / `frozenRowsEnd`: data fields starting at index `pinColumns`.
+   */
+  public getFieldIndex(plane: DxGridPlane, planeCol: number): number | undefined {
+    switch (plane) {
+      case 'frozenColsStart':
+      case 'fixedStartStart':
+      case 'fixedEndStart': {
+        const dataCol = planeCol - this.selectionColumns;
+        if (dataCol < 0 || dataCol >= this.pinColumns) {
+          return undefined;
+        }
+        return dataCol;
+      }
+      case 'grid':
+      case 'frozenRowsStart':
+      case 'frozenRowsEnd':
+        return this.pinColumns + planeCol;
+      default:
+        return undefined;
+    }
+  }
+
   /**
    * Gets the current sort state.
    * Priority: in-memory sort (local changes) > persisted sort (from query AST).
@@ -420,14 +497,38 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
     // The projection.fields atom handles subscriptions to view changes internally.
     this._columnMeta = Atom.make((get) => {
       const fields = get(this._projection.fields);
-      const meta = Object.fromEntries(
-        fields.map((field, index: number) => [index, { size: this.table.sizes[field.path] ?? 256, resizeable: true }]),
-      );
+      const pin = this.pinColumns;
+      const selectionColumns = this.selectionColumns;
+
+      const fieldSize = (field: (typeof fields)[number]) => ({
+        size: this.table.sizes[field.path] ?? 256,
+        resizeable: true,
+      });
+
+      // The scrolling `grid` plane holds the un-pinned fields, re-keyed to plane-local indices.
+      const grid = Object.fromEntries(fields.slice(pin).map((field, index: number) => [index, fieldSize(field)]));
+
+      // The `frozenColsStart` plane holds the selection column (if enabled) followed by the pinned fields.
+      const frozenColsStart: Record<number, { size: number; resizeable: boolean }> = {};
+      if (selectionColumns > 0) {
+        frozenColsStart[0] = {
+          size: 32,
+          resizeable: false,
+        };
+      }
+      fields.slice(0, pin).forEach((field, index: number) => {
+        frozenColsStart[selectionColumns + index] = fieldSize(field);
+      });
 
       return {
-        grid: meta,
-        frozenColsStart: { 0: { size: 30, resizeable: false } },
-        frozenColsEnd: { 0: { size: 32, resizeable: false } },
+        grid,
+        frozenColsStart,
+        frozenColsEnd: {
+          0: {
+            size: 32,
+            resizeable: false,
+          },
+        },
       };
     });
   }
@@ -442,9 +543,10 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
     // Track row subscriptions for cleanup.
     const rowSubscriptions = new Map<string, () => void>();
 
-    // Subscribe to visible range changes to set up row subscriptions.
-    const visibleRangeUnsubscribe = this._registry.subscribe(this._visibleRange, () => {
-      // Unsubscribe from old row subscriptions.
+    // (Re)subscribe to each visible row's mutations so external edits (e.g. from a companion form) bump the
+    // cell-update counter and repaint the affected cells. Must re-run when either the visible range changes (scroll)
+    // or the row set changes (data load / sort), since rows arrive asynchronously after the range is first reported.
+    const subscribeVisibleRows = () => {
       for (const [id, unsub] of rowSubscriptions) {
         unsub();
         rowSubscriptions.delete(id);
@@ -453,21 +555,25 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
       const { start, end } = this._registry.get(this._visibleRange);
       const sortedRows = this._registry.get(this._sortedRows);
 
-      // Subscribe to each visible row's changes.
       for (let row = start.row; row <= end.row && row < sortedRows.length; row++) {
         const obj = sortedRows[row];
         if (Obj.isObject(obj) && !rowSubscriptions.has(obj.id)) {
+          const cell = { row, col: start.col, plane: 'grid' as const };
           const unsub = Obj.subscribe(obj, () => {
             // Increment cell update counter to notify UI of changes.
             this._registry.set(this._cellUpdateCounter, this._registry.get(this._cellUpdateCounter) + 1);
-            this._onCellUpdate?.({ row, col: start.col, plane: 'grid' });
+            this._onCellUpdate?.(cell);
           });
           rowSubscriptions.set(obj.id, unsub);
         }
       }
-    });
+    };
+
+    const visibleRangeUnsubscribe = this._registry.subscribe(this._visibleRange, subscribeVisibleRows);
+    const sortedRowsUnsubscribe = this._registry.subscribe(this._sortedRows, subscribeVisibleRows);
     this._ctx.onDispose(() => {
       visibleRangeUnsubscribe();
+      sortedRowsUnsubscribe();
       for (const unsub of rowSubscriptions.values()) {
         unsub();
       }
@@ -625,11 +731,12 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
   public getCellData = (cell: DxGridPosition): any => {
     const { col, row, plane } = cell;
     const fields = this._projection?.getFields() ?? [];
-    if (col < 0 || col >= fields.length) {
+    const fieldIndex = this.getFieldIndex(plane, col);
+    if (fieldIndex === undefined || fieldIndex < 0 || fieldIndex >= fields.length) {
       return undefined;
     }
 
-    const field = fields[col];
+    const field = fields[fieldIndex];
     let value: any;
 
     if (plane === 'frozenRowsEnd') {
@@ -671,11 +778,12 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
 
   public validateCellData = async ({ col, row, plane }: DxGridPosition, value: any): Promise<ValidationResult> => {
     const fields = this._projection?.getFields() ?? [];
-    if (col < 0 || col >= fields.length) {
+    const fieldIndex = this.getFieldIndex(plane, col);
+    if (fieldIndex === undefined || fieldIndex < 0 || fieldIndex >= fields.length) {
       return { valid: false, error: 'Invalid column index' };
     }
 
-    const field = fields[col];
+    const field = fields[fieldIndex];
     const { props } = this._projection.getFieldProjection(field.id);
     const transformedValue = editorTextToCellValue(props, value);
 
@@ -727,11 +835,12 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
   public setCellData = (cell: DxGridPosition, value: any): void => {
     const { col, row, plane } = cell;
     const fields = this._projection?.getFields() ?? [];
-    if (col < 0 || col >= fields.length) {
+    const fieldIndex = this.getFieldIndex(plane, col);
+    if (fieldIndex === undefined || fieldIndex < 0 || fieldIndex >= fields.length) {
       return;
     }
 
-    const field = fields[col];
+    const field = fields[fieldIndex];
     const { props } = this._projection.getFieldProjection(field.id);
     const transformedValue = editorTextToCellValue(props, value);
 
@@ -762,9 +871,16 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
    * @param {DxGridPlanePosition} position - The position of the cell to update.
    * @param {(value: any) => any} update - A function that takes the current value and returns the updated value.
    */
-  public updateCellData({ col, row }: DxGridPlanePosition, update: (value: any) => any): void {
+  public updateCellData(
+    { col, row, plane = 'grid' }: DxGridPlanePosition & { plane?: DxGridPlane },
+    update: (value: any) => any,
+  ): void {
     const fields = this._projection?.getFields() ?? [];
-    const field = fields[col];
+    const fieldIndex = this.getFieldIndex(plane, col);
+    if (fieldIndex === undefined || fieldIndex < 0 || fieldIndex >= fields.length) {
+      return;
+    }
+    const field = fields[fieldIndex];
     const sortedRows = this._registry.get(this._sortedRows);
     const rowData = sortedRows[row];
 
@@ -821,11 +937,12 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
   // Resize
   //
 
-  public setColumnWidth(columnIndex: number, width: number): void {
+  public setColumnWidth(columnIndex: number, width: number, plane: DxGridPlane = 'grid'): void {
     const fields = this._projection?.getFields() ?? [];
-    if (columnIndex < fields.length) {
+    const fieldIndex = this.getFieldIndex(plane, columnIndex);
+    if (fieldIndex !== undefined && fieldIndex < fields.length) {
       const newWidth = Math.max(0, width);
-      const field = fields[columnIndex];
+      const field = fields[fieldIndex];
       if (field) {
         this._change.table((mutableTable) => {
           mutableTable.sizes[field.path] = newWidth;
@@ -866,7 +983,7 @@ export class TableModel<T extends TableRow = TableRow> extends Resource {
   }
 
   /**
-   * Writes the per-user sort, routing through the ViewStateManager (so the `local` backend persists)
+   * Writes the per-user sort, routing through the ViewState.Manager (so the `local` backend persists)
    * when one is configured, otherwise updating the ephemeral atom directly.
    */
   private _writeSort(value: FieldSortType | undefined): void {

package/src/model/table-presentation.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Registry } from '@effect-atom/atom-react';
+import { Registry } from '@effect-atom/atom';
 import * as Schema from 'effect/Schema';
 import { beforeEach, describe, expect, it } from 'vitest';
 
@@ -84,6 +84,64 @@ describe('TablePresentation', () => {
       expect(cells['0,1']?.value).toBe('C');
     });
   });
+
+  describe('pinned columns', () => {
+    let registry: Registry.Registry;
+    let model: TableModel;
+    let presentation: TablePresentation;
+
+    beforeEach(async () => {
+      registry = Registry.make();
+      model = createTableModel(registry, { features: { selection: { enabled: false }, pinColumns: 1 } });
+      await model.open();
+      const rows: any[] = [
+        { id: '1', title: 'A', count: 1 },
+        { id: '2', title: 'B', count: 2 },
+      ];
+      model.setRows(rows);
+      presentation = new TablePresentation(registry, model);
+    });
+
+    it('renders the first data column in the frozenColsStart plane', () => {
+      const cells = presentation.getCells({ start: { row: 0, col: 0 }, end: { row: 1, col: 0 } }, 'frozenColsStart');
+      // Pinned field occupies plane-local column 0 (no selection column).
+      expect(cells['0,0']?.value).toBe('A');
+      expect(cells['0,1']?.value).toBe('B');
+    });
+
+    it('offsets the scrolling grid plane past the pinned columns', () => {
+      const cells = presentation.getCells({ start: { row: 0, col: 0 }, end: { row: 1, col: 0 } }, 'grid');
+      // The grid plane starts at the second field (count) since the first (title) is pinned.
+      expect(cells['0,0']?.value).toBe('1');
+      expect(cells['0,1']?.value).toBe('2');
+    });
+
+    it('renders the pinned column header in the fixedStartStart corner', () => {
+      const cells = presentation.getCells({ start: { row: 0, col: 0 }, end: { row: 0, col: 0 } }, 'fixedStartStart');
+      expect(cells['0,0']?.accessoryHtml).toContain('title');
+    });
+
+    it('maps plane-local columns to field indices', () => {
+      // frozenColsStart column 0 -> field 0 (pinned); grid column 0 -> field 1.
+      expect(model.getFieldIndex('frozenColsStart', 0)).toBe(0);
+      expect(model.getFieldIndex('frozenColsStart', 1)).toBeUndefined();
+      expect(model.getFieldIndex('grid', 0)).toBe(1);
+      expect(model.getFieldIndex('grid', 1)).toBe(2);
+    });
+
+    it('mutates the pinned field via its frozen-plane column', () => {
+      model.updateCellData({ plane: 'frozenColsStart', col: 0, row: 0 }, () => 'Pinned');
+      const cells = presentation.getCells({ start: { row: 0, col: 0 }, end: { row: 0, col: 0 } }, 'frozenColsStart');
+      expect(cells['0,0']?.value).toBe('Pinned');
+    });
+
+    it('ignores mutations for out-of-range columns without throwing', () => {
+      expect(() => model.updateCellData({ plane: 'grid', col: 999, row: 0 }, () => 'x')).not.toThrow();
+      // The pinned field is unchanged.
+      const cells = presentation.getCells({ start: { row: 0, col: 0 }, end: { row: 0, col: 0 } }, 'frozenColsStart');
+      expect(cells['0,0']?.value).toBe('A');
+    });
+  });
 });
 
 const Test = Type.makeObject(DXN.make('com.example.type.test', '0.1.0'))(