@elabs-ai/components-data 4.2.0 → 5.0.0

package/src/data-table/ranks-column.test.tsx

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { DataTableRankCell, DataTableRankHeader, computeRowRanks } from "./ranks-column";
+
+describe("ranks-column", () => {
+  it("computeRowRanks numbers rows 1…n in data order, skipping excluded (sticky) rows", () => {
+    const ranks = computeRowRanks(["a", "avg", "b", "c"], new Set(["avg"]));
+    expect([...ranks.entries()]).toEqual([
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+    ]);
+  });
+  it("renders a column header and a rank cell", () => {
+    render(
+      <table>
+        <thead>
+          <tr>
+            <DataTableRankHeader />
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <DataTableRankCell rank="3" />
+          </tr>
+        </tbody>
+      </table>,
+    );
+    expect(screen.getByRole("columnheader")).toHaveTextContent("#");
+    expect(screen.getByRole("cell")).toHaveTextContent("3");
+  });
+  /**
+   * b-5 — the printed number is the row's position in the DATA, which is why
+   * it reads 2, 1, 6, 4 beside a sorted column. A header whose accessible name
+   * is the single character "#" never says so, so the rule is unlearnable:
+   * the name has to BE the rule. Exact string, per the conventions' "never a
+   * name regex" note.
+   */
+  it("names the column by what the number means, not by the glyph", () => {
+    render(
+      <table>
+        <thead>
+          <tr>
+            <DataTableRankHeader />
+          </tr>
+        </thead>
+      </table>,
+    );
+    const header = screen.getByRole("columnheader");
+    expect(header).toHaveAccessibleName("Position in the data as supplied");
+    expect(header).toHaveAttribute("title", "Position in the data as supplied");
+  });
+  it("takes a caller's own name for the column", () => {
+    render(
+      <table>
+        <thead>
+          <tr>
+            <DataTableRankHeader label="Rank in the 2024 census" />
+          </tr>
+        </thead>
+      </table>,
+    );
+    expect(screen.getByRole("columnheader")).toHaveAccessibleName("Rank in the 2024 census");
+  });
+});

package/src/data-table/ranks-column.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import { forwardRef, type TdHTMLAttributes, type ThHTMLAttributes } from "react";
+import { useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+/**
+ * ranks-column.tsx — `DataTable`'s `showRanks` column (RM-123).
+ *
+ * A rank belongs to the ROW: it is the row's 1-based position in the `data`
+ * you passed (sticky rows excluded), so re-sorting, filtering or paging moves
+ * the numbers with their rows and never renumbers them. It is rendered beside
+ * the TanStack columns, not as one, so the table model is unchanged.
+ */
+
+/** Row id → rank (1…n in data order), skipping the ids in `exclude`. */
+export function computeRowRanks(
+  rowIds: readonly string[],
+  exclude: ReadonlySet<string> = new Set(),
+): Map<string, number> {
+  const ranks = new Map<string, number>();
+  let rank = 0;
+  for (const id of rowIds) {
+    if (!exclude.has(id)) ranks.set(id, ++rank);
+  }
+  return ranks;
+}
+
+export interface DataTableRankHeaderProps extends ThHTMLAttributes<HTMLTableCellElement> {
+  /**
+   * The column's accessible NAME, and its `title`. Defaults to the locale
+   * seam's `data.table.rankHeader`.
+   *
+   * The visible glyph stays "#" — it has to, in a 40px column — so the glyph
+   * is decorative (`aria-hidden`) and this string is what the column is
+   * actually called. Without it the header's accessible name is the single
+   * character "#", which says nothing about WHICH position is printed: beside
+   * a sorted column the numbers legitimately read 2, 1, 6, 4 and a reader has
+   * no way to learn why. `DataTable` prints the same rule visibly, once, above
+   * the table (`data-slot="data-table-rank-key"`).
+   */
+  label?: string;
+}
+
+/**
+ * The ranks column's header cell: "#" as the visible glyph, `label` as the
+ * name AT reads.
+ */
+export const DataTableRankHeader = forwardRef<HTMLTableCellElement, DataTableRankHeaderProps>(
+  function DataTableRankHeader({ className, children, label, ...props }, ref) {
+    const { t } = useLocale();
+    const name = label ?? t("data.table.rankHeader");
+    return (
+      <th
+        ref={ref}
+        scope="col"
+        title={name}
+        data-slot="data-table-rank-header"
+        className={cn("w-10 px-3 text-end align-middle tabular-nums", className)}
+        {...props}
+      >
+        {children ?? (
+          <>
+            <span aria-hidden="true">#</span>
+            <span className="sr-only">{name}</span>
+          </>
+        )}
+      </th>
+    );
+  },
+);
+
+/** One row's rank cell; `rank` undefined (a sticky row) renders empty. */
+export const DataTableRankCell = forwardRef<
+  HTMLTableCellElement,
+  TdHTMLAttributes<HTMLTableCellElement> & { rank?: string }
+>(function DataTableRankCell({ rank, className, ...props }, ref) {
+  return (
+    <td
+      ref={ref}
+      data-slot="data-table-rank-cell"
+      className={cn(
+        "w-10 px-3 text-end align-middle tabular-nums text-muted-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {rank}
+    </td>
+  );
+});

package/src/data-table/sticky-rows.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { stickyRowPinning } from "./sticky-rows";
+
+describe("stickyRowPinning", () => {
+  const data = [{ n: "a" }, { n: "avg" }, { n: "b" }, { n: "total" }];
+  it("maps records to TanStack row ids (index, or getRowId) in data order", () => {
+    const sticky = (r: { n: string }) =>
+      r.n === "avg" ? "top" : r.n === "total" ? "bottom" : undefined;
+    expect(stickyRowPinning(data, sticky)).toEqual({ top: ["1"], bottom: ["3"] });
+    expect(stickyRowPinning(data, sticky, (r) => r.n)).toEqual({ top: ["avg"], bottom: ["total"] });
+  });
+  it("is empty without a predicate or a match", () => {
+    expect(stickyRowPinning(data, undefined)).toEqual({ top: [], bottom: [] });
+    expect(stickyRowPinning(data, () => undefined)).toEqual({ top: [], bottom: [] });
+  });
+});

package/src/data-table/sticky-rows.ts

@@ -0,0 +1,77 @@
+import type { RowModel, RowPinningState, Table } from "@tanstack/react-table";
+
+/**
+ * sticky-rows.ts — `DataTable`'s `stickyRows` (RM-123): rows such as an
+ * "average" or "total" that stay at the top or bottom of EVERY page and after
+ * every sort.
+ *
+ * Built on TanStack's own row pinning (`keepPinnedRows`), so the table model is
+ * unchanged: a sticky row keeps its id, its selection and its `data` index; it
+ * is only rendered outside the sorted / paged centre rows.
+ */
+
+export type DataTableStickyRowPosition = "top" | "bottom";
+
+/** Decides, per record, whether its row sticks to the top or the bottom (or neither). */
+export type DataTableStickyRows<TData> = (
+  row: TData,
+  index: number,
+) => DataTableStickyRowPosition | undefined;
+
+const EMPTY: RowPinningState = { top: [], bottom: [] };
+
+/**
+ * The TanStack `rowPinning` state for `stickyRows` over `data`, in data order.
+ * Row ids follow TanStack's own rule: `getRowId(row, index)`, else the index.
+ */
+export function stickyRowPinning<TData>(
+  data: readonly TData[],
+  stickyRows: DataTableStickyRows<TData> | undefined,
+  getRowId?: (row: TData, index: number) => string,
+): RowPinningState {
+  if (!stickyRows) return EMPTY;
+  const top: string[] = [];
+  const bottom: string[] = [];
+  data.forEach((row, index) => {
+    const position = stickyRows(row, index);
+    if (!position) return;
+    const id = getRowId ? getRowId(row, index) : String(index);
+    (position === "top" ? top : bottom).push(id);
+  });
+  return top.length === 0 && bottom.length === 0 ? EMPTY : { top, bottom };
+}
+
+/**
+ * Wraps a filtered-row-model factory so sticky (pinned) rows leave the flow the
+ * table sorts and pages: every page holds `pageSize` ordinary rows and the page
+ * count ignores the sticky ones, which `keepPinnedRows` still renders at the
+ * top / bottom of every page. Sticky rows are also exempt from search and
+ * filters — an "average" row describes the whole table, not the matches.
+ */
+export function withoutStickyRows<TData>(
+  factory: (table: Table<TData>) => () => RowModel<TData>,
+): (table: Table<TData>) => () => RowModel<TData> {
+  return (table) => {
+    const compute = factory(table);
+    let lastModel: RowModel<TData> | undefined;
+    let lastPinning: RowPinningState | undefined;
+    let lastResult: RowModel<TData> | undefined;
+    return () => {
+      const model = compute();
+      const pinning = table.getState().rowPinning;
+      if (model === lastModel && pinning === lastPinning && lastResult) return lastResult;
+      lastModel = model;
+      lastPinning = pinning;
+      const sticky = new Set([...(pinning?.top ?? []), ...(pinning?.bottom ?? [])]);
+      if (sticky.size === 0) {
+        lastResult = model;
+        return model;
+      }
+      const rows = model.rows.filter((row) => !sticky.has(row.id));
+      const flatRows = model.flatRows.filter((row) => !sticky.has(row.id));
+      const rowsById = Object.fromEntries(flatRows.map((row) => [row.id, row]));
+      lastResult = { rows, flatRows, rowsById };
+      return lastResult;
+    };
+  };
+}

package/src/data-table/use-table-breakpoint.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { DATA_TABLE_BREAKPOINT_THRESHOLDS, tableBreakpointForWidth } from "./use-table-breakpoint";
+
+describe("tableBreakpointForWidth", () => {
+  it("is narrow below 450 px; the boundary and unmeasured widths are wide", () => {
+    expect(DATA_TABLE_BREAKPOINT_THRESHOLDS.narrow).toBe(450);
+    expect(tableBreakpointForWidth(348)).toBe("narrow");
+    expect(tableBreakpointForWidth(449.5)).toBe("narrow");
+    expect(tableBreakpointForWidth(450)).toBe("wide");
+    expect(tableBreakpointForWidth(640)).toBe("wide");
+    expect(tableBreakpointForWidth(0)).toBe("wide");
+    expect(tableBreakpointForWidth(Number.NaN)).toBe("wide");
+  });
+});

package/src/data-table/use-table-breakpoint.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * use-table-breakpoint.ts — `DataTable`'s own container-measured breakpoint.
+ *
+ * A DELIBERATE COPY of `charts`' `useMeasuredChartBreakpoint`
+ * (`packages/charts/src/charts/chart-breakpoint.ts`, ADR 0039): `data` may not
+ * import `charts` (one-way dependency graph), and a table's threshold is its
+ * own. Keep the two in step when either changes; `.claude/rules/data.md`
+ * carries the same table.
+ *
+ * | Helper                      | Package | Tiers                     | Thresholds (container px) |
+ * | --------------------------- | ------- | ------------------------- | ------------------------- |
+ * | `useMeasuredChartBreakpoint` | charts | narrow / medium / wide    | narrow < 480, medium < 768 |
+ * | `useTableBreakpoint`         | data   | narrow / wide             | narrow < 450              |
+ *
+ * Measured on the table's OWN width, never the viewport. A width of `0` (not
+ * measured yet: server render, first pass, `display: none`) is `wide`, so a
+ * first paint matches the pre-breakpoint table. A boundary belongs to the
+ * wider tier (450 → wide).
+ */
+
+import { useCallback, useLayoutEffect, useState } from "react";
+
+/** A table container's width tier. */
+export type DataTableBreakpoint = "narrow" | "wide";
+
+/** A width (CSS px) below `narrow` is narrow. */
+export const DATA_TABLE_BREAKPOINT_THRESHOLDS = { narrow: 450 } as const;
+
+/** The tier for a measured container width. */
+export function tableBreakpointForWidth(width: number): DataTableBreakpoint {
+  if (!Number.isFinite(width) || width <= 0) return "wide";
+  return width < DATA_TABLE_BREAKPOINT_THRESHOLDS.narrow ? "narrow" : "wide";
+}
+
+/**
+ * Measures the element the returned `ref` is attached to with a
+ * `ResizeObserver` and returns its tier. Re-renders only when the TIER changes.
+ * `enabled: false` skips the observer entirely (a table that uses no
+ * breakpoint behaviour pays nothing).
+ */
+export function useTableBreakpoint<E extends Element = HTMLDivElement>(
+  enabled = true,
+): { ref: (node: E | null) => void; breakpoint: DataTableBreakpoint } {
+  const [node, setNode] = useState<E | null>(null);
+  const [breakpoint, setBreakpoint] = useState<DataTableBreakpoint>("wide");
+  const ref = useCallback((next: E | null) => setNode(next), []);
+
+  useLayoutEffect(() => {
+    if (!enabled || !node) return undefined;
+    const update = (width: number) => {
+      const next = tableBreakpointForWidth(width);
+      setBreakpoint((prev) => (prev === next ? prev : next));
+    };
+    update(node.getBoundingClientRect().width);
+    if (typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (entry) update(entry.contentRect.width);
+    });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [enabled, node]);
+
+  return { ref, breakpoint: enabled ? breakpoint : "wide" };
+}

package/src/filter-bar/filter-chip.stories.tsx

@@ -137,6 +137,7 @@ export const LongLabelWithCount: Story = {
 };
 
 export const WithCountHighDecoration: Story = {
+  tags: ["!dev"],
   name: "With count — high decoration",
   globals: { decoration: "10" },
   args: { count: 1204, countLabel: "excluded" },

package/src/index.ts

@@ -25,3 +25,67 @@ export type {
 
 // CSV helpers — pure, dependency-free serializer + browser download trigger.
 export * from "./to-csv";
+
+// DataTable presentation layer — RM-123: typed column meta (visuals, format,
+// colorBy, showAt, sizing, markdown), the in-cell visuals, the shared cell
+// scales, the table breakpoint, card layout, sticky rows and ranks.
+export {
+  columnSizeStyle,
+  formatCellValue,
+  resolveShowAt,
+  type DataTableBarVisual,
+  type DataTableCellVisual,
+  type DataTableColorBy,
+  type DataTableColumnsVisual,
+  type DataTableHeatmapScale,
+  type DataTableHeatmapVisual,
+  type DataTableMarkdownOptions,
+  type DataTableShowAt,
+  type DataTableSparklineVisual,
+  type DataTableValueFormatSpec,
+} from "./data-table/column-meta";
+export {
+  barDomain,
+  barGeometry,
+  computeColumnScales,
+  extentOf,
+  heatmapColorScaleSpec,
+  seriesValues,
+  type DataTableColumnScale,
+  type NumericExtent,
+} from "./data-table/cell-scales";
+export {
+  DATA_TABLE_BREAKPOINT_THRESHOLDS,
+  tableBreakpointForWidth,
+  useTableBreakpoint,
+  type DataTableBreakpoint,
+} from "./data-table/use-table-breakpoint";
+export {
+  stickyRowPinning,
+  type DataTableStickyRowPosition,
+  type DataTableStickyRows,
+} from "./data-table/sticky-rows";
+export { DataTableRankCell, DataTableRankHeader, computeRowRanks } from "./data-table/ranks-column";
+export {
+  DataTableCard,
+  DataTableCardList,
+  type DataTableCardField,
+  type DataTableCardProps,
+} from "./data-table/card-layout";
+export { BarCell, type BarCellProps } from "./data-table/cells/bar-cell";
+export { CategoryLegend, type CategoryLegendProps } from "./data-table/cells/category-legend";
+export { SparklineCell, type SparklineCellProps } from "./data-table/cells/sparkline-cell";
+export { ColumnsCell, type ColumnsCellProps } from "./data-table/cells/columns-cell";
+export {
+  HeatmapCell,
+  HeatmapLegend,
+  heatmapCellStyle,
+  type HeatmapCellProps,
+  type HeatmapLegendProps,
+} from "./data-table/cells/heatmap-cell";
+export {
+  MarkdownCell,
+  isSafeCellUrl,
+  parseCellMarkdown,
+  type MarkdownCellProps,
+} from "./data-table/cells/markdown-cell";

package/src/templates-data-app.stories.tsx

@@ -9,8 +9,10 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
 import {
   Badge,
+  NavUser,
   Sidebar,
   SidebarContent,
+  SidebarFooter,
   SidebarGroup,
   SidebarGroupContent,
   SidebarHeader,
@@ -108,9 +110,12 @@ function DataAppTemplate({ loading = false }: { loading?: boolean }) {
             </SidebarGroupContent>
           </SidebarGroup>
         </SidebarContent>
+        <SidebarFooter>
+          <NavUser user={{ name: "Avery Rao", email: "avery@example.com" }} />
+        </SidebarFooter>
       </Sidebar>
       <SidebarInset>
-        <header className="flex h-14 items-center gap-2 border-b px-4">
+        <header className="flex h-header items-center gap-2 border-b px-4">
           <SidebarTrigger />
           <h1 className="text-body font-medium capitalize">{active}</h1>
         </header>
@@ -146,7 +151,7 @@ function DataAppTemplate({ loading = false }: { loading?: boolean }) {
 }
 
 const meta = {
-  title: "Patterns/Templates/Data App",
+  title: "Patterns/Templates/Starters/Data App",
   parameters: { layout: "fullscreen" },
   tags: ["autodocs"],
 } satisfies Meta;