@dxos/react-ui-canvas 0.8.4-main.b97322e → 0.8.4-main.bc2380dfbc

package/src/components/CellGrid/render/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './overlay-layer';
+export * from './static-layer';

package/src/components/CellGrid/render/overlay-layer.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Headers, Selection, Viewport } from '../state/types';
+import { cellWidth, worldToScreen } from '../state/viewport';
+
+export type OverlayStyle = {
+  playhead: string;
+  selectionFill: string;
+  selectionStroke: string;
+};
+
+export type DrawOverlayOptions = {
+  ctx: CanvasRenderingContext2D;
+  size: { width: number; height: number };
+  viewport: Viewport;
+  headers: Headers;
+  selection: Selection;
+  /** Playhead position in world units (col + fraction), or null when not playing. */
+  playhead: number | null;
+  style: OverlayStyle;
+};
+
+export const drawOverlay = ({ ctx, size, viewport, headers, selection, playhead, style }: DrawOverlayOptions): void => {
+  ctx.clearRect(0, 0, size.width, size.height);
+
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(headers.left, headers.top, size.width - headers.left, size.height - headers.top);
+  ctx.clip();
+
+  // Selection rectangle.
+  if (selection.range) {
+    const { col0, row0, col1, row1 } = selection.range;
+    const minCol = Math.min(col0, col1);
+    const maxCol = Math.max(col0, col1);
+    const minRow = Math.min(row0, row1);
+    const maxRow = Math.max(row0, row1);
+    const tl = worldToScreen(viewport, headers, { col: minCol, row: minRow });
+    const br = worldToScreen(viewport, headers, { col: maxCol + 1, row: maxRow + 1 });
+    ctx.fillStyle = style.selectionFill;
+    ctx.fillRect(tl.x, tl.y, br.x - tl.x, br.y - tl.y);
+    ctx.strokeStyle = style.selectionStroke;
+    ctx.setLineDash([4, 3]);
+    ctx.lineWidth = 1;
+    ctx.strokeRect(tl.x + 0.5, tl.y + 0.5, br.x - tl.x - 1, br.y - tl.y - 1);
+    ctx.setLineDash([]);
+  }
+
+  // Playhead.
+  if (playhead !== null) {
+    const w = cellWidth(viewport);
+    const x = headers.left + playhead * w - viewport.scrollX;
+    if (x >= headers.left && x <= size.width) {
+      ctx.strokeStyle = style.playhead;
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      ctx.moveTo(x, headers.top);
+      ctx.lineTo(x, size.height);
+      ctx.stroke();
+    }
+  }
+
+  ctx.restore();
+};

