@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/containers/data-grid/tool-panel.tsx

@@ -0,0 +1,289 @@
+"use client";
+
+import { ArrowDown, ArrowUp } from "lucide-react";
+import { type ReactNode, useId } from "react";
+import { cn } from "../../utils/cn.js";
+import type { DataGridLabels } from "./labels.js";
+import type { PivotConfig } from "./pivot.js";
+import type { AggregateKind, DataGridColumn } from "./types.js";
+
+const AGGREGATES: AggregateKind[] = ["sum", "avg", "count", "min", "max"];
+
+export const EMPTY_PIVOT: PivotConfig = {
+  enabled: false,
+  rows: [],
+  column: "",
+  value: "",
+  aggregate: "sum",
+};
+
+export interface GridToolPanelProps<T> {
+  labels: DataGridLabels;
+  columns: readonly DataGridColumn<T>[];
+  /** Columns the grid shows now (a pivot replaces them); `columns` when absent. */
+  shownColumns?: readonly DataGridColumn<T>[];
+  /** Every column id in layout order. */
+  order: readonly string[];
+  hidden: readonly string[];
+  onHidden: (id: string, hidden: boolean) => void;
+  onMove: (id: string, delta: number) => void;
+  groupBy: readonly string[];
+  onGroup: (id: string, on: boolean) => void;
+  pivot: PivotConfig;
+  onPivot: (next: PivotConfig) => void;
+  pivotValid: boolean;
+  /** Row grouping is off while a tree, pivot or remote source drives the rows. */
+  canGroup: boolean;
+  canPivot: boolean;
+  /** Height cap in px; the panel scrolls inside it. */
+  maxHeight?: number;
+  className?: string;
+}
+
+const selectClass =
+  "h-control-sm w-full min-w-0 rounded-input border-control bg-surface-control px-2 text-[13px] text-ink focus-visible:border-accent focus-visible:outline-none";
+const iconButton =
+  "grid size-6 shrink-0 place-items-center rounded-xs text-ink-3 hover:bg-surface hover:text-ink disabled:pointer-events-none disabled:opacity-30 [&_svg]:size-3.5";
+
+function Section({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <section className="grid gap-1 border-b-divider p-2 last:border-b-0">
+      <h3 className="px-1 pb-0.5 font-[650] text-[11px] text-ink-3 uppercase tracking-[.07em]">
+        {title}
+      </h3>
+      {children}
+    </section>
+  );
+}
+
+function Check({
+  checked,
+  disabled,
+  onChange,
+  children,
+}: {
+  checked: boolean;
+  disabled?: boolean;
+  onChange: (checked: boolean) => void;
+  children: ReactNode;
+}) {
+  return (
+    <label className="flex min-h-7 min-w-0 flex-1 items-center gap-2 text-[13px] text-ink">
+      <input
+        type="checkbox"
+        className="size-4 shrink-0 accent-accent"
+        checked={checked}
+        disabled={disabled}
+        onChange={(event) => onChange(event.target.checked)}
+      />
+      <span className="truncate">{children}</span>
+    </label>
+  );
+}
+
+/**
+ * Side panel to show, hide and reorder columns, group rows and configure a pivot (row fields,
+ * pivot column, aggregated value). It stacks above the grid when its container is narrow.
+ */
+export function GridToolPanel<T>({
+  labels,
+  columns,
+  shownColumns,
+  order,
+  hidden,
+  onHidden,
+  onMove,
+  groupBy,
+  onGroup,
+  pivot,
+  onPivot,
+  pivotValid,
+  canGroup,
+  canPivot,
+  maxHeight,
+  className,
+}: GridToolPanelProps<T>) {
+  const id = useId();
+  const byId = new Map((shownColumns ?? columns).map((column) => [column.id, column]));
+  const ordered = order.map((key) => byId.get(key)).filter((c): c is DataGridColumn<T> => !!c);
+  const visibleCount = ordered.length - hidden.length;
+  const groupable = columns.filter((column) => column.groupable === true);
+  const dimensions = columns.filter(
+    (column) => column.type !== "number" && column.type !== "currency",
+  );
+  const measures = columns.filter(
+    (column) => column.type === "number" || column.type === "currency",
+  );
+  const patch = (next: Partial<PivotConfig>) => onPivot({ ...pivot, ...next });
+  const pivotOn = pivot.enabled !== false && canPivot;
+
+  return (
+    <aside
+      aria-label={labels.toolPanel}
+      style={maxHeight ? { maxHeight } : undefined}
+      className={cn(
+        "min-h-0 min-w-0 overflow-y-auto bg-surface-2/40 text-[13px] @max-2xl/grid:max-h-72 @max-2xl/grid:border-b-divider @2xl/grid:w-64 @2xl/grid:shrink-0 @2xl/grid:border-l-divider",
+        className,
+      )}
+    >
+      <Section title={labels.panelColumns}>
+        <ul className="grid gap-0.5">
+          {ordered.map((column, index) => {
+            const isHidden = hidden.includes(column.id);
+            return (
+              <li
+                key={column.id}
+                className="flex items-center gap-1 rounded-xs px-1 hover:bg-surface"
+              >
+                <Check
+                  checked={!isHidden}
+                  disabled={column.hideable === false || (!isHidden && visibleCount <= 1)}
+                  onChange={(checked) => onHidden(column.id, !checked)}
+                >
+                  {column.header}
+                </Check>
+                <button
+                  type="button"
+                  className={iconButton}
+                  aria-label={`${labels.moveColumnUp}: ${column.header}`}
+                  title={labels.moveColumnUp}
+                  disabled={index === 0 || column.reorderable === false}
+                  onClick={() => onMove(column.id, -1)}
+                >
+                  <ArrowUp aria-hidden="true" />
+                </button>
+                <button
+                  type="button"
+                  className={iconButton}
+                  aria-label={`${labels.moveColumnDown}: ${column.header}`}
+                  title={labels.moveColumnDown}
+                  disabled={index === ordered.length - 1 || column.reorderable === false}
+                  onClick={() => onMove(column.id, 1)}
+                >
+                  <ArrowDown aria-hidden="true" />
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      </Section>
+
+      {groupable.length > 0 ? (
+        <Section title={labels.panelRowGroups}>
+          <ul className="grid gap-0.5">
+            {groupable.map((column) => (
+              <li key={column.id} className="flex items-center gap-1 px-1">
+                <Check
+                  checked={groupBy.includes(column.id)}
+                  disabled={!canGroup}
+                  onChange={(checked) => onGroup(column.id, checked)}
+                >
+                  {column.header}
+                </Check>
+                {groupBy.includes(column.id) ? (
+                  <span className="text-[11px] text-ink-3 tabular-nums">
+                    {groupBy.indexOf(column.id) + 1}
+                  </span>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        </Section>
+      ) : null}
+
+      {measures.length > 0 && dimensions.length > 1 ? (
+        <Section title={labels.panelPivot}>
+          <Check
+            checked={pivotOn}
+            disabled={!canPivot}
+            onChange={(checked) => patch({ enabled: checked })}
+          >
+            {labels.pivotMode}
+          </Check>
+          {pivotOn ? (
+            <div className="grid gap-2 pt-1">
+              <fieldset className="grid gap-0.5 border-0 p-0">
+                <legend className="px-1 pb-0.5 text-[12px] text-ink-3">{labels.pivotRows}</legend>
+                {dimensions
+                  .filter((column) => column.id !== pivot.column)
+                  .map((column) => (
+                    <div key={column.id} className="flex items-center px-1">
+                      <Check
+                        checked={pivot.rows.includes(column.id)}
+                        onChange={(checked) =>
+                          patch({
+                            rows: checked
+                              ? [...pivot.rows, column.id]
+                              : pivot.rows.filter((x) => x !== column.id),
+                          })
+                        }
+                      >
+                        {column.header}
+                      </Check>
+                    </div>
+                  ))}
+              </fieldset>
+              <label className="grid gap-1" htmlFor={`${id}-column`}>
+                <span className="px-1 text-[12px] text-ink-3">{labels.pivotColumn}</span>
+                <select
+                  id={`${id}-column`}
+                  className={selectClass}
+                  value={pivot.column}
+                  onChange={(event) =>
+                    patch({
+                      column: event.target.value,
+                      rows: pivot.rows.filter((x) => x !== event.target.value),
+                    })
+                  }
+                >
+                  <option value="">{labels.noneOption}</option>
+                  {dimensions.map((column) => (
+                    <option key={column.id} value={column.id}>
+                      {column.header}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <label className="grid gap-1" htmlFor={`${id}-value`}>
+                <span className="px-1 text-[12px] text-ink-3">{labels.pivotValue}</span>
+                <select
+                  id={`${id}-value`}
+                  className={selectClass}
+                  value={pivot.value}
+                  onChange={(event) => patch({ value: event.target.value })}
+                >
+                  <option value="">{labels.noneOption}</option>
+                  {measures.map((column) => (
+                    <option key={column.id} value={column.id}>
+                      {column.header}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <label className="grid gap-1" htmlFor={`${id}-aggregate`}>
+                <span className="px-1 text-[12px] text-ink-3">{labels.pivotAggregate}</span>
+                <select
+                  id={`${id}-aggregate`}
+                  className={selectClass}
+                  value={pivot.aggregate}
+                  onChange={(event) => patch({ aggregate: event.target.value as AggregateKind })}
+                >
+                  {AGGREGATES.map((kind) => (
+                    <option key={kind} value={kind}>
+                      {labels.aggregate[kind]}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              {pivotValid ? null : (
+                <p role="status" className="px-1 text-[12px] text-ink-3">
+                  {labels.pivotIncomplete}
+                </p>
+              )}
+            </div>
+          ) : null}
+        </Section>
+      ) : null}
+    </aside>
+  );
+}

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

@@ -0,0 +1,97 @@
+// Tree data: a flat list of rows linked by a parent id, flattened for display with aggregates.
+import { computeAggregates } from "./model.js";
+import type { DataDisplayRow, DataGridColumn, DisplayRow } from "./types.js";
+
+export interface TreeOptions<T> {
+  getKey: (row: T) => string;
+  /** Key of the parent row; nullish for roots. Unknown parents make the row a root. */
+  getParentId: (row: T) => string | null | undefined;
+}
+
+/**
+ * Keeps `matches` plus every ancestor of a match, in the order of `all`, so a filtered tree
+ * still shows the path to each hit.
+ */
+export function withAncestors<T>(
+  all: readonly T[],
+  matches: readonly T[],
+  options: TreeOptions<T>,
+): T[] {
+  const byKey = new Map(all.map((row) => [options.getKey(row), row]));
+  const keep = new Set<string>();
+  for (const row of matches) {
+    let current: T | undefined = row;
+    while (current) {
+      const key = options.getKey(current);
+      if (keep.has(key)) break;
+      keep.add(key);
+      const parent = options.getParentId(current);
+      current = parent === null || parent === undefined ? undefined : byKey.get(parent);
+    }
+  }
+  return all.filter((row) => keep.has(options.getKey(row)));
+}
+
+export interface TreeResult<T> {
+  rows: DisplayRow<T>[];
+  /** Rows without children: what the footer totals aggregate. */
+  leaves: T[];
+}
+
+/**
+ * Depth-first flattening. Children keep the order of `rows` (sort before calling). A collapsed
+ * node hides its subtree unless `forceExpand` is on. Parents carry the aggregates of every leaf
+ * below them. Cycles are cut where they close.
+ */
+export function buildTreeRows<T>(
+  rows: readonly T[],
+  columns: readonly DataGridColumn<T>[],
+  options: TreeOptions<T> & { expanded: ReadonlySet<string>; forceExpand?: boolean },
+): TreeResult<T> {
+  const { getKey, getParentId, expanded, forceExpand = false } = options;
+  const keys = new Set(rows.map(getKey));
+  const children = new Map<string, T[]>();
+  const roots: T[] = [];
+  for (const row of rows) {
+    const parent = getParentId(row);
+    if (parent === null || parent === undefined || !keys.has(parent) || parent === getKey(row)) {
+      roots.push(row);
+    } else {
+      const list = children.get(parent);
+      if (list) list.push(row);
+      else children.set(parent, [row]);
+    }
+  }
+
+  const out: DisplayRow<T>[] = [];
+  const leaves: T[] = [];
+  const visited = new Set<string>();
+
+  const walk = (row: T, depth: number): T[] => {
+    const key = getKey(row);
+    visited.add(key);
+    const kids = (children.get(key) ?? []).filter((child) => !visited.has(getKey(child)));
+    const isExpanded = forceExpand || expanded.has(key);
+    const entry: DataDisplayRow<T> = {
+      kind: "data",
+      key,
+      depth,
+      row,
+      tree: { hasChildren: kids.length > 0, expanded: isExpanded, aggregates: {} },
+    };
+    out.push(entry);
+    if (kids.length === 0) {
+      leaves.push(row);
+      return [row];
+    }
+    const below: T[] = [];
+    const mark = out.length;
+    for (const child of kids) below.push(...walk(child, depth + 1));
+    if (entry.tree) entry.tree.aggregates = computeAggregates(below, columns);
+    if (!isExpanded) out.length = mark;
+    return below;
+  };
+
+  for (const root of roots) walk(root, 0);
+  return { rows: out, leaves };
+}

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

@@ -0,0 +1,166 @@
+import type { ReactNode } from "react";
+import type { ChipTone } from "../../atoms/chip/chip.js";
+import type { PinSide } from "../table/pin.js";
+
+export type { PinSide };
+
+export type CellValue = string | number | boolean | Date | null | undefined;
+
+export type ColumnType =
+  | "text"
+  | "number"
+  | "currency"
+  | "date"
+  | "status"
+  | "boolean"
+  /** A mini chart per row; see `DataGridColumn.sparkline`. The accessor still drives sort, filter and CSV. */
+  | "sparkline";
+export type ColumnAlign = "start" | "center" | "end";
+export type AggregateKind = "sum" | "avg" | "count" | "min" | "max";
+/** `set` is `select` with a searchable checkbox list and a select-all control. */
+export type FilterKind = "text" | "range" | "dateRange" | "select" | "set";
+export type EditorKind = "text" | "number" | "select";
+export type SortDirection = "asc" | "desc";
+export type Density = "compact" | "normal" | "comfortable";
+
+export interface SortRule {
+  id: string;
+  direction: SortDirection;
+}
+
+/** One filter per column. Empty values (blank query, open range, no values) match everything. */
+export type FilterValue =
+  | { kind: "text"; query: string }
+  | { kind: "range"; min?: number | null; max?: number | null }
+  /** ISO dates (`yyyy-mm-dd`), both ends inclusive. */
+  | { kind: "dateRange"; from?: string | null; to?: string | null }
+  | { kind: "select"; values: readonly string[] };
+
+export type Filters = Readonly<Record<string, FilterValue>>;
+
+export interface CellContext<T> {
+  row: T;
+  rowId: string;
+  value: CellValue;
+  /** The value as text, with the column's formatter applied. */
+  formatted: string;
+}
+
+/** Mini chart of a `sparkline` column. */
+export interface SparklineOptions<T> {
+  /** Points of the row's chart, in order; `null` leaves a gap. */
+  values: (row: T) => ReadonlyArray<number | null>;
+  kind?: "line" | "area" | "bar";
+  /** CSS color of the line or bars. */
+  color?: string;
+  /** Accessible description of each chart, e.g. "Ventas de los últimos 7 días". */
+  label?: string | ((row: T) => string);
+}
+
+export interface DataGridColumn<T> {
+  id: string;
+  header: string;
+  /** Property name or function that reads the cell value from a row. */
+  accessor: keyof T | ((row: T) => CellValue);
+  /** Custom cell content; the formatted text is used otherwise. */
+  cell?: (context: CellContext<T>) => ReactNode;
+  /** Drives formatting, alignment, the default filter and the default editor. `text` by default. */
+  type?: ColumnType;
+  /** Text shown for a value (cells, filters, group rows, CSV keeps raw numbers). */
+  format?: (value: CellValue) => string;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  /**
+   * Weight of the leftover width this column takes when the grid is wider than its columns.
+   * Text columns default to `1`, the rest to `0` (fixed); a user-resized column never grows.
+   */
+  grow?: number;
+  align?: ColumnAlign;
+  sortable?: boolean;
+  filterable?: boolean;
+  /** Overrides the filter picked from `type`. */
+  filter?: FilterKind;
+  pinnable?: boolean;
+  hideable?: boolean;
+  resizable?: boolean;
+  reorderable?: boolean;
+  groupable?: boolean;
+  /** Shown in group rows and in the footer totals. */
+  aggregate?: AggregateKind;
+  /** Chip tone per status value (`status` columns). */
+  statusTones?: Readonly<Record<string, ChipTone>>;
+  editable?: boolean | ((row: T) => boolean);
+  /** Editor kind; `number` for numeric types, `select` when `options` exist, `text` otherwise. */
+  editor?: EditorKind;
+  /** Values offered by the `select` editor. */
+  options?: readonly string[];
+  /**
+   * Returns an error message when `value` is not acceptable, nothing otherwise. A failing edit stays
+   * open with the message instead of being committed; already invalid cells are flagged.
+   */
+  validate?: (value: CellValue, row: T) => string | null | undefined;
+  /** Mini chart per row for `type: "sparkline"` columns. */
+  sparkline?: SparklineOptions<T>;
+  /** Header group path from the outermost level down; adjacent columns sharing it share a header. */
+  group?: string | readonly string[];
+}
+
+export interface GroupDisplayRow {
+  kind: "group";
+  key: string;
+  depth: number;
+  columnId: string;
+  label: string;
+  count: number;
+  collapsed: boolean;
+  aggregates: Record<string, number | null>;
+}
+
+/** Tree metadata of a data row (`tree` mode). */
+export interface TreeInfo {
+  hasChildren: boolean;
+  expanded: boolean;
+  /** Aggregates over all descendant leaves; only for rows with children. */
+  aggregates: Record<string, number | null>;
+}
+
+export interface DataDisplayRow<T> {
+  kind: "data";
+  key: string;
+  depth: number;
+  row: T;
+  tree?: TreeInfo;
+}
+
+/** Detail panel shown under an expanded data row (master / detail). */
+export interface DetailDisplayRow<T> {
+  kind: "detail";
+  key: string;
+  depth: number;
+  row: T;
+  rowKey: string;
+  height: number;
+}
+
+/** A row of a remote data source whose block is not loaded yet. */
+export interface PlaceholderDisplayRow {
+  kind: "placeholder";
+  key: string;
+  index: number;
+}
+
+export type DisplayRow<T> =
+  | GroupDisplayRow
+  | DataDisplayRow<T>
+  | DetailDisplayRow<T>
+  | PlaceholderDisplayRow;
+
+/** Column layout the user can change; it is what `storageKey` persists. */
+export interface GridLayout {
+  order: string[];
+  hidden: string[];
+  widths: Record<string, number>;
+  pinned: { left: string[]; right: string[] };
+  density?: Density;
+}

package/src/containers/data-grid/use-data-source.ts

@@ -0,0 +1,124 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import { BlockCache, type DataSource } from "./data-source.js";
+import type { Filters, SortRule } from "./types.js";
+
+export interface DataSourceParams {
+  sort: readonly SortRule[];
+  filters: Filters;
+  search: string;
+  blockSize: number;
+  maxBlocks?: number;
+  /** Rows currently shown: `[start, end)` of the sorted, filtered result. */
+  range: { start: number; end: number };
+}
+
+export interface DataSourceView<T> {
+  /** Row count reported by the server; null until the first response. */
+  total: number | null;
+  rowAt: (index: number) => T | undefined;
+  /** A request is in flight for the shown range. */
+  loading: boolean;
+  /** The shown range failed to load. */
+  failed: boolean;
+  retry: () => void;
+  /** Changes whenever a block settles. */
+  version: number;
+}
+
+/**
+ * Drives a `DataSource`: one `BlockCache` per sort / filter / search / block size, blocks fetched
+ * for the shown range, late responses of an older query dropped.
+ */
+export function useDataSource<T>(
+  source: DataSource<T> | undefined,
+  params: DataSourceParams,
+): DataSourceView<T> {
+  const { sort, filters, search, blockSize, maxBlocks = 20, range } = params;
+  const [version, bump] = useReducer((n: number) => n + 1, 0);
+  const query = JSON.stringify({ sort, filters, search });
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a new cache per query, block size or source; sort and filters are tracked through `query`.
+  const cache = useMemo(
+    () => new BlockCache<T>(blockSize, maxBlocks),
+    [source, query, blockSize, maxBlocks],
+  );
+  const controllers = useRef(new Set<AbortController>());
+  const latest = useRef({ sort, filters, search });
+  latest.current = { sort, filters, search };
+
+  const fetchMissing = useCallback(
+    (start: number, end: number) => {
+      if (!source) return;
+      for (const block of cache.missing(start, end)) {
+        cache.markLoading(block);
+        const controller = new AbortController();
+        const startRow = block * cache.blockSize;
+        source
+          .getRows(
+            {
+              startRow,
+              endRow: startRow + cache.blockSize,
+              sort: [...latest.current.sort],
+              filters: latest.current.filters,
+              search: latest.current.search,
+            },
+            { signal: controller.signal },
+          )
+          .then((result) => {
+            if (controller.signal.aborted) return;
+            cache.setBlock(block, result.rows, result.total, cache.blocksFor(start, end));
+            bump();
+          })
+          .catch(() => {
+            if (controller.signal.aborted) return;
+            cache.markError(block);
+            bump();
+          });
+        controllers.current.add(controller);
+      }
+      bump();
+    },
+    [source, cache],
+  );
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a new cache means a new query, so the requests of the previous one are cancelled.
+  useEffect(
+    () => () => {
+      for (const controller of controllers.current) controller.abort();
+      controllers.current.clear();
+    },
+    [cache],
+  );
+
+  const { start, end } = range;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `version` re-runs the effect when a block settles, to chase a changed range.
+  useEffect(() => {
+    if (!source) return;
+    const wantEnd = cache.total === null ? Math.max(end, start + cache.blockSize) : end;
+    const missing = cache.missing(start, wantEnd);
+    if (missing.length > 0) fetchMissing(start, wantEnd);
+    else cache.touch(cache.blocksFor(start, wantEnd));
+  }, [source, cache, start, end, fetchMissing, version]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `version` marks that blocks settled, so readers re-run.
+  const rowAt = useCallback((index: number) => cache.getRow(index), [cache, version]);
+
+  const retry = useCallback(() => {
+    cache.retry(start, Math.max(end, start + 1));
+    fetchMissing(start, Math.max(end, start + 1));
+  }, [cache, start, end, fetchMissing]);
+
+  return {
+    total: cache.total,
+    rowAt,
+    loading:
+      cache.isLoading(start, Math.max(end, start + 1)) ||
+      (source !== undefined && cache.total === null && !cache.hasError(0, 1)),
+    failed:
+      cache.hasError(start, Math.max(end, start + 1)) ||
+      (cache.total === null && cache.hasError(0, 1)),
+    retry,
+    version,
+  };
+}