@dxos/react-ui-canvas 0.8.4-main.ead640a → 0.8.4-main.f466a3d56e

package/src/components/CellGrid/headers/Ruler.tsx

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import type { Headers, Viewport } from '../state/types';
+import { cellWidth } from '../state/viewport';
+
+export type RulerProps = {
+  viewport: Viewport;
+  headers: Headers;
+  width: number;
+  /** Number of columns to label between major ticks. */
+  majorEvery?: number;
+  classNames?: string;
+};
+
+/**
+ * Frozen top ruler. Ticks reflect the current viewport scroll and zoom.
+ */
+export const Ruler = ({ viewport, headers, width, majorEvery = 4, classNames }: RulerProps) => {
+  // Clamp to >= 1 — a zero or negative `majorEvery` makes `col % majorEvery`
+  // NaN / always-zero and breaks major-tick detection.
+  const safeMajorEvery = Math.max(1, Math.floor(majorEvery));
+  const ticks = useMemo(() => {
+    const w = cellWidth(viewport);
+    if (w < 1 || width <= headers.left) {
+      return [];
+    }
+    const innerWidth = width - headers.left;
+    const startCol = Math.floor(viewport.scrollX / w);
+    const endCol = Math.ceil((viewport.scrollX + innerWidth) / w);
+    const result: Array<{ col: number; x: number; major: boolean }> = [];
+    for (let col = startCol; col <= endCol; col++) {
+      result.push({
+        col,
+        x: headers.left + col * w - viewport.scrollX,
+        major: col % safeMajorEvery === 0,
+      });
+    }
+    return result;
+  }, [viewport, headers.left, width, safeMajorEvery]);
+
+  return (
+    <div
+      className={mx(
+        'absolute top-0 left-0 right-0 border-b border-neutral-200 dark:border-neutral-700 bg-baseSurface select-none overflow-hidden',
+        classNames,
+      )}
+      style={{ height: headers.top }}
+    >
+      {ticks.map(({ col, x, major }) => (
+        <div
+          key={col}
+          className={mx(
+            'absolute top-0 bottom-0 text-[10px] text-neutral-500 dark:text-neutral-400',
+            major
+              ? 'border-l border-neutral-400 dark:border-neutral-500'
+              : 'border-l border-neutral-200 dark:border-neutral-700',
+          )}
+          style={{ transform: `translateX(${x}px)` }}
+        >
+          {major ? <span className='absolute left-1 top-0'>{col}</span> : null}
+        </div>
+      ))}
+    </div>
+  );
+};

package/src/components/CellGrid/headers/TrackHeader.tsx