package/src/components/CellGrid/render/static-layer.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Cell, Headers, Row, Viewport } from '../state/types';
+import { cellWidth, visibleCellRange, visibleCells, worldToScreen } from '../state/viewport';
+
+export type RenderCellArgs<T> = {
+  ctx: CanvasRenderingContext2D;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  cell: Cell<T>;
+};
+
+export type RenderCell<T = unknown> = (args: RenderCellArgs<T>) => void;
+
+export type StaticLayerStyle = {
+  /** Grid line color, e.g. 'rgba(0,0,0,0.08)'. */
+  gridLine: string;
+  /** Row band fill (alternating), e.g. 'rgba(0,0,0,0.02)'. */
+  rowBand?: string;
+  background?: string;
+};
+
+export type DrawCellsOptions<T> = {
+  ctx: CanvasRenderingContext2D;
+  size: { width: number; height: number };
+  viewport: Viewport;
+  headers: Headers;
+  rows: ReadonlyArray<Row>;
+  cells: ReadonlyMap<string, Cell<T>>;
+  renderCell: RenderCell<T>;
+  style: StaticLayerStyle;
+};
+
+/**
+ * Paint the static layer: background, gridlines, alternating row bands, and cells.
+ * Pure with respect to its inputs (writes only to the supplied ctx).
+ */
+export const drawCells = <T>({
+  ctx,
+  size,
+  viewport,
+  headers,
+  rows,
+  cells,
+  renderCell,
+  style,
+}: DrawCellsOptions<T>): void => {
+  ctx.clearRect(0, 0, size.width, size.height);
+
+  if (style.background) {
+    ctx.fillStyle = style.background;
+    ctx.fillRect(0, 0, size.width, size.height);
+  }
+
+  const range = visibleCellRange(viewport, headers, size);
+  const w = cellWidth(viewport);
+  const h = viewport.cellHeight;
+
+  // Row bands. Paint odd rows so the stripe pattern matches the TrackHeader's
+  // label backgrounds (which darken odd row indices) — keeps the frozen left
+  // column and the cell area visually in lockstep.
+  if (style.rowBand) {
+    ctx.fillStyle = style.rowBand;
+    for (let row = range.minRow; row <= Math.min(range.maxRow, rows.length - 1); row++) {
+      if (row % 2 === 0) {
+        continue;
+      }
+      const y = headers.top + row * h - viewport.scrollY;
+      ctx.fillRect(headers.left, y, size.width - headers.left, h);
+    }
+  }
+
+  // Gridlines.
+  ctx.strokeStyle = style.gridLine;
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  for (let col = range.minCol; col <= range.maxCol + 1; col++) {
+    const x = Math.floor(headers.left + col * w - viewport.scrollX) + 0.5;
+    if (x < headers.left) {
+      continue;
+    }
+    ctx.moveTo(x, headers.top);
+    ctx.lineTo(x, size.height);
+  }
+  for (let row = range.minRow; row <= Math.min(range.maxRow + 1, rows.length); row++) {
+    const y = Math.floor(headers.top + row * h - viewport.scrollY) + 0.5;
+    if (y < headers.top) {
+      continue;
+    }
+    ctx.moveTo(headers.left, y);
+    ctx.lineTo(size.width, y);
+  }
+  ctx.stroke();
+
+  // Cells.
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(headers.left, headers.top, size.width - headers.left, size.height - headers.top);
+  ctx.clip();
+  for (const cell of visibleCells(cells, range)) {
+    if (cell.row >= rows.length) {
+      continue;
+    }
+    const rect = worldToScreen(viewport, headers, cell);
+    renderCell({ ctx, ...rect, cell });
+  }
+  ctx.restore();
+};

package/src/components/CellGrid/state/atoms.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+
+import type { Cell, Selection, Tool, Viewport } from './types';
+
+export type CellGridAtoms<T = unknown> = {
+  cells: Atom.Writable<ReadonlyMap<string, Cell<T>>>;
+  viewport: Atom.Writable<Viewport>;
+  selection: Atom.Writable<Selection>;
+  playhead: Atom.Writable<number | null>;
+  tool: Atom.Writable<Tool>;
+};
+
+export type CellGridAtomsOptions = {
+  cellWidth?: number;
+  cellHeight?: number;
+};
+
+export const defaultViewport = (options: CellGridAtomsOptions = {}): Viewport => ({
+  scrollX: 0,
+  scrollY: 0,
+  baseCellWidth: options.cellWidth ?? 24,
+  cellHeight: options.cellHeight ?? 24,
+  zoomX: 1,
+});
+
+/**
+ * Create a fresh set of atoms backing a CellGrid instance. Consumers may pass any of these as props
+ * or substitute their own (e.g., a cells atom backed by ECHO).
+ *
+ * Atoms are marked keepAlive so they preserve state across transient unsubscribe windows (e.g. React
+ * Strict Mode mount-unmount-remount). Consumers are responsible for the atoms' lifetime.
+ */
+export const createCellGridAtoms = <T = unknown>(options: CellGridAtomsOptions = {}): CellGridAtoms<T> => ({
+  cells: Atom.keepAlive(Atom.make<ReadonlyMap<string, Cell<T>>>(new Map())),
+  viewport: Atom.keepAlive(Atom.make<Viewport>(defaultViewport(options))),
+  selection: Atom.keepAlive(Atom.make<Selection>({ range: null })),
+  playhead: Atom.keepAlive(Atom.make<number | null>(null)),
+  tool: Atom.keepAlive(Atom.make<Tool>('toggle')),
+});

package/src/components/CellGrid/state/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './atoms';
+export * from './types';
+export * from './viewport';

