@elabs-ai/components-data 4.1.0 → 5.0.0

package/src/data-table/cells/sparkline-cell.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { NumericExtent } from "../cell-scales";
+import { BAR_CELL_POSITIVE_COLOR } from "./bar-cell";
+
+/** The line's stroke width (px, unscaled by the viewBox). */
+export const SPARKLINE_CELL_STROKE_WIDTH = 1.5;
+const VIEW_WIDTH = 100;
+const PAD = 2;
+
+export interface SparklineCellProps extends HTMLAttributes<HTMLDivElement> {
+  values: readonly (number | null)[];
+  /** The y domain: this row's own extent (`range: "cell"`) or the column's. */
+  domain: NumericExtent | null;
+  /** Every value as text, for screen readers, sorting and copy. */
+  label: string;
+  /** Printed first / last values (with `labels: "ends"`). */
+  ends?: readonly [first: string, last: string];
+  /**
+   * Room reserved for those two labels, in `ch` (`labelBoxCh` over the whole
+   * column). The drawing takes what they leave over, so one reservation per
+   * column keeps every row's line on the same x scale.
+   */
+  endsWidth?: readonly [first: number, last: number];
+  fill?: boolean;
+  /** Drawing height in px. Default 24. */
+  height?: number;
+}
+
+/** `M`/`L` path through the finite points; a `null` breaks the line. */
+function sparkPath(values: readonly (number | null)[], domain: NumericExtent, height: number) {
+  const span = domain.max - domain.min;
+  const step = values.length > 1 ? VIEW_WIDTH / (values.length - 1) : 0;
+  const y = (v: number) =>
+    span > 0 ? PAD + (1 - (v - domain.min) / span) * Math.max(0, height - 2 * PAD) : height / 2;
+  let d = "";
+  let open = false;
+  values.forEach((v, i) => {
+    if (v === null) return void (open = false);
+    d += `${open ? "L" : "M"}${(i * step).toFixed(2)} ${y(v).toFixed(2)}`;
+    open = true;
+  });
+  return d;
+}
+
+/** An in-cell sparkline: a ≤ 40-line inline SVG on a shared or own y domain. */
+export const SparklineCell = forwardRef<HTMLDivElement, SparklineCellProps>(function SparklineCell(
+  { values, domain, label, ends, endsWidth, fill = false, height = 24, className, ...props },
+  ref,
+) {
+  const h = Math.max(0, height);
+  const d = domain ? sparkPath(values, domain, h) : "";
+  const area = fill && d ? `${d}L${VIEW_WIDTH} ${h}L0 ${h}Z` : "";
+  return (
+    <div
+      ref={ref}
+      data-slot="sparkline-cell"
+      className={cn("flex min-w-0 items-center gap-1.5", className)}
+      {...props}
+    >
+      <span className="sr-only">{label}</span>
+      {/*
+        Both end labels are column-wide reservations (`endsWidth`), never this
+        row's own text width, so every row's drawing gets the same width and the
+        lines share one x scale as well as the y scale.
+      */}
+      {ends && (
+        <span
+          aria-hidden="true"
+          className="shrink-0 whitespace-nowrap text-end text-meta text-muted-foreground tabular-nums"
+          style={endsWidth?.[0] ? { width: `${endsWidth[0]}ch` } : undefined}
+        >
+          {ends[0]}
+        </span>
+      )}
+      <svg
+        aria-hidden="true"
+        data-slot="sparkline-cell-svg"
+        data-y-min={domain?.min}
+        data-y-max={domain?.max}
+        viewBox={`0 0 ${VIEW_WIDTH} ${h}`}
+        preserveAspectRatio="none"
+        className="block min-w-8 flex-1 overflow-visible"
+        style={{ height: h }}
+      >
+        {area && <path d={area} fill={BAR_CELL_POSITIVE_COLOR} fillOpacity={0.2} stroke="none" />}
+        <path
+          data-slot="sparkline-cell-line"
+          d={d}
+          fill="none"
+          // Same mark ink as the in-cell bar: a categorical token carries no
+          // contrast guarantee and read as 1.42:1 on `--card` in light (b-4).
+          stroke={BAR_CELL_POSITIVE_COLOR}
+          strokeWidth={SPARKLINE_CELL_STROKE_WIDTH}
+          strokeLinejoin="round"
+          strokeLinecap="round"
+          vectorEffect="non-scaling-stroke"
+        />
+      </svg>
+      {ends && (
+        <span
+          aria-hidden="true"
+          className="shrink-0 whitespace-nowrap text-start text-meta text-foreground tabular-nums"
+          style={endsWidth?.[1] ? { width: `${endsWidth[1]}ch` } : undefined}
+        >
+          {ends[1]}
+        </span>
+      )}
+    </div>
+  );
+});