@@ -0,0 +1,58 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import type { Headers, Row, Viewport } from '../state/types';
+
+export type TrackHeaderProps = {
+  viewport: Viewport;
+  headers: Headers;
+  rows: ReadonlyArray<Row>;
+  height: number;
+  classNames?: string;
+};
+
+/**
+ * Frozen left column listing row labels. Translates vertically in sync with viewport scroll.
+ *
+ * Row dividers and alternating shading intentionally MATCH the canvas — opaque borders
+ * and opaque alternating fills make the labels look out of phase with the cell area
+ * even when the y-positions align. We mirror the canvas's transparent-overlay model
+ * here so the frozen column reads as a direct continuation of the grid.
+ */
+export const TrackHeader = ({ viewport, headers, rows, height, classNames }: TrackHeaderProps) => {
+  return (
+    <div
+      className={mx(
+        'absolute left-0 border-r border-neutral-200 dark:border-neutral-700 select-none overflow-hidden',
+        classNames,
+      )}
+      style={{ top: headers.top, width: headers.left, height: Math.max(0, height - headers.top) }}
+    >
+      <div style={{ transform: `translateY(${-viewport.scrollY}px)` }}>
+        {rows.map((row, index) => (
+          <div
+            key={row.id}
+            className='flex items-center px-2 text-xs text-neutral-700 dark:text-neutral-300'
+            style={{
+              height: viewport.cellHeight,
+              // Match the canvas's row-band: a translucent gray overlay on odd rows,
+              // transparent on even rows. The container's overall background bleeds
+              // through, so the labels stay legible in both themes.
+              backgroundColor: index % 2 === 0 ? 'transparent' : 'rgba(128, 128, 128, 0.08)',
+              // Match the canvas gridline color (rgba(128, 128, 128, 0.25)). Use a
+              // half-pixel inset to keep crisp single-pixel rendering on retina.
+              boxShadow: 'inset 0 -1px 0 rgba(128, 128, 128, 0.25)',
+            }}
+          >
+            {row.label ?? row.id}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Ruler';
+export * from './TrackHeader';

package/src/components/CellGrid/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CellGrid';
+export * from './headers';
+export * from './input';
+export * from './render';
+export * from './state';

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './pointer';
+export * from './wheel';

package/src/components/CellGrid/input/pointer.ts

@@ -0,0 +1,208 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Registry } from '@effect-atom/atom-react';
+
+import type { CellGridAtoms } from '../state/atoms';
+import type { Cell, CellCoord, Headers, SelectionRange, Tool } from '../state/types';
+import { cellKey, hitTestCell } from '../state/viewport';
+
+/**
+ * 'set' / 'unset' are idempotent — the receiver must add or remove the cell
+ * regardless of current state. 'toggle' flips it. Drag operations always pick
+ * a fixed mode (set or unset) based on the cell under the initial pointerdown
+ * so the user paints a uniform stroke instead of flipping each cell.
+ */
+export type ToggleMode = 'set' | 'unset' | 'toggle';
+
+export type PointerHandlers = {
+  onCellToggle?: (coord: CellCoord, mode: ToggleMode) => void;
+  onSelectionCommit?: (range: SelectionRange) => void;
+};
+
+type DragState =
+  | { kind: 'toggle'; mode: 'set' | 'unset'; touched: Set<string> }
+  | { kind: 'select'; origin: CellCoord }
+  | { kind: 'pan'; lastX: number; lastY: number };
+
+export type PointerControllerOptions<T> = {
+  registry: Registry.Registry;
+  atoms: CellGridAtoms<T>;
+  headers: Headers;
+  handlers: PointerHandlers;
+};
+
+/**
+ * Attach pointer handlers to an element. Returns an unsubscribe.
+ */
+export const attachPointerHandlers = <T>(
+  element: HTMLElement,
+  { registry, atoms, headers, handlers }: PointerControllerOptions<T>,
+): (() => void) => {
+  let drag: DragState | null = null;
+
+  const local = (event: PointerEvent) => {
+    const rect = element.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  };
+
+  // setPointerCapture throws for synthetic / untrusted PointerEvents (e.g. those
+  // dispatched by tests). Capture is a best-effort UX nicety — never let it abort
+  // the click path.
+  const tryCapture = (pointerId: number) => {
+    try {
+      element.setPointerCapture(pointerId);
+    } catch {
+      // Ignore — drag tracking still works without capture.
+    }
+  };
+
+  const onPointerDown = (event: PointerEvent) => {
+    // Middle-mouse or space-held pan: pan tool regardless of `tool` atom.
+    if (event.button === 1 || (event.button === 0 && event.altKey)) {
+      drag = { kind: 'pan', lastX: event.clientX, lastY: event.clientY };
+      tryCapture(event.pointerId);
+      event.preventDefault();
+      return;
+    }
+
+    if (event.button !== 0) {
+      return;
+    }
+
+    const viewport = registry.get(atoms.viewport);
+    const point = local(event);
+    const coord = hitTestCell(viewport, headers, point);
+    if (!coord) {
+      return;
+    }
+
+    const tool = registry.get(atoms.tool) as Tool;
+    tryCapture(event.pointerId);
+
+    switch (tool) {
+      case 'toggle':
+      case 'resize': {
+        // Inspect the cells atom under the pointer to decide whether the gesture
+        // is a paint (set) or an erase (unset). Subsequent drag movements apply the
+        // same operation idempotently to every cell the cursor crosses.
+        const cells = registry.get(atoms.cells) as ReadonlyMap<string, unknown>;
+        const key = cellKey(coord.col, coord.row);
+        const mode: 'set' | 'unset' = cells.has(key) ? 'unset' : 'set';
+        handlers.onCellToggle?.(coord, mode);
+        drag = { kind: 'toggle', mode, touched: new Set([key]) };
+        break;
+      }
+      case 'select': {
+        drag = { kind: 'select', origin: coord };
+        registry.set(atoms.selection, {
+          range: { col0: coord.col, row0: coord.row, col1: coord.col, row1: coord.row },
+        });
+        break;
+      }
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent) => {
+    if (!drag) {
+      return;
+    }
+    if (drag.kind === 'pan') {
+      const dx = event.clientX - drag.lastX;
+      const dy = event.clientY - drag.lastY;
+      drag.lastX = event.clientX;
+      drag.lastY = event.clientY;
+      registry.update(atoms.viewport, (current) => ({
+        ...current,
+        scrollX: Math.max(0, current.scrollX - dx),
+        scrollY: Math.max(0, current.scrollY - dy),
+      }));
+      return;
+    }
+
+    const viewport = registry.get(atoms.viewport);
+    const coord = hitTestCell(viewport, headers, local(event));
+    if (!coord) {
+      return;
+    }
+
+    if (drag.kind === 'toggle') {
+      // Apply the drag's chosen mode to every cell the cursor enters, across rows,
+      // de-duplicating per cell so we don't fire the same coord twice.
+      const key = cellKey(coord.col, coord.row);
+      if (!drag.touched.has(key)) {
+        drag.touched.add(key);
+        handlers.onCellToggle?.(coord, drag.mode);
+      }
+    } else if (drag.kind === 'select') {
+      registry.set(atoms.selection, {
+        range: { col0: drag.origin.col, row0: drag.origin.row, col1: coord.col, row1: coord.row },
+      });
+    }
+  };
+
+  const releaseCapture = (event: PointerEvent) => {
+    if (element.hasPointerCapture(event.pointerId)) {
+      element.releasePointerCapture(event.pointerId);
+    }
+  };
+
+  const onPointerUp = (event: PointerEvent) => {
+    if (!drag) {
+      return;
+    }
+    if (drag.kind === 'select') {
+      const range = registry.get(atoms.selection).range;
+      if (range) {
+        handlers.onSelectionCommit?.(range);
+      }
+    }
+    drag = null;
+    releaseCapture(event);
+  };
+
+  // pointercancel signals an interrupted gesture (system gesture, palm rejection,
+  // capture lost). Per the Pointer Events spec this should clean up local state
+  // ONLY and not be treated as a successful completion — so we never commit a
+  // selection from cancel.
+  const onPointerCancel = (event: PointerEvent) => {
+    drag = null;
+    releaseCapture(event);
+  };
+
+  element.addEventListener('pointerdown', onPointerDown);
+  element.addEventListener('pointermove', onPointerMove);
+  element.addEventListener('pointerup', onPointerUp);
+  element.addEventListener('pointercancel', onPointerCancel);
+
+  return () => {
+    element.removeEventListener('pointerdown', onPointerDown);
+    element.removeEventListener('pointermove', onPointerMove);
+    element.removeEventListener('pointerup', onPointerUp);
+    element.removeEventListener('pointercancel', onPointerCancel);
+  };
+};
+
+/**
+ * Utility for consumers: toggle, set, or unset membership of a cell in the cells atom.
+ */
+export const toggleCell = <T>(
+  registry: Registry.Registry,
+  atoms: CellGridAtoms<T>,
+  coord: CellCoord,
+  factory: (coord: CellCoord) => Cell<T>,
+  mode: ToggleMode = 'toggle',
+): void => {
+  registry.update(atoms.cells, (current) => {
+    const next = new Map(current);
+    const key = cellKey(coord.col, coord.row);
+    const exists = next.has(key);
+    if (mode === 'set' || (mode === 'toggle' && !exists)) {
+      next.set(key, factory(coord));
+    } else if (mode === 'unset' || (mode === 'toggle' && exists)) {
+      next.delete(key);
+    }
+    return next;
+  });
+};

package/src/components/CellGrid/input/wheel.ts

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Registry } from '@effect-atom/atom-react';
+
+import type { CellGridAtoms } from '../state/atoms';
+import type { Headers } from '../state/types';
+import { cellWidth } from '../state/viewport';
+
+const MIN_ZOOM = 0.25;
+const MAX_ZOOM = 8;
+
+export type WheelControllerOptions<T> = {
+  registry: Registry.Registry;
+  atoms: CellGridAtoms<T>;
+  headers: Headers;
+};
+
+/**
+ * Attach wheel handlers. Vertical wheel scrolls y; shift+wheel scrolls x;
+ * cmd/ctrl+wheel zooms x around the cursor.
+ */
+export const attachWheelHandlers = <T>(
+  element: HTMLElement,
+  { registry, atoms, headers }: WheelControllerOptions<T>,
+): (() => void) => {
+  const onWheel = (event: WheelEvent) => {
+    if (event.ctrlKey || event.metaKey) {
+      event.preventDefault();
+      // Zoom around cursor x.
+      const rect = element.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const factor = Math.exp(-event.deltaY / 200);
+      registry.update(atoms.viewport, (current) => {
+        const nextZoom = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, current.zoomX * factor));
+        if (nextZoom === current.zoomX) {
+          return current;
+        }
+        const w = cellWidth(current);
+        const worldX = (x - headers.left + current.scrollX) / w;
+        const nextW = current.baseCellWidth * nextZoom;
+        const nextScrollX = Math.max(0, worldX * nextW - (x - headers.left));
+        return { ...current, zoomX: nextZoom, scrollX: nextScrollX };
+      });
+      return;
+    }
+
+    const dx = event.shiftKey ? event.deltaY : event.deltaX;
+    const dy = event.shiftKey ? 0 : event.deltaY;
+    const current = registry.get(atoms.viewport);
+    const nextScrollX = Math.max(0, current.scrollX + dx);
+    const nextScrollY = Math.max(0, current.scrollY + dy);
+
+    // Only consume the wheel event if we're actually scrolling within the grid.
+    // When the user wheels up at the top (scrollY === 0 && dy < 0) or wheels left
+    // at the left edge, let the event bubble to the parent so the page or
+    // enclosing container can scroll instead of swallowing the gesture.
+    if (nextScrollX === current.scrollX && nextScrollY === current.scrollY) {
+      return;
+    }
+    event.preventDefault();
+    registry.set(atoms.viewport, { ...current, scrollX: nextScrollX, scrollY: nextScrollY });
+  };
+
+  element.addEventListener('wheel', onWheel, { passive: false });
+  return () => element.removeEventListener('wheel', onWheel);
+};

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';