package/src/components/CellGrid/state/types.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export type CellCoord = { col: number; row: number };
+
+export type Cell<T = unknown> = {
+  col: number;
+  row: number;
+  length: number;
+  data?: T;
+};
+
+export type Viewport = {
+  /** World-space scroll offset (pixels). */
+  scrollX: number;
+  scrollY: number;
+  /** Cell dimensions in pixels at zoomX = 1. */
+  baseCellWidth: number;
+  cellHeight: number;
+  /** Horizontal zoom factor. */
+  zoomX: number;
+};
+
+export type SelectionRange = {
+  col0: number;
+  row0: number;
+  col1: number;
+  row1: number;
+};
+
+export type Selection = {
+  range: SelectionRange | null;
+};
+
+export type Tool = 'toggle' | 'select' | 'resize';
+
+export type Row = { id: string; label?: string };
+
+export type Headers = { left: number; top: number };

package/src/components/CellGrid/state/viewport.test.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { defaultViewport } from './atoms';
+import { hitTestCell, screenToWorld, visibleCellRange, visibleCells, worldToScreen } from './viewport';
+
+const headers = { left: 80, top: 24 };
+
+describe('viewport', () => {
+  test('worldToScreen / screenToWorld round-trip', ({ expect }) => {
+    const viewport = { ...defaultViewport(), scrollX: 100, scrollY: 50 };
+    const { x, y } = worldToScreen(viewport, headers, { col: 5, row: 3 });
+    const back = screenToWorld(viewport, headers, { x, y });
+    expect(back.col).toBeCloseTo(5);
+    expect(back.row).toBeCloseTo(3);
+  });
+
+  test('hitTestCell returns null in header region', ({ expect }) => {
+    const viewport = defaultViewport();
+    expect(hitTestCell(viewport, headers, { x: 10, y: 10 })).toBeNull();
+    expect(hitTestCell(viewport, headers, { x: 200, y: 10 })).toBeNull();
+    expect(hitTestCell(viewport, headers, { x: 10, y: 200 })).toBeNull();
+  });
+
+  test('hitTestCell floors fractional coords', ({ expect }) => {
+    const viewport = { ...defaultViewport(), baseCellWidth: 20, cellHeight: 20 };
+    const coord = hitTestCell(viewport, headers, { x: 80 + 25, y: 24 + 45 });
+    expect(coord).toEqual({ col: 1, row: 2 });
+  });
+
+  test('visibleCellRange respects scroll', ({ expect }) => {
+    const viewport = { ...defaultViewport(), scrollX: 240, baseCellWidth: 24, cellHeight: 24 };
+    const range = visibleCellRange(viewport, headers, { width: 400, height: 200 });
+    expect(range.minCol).toBe(10);
+  });
+
+  test('visibleCells filters by row and column extent', ({ expect }) => {
+    const cells = new Map([
+      ['0,0', { col: 0, row: 0, length: 1 }],
+      ['100,0', { col: 100, row: 0, length: 1 }],
+      ['5,5', { col: 5, row: 5, length: 1 }],
+      ['8,1', { col: 8, row: 1, length: 10 }],
+    ]);
+    const result = Array.from(visibleCells(cells, { minCol: 0, maxCol: 12, minRow: 0, maxRow: 2 }));
+    expect(result.map((cell) => `${cell.col},${cell.row}`).sort()).toEqual(['0,0', '8,1']);
+  });
+});

