@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/containers/cols/cols.tsx

@@ -0,0 +1,64 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../../utils/cn.js";
+
+export type ColsVariant = "rail" | "half" | "calc";
+
+/**
+ * Responsive column layouts. Breakpoints react to the nearest ancestor
+ * container named `page` (`@container/page`), not to the viewport; without
+ * such an ancestor the wide layouts always apply.
+ */
+const variantClasses: Record<"base" | ColsVariant, string> = {
+  base: cn(
+    "grid-cols-[minmax(0,1.6fr)_minmax(0,1fr)]",
+    "@min-[1500px]/page:grid-cols-[minmax(0,1.3fr)_minmax(0,1fr)]",
+    "@max-[940px]/page:grid-cols-[minmax(0,1fr)]",
+  ),
+  rail: cn(
+    "grid-cols-[minmax(0,1fr)_372px]",
+    "@min-[1500px]/page:grid-cols-[minmax(0,1fr)_420px]",
+    "@max-[1080px]/page:grid-cols-[minmax(0,1fr)]",
+  ),
+  half: cn("grid-cols-[repeat(2,minmax(0,1fr))]", "@max-[940px]/page:grid-cols-[minmax(0,1fr)]"),
+  calc: cn(
+    "grid-cols-[minmax(0,1fr)_minmax(0,1.5fr)]",
+    "@min-[1500px]/page:grid-cols-[minmax(0,1fr)_minmax(0,2fr)]",
+    "@max-[940px]/page:grid-cols-[minmax(0,1fr)]",
+  ),
+};
+
+export interface ColsProps extends ComponentPropsWithoutRef<"div"> {
+  /** Column proportions. Omit for the base main + side split. */
+  variant?: ColsVariant;
+}
+
+export function Cols({ variant, className, ...props }: ColsProps) {
+  return (
+    <div
+      className={cn("grid items-start gap-4", variantClasses[variant ?? "base"], className)}
+      {...props}
+    />
+  );
+}
+
+export interface ColsStackProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * From 1500px of page width the stack becomes 2 columns and its first
+   * child spans both rows.
+   */
+  wideSplit?: boolean;
+}
+
+export function ColsStack({ wideSplit, className, ...props }: ColsStackProps) {
+  return (
+    <div
+      className={cn(
+        "flex min-w-0 flex-col gap-4",
+        wideSplit &&
+          "@min-[1500px]/page:grid @min-[1500px]/page:grid-cols-[repeat(2,minmax(0,1fr))] @min-[1500px]/page:items-start @min-[1500px]/page:[&>*:first-child]:[grid-row:span_2]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/containers/cols/index.ts

@@ -0,0 +1 @@
+export * from "./cols.js";

package/src/containers/comment/comment.tsx

@@ -0,0 +1,56 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../../utils/cn.js";
+
+export type CommentTone = "pending" | "reply";
+
+const toneClasses: Record<CommentTone, string> = {
+  pending: "bg-warning-soft",
+  reply: "bg-surface-2",
+};
+
+const toneAuthorClasses: Record<CommentTone, string> = {
+  pending: "text-warning",
+  reply: "text-ink",
+};
+
+export interface CommentProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
+  tone?: CommentTone;
+  /** Name of the commenter. */
+  author: string;
+  /** Accessible name of the note (`role=note` takes no name from content). */
+  label: string;
+  /** Optional counter shown before the author. */
+  number?: number;
+  children?: ReactNode;
+}
+
+/** Annotation callout on a document: bold author, optional counter, body. */
+export function Comment({
+  tone = "pending",
+  author,
+  label,
+  number,
+  className,
+  children,
+  ...props
+}: CommentProps) {
+  return (
+    <div
+      role="note"
+      aria-label={label}
+      className={cn(
+        "mx-4 mb-3.5 break-words rounded-control px-3 py-2.5 text-[12.5px]",
+        toneClasses[tone],
+        className,
+      )}
+      {...props}
+    >
+      <b className={cn("font-semibold", toneAuthorClasses[tone])}>
+        {number != null ? `${number} · ` : null}
+        {author}
+      </b>
+      {" — "}
+      {children}
+    </div>
+  );
+}

package/src/containers/comment/index.ts

@@ -0,0 +1 @@
+export * from "./comment.js";

package/src/containers/data-grid/README.md

@@ -0,0 +1,38 @@
+# DataGrid
+
+Pure logic lives in plain modules (tested in `test/data-grid*.test.mjs`); `data-grid.tsx` only wires it.
+
+| Feature | Props | Logic |
+| --- | --- | --- |
+| Column types, validation | `type` (`boolean` added), `validate` | `model.ts` |
+| Column groups | `column.group` (path) | `column-groups.ts` |
+| Set filter | `filter: "set"` | `model.ts` (`toggleSetValues`) |
+| Advanced filter | `advancedFilter`, `showAdvancedFilter`, `FilterBuilder` | `filter-builder.ts` |
+| Tree data | `tree`, `expandedRowIds` | `tree.ts` |
+| Master / detail | `renderDetail`, `detailHeight` | `rows.ts`, `virtual.ts` |
+| Row pinning / reorder | `rowPinning`, `rowReorder` | `rows.ts` |
+| Range selection | `rangeSelection` | `range.ts` |
+| Server-side rows | `dataSource`, `pageSize`, `maxBlocks` | `data-source.ts`, `use-data-source.ts` |
+| Pivot, tool panel | `pivot`, `toolPanel` | `pivot.ts`, `tool-panel.tsx` |
+| CSV export | `exportFilename`, `onExport` | `model.ts` (`toCSV`) |
+| Undo / redo | `history`, `historyDepth`, `onHistoryChange`, `onCellsChange`, `createRow`, `onRowsChange` | `history.ts` |
+| Formulas | `formulas` | `formula.ts` (parser, evaluator), `formula-sheet.ts` (dependency graph, cycles) |
+| XLSX export | `exportXlsx`, `onExportXlsx` | `xlsx-export.ts` + `src/xlsx` (`@jcsoftdev/ui/xlsx`: OOXML and ZIP writers, lazy loaded) |
+| Integrated charts | `charts` (button in the range status bar) | `chart-range.ts`, `chart-panel.tsx` (lazy) |
+| Sparkline column | `type: "sparkline"`, `sparkline` | `data-grid.tsx` (`Sparkline`) |
+| Paste, fill | Ctrl + V, Ctrl + D / R (needs `onCellChange` or `onCellsChange`) | `grid-edit.ts` |
+| Fill handle | square at the bottom-right of a range (`rangeSelection`, needs `onCellChange` or `onCellsChange`): drag down, right, up or left to extend; Ctrl on release copies only; Escape cancels | `fill-series.ts` (`handleExtent`, `fillLanes`, `seriesFill`, `edgeScrollStep`) |
+
+The fill handle continues linear numeric runs (1, 2, 3 or 10, 20), dates (daily, weekly, by month or year, month ends
+kept) and text ending in a number ("Silla 1" gives "Silla 2", zero padding kept); a lone number or date, irregular
+runs and plain text are copied, and formulas are copied with their relative references shifted (`shiftFormula`).
+One drag is one history entry and one `onCellsChange` call with `source: "fill"`; the range grows to cover the fill.
+Dragging up or left runs the series backwards (10, 20, 30 gives 0, -10; dates go back; "Silla 3" gives "Silla 2"; copies repeat from the nearest cell). The viewport auto-scrolls on a `requestAnimationFrame` loop while the pointer is within 40 px of an edge, until release, Escape or cancel. `fillSeries={{ dateStep }}` sets how dates count: `"auto"` (default; months when they share the day of the month, days otherwise), `"day"` or `"month"`.
+
+The grid never mutates `data`: edits, paste, fill, undo and redo are reported through
+`onCellChange` (one change) or `onCellsChange` (several) with a `source`, and row changes through
+`onRowsChange`; the parent applies them. Use a stable `getRowId` so history survives row changes.
+
+Server-side mode sends sort, filters and quick search to `dataSource.getRows`; grouping, tree,
+row pinning, pivot and detail rows are off there. Pivot and tree replace grouping.
+Responsive behaviour uses container queries on `@container/grid` only.

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

@@ -0,0 +1,141 @@
+"use client";
+
+import { BarChart2, X } from "lucide-react";
+import { useMemo } from "react";
+import { AreaChart } from "../../charts/area-chart/area-chart.js";
+import { BarChart } from "../../charts/bar-chart/bar-chart.js";
+import type { ValueFormat } from "../../charts/core/format.js";
+import { LineChart } from "../../charts/line-chart/line-chart.js";
+import { PieChart } from "../../charts/pie-chart/pie-chart.js";
+import { cn } from "../../utils/cn.js";
+import {
+  availableKinds,
+  type GridChartKind,
+  pieSlices,
+  type RangeChartData,
+} from "./chart-range.js";
+
+export interface ChartPanelLabels {
+  title: string;
+  kinds: Record<GridChartKind, string>;
+  kindGroup: string;
+  close: string;
+  noData: string;
+  other: string;
+}
+
+export interface ChartPanelProps {
+  /** Null when the range holds no numbers. */
+  data: RangeChartData | null;
+  kind: GridChartKind;
+  onKind: (kind: GridChartKind) => void;
+  onClose: () => void;
+  valueFormat: ValueFormat;
+  labels: ChartPanelLabels;
+  /** Height of the drawing in px. */
+  height?: number;
+  className?: string;
+}
+
+const buttonClass =
+  "inline-flex h-7 items-center rounded-xs px-2 font-[600] text-[12px] text-ink-3 hover:text-ink aria-pressed:bg-accent-soft aria-pressed:text-accent-ink";
+
+/** Chart drawn from a range of grid cells: bars, lines, areas or a pie. Loaded on demand by the grid. */
+export function ChartPanel({
+  data,
+  kind,
+  onKind,
+  onClose,
+  valueFormat,
+  labels,
+  height = 260,
+  className,
+}: ChartPanelProps) {
+  const kinds = useMemo(() => (data ? availableKinds(data) : []), [data]);
+  const shown = kinds.includes(kind) ? kind : "bar";
+  const slices = useMemo(
+    () => (data && shown === "pie" ? pieSlices(data, 0, 8, labels.other) : []),
+    [data, shown, labels.other],
+  );
+
+  return (
+    <section
+      aria-label={labels.title}
+      className={cn("@container/gridchart min-w-0 border-t-divider", className)}
+    >
+      <header className="flex flex-wrap items-center gap-2 px-3 pt-2">
+        <BarChart2 aria-hidden="true" className="size-4 shrink-0 text-ink-3" />
+        <h3 className="mr-auto min-w-0 truncate font-[650] text-[13px] text-ink">{labels.title}</h3>
+        {data ? (
+          <fieldset className="flex h-control-sm items-center rounded-control border-divider bg-surface-control p-0.5">
+            <legend className="sr-only">{labels.kindGroup}</legend>
+            {kinds.map((option) => (
+              <button
+                key={option}
+                type="button"
+                aria-pressed={shown === option}
+                onClick={() => onKind(option)}
+                className={buttonClass}
+              >
+                {labels.kinds[option]}
+              </button>
+            ))}
+          </fieldset>
+        ) : null}
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label={labels.close}
+          title={labels.close}
+          className="grid size-7 place-items-center rounded-xs text-ink-3 hover:bg-surface-2 hover:text-ink [&_svg]:size-4"
+        >
+          <X aria-hidden="true" />
+        </button>
+      </header>
+      {data ? (
+        <div className="min-w-0 p-3" style={{ height: height + 24 }}>
+          {shown === "pie" ? (
+            <PieChart
+              title={labels.title}
+              data={slices.map((slice) => ({ id: slice.id, name: slice.name, value: slice.value }))}
+              height="fill"
+              valueFormat={valueFormat}
+              legend="bottom"
+              animate={false}
+            />
+          ) : shown === "bar" ? (
+            <BarChart
+              title={labels.title}
+              categories={data.categories}
+              series={data.series}
+              height="fill"
+              valueFormat={valueFormat}
+              animate={false}
+            />
+          ) : shown === "line" ? (
+            <LineChart
+              title={labels.title}
+              categories={data.categories}
+              series={data.series}
+              height="fill"
+              valueFormat={valueFormat}
+              markers
+              animate={false}
+            />
+          ) : (
+            <AreaChart
+              title={labels.title}
+              categories={data.categories}
+              series={data.series}
+              height="fill"
+              valueFormat={valueFormat}
+              animate={false}
+            />
+          )}
+        </div>
+      ) : (
+        <p className="px-3 py-6 text-center text-[13px] text-ink-3">{labels.noData}</p>
+      )}
+    </section>
+  );
+}

package/src/containers/data-grid/chart-range.ts

@@ -0,0 +1,131 @@
+// Turns a range of grid cells into chart series. Pure: the grid passes the cells, a chart draws them.
+import type { CellValue } from "./types.js";
+
+export type GridChartKind = "bar" | "line" | "area" | "pie";
+
+export interface RangeCellInput {
+  value: CellValue;
+  /** The cell as shown (formatted); used for category names. */
+  text: string;
+}
+
+export interface RangeChartInput {
+  /** Header of each column in the range, left to right. */
+  headers: readonly string[];
+  /** Column ids, same order. */
+  columnIds: readonly string[];
+  /** One array per row of the range; `null` for a cell that is not data (group rows, selection column). */
+  cells: ReadonlyArray<ReadonlyArray<RangeCellInput | null>>;
+  /** Name of a category when the range has no text column: "Fila 1", "Fila 2"... */
+  rowLabel?: (position: number) => string;
+}
+
+export interface RangeSeries {
+  id: string;
+  name: string;
+  data: Array<number | null>;
+}
+
+export interface RangeChartData {
+  categories: string[];
+  /** Header of the column the categories came from, null when they are row numbers. */
+  categoryHeader: string | null;
+  series: RangeSeries[];
+}
+
+function isNumber(value: CellValue): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** A column is numeric when at least half of its filled cells hold numbers. */
+function numericColumn(cells: ReadonlyArray<ReadonlyArray<RangeCellInput | null>>, c: number) {
+  let filled = 0;
+  let numbers = 0;
+  for (const line of cells) {
+    const cell = line[c];
+    if (!cell || cell.value === null || cell.value === undefined || cell.value === "") continue;
+    filled += 1;
+    if (isNumber(cell.value)) numbers += 1;
+  }
+  return numbers > 0 && numbers * 2 >= filled;
+}
+
+/**
+ * Series from a cell range: the first text or date column names the categories and every numeric
+ * column becomes a series (named by its header). Without a text column the categories are the row
+ * numbers of the range. Rows that are not data rows are left out. Null when nothing is numeric.
+ */
+export function rangeToChart(input: RangeChartInput): RangeChartData | null {
+  const { headers, columnIds, cells } = input;
+  const rowLabel = input.rowLabel ?? ((position: number) => `Fila ${position}`);
+  const rows = cells.filter((line) => line.some((cell) => cell !== null));
+  if (rows.length === 0 || headers.length === 0) return null;
+
+  const numeric = headers.map((_, c) => numericColumn(rows, c));
+  const dataColumn = headers.map((_, c) =>
+    rows.some((line) => line[c] !== null && line[c] !== undefined),
+  );
+  const categoryColumn = headers.findIndex((_, c) => dataColumn[c] && !numeric[c]);
+  const valueColumns = headers.map((_, c) => c).filter((c) => numeric[c] && dataColumn[c]);
+  if (valueColumns.length === 0) return null;
+
+  const categories = rows.map((line, index) => {
+    const text = categoryColumn >= 0 ? line[categoryColumn]?.text.trim() : "";
+    return text ? text : rowLabel(index + 1);
+  });
+  const series = valueColumns.map<RangeSeries>((c) => ({
+    id: columnIds[c] ?? `col-${c}`,
+    name: headers[c] ?? `Serie ${c + 1}`,
+    data: rows.map((line) => {
+      const value = line[c]?.value;
+      return isNumber(value) ? value : null;
+    }),
+  }));
+  return {
+    categories,
+    categoryHeader: categoryColumn >= 0 ? (headers[categoryColumn] ?? null) : null,
+    series,
+  };
+}
+
+export interface PieSlice {
+  id: string;
+  name: string;
+  value: number;
+}
+
+/**
+ * Slices of a pie from one series: only positive values, largest first. Beyond `maxSlices` the
+ * smallest are summed into one slice called `otherLabel`.
+ */
+export function pieSlices(
+  data: RangeChartData,
+  seriesIndex = 0,
+  maxSlices = 8,
+  otherLabel = "Otros",
+): PieSlice[] {
+  const values = data.series[seriesIndex]?.data ?? [];
+  const slices: PieSlice[] = [];
+  values.forEach((value, index) => {
+    if (value !== null && value > 0) {
+      slices.push({
+        id: `${seriesIndex}-${index}`,
+        name: data.categories[index] ?? `${index + 1}`,
+        value,
+      });
+    }
+  });
+  slices.sort((a, b) => b.value - a.value);
+  if (slices.length <= maxSlices) return slices;
+  const head = slices.slice(0, Math.max(1, maxSlices - 1));
+  const rest = slices.slice(head.length).reduce((sum, slice) => sum + slice.value, 0);
+  return [...head, { id: "other", name: otherLabel, value: rest }];
+}
+
+/** Charts that make sense for the data: a pie needs positive values, a line needs two or more points. */
+export function availableKinds(data: RangeChartData): GridChartKind[] {
+  const kinds: GridChartKind[] = ["bar"];
+  if (data.categories.length >= 2) kinds.push("line", "area");
+  if (pieSlices(data).length >= 2) kinds.push("pie");
+  return kinds;
+}

package/src/containers/data-grid/column-groups.ts

@@ -0,0 +1,45 @@
+// Multi-level column headers: spans of adjacent columns that share a group path.
+import type { DataGridColumn } from "./types.js";
+
+export function groupPathOf<T>(column: DataGridColumn<T>): string[] {
+  if (column.group === undefined) return [];
+  return typeof column.group === "string" ? [column.group] : [...column.group];
+}
+
+export interface HeaderGroupCell {
+  /** Group label; empty for the columns that have no group at this level. */
+  label: string;
+  /** Index of the first column it covers. */
+  start: number;
+  span: number;
+}
+
+/**
+ * One list of cells per header level, outermost first. Adjacent columns with the same path up to
+ * a level share a cell; columns without a group at that level get blank cells. Spans never cross
+ * a `breaks` index (pinned zone edges, where the table adds its filler cell).
+ */
+export function buildHeaderGroups(
+  paths: readonly (readonly string[])[],
+  breaks: readonly number[] = [],
+): HeaderGroupCell[][] {
+  const depth = paths.reduce((max, path) => Math.max(max, path.length), 0);
+  const breakSet = new Set(breaks);
+  const levels: HeaderGroupCell[][] = [];
+  for (let level = 0; level < depth; level += 1) {
+    const cells: HeaderGroupCell[] = [];
+    paths.forEach((path, index) => {
+      const label = path[level] ?? "";
+      const prefix = path.slice(0, level + 1).join("\u0001");
+      const last = cells[cells.length - 1];
+      const lastPrefix = last ? paths[last.start]?.slice(0, level + 1).join("\u0001") : undefined;
+      if (last && !breakSet.has(index) && last.label === label && lastPrefix === prefix) {
+        last.span += 1;
+      } else {
+        cells.push({ label, start: index, span: 1 });
+      }
+    });
+    levels.push(cells);
+  }
+  return levels;
+}