@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/containers/data-grid/grid-edit.ts

@@ -0,0 +1,137 @@
+// Pure planning of multi-cell edits: TSV parsing for paste and fill down / right.
+import type { CellValue } from "./types.js";
+
+/**
+ * Parses tab separated text (the clipboard format of spreadsheets): quoted fields may hold tabs,
+ * quotes (`""`) and line breaks. One trailing line break is ignored.
+ */
+export function parseTSV(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+  let atStart = true;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i] as string;
+    if (quoted) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i += 1;
+        } else quoted = false;
+      } else field += char;
+      continue;
+    }
+    if (char === '"' && atStart) {
+      quoted = true;
+      atStart = false;
+    } else if (char === "\t") {
+      row.push(field);
+      field = "";
+      atStart = true;
+    } else if (char === "\n" || char === "\r") {
+      if (char === "\r" && text[i + 1] === "\n") i += 1;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+      atStart = true;
+    } else {
+      field += char;
+      atStart = false;
+    }
+  }
+  if (field !== "" || row.length > 0 || quoted) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+export interface CellTarget {
+  r: number;
+  c: number;
+  text: string;
+}
+
+/**
+ * Cells a paste writes. A single value pasted over a larger selection fills it; otherwise the
+ * block lands from the top-left corner and is cut at the grid limits.
+ */
+export function planPaste(
+  table: readonly (readonly string[])[],
+  origin: { r: number; c: number },
+  limits: { maxR: number; maxC: number },
+  selection?: { r0: number; r1: number; c0: number; c1: number } | null,
+): CellTarget[] {
+  if (table.length === 0) return [];
+  const single = table.length === 1 && table[0]?.length === 1;
+  const out: CellTarget[] = [];
+  if (single && selection && (selection.r1 > selection.r0 || selection.c1 > selection.c0)) {
+    const text = table[0]?.[0] ?? "";
+    for (let r = selection.r0; r <= Math.min(selection.r1, limits.maxR); r += 1) {
+      for (let c = selection.c0; c <= Math.min(selection.c1, limits.maxC); c += 1) {
+        out.push({ r, c, text });
+      }
+    }
+    return out;
+  }
+  table.forEach((line, dr) => {
+    line.forEach((text, dc) => {
+      const r = origin.r + dr;
+      const c = origin.c + dc;
+      if (r <= limits.maxR && c <= limits.maxC) out.push({ r, c, text });
+    });
+  });
+  return out;
+}
+
+export type FillDirection = "down" | "right";
+
+export interface FillTarget {
+  r: number;
+  c: number;
+  /** Source cell the value is copied from. */
+  from: { r: number; c: number };
+}
+
+/** Cells a fill writes and where each value comes from: `down` copies the first row, `right` the first column. */
+export function planFill(
+  bounds: { r0: number; r1: number; c0: number; c1: number },
+  direction: FillDirection,
+): FillTarget[] {
+  const out: FillTarget[] = [];
+  if (direction === "down") {
+    for (let r = bounds.r0 + 1; r <= bounds.r1; r += 1) {
+      for (let c = bounds.c0; c <= bounds.c1; c += 1) out.push({ r, c, from: { r: bounds.r0, c } });
+    }
+  } else {
+    for (let c = bounds.c0 + 1; c <= bounds.c1; c += 1) {
+      for (let r = bounds.r0; r <= bounds.r1; r += 1) out.push({ r, c, from: { r, c: bounds.c0 } });
+    }
+  }
+  return out;
+}
+
+/**
+ * A number from pasted text such as `S/ 1,234.50`, `12,5` or `-3`: currency marks and spaces are
+ * dropped, a lone comma followed by one or two digits is a decimal comma, other commas group
+ * thousands. Null when no number can be read.
+ */
+export function parseLooseNumber(text: string): number | null {
+  let clean = text.replace(/[^\d.,+-]/g, "");
+  if (clean === "") return null;
+  if (clean.includes(".")) clean = clean.replace(/,/g, "");
+  else if (/^[+-]?\d+,\d{1,2}$/.test(clean)) clean = clean.replace(",", ".");
+  else clean = clean.replace(/,/g, "");
+  const value = Number(clean);
+  return Number.isFinite(value) ? value : null;
+}
+
+/** Whether an edited value equals the previous one (numbers by identity, the rest by text). */
+export function sameCellValue(value: CellValue, previous: CellValue): boolean {
+  if (value === previous) return true;
+  if (value instanceof Date && previous instanceof Date)
+    return value.getTime() === previous.getTime();
+  return typeof previous !== "number" && String(value ?? "") === String(previous ?? "");
+}