package/src/components/CellGrid/state/viewport.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Cell, CellCoord, Headers, Viewport } from './types';
+
+export const cellKey = (col: number, row: number): string => `${col},${row}`;
+
+export const cellWidth = (viewport: Viewport): number => viewport.baseCellWidth * viewport.zoomX;
+
+/**
+ * Convert a cell's world coordinates to screen-space pixel rectangle (relative to canvas origin).
+ */
+export const worldToScreen = (
+  viewport: Viewport,
+  headers: Headers,
+  coord: { col: number; row: number; length?: number },
+): { x: number; y: number; w: number; h: number } => {
+  const w = cellWidth(viewport);
+  return {
+    x: headers.left + coord.col * w - viewport.scrollX,
+    y: headers.top + coord.row * viewport.cellHeight - viewport.scrollY,
+    w: (coord.length ?? 1) * w,
+    h: viewport.cellHeight,
+  };
+};
+
+/**
+ * Convert screen-space pixels (relative to canvas origin) to fractional cell coordinates.
+ */
+export const screenToWorld = (
+  viewport: Viewport,
+  headers: Headers,
+  point: { x: number; y: number },
+): { col: number; row: number } => {
+  const w = cellWidth(viewport);
+  return {
+    col: (point.x - headers.left + viewport.scrollX) / w,
+    row: (point.y - headers.top + viewport.scrollY) / viewport.cellHeight,
+  };
+};
+
+export const hitTestCell = (
+  viewport: Viewport,
+  headers: Headers,
+  point: { x: number; y: number },
+): CellCoord | null => {
+  if (point.x < headers.left || point.y < headers.top) {
+    return null;
+  }
+  const { col, row } = screenToWorld(viewport, headers, point);
+  if (col < 0 || row < 0) {
+    return null;
+  }
+  return { col: Math.floor(col), row: Math.floor(row) };
+};
+
+/**
+ * Compute the inclusive range of cell coordinates intersecting the visible content rect.
+ */
+export const visibleCellRange = (
+  viewport: Viewport,
+  headers: Headers,
+  size: { width: number; height: number },
+): { minCol: number; maxCol: number; minRow: number; maxRow: number } => {
+  const w = cellWidth(viewport);
+  const innerW = Math.max(0, size.width - headers.left);
+  const innerH = Math.max(0, size.height - headers.top);
+  const minCol = Math.max(0, Math.floor(viewport.scrollX / w));
+  const maxCol = Math.floor((viewport.scrollX + innerW) / w);
+  const minRow = Math.max(0, Math.floor(viewport.scrollY / viewport.cellHeight));
+  const maxRow = Math.floor((viewport.scrollY + innerH) / viewport.cellHeight);
+  return { minCol, maxCol, minRow, maxRow };
+};
+
+/**
+ * Iterate sparse cell map, yielding only cells whose horizontal extent intersects visible cols and whose row is visible.
+ */
+export const visibleCells = function* <T>(
+  cells: ReadonlyMap<string, Cell<T>>,
+  range: { minCol: number; maxCol: number; minRow: number; maxRow: number },
+): Generator<Cell<T>> {
+  for (const cell of cells.values()) {
+    if (cell.row < range.minRow || cell.row > range.maxRow) {
+      continue;
+    }
+    const start = cell.col;
+    const end = cell.col + cell.length - 1;
+    if (end < range.minCol || start > range.maxCol) {
+      continue;
+    }
+    yield cell;
+  }
+};

package/src/components/FPS.tsx