package/src/data-table/column-meta.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { columnSizeStyle, formatCellValue, resolveShowAt } from "./column-meta";
+
+const fmt = (n: number, opts?: Intl.NumberFormatOptions) =>
+  new Intl.NumberFormat("en-US", opts).format(n);
+
+describe("column-meta", () => {
+  it("formatCellValue mirrors the charts valueFormat object shape", () => {
+    expect(formatCellValue(1234.5, undefined, fmt)).toBe("1,234.5");
+    expect(formatCellValue(1234.5, { abbreviate: false, decimals: 0 }, fmt)).toBe("1,235");
+    expect(formatCellValue(1500, {}, fmt)).toBe("1.5K");
+    expect(formatCellValue(0.423, { style: "percent" }, fmt)).toBe("42.3%");
+    expect(formatCellValue(12, { sign: "always", suffix: " pts" }, fmt)).toBe("+12 pts");
+    expect(formatCellValue(-12, { sign: "parens" }, fmt)).toBe("(12)");
+    expect(formatCellValue(12, { decimals: 1, optionalDecimals: false }, fmt)).toBe("12.0");
+    expect(formatCellValue(820, { style: "currency", currency: "EUR", decimals: 0 }, fmt)).toBe(
+      "€820",
+    );
+    expect(formatCellValue(12345, { abbreviate: false, grouping: false }, fmt)).toBe("12345");
+    expect(formatCellValue("text", { decimals: 2 }, fmt)).toBe("text");
+    expect(formatCellValue(null, undefined, fmt)).toBe("");
+  });
+
+  it("resolveShowAt: base is the wide value, narrow overrides below 450 px", () => {
+    expect(resolveShowAt(undefined, "narrow")).toBe(true);
+    expect(resolveShowAt(false, "wide")).toBe(false);
+    expect(resolveShowAt({ base: true, narrow: false }, "wide")).toBe(true);
+    expect(resolveShowAt({ base: true, narrow: false }, "narrow")).toBe(false);
+    expect(resolveShowAt({ base: false }, "narrow")).toBe(false);
+  });
+
+  it("columnSizeStyle: width %, min width px, style last; nothing for a plain column", () => {
+    expect(columnSizeStyle(undefined)).toBeUndefined();
+    expect(columnSizeStyle({ numeric: true })).toBeUndefined();
+    expect(columnSizeStyle({ width: 30, minWidth: 80, style: { fontStyle: "italic" } })).toEqual({
+      width: "30%",
+      minWidth: 80,
+      fontStyle: "italic",
+    });
+    expect(columnSizeStyle({ width: -4 })).toEqual({ width: "0%" });
+  });
+});

package/src/data-table/column-meta.ts