package/src/containers/data-grid/grid-toolbar.tsx

@@ -0,0 +1,307 @@
+"use client";
+
+import {
+  Columns3,
+  Download,
+  FileSpreadsheet,
+  ListFilter,
+  PanelRight,
+  Plus,
+  Redo2,
+  Search,
+  Trash2,
+  Undo2,
+  X,
+} from "lucide-react";
+import type { ReactNode } from "react";
+import { Popover, PopoverContent, PopoverTrigger } from "../../overlays/popover/popover.js";
+import { cn } from "../../utils/cn.js";
+import type { DataGridLabels } from "./labels.js";
+import type { DataGridColumn, Density } from "./types.js";
+
+const DENSITIES: Density[] = ["compact", "normal", "comfortable"];
+
+const buttonClass =
+  "inline-flex h-control-sm shrink-0 items-center gap-1.5 whitespace-nowrap rounded-control border-divider bg-surface-control px-2.5 font-[600] text-[12.5px] text-ink-2 hover:border-line-strong hover:text-ink [&_svg]:size-3.5";
+
+export interface GridToolbarProps<T> {
+  labels: DataGridLabels;
+  search: string;
+  onSearch: (value: string) => void;
+  activeFilters: number;
+  onClearFilters: () => void;
+  groupBy: readonly string[];
+  columns: readonly DataGridColumn<T>[];
+  onUngroup: (id: string) => void;
+  density: Density;
+  onDensity: (density: Density) => void;
+  hidden: readonly string[];
+  onHidden: (id: string, hidden: boolean) => void;
+  onResetColumns: () => void;
+  onExport?: () => void;
+  /** Adds the XLSX export button next to the CSV one. */
+  onExportXlsx?: () => void;
+  rowCount: number;
+  selectedCount: number | null;
+  /** Extra content at the end of the toolbar. */
+  actions?: ReactNode;
+  /** Advanced filter editor shown in a popover; the button is hidden without it. */
+  advancedFilter?: ReactNode;
+  advancedFilterCount?: number;
+  onClearAdvancedFilter?: () => void;
+  /** Toggle of the side tool panel; hidden when absent. */
+  toolPanel?: { open: boolean; onToggle: () => void };
+  /** The export button exports the selected rows. */
+  exportSelected?: boolean;
+  /** Hides the column picker (pivot and tool-panel modes manage columns elsewhere). */
+  hideColumnPicker?: boolean;
+  /** Undo / redo buttons; hidden when absent. */
+  history?: { canUndo: boolean; canRedo: boolean; onUndo: () => void; onRedo: () => void };
+  /** Add / remove row buttons; each is hidden when its handler is absent. */
+  rowTools?: { onAdd?: () => void; onRemove?: () => void; removeDisabled: boolean };
+}
+
+/** Search, filter and grouping chips, column visibility, density and export. Wraps when narrow. */
+export function GridToolbar<T>({
+  labels,
+  search,
+  onSearch,
+  activeFilters,
+  onClearFilters,
+  groupBy,
+  columns,
+  onUngroup,
+  density,
+  onDensity,
+  hidden,
+  onHidden,
+  onResetColumns,
+  onExport,
+  onExportXlsx,
+  rowCount,
+  selectedCount,
+  actions,
+  advancedFilter,
+  advancedFilterCount = 0,
+  onClearAdvancedFilter,
+  toolPanel,
+  exportSelected = false,
+  hideColumnPicker = false,
+  history,
+  rowTools,
+}: GridToolbarProps<T>) {
+  const hideable = columns.filter((column) => column.hideable !== false);
+  const visibleCount = columns.length - hidden.length;
+
+  return (
+    <div className="flex flex-wrap items-center gap-2 border-b-divider p-2">
+      <label className="relative flex h-control-sm w-full min-w-0 items-center @md/grid:w-60">
+        <span className="sr-only">{labels.search}</span>
+        <Search
+          aria-hidden="true"
+          className="pointer-events-none absolute left-2.5 size-3.5 text-ink-3"
+        />
+        <input
+          type="search"
+          value={search}
+          placeholder={labels.searchPlaceholder}
+          onChange={(event) => onSearch(event.target.value)}
+          className="h-control-sm w-full min-w-0 rounded-input border-control bg-surface-control pr-2 pl-8 text-[13px] text-ink placeholder:text-ink-3 focus-visible:border-accent focus-visible:outline-none"
+        />
+      </label>
+
+      {activeFilters > 0 ? (
+        <button type="button" className={buttonClass} onClick={onClearFilters}>
+          <X aria-hidden="true" />
+          <span>
+            {labels.filtersActive(activeFilters)} · {labels.clearFilters}
+          </span>
+        </button>
+      ) : null}
+
+      {advancedFilter ? (
+        <Popover>
+          <PopoverTrigger
+            className={cn(
+              buttonClass,
+              advancedFilterCount > 0 && "border-accent-line bg-accent-soft text-accent-ink",
+            )}
+          >
+            <ListFilter aria-hidden="true" />
+            {labels.advancedFilter}
+            {advancedFilterCount > 0 ? (
+              <span className="tabular-nums">· {advancedFilterCount}</span>
+            ) : null}
+          </PopoverTrigger>
+          <PopoverContent
+            align="start"
+            aria-label={labels.advancedFilter}
+            className="w-[36rem] p-3"
+          >
+            {advancedFilter}
+            {advancedFilterCount > 0 && onClearAdvancedFilter ? (
+              <div className="mt-3 flex justify-end border-t-divider pt-2">
+                <button type="button" className={buttonClass} onClick={onClearAdvancedFilter}>
+                  <X aria-hidden="true" />
+                  {labels.clearAdvancedFilter}
+                </button>
+              </div>
+            ) : null}
+          </PopoverContent>
+        </Popover>
+      ) : null}
+
+      {groupBy.map((id) => {
+        const header = columns.find((column) => column.id === id)?.header ?? id;
+        return (
+          <button
+            key={id}
+            type="button"
+            className={cn(buttonClass, "border-accent-line bg-accent-soft text-accent-ink")}
+            aria-label={`${labels.removeGrouping}: ${header}`}
+            onClick={() => onUngroup(id)}
+          >
+            <span className="font-normal">{labels.groupedBy}</span> {header}
+            <X aria-hidden="true" />
+          </button>
+        );
+      })}
+
+      <p className="mr-auto text-[12px] text-ink-3" aria-live="polite">
+        {labels.rowsCount(rowCount)}
+        {selectedCount ? ` · ${labels.selectedCount(selectedCount)}` : ""}
+      </p>
+
+      {history ? (
+        <fieldset className="flex items-center gap-1">
+          <legend className="sr-only">{labels.history}</legend>
+          <button
+            type="button"
+            className={cn(buttonClass, "px-2")}
+            disabled={!history.canUndo}
+            title={labels.undo}
+            aria-label={labels.undo}
+            onClick={history.onUndo}
+          >
+            <Undo2 aria-hidden="true" />
+          </button>
+          <button
+            type="button"
+            className={cn(buttonClass, "px-2")}
+            disabled={!history.canRedo}
+            title={labels.redo}
+            aria-label={labels.redo}
+            onClick={history.onRedo}
+          >
+            <Redo2 aria-hidden="true" />
+          </button>
+        </fieldset>
+      ) : null}
+
+      {rowTools?.onAdd ? (
+        <button type="button" className={buttonClass} onClick={rowTools.onAdd}>
+          <Plus aria-hidden="true" />
+          {labels.addRow}
+        </button>
+      ) : null}
+      {rowTools?.onRemove ? (
+        <button
+          type="button"
+          className={buttonClass}
+          disabled={rowTools.removeDisabled}
+          onClick={rowTools.onRemove}
+        >
+          <Trash2 aria-hidden="true" />
+          {labels.removeRows}
+        </button>
+      ) : null}
+
+      {actions}
+
+      <fieldset className="flex h-control-sm items-center rounded-control border-divider bg-surface-control p-0.5">
+        <legend className="sr-only">{labels.density}</legend>
+        {DENSITIES.map((option) => (
+          <button
+            key={option}
+            type="button"
+            aria-pressed={density === option}
+            onClick={() => onDensity(option)}
+            className="h-full rounded-xs px-2 font-[600] text-[12px] text-ink-3 hover:text-ink aria-pressed:bg-accent-soft aria-pressed:text-accent-ink"
+          >
+            {labels.densities[option]}
+          </button>
+        ))}
+      </fieldset>
+
+      {hideColumnPicker ? null : (
+        <Popover>
+          <PopoverTrigger className={buttonClass}>
+            <Columns3 aria-hidden="true" />
+            {labels.columns}
+          </PopoverTrigger>
+          <PopoverContent align="end" aria-label={labels.columns} className="w-60">
+            <fieldset className="grid max-h-72 gap-0.5 overflow-y-auto p-1">
+              <legend className="sr-only">{labels.columns}</legend>
+              {hideable.map((column) => {
+                const isHidden = hidden.includes(column.id);
+                return (
+                  <label
+                    key={column.id}
+                    className="flex min-h-8 items-center gap-2 rounded-xs px-1.5 text-[13px] text-ink hover:bg-surface-2"
+                  >
+                    <input
+                      type="checkbox"
+                      className="size-4 accent-accent"
+                      checked={!isHidden}
+                      disabled={!isHidden && visibleCount <= 1}
+                      onChange={(event) => onHidden(column.id, !event.target.checked)}
+                    />
+                    <span className="truncate">{column.header}</span>
+                  </label>
+                );
+              })}
+            </fieldset>
+            <div className="border-t-divider p-1 pt-1.5">
+              <button
+                type="button"
+                className={cn(buttonClass, "w-full justify-center")}
+                onClick={onResetColumns}
+              >
+                {labels.resetColumns}
+              </button>
+            </div>
+          </PopoverContent>
+        </Popover>
+      )}
+
+      {toolPanel ? (
+        <button
+          type="button"
+          className={cn(
+            buttonClass,
+            toolPanel.open && "border-accent-line bg-accent-soft text-accent-ink",
+          )}
+          aria-pressed={toolPanel.open}
+          onClick={toolPanel.onToggle}
+        >
+          <PanelRight aria-hidden="true" />
+          {labels.toolPanel}
+        </button>
+      ) : null}
+
+      {onExport ? (
+        <button type="button" className={buttonClass} onClick={onExport}>
+          <Download aria-hidden="true" />
+          {exportSelected ? labels.exportSelection : labels.exportCsv}
+        </button>
+      ) : null}
+
+      {onExportXlsx ? (
+        <button type="button" className={buttonClass} onClick={onExportXlsx}>
+          <FileSpreadsheet aria-hidden="true" />
+          {exportSelected ? labels.exportSelectionXlsx : labels.exportXlsx}
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/containers/data-grid/history.ts

@@ -0,0 +1,137 @@
+// Undo / redo command stack for grid edits. Pure and immutable: the grid keeps the state in a ref.
+import type { CellValue } from "./types.js";
+
+/** What produced a change; also tells a controlled parent that a change is an undo or a redo. */
+export type ChangeSource = "edit" | "paste" | "fill" | "undo" | "redo";
+
+export interface CellDelta {
+  rowId: string;
+  columnId: string;
+  before: CellValue;
+  after: CellValue;
+}
+
+export interface RowRef<R> {
+  row: R;
+  rowId: string;
+  /** Position of the row in the source data when it was added or removed. */
+  index: number;
+}
+
+export type HistoryCommand<R = unknown> =
+  | { kind: "cells"; source: "edit" | "paste" | "fill"; changes: readonly CellDelta[] }
+  | { kind: "rows-add"; rows: readonly RowRef<R>[] }
+  | { kind: "rows-remove"; rows: readonly RowRef<R>[] };
+
+export interface HistoryState<R = unknown> {
+  past: readonly HistoryCommand<R>[];
+  future: readonly HistoryCommand<R>[];
+  depth: number;
+}
+
+export const DEFAULT_HISTORY_DEPTH = 100;
+
+export function createHistory<R = unknown>(depth = DEFAULT_HISTORY_DEPTH): HistoryState<R> {
+  return { past: [], future: [], depth: Math.max(1, Math.floor(depth)) };
+}
+
+export function canUndo(state: HistoryState<unknown>): boolean {
+  return state.past.length > 0;
+}
+
+export function canRedo(state: HistoryState<unknown>): boolean {
+  return state.future.length > 0;
+}
+
+/** A command that changes nothing is not worth an undo step. */
+export function isNoop<R>(command: HistoryCommand<R>): boolean {
+  if (command.kind === "cells") {
+    return command.changes.every((change) => Object.is(change.before, change.after));
+  }
+  return command.rows.length === 0;
+}
+
+/** Records a command; the redo branch is dropped and the oldest commands past `depth` fall off. */
+export function pushCommand<R>(
+  state: HistoryState<R>,
+  command: HistoryCommand<R>,
+): HistoryState<R> {
+  if (isNoop(command)) return state;
+  const past = [...state.past, command];
+  return { ...state, past: past.slice(Math.max(0, past.length - state.depth)), future: [] };
+}
+
+/** The command that cancels `command`. */
+export function invertCommand<R>(command: HistoryCommand<R>): HistoryCommand<R> {
+  if (command.kind === "cells") {
+    return {
+      ...command,
+      changes: command.changes.map((change) => ({
+        ...change,
+        before: change.after,
+        after: change.before,
+      })),
+    };
+  }
+  return command.kind === "rows-add"
+    ? { kind: "rows-remove", rows: command.rows }
+    : { kind: "rows-add", rows: command.rows };
+}
+
+export interface HistoryStep<R> {
+  state: HistoryState<R>;
+  /** What the caller has to apply: the inverse for an undo, the original for a redo. */
+  apply: HistoryCommand<R>;
+}
+
+/** Moves the last command to the redo branch; null when there is nothing to undo. */
+export function undoCommand<R>(state: HistoryState<R>): HistoryStep<R> | null {
+  const command = state.past[state.past.length - 1];
+  if (!command) return null;
+  return {
+    state: { ...state, past: state.past.slice(0, -1), future: [...state.future, command] },
+    apply: invertCommand(command),
+  };
+}
+
+/** Moves the last undone command back to the past; null when there is nothing to redo. */
+export function redoCommand<R>(state: HistoryState<R>): HistoryStep<R> | null {
+  const command = state.future[state.future.length - 1];
+  if (!command) return null;
+  return {
+    state: { ...state, past: [...state.past, command], future: state.future.slice(0, -1) },
+    apply: command,
+  };
+}
+
+/** Shrinks (or grows) the depth, trimming the oldest commands. */
+export function setHistoryDepth<R>(state: HistoryState<R>, depth: number): HistoryState<R> {
+  const next = Math.max(1, Math.floor(depth));
+  if (next === state.depth) return state;
+  return {
+    depth: next,
+    past: state.past.slice(Math.max(0, state.past.length - next)),
+    future: state.future.slice(Math.max(0, state.future.length - next)),
+  };
+}
+
+export interface HistorySummary {
+  canUndo: boolean;
+  canRedo: boolean;
+  undoCount: number;
+  redoCount: number;
+}
+
+export function summarizeHistory(state: HistoryState<unknown>): HistorySummary {
+  return {
+    canUndo: canUndo(state),
+    canRedo: canRedo(state),
+    undoCount: state.past.length,
+    redoCount: state.future.length,
+  };
+}
+
+/** Number of cells or rows a command touches (for announcements). */
+export function commandSize<R>(command: HistoryCommand<R>): number {
+  return command.kind === "cells" ? command.changes.length : command.rows.length;
+}

package/src/containers/data-grid/index.ts

@@ -0,0 +1,18 @@
+export * from "./column-groups.js";
+export * from "./data-grid.js";
+export * from "./data-source.js";
+export * from "./filter-builder.js";
+export * from "./filter-builder-editor.js";
+export * from "./formula.js";
+export * from "./formula-sheet.js";
+export * from "./grid-edit.js";
+export * from "./history.js";
+export * from "./labels.js";
+export * from "./model.js";
+export * from "./pivot.js";
+export * from "./range.js";
+export * from "./rows.js";
+export * from "./tree.js";
+export * from "./types.js";
+export * from "./virtual.js";
+export * from "./xlsx-export.js";