@@ -6,7 +6,7 @@
 import React, { useEffect, useReducer, useRef } from 'react';
 
 import { type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 export type FPSProps = ThemedClassName<{
   width?: number;
@@ -53,7 +53,7 @@ export const FPS = ({ classNames, width = 60, height = 30, bar = 'bg-cyan-500' }
     },
   );
 
-  const requestRef = useRef<number>();
+  const requestRef = useRef<number | null>(null);
   const tick = () => {
     dispatch();
     requestRef.current = requestAnimationFrame(tick);
@@ -73,7 +73,7 @@ export const FPS = ({ classNames, width = 60, height = 30, bar = 'bg-cyan-500' }
       style={{ width: width + 6 }}
       className={mx(
         'relative flex flex-col p-0.5',
-        'bg-baseSurface text-xs text-subdued font-thin pointer-events-none border border-separator',
+        'bg-base-surface text-xs text-subdued font-thin pointer-events-none border border-separator',
         classNames,
       )}
     >

package/src/components/Grid/Grid.stories.tsx

@@ -2,15 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import '@dxos-theme';
-
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useRef, useState } from 'react';
 
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { GridComponent, type GridProps } from './Grid';
 import { type ProjectionState } from '../../hooks';
+import { GridComponent, type GridProps } from './Grid';
 
 const DefaultStory = (props: GridProps) => {
   const ref = useRef<HTMLDivElement>(null);
@@ -23,16 +21,19 @@ const DefaultStory = (props: GridProps) => {
   );
 };
 
-const meta: Meta<GridProps> = {
+const meta = {
   title: 'ui/react-ui-canvas/Grid',
   component: GridComponent,
   render: DefaultStory,
-  decorators: [withTheme, withLayout({ fullscreen: true })],
-};
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof GridComponent>;
 
 export default meta;
 
-type Story = StoryObj<GridProps>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {

package/src/components/Grid/Grid.tsx

@@ -2,10 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { forwardRef, useMemo, useId } from 'react';
+import React, { forwardRef, useId, useMemo } from 'react';
 
-import { useForwardedRef, type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { type ThemedClassName, useForwardedRef } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 import { useCanvasContext } from '../../hooks';
 import { type Point } from '../../types';
@@ -18,6 +18,8 @@ const defaultOffset: Point = { x: 0, y: 0 };
 
 const createId = (parent: string, grid: number) => `dx-canvas-grid-${parent}-${grid}`;
 
+// TODO(burdon): Click to drag.
+
 export type GridProps = ThemedClassName<{
   size?: number;
   scale?: number;
@@ -25,32 +27,34 @@ export type GridProps = ThemedClassName<{
   showAxes?: boolean;
 }>;
 
+// TODO(burdon): Use id of parent canvas.
+export const Grid = (props: GridProps) => {
+  const { scale, offset } = useCanvasContext();
+  return <GridComponent {...props} scale={scale} offset={offset} />;
+};
+
 export const GridComponent = forwardRef<SVGSVGElement, GridProps>(
   (
     { size: gridSize = defaultGridSize, scale = 1, offset = defaultOffset, showAxes = true, classNames },
     forwardedRef,
   ) => {
     const svgRef = useForwardedRef(forwardedRef);
+    const { width = 0, height = 0 } = svgRef.current?.getBoundingClientRect() ?? {};
+
     const instanceId = useId();
     const grids = useMemo(
       () =>
         gridRatios
           .map((ratio) => ({ id: ratio, size: ratio * gridSize * scale }))
-          .filter(({ size }) => size >= gridSize && size <= 256),
+          .filter(({ size }) => size >= gridSize && size <= 128),
       [gridSize, scale],
     );
 
-    const { width = 0, height = 0 } = svgRef.current?.getBoundingClientRect() ?? {};
-
     return (
       <svg
         {...testId('dx-canvas-grid')}
         ref={svgRef}
-        className={mx(
-          'absolute inset-0 w-full h-full pointer-events-none touch-none select-none',
-          'stroke-neutral-500',
-          classNames,
-        )}
+        className={mx('dx-fullscreen pointer-events-none touch-none select-none', 'stroke-neutral-500', classNames)}
       >
         {/* NOTE: The pattern is offset so that the middle of the pattern aligns with the grid. */}
         <defs>
@@ -79,9 +83,3 @@ export const GridComponent = forwardRef<SVGSVGElement, GridProps>(
     );
   },
 );
-
-// TODO(burdon): Use id of parent canvas.
-export const Grid = (props: GridProps) => {
-  const { scale, offset } = useCanvasContext();
-  return <GridComponent {...props} scale={scale} offset={offset} />;
-};

package/src/components/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './Canvas';
+export * from './CellGrid';
 export * from './FPS';
 export * from './Grid';

package/src/hooks/index.ts

@@ -4,4 +4,5 @@
 
 export * from './projection';
 export * from './useCanvasContext';
+export * from './useDrag';
 export * from './useWheel';

package/src/hooks/projection.tsx

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { interpolate, interpolateObject, transition, easeSinOut } from 'd3';
+import { easeSinOut, interpolate, interpolateObject, transition } from 'd3';
 import {
   type Matrix,
   applyToPoints,
@@ -13,7 +13,7 @@ import {
   translate as translateMatrix,
 } from 'transformation-matrix';
 
-import { type Point, type Dimension } from '../types';
+import { type Dimension, type Point } from '../types';
 
 export const defaultOrigin: Point = { x: 0, y: 0 };