@@ -0,0 +1,282 @@
+import type { CSSProperties } from "react";
+import type { RowData } from "@tanstack/react-table";
+import type { ColorScaleDomain } from "@elabs-ai/components-ui";
+import type { DataTableBreakpoint } from "./use-table-breakpoint";
+
+/**
+ * column-meta.ts — the typed `columnDef.meta` contract `DataTable` reads.
+ *
+ * `numeric` / `align` (#69) style a column; everything else is the editorial
+ * presentation layer (RM-123): an in-cell visual, a number format, categorical
+ * colouring, per-breakpoint visibility and column sizing. Every key is optional
+ * and a column without them renders exactly as before.
+ *
+ * `data` never imports `@elabs-ai/components-charts` (one-way dependency
+ * graph), so the number-format shape below is a STRUCTURAL twin of charts'
+ * `ChartValueFormatSpec` (RM-109): a spec written for a chart type-checks here
+ * unchanged, and formats the same way.
+ */
+
+/**
+ * A number format — the same object shape as charts' `ChartValueFormatSpec`.
+ *
+ * - `style`: `"number"` (default), `"currency"`, or `"percent"` (fraction in,
+ *   `%` out).
+ * - `decimals`: maximum fraction digits. `optionalDecimals: false` makes it
+ *   the minimum too.
+ * - `abbreviate`: `true` always compact (`1.5K`), `false` never, `"auto"`
+ *   (default) from 1,000 up. Percent is never compacted.
+ * - `sign`: `"auto"` (minus only), `"always"` (`+`/`-`), `"parens"` (`(12)`).
+ * - `prefix` / `suffix`: literal text around the number.
+ * - `grouping: false` drops the thousands separator.
+ * - `currency`: ISO 4217 code for `style: "currency"` (default `"USD"`).
+ */
+export interface DataTableValueFormatSpec {
+  style?: "number" | "currency" | "percent";
+  decimals?: number;
+  optionalDecimals?: boolean;
+  abbreviate?: boolean | "auto";
+  sign?: "auto" | "always" | "parens";
+  prefix?: string;
+  suffix?: string;
+  grouping?: boolean;
+  currency?: string;
+}
+
+/** An in-cell bar: the value as a horizontal bar from zero. */
+export interface DataTableBarVisual {
+  kind: "bar";
+  /** `"regular"` (default) sits beside the value; `"slim"` is a thin rule under it. */
+  style?: "regular" | "slim";
+  /** Paint the grey remainder of the range behind the bar. */
+  track?: boolean;
+  /**
+   * The range a full-width bar spans. `"column"` (default): this column's own
+   * min / max; `"table"`: shared by every bar column with `range: "table"`;
+   * `[min, max]`: fixed. Zero is always inside the range.
+   */
+  range?: readonly [min: number, max: number] | "column" | "table";
+  /** Row key whose category picks the bar colour (`--chart-1…12`). */
+  colorBy?: string;
+  /**
+   * The `colorBy` key's title, or `false` to draw no key. Default `true`: a
+   * category carried by hue alone is unreadable without one (WCAG 1.4.1), so
+   * the key is opt-OUT — turn it off only when the table prints the category
+   * in a column of its own.
+   */
+  legend?: string | boolean;
+  /** Paint negative values in the negative token. Default `true`. */
+  negative?: boolean;
+}
+
+/** An in-cell sparkline across several numeric row keys (one point per key). */
+export interface DataTableSparklineVisual {
+  kind: "sparkline";
+  /** Row keys, in x order. */
+  keys: readonly string[];
+  /** Fill the area under the line. */
+  fill?: boolean;
+  /** `"ends"` prints the first and last values beside the line. Default `"none"`. */
+  labels?: "ends" | "none";
+  /** Drawing height in px. Default 24. */
+  height?: number;
+  /** `"cell"` (default): this row's own min / max; `"column"`: shared by every row. */
+  range?: "cell" | "column";
+}
+
+/** In-cell mini columns across several numeric row keys. */
+export interface DataTableColumnsVisual {
+  kind: "columns";
+  keys: readonly string[];
+  /** Drawing height in px. Default 24. */
+  height?: number;
+  /** `"cell"` (default): this row's own max; `"column"`: shared by every row. */
+  range?: "cell" | "column";
+}
+
+/**
+ * A heatmap colour scale. Resolved by `colorScaleFor` (`@elabs-ai/components-ui`),
+ * so the colours are `--chart-seq-*` / `--chart-div-*` ramp tokens.
+ */
+export interface DataTableHeatmapScale {
+  /** `"stepped"` cuts countable classes; `"continuous"` snaps to the nearest ramp step. */
+  type: "stepped" | "continuous";
+  /** How many classes (stepped) or Jenks classes (continuous `jenks`). Default 5. */
+  steps?: number;
+  /**
+   * `"linear"` (default) equal widths; `"quantile"` equal counts; `"jenks"`
+   * natural breaks; `"custom"` the `breaks` you pass (always stepped).
+   */
+  method?: "linear" | "quantile" | "jenks" | "custom";
+  /** `method: "custom"` only: the inner thresholds, ascending. */
+  breaks?: readonly number[];
+  /** `[min, max]`, or `[min, center, max]` to pin the ramp's middle colour. */
+  domain?: ColorScaleDomain;
+  /** Default `"diverging"` when `domain` has a centre, else `"sequential"`. */
+  palette?: "sequential" | "diverging";
+}
+
+/** The cell's background is the value's ramp colour. */
+export interface DataTableHeatmapVisual {
+  kind: "heatmap";
+  scale: DataTableHeatmapScale;
+  /** Hide the printed value visually; screen readers, sorting and copy still read it. */
+  hideValue?: boolean;
+  /**
+   * Print the scale's colour key above the table. `true` titles it with the
+   * column header; a string is the title (use it when one heatmap spans several
+   * columns — the key is printed once per shared scale).
+   */
+  legend?: boolean | string;
+}
+
+export type DataTableCellVisual =
+  | DataTableBarVisual
+  | DataTableSparklineVisual
+  | DataTableColumnsVisual
+  | DataTableHeatmapVisual;
+
+/**
+ * Categorical conditional formatting: the category in row key `key` picks a
+ * `--chart-1…12` colour, painted as a background wash or as text ink, on this
+ * column's cell or on the whole row.
+ */
+export interface DataTableColorBy {
+  key: string;
+  target: "background" | "text";
+  /** Default `"cell"`. */
+  scope?: "cell" | "row";
+  /**
+   * The colour key's title, or `false` to draw none. Default `true` — see
+   * `DataTableBarVisual.legend`.
+   */
+  legend?: string | boolean;
+}
+
+/**
+ * Show a column at a table breakpoint. `true` / `false` for every width, or
+ * `{ base, narrow }`: `base` is the wide value, `narrow` applies below 450 px.
+ */
+export type DataTableShowAt = boolean | { base: boolean; narrow?: boolean };
+
+/** `markdown: true` or options. Images are off unless `images: true`. */
+export interface DataTableMarkdownOptions {
+  images?: boolean;
+}
+
+/**
+ * `DataTable`'s `columnDef.meta` contract, read by the header, body, card and
+ * skeleton cell renderers. Set `numeric: true` on a column to get
+ * `tabular-nums` + end-alignment on both the `<th>` and every `<td>`
+ * (including the loading skeleton) for free.
+ */
+export interface DataTableColumnMeta {
+  /** Numeric column: tabular figures + end alignment on header and cells. */
+  numeric?: boolean;
+  /**
+   * Explicit alignment override for when `numeric` isn't the right cue (or
+   * to align a non-numeric column). Independent of `numeric` — `numeric`
+   * alone still drives `tabular-nums` even when `align` overrides the
+   * alignment away from `"end"`.
+   */
+  align?: "start" | "center" | "end";
+  /**
+   * An in-cell visual (bar, sparkline, mini columns, heatmap). The cell keeps
+   * its value as text — visually hidden only with `hideValue` — so sorting,
+   * copy and screen readers still read the number. Replaces the column's
+   * `cell` renderer.
+   */
+  visual?: DataTableCellVisual;
+  /** Number format for the printed value (the charts `valueFormat` object shape). */
+  format?: DataTableValueFormatSpec;
+  /** Categorical colouring driven by another row key. */
+  colorBy?: DataTableColorBy;
+  /** Per-breakpoint visibility; render-only, never written to `columnVisibility`. */
+  showAt?: DataTableShowAt;
+  /** Column width as a percentage of the table width. */
+  width?: number;
+  /** Minimum column width in px. */
+  minWidth?: number;
+  /** Extra inline style on this column's header and body cells. */
+  style?: CSSProperties;
+  /** Render a string value as safe inline markdown (bold, italic, links, `sup`, `code`). */
+  markdown?: boolean | DataTableMarkdownOptions;
+}
+
+declare module "@tanstack/react-table" {
+  // `TData`/`TValue` must stay in the signature to match the interface being
+  // augmented, even though `DataTableColumnMeta` (deliberately) doesn't use
+  // them; the empty extends-body is how TanStack's own module-augmentation
+  // pattern for `ColumnMeta` is documented.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-object-type
+  interface ColumnMeta<TData extends RowData, TValue> extends DataTableColumnMeta {}
+}
+
+/** Charts' compaction threshold (`COMPACT_THRESHOLD`), mirrored. */
+const COMPACT_THRESHOLD = 1000;
+
+/**
+ * The printed text for a cell value. Numbers go through `format` (or the
+ * locale's plain number format); anything else is stringified; nullish is `""`.
+ */
+export function formatCellValue(
+  value: unknown,
+  format: DataTableValueFormatSpec | undefined,
+  formatNumber: (n: number, opts?: Intl.NumberFormatOptions) => string,
+): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value !== "number") return String(value);
+  if (!Number.isFinite(value)) return "";
+  if (!format) return formatNumber(value);
+  const style = format.style ?? "number";
+  const options: Intl.NumberFormatOptions = {};
+  if (style === "currency") {
+    options.style = "currency";
+    options.currency = format.currency ?? "USD";
+  } else if (style === "percent") {
+    options.style = "percent";
+  }
+  const abbreviate =
+    style !== "percent" &&
+    (format.abbreviate === true ||
+      (format.abbreviate !== false && Math.abs(value) >= COMPACT_THRESHOLD));
+  if (abbreviate) {
+    options.notation = "compact";
+    options.compactDisplay = "short";
+  }
+  const exact = style === "number" && format.abbreviate === false;
+  const digits = format.decimals ?? (exact ? undefined : 1);
+  if (digits !== undefined) {
+    options.maximumFractionDigits = digits;
+    if (format.optionalDecimals === false) options.minimumFractionDigits = digits;
+  }
+  if (format.grouping === false) options.useGrouping = false;
+  const parens = format.sign === "parens";
+  if (format.sign === "always") options.signDisplay = "always";
+  if (parens) options.signDisplay = "never";
+  const body = formatNumber(value, options);
+  const signed = parens && value < 0 ? `(${body})` : body;
+  return `${format.prefix ?? ""}${signed}${format.suffix ?? ""}`;
+}
+
+/** Whether a column is shown at `breakpoint` (no `showAt` → always). */
+export function resolveShowAt(
+  showAt: DataTableShowAt | undefined,
+  breakpoint: DataTableBreakpoint,
+): boolean {
+  if (showAt === undefined) return true;
+  if (typeof showAt === "boolean") return showAt;
+  return breakpoint === "narrow" ? (showAt.narrow ?? showAt.base) : showAt.base;
+}
+
+/** The inline style for `meta.width` (%), `meta.minWidth` (px) and `meta.style`. */
+export function columnSizeStyle(meta: DataTableColumnMeta | undefined): CSSProperties | undefined {
+  if (!meta || (meta.width === undefined && meta.minWidth === undefined && !meta.style)) {
+    return undefined;
+  }
+  return {
+    ...(meta.width !== undefined ? { width: `${Math.max(0, meta.width)}%` } : null),
+    ...(meta.minWidth !== undefined ? { minWidth: Math.max(0, meta.minWidth) } : null),
+    ...meta.style,
+  };
+}