@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/desk/DataTable.tsx

@@ -0,0 +1,373 @@
+"use client";
+
+import { useMemo, useState, type KeyboardEvent, type ReactNode } from "react";
+import { cn } from "../../lib/utils";
+
+/** How a desk column behaves when the table is narrower than its rows.
+ *  `key` is the row label, pinned left while the rest scrolls.
+ *  `num` is a number or a date: never wrapped, right-aligned, tabular figures.
+ *  `text` is prose: the column that gives up width and wraps on word breaks. */
+export type ColumnRole = "key" | "num" | "text";
+
+const EMPTY_CELL = new Set(["", "—", "–", "-", "n/a", "N/A"]);
+const NUMBER_CELL = /^[+\-−]?[$€£¥]?\d[\d,]*(\.\d+)?\s?(%|bp|bps|x|k|m|bn|[A-Z]{3})?$/i;
+const DATE_CELL = /^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}(:\d{2})?Z?)?$/;
+
+const isNumeric = (cell: string): boolean => NUMBER_CELL.test(cell) || DATE_CELL.test(cell);
+
+/** One role per column. A column is `num` only when every filled cell reads as
+ *  a number or a date; the first column of a multi-column table is the row label. */
+export function columnRoles(columns: string[], rows: string[][]): ColumnRole[] {
+  const width = Math.max(columns.length, ...rows.map((row) => row.length), 0);
+  const roles: ColumnRole[] = [];
+  for (let col = 0; col < width; col += 1) {
+    if (col === 0 && width > 1) {
+      roles.push("key");
+      continue;
+    }
+    const filled = rows
+      .map((row) => (row[col] ?? "").trim())
+      .filter((cell) => !EMPTY_CELL.has(cell));
+    roles.push(filled.length > 0 && filled.every(isNumeric) ? "num" : "text");
+  }
+  return roles;
+}
+
+export type DataTableTone = "pos" | "neg";
+export type DataTableRowVariant = "grp" | "total" | "sel";
+type Direction = "asc" | "desc";
+
+export type DataTableColumn<Row> = {
+  key: string;
+  label: string;
+  /** Desk column role. `role="num"` and `num: true` are the same thing. */
+  role?: ColumnRole;
+  /** Numeric column — right-aligned, tabular figures. Shorthand for `role="num"`. */
+  num?: boolean;
+  /** Long text: wraps within the column and clamps instead of widening the table. */
+  wrap?: boolean;
+  /** Inline weight bar under the figure, 0–100. */
+  bar?: (row: Row) => number | null;
+  cell: (row: Row) => ReactNode;
+  /** Money semantics for this cell — `--up` / `--down`, never a livery. */
+  tone?: (row: Row) => DataTableTone | undefined;
+  /** Sortable column. `true` sorts by the cell text/number; a function gives
+   *  the sort value (null sorts last). */
+  sort?: boolean | ((row: Row) => string | number | null | undefined);
+  /** Plain text for the filter box; defaults to the sort value or a string/number cell. */
+  text?: (row: Row) => string;
+};
+
+export type DataTableProps<Row> = {
+  rows: Row[];
+  cols: DataTableColumn<Row>[];
+  rowKey: (row: Row, index: number) => string;
+  variant?: (row: Row) => DataTableRowVariant | undefined;
+  /** Shown when there are no rows at all. */
+  empty?: string;
+  /** Shown when a filter matches nothing. */
+  noMatch?: string;
+  /** Show a text filter box (matches any column's text). */
+  filter?: boolean;
+  /** Accessible name for the scroll region and the filter box. */
+  label?: string;
+  /** Row click / Enter / Space. Rows become keyboard-focusable. */
+  onRowClick?: (row: Row, index: number) => void;
+  /** Pin the first column while scrolling horizontally. */
+  stickyFirst?: boolean;
+  /** Rows per page; omit for no pagination. */
+  pageSize?: number;
+  className?: string;
+};
+
+const roleOf = <Row,>(column: DataTableColumn<Row>): ColumnRole =>
+  column.role ?? (column.num ? "num" : "text");
+
+const primitive = (value: ReactNode): string | number | null =>
+  typeof value === "string" || typeof value === "number" ? value : null;
+
+const sortValue = <Row,>(column: DataTableColumn<Row>, row: Row): string | number | null => {
+  const value = typeof column.sort === "function" ? column.sort(row) : primitive(column.cell(row));
+  return typeof value === "number" && !Number.isFinite(value) ? null : (value ?? null);
+};
+
+/** Nulls sort last in both directions, so a missing figure never heads the table. */
+const compare = (a: string | number | null, b: string | number | null, dir: Direction): number => {
+  if (a == null || b == null) return a == null ? (b == null ? 0 : 1) : -1;
+  const delta =
+    typeof a === "number" && typeof b === "number"
+      ? a - b
+      : String(a).localeCompare(String(b), undefined, { numeric: true });
+  return dir === "asc" ? delta : -delta;
+};
+
+/** A `<button>` does not inherit the page face, so the header voice is restated. */
+const SORT_BUTTON =
+  "inline-flex w-full cursor-pointer items-center gap-1 bg-transparent p-0 text-left " +
+  "font-mono text-[0.64rem] tracking-[0.08em] hover:text-ink " +
+  "focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-accent";
+
+const CONTROL =
+  "cursor-pointer border border-hair px-2 py-0.5 font-mono text-[0.72rem] text-ink " +
+  "disabled:cursor-not-allowed disabled:text-ink-mute " +
+  "focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-accent";
+
+/**
+ * DataTable — hairline rows, mono right-aligned figures, sticky header.
+ * Every extra is opt-in: sortable columns, text filter, row click, sticky first
+ * column, pagination. With none of them it renders the bare table.
+ *
+ * The sort is a real button per header (keyboard-native) and reports `aria-sort`
+ * on its `<th>`; `tone` wears the money colours; `variant` marks group and total
+ * rows, which stay pinned below the sorted body.
+ */
+export function DataTable<Row>({
+  rows,
+  cols,
+  rowKey,
+  variant,
+  empty = "no rows",
+  noMatch = "no match",
+  filter,
+  label,
+  onRowClick,
+  stickyFirst,
+  pageSize,
+  className,
+}: DataTableProps<Row>) {
+  const [query, setQuery] = useState("");
+  const [sort, setSort] = useState<{ key: string; dir: Direction } | null>(null);
+  const [page, setPage] = useState(0);
+  const safe = Array.isArray(rows) ? rows : [];
+
+  const view = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    let out = safe.map((row, index) => ({ row, index }));
+    if (needle) {
+      out = out.filter(({ row }) =>
+        cols.some((column) => {
+          const text = column.text ? column.text(row) : sortValue(column, row);
+          return text != null && String(text).toLowerCase().includes(needle);
+        }),
+      );
+    }
+    const column = sort && cols.find((c) => c.key === sort.key);
+    if (column && sort) {
+      // Total rows stay pinned at the end; everything else sorts.
+      const tail = out.filter(({ row }) => variant?.(row) === "total");
+      const body = out.filter(({ row }) => variant?.(row) !== "total");
+      body.sort(
+        (a, b) =>
+          compare(sortValue(column, a.row), sortValue(column, b.row), sort.dir) ||
+          a.index - b.index,
+      );
+      out = [...body, ...tail];
+    }
+    return out;
+  }, [safe, cols, query, sort, variant]);
+
+  if (!safe.length) return <p className="py-2 font-mono text-[0.72rem] text-ink-mute">{empty}</p>;
+
+  const pages = pageSize ? Math.max(1, Math.ceil(view.length / pageSize)) : 1;
+  const current = Math.min(page, pages - 1);
+  const shown = pageSize ? view.slice(current * pageSize, (current + 1) * pageSize) : view;
+
+  const toggle = (key: string) => {
+    setPage(0);
+    setSort((active) =>
+      !active || active.key !== key
+        ? { key, dir: "asc" }
+        : active.dir === "asc"
+          ? { key, dir: "desc" }
+          : null,
+    );
+  };
+
+  const onKey = (event: KeyboardEvent, row: Row, index: number) => {
+    if (event.target !== event.currentTarget) return;
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onRowClick?.(row, index);
+    }
+  };
+
+  const table = (
+    <div
+      // A horizontally-scrolling region has no keyboard route on its own: without
+      // a tab stop a keyboard user cannot arrow-scroll the clipped columns.
+      tabIndex={0}
+      role="region"
+      aria-label={label ? `${label} table` : "Table, scrollable horizontally"}
+      className={cn(
+        "overflow-x-auto rounded-none border border-hair bg-surface text-ink",
+        "focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-accent",
+        className,
+      )}
+    >
+      <table className="w-full border-collapse text-[0.8125rem]">
+        <thead>
+          <tr>
+            {cols.map((column, position) => {
+              const role = roleOf(column);
+              const active = sort?.key === column.key ? sort.dir : null;
+              return (
+                <th
+                  key={column.key}
+                  scope="col"
+                  data-col={role}
+                  aria-sort={
+                    active
+                      ? active === "asc"
+                        ? "ascending"
+                        : "descending"
+                      : column.sort
+                        ? "none"
+                        : undefined
+                  }
+                  className={cn(
+                    "sticky top-0 z-[2] border-b border-hair-2 bg-surface px-3 py-2 align-bottom",
+                    "font-normal tracking-[0.08em] text-ink-mute uppercase text-[0.64rem]",
+                    role === "num" ? "text-right" : "text-left",
+                    stickyFirst && position === 0 && "left-0 z-[3]",
+                  )}
+                >
+                  {column.sort ? (
+                    <button
+                      type="button"
+                      className={cn(SORT_BUTTON, role === "num" && "justify-end")}
+                      onClick={() => toggle(column.key)}
+                    >
+                      {column.label}
+                      <span aria-hidden="true">
+                        {active === "asc" ? "▲" : active === "desc" ? "▼" : ""}
+                      </span>
+                    </button>
+                  ) : (
+                    column.label
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {shown.map(({ row, index }) => {
+            const state = variant?.(row);
+            return (
+              <tr
+                key={rowKey(row, index)}
+                className={cn(
+                  "border-b border-hair last:border-b-0",
+                  state === "total" && "border-t border-hair-2 font-semibold",
+                  state === "grp" && "text-[0.72rem] tracking-[0.08em] text-ink-mute uppercase",
+                  state === "sel" && "bg-surface-2",
+                  onRowClick &&
+                    "cursor-pointer hover:bg-surface-2 focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-2px] focus-visible:outline-accent",
+                )}
+                tabIndex={onRowClick ? 0 : undefined}
+                onClick={onRowClick ? () => onRowClick(row, index) : undefined}
+                onKeyDown={onRowClick ? (event) => onKey(event, row, index) : undefined}
+              >
+                {cols.map((column, position) => {
+                  const role = roleOf(column);
+                  const bar = column.bar?.(row);
+                  const filled = bar != null && Number.isFinite(bar);
+                  return (
+                    <td
+                      key={column.key}
+                      data-col={role}
+                      className={cn(
+                        "px-3 py-1.5 align-baseline",
+                        role === "num" &&
+                          "whitespace-nowrap text-right [font-variant-numeric:tabular-nums]",
+                        role === "key" && "text-ink",
+                        role === "text" && "text-ink-soft",
+                        column.wrap ? "max-w-[28rem]" : role === "text" && "whitespace-nowrap",
+                        column.tone?.(row) === "pos" && "text-up",
+                        column.tone?.(row) === "neg" && "text-down",
+                        stickyFirst && position === 0 && "sticky left-0 z-[1] bg-surface",
+                      )}
+                    >
+                      {column.wrap ? (
+                        <span className="line-clamp-3 break-words">{column.cell(row)}</span>
+                      ) : (
+                        column.cell(row)
+                      )}
+                      {filled ? (
+                        <span className="mt-1 block h-[2px] w-full bg-hair-2" aria-hidden="true">
+                          <i
+                            className="block h-full bg-accent"
+                            style={{ width: `${Math.max(0, Math.min(100, bar))}%` }}
+                          />
+                        </span>
+                      ) : null}
+                    </td>
+                  );
+                })}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+
+  if (!filter && !pageSize) return table;
+
+  return (
+    <div className="flex flex-col">
+      {filter ? (
+        <div className="flex items-center gap-3 pb-2">
+          <input
+            type="search"
+            value={query}
+            aria-label={label ? `Filter ${label}` : "Filter rows"}
+            placeholder="filter"
+            onChange={(event) => {
+              setQuery(event.target.value);
+              setPage(0);
+            }}
+            className={cn(
+              "min-w-[10rem] flex-1 rounded-none border border-hair bg-transparent px-2 py-1",
+              "font-mono text-[0.75rem] text-ink placeholder:text-ink-mute",
+              "focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-accent",
+            )}
+          />
+          <span aria-live="polite" className="font-mono text-[0.72rem] text-ink-mute">
+            {view.length}/{safe.length}
+          </span>
+        </div>
+      ) : null}
+      {view.length ? (
+        table
+      ) : (
+        <p className="py-2 font-mono text-[0.72rem] text-ink-mute">{noMatch}</p>
+      )}
+      {pageSize && pages > 1 ? (
+        <div className="flex items-center gap-3 border-t border-hair pt-2 font-mono text-[0.72rem]">
+          <button
+            type="button"
+            className={CONTROL}
+            disabled={current === 0}
+            aria-label="Previous page"
+            onClick={() => setPage(current - 1)}
+          >
+            ‹ prev
+          </button>
+          <span className="text-ink-soft">
+            {current + 1} / {pages}
+          </span>
+          <button
+            type="button"
+            className={CONTROL}
+            disabled={current >= pages - 1}
+            aria-label="Next page"
+            onClick={() => setPage(current + 1)}
+          >
+            next ›
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/desk/KpiGrid.tsx

@@ -0,0 +1,80 @@
+import { cn } from "../../lib/utils";
+
+export type KpiTone = "pos" | "neg";
+
+export type KpiCell = {
+  /** Visible cell label. */
+  label: string;
+  /** The figure as it should read. `null`, `undefined`, `""` and non-finite
+   *  numbers render the missing mark — never a zero the data did not contain. */
+  value: string | number | null | undefined;
+  /** Money semantics — `--up` / `--down`, signed P&L only. */
+  tone?: KpiTone;
+  /** Secondary line under the figure. */
+  note?: string;
+  /** Accessible name when the figure alone does not read as a value to a
+   *  screen reader (a glyph, a dash, a bare ratio). Defaults to the visible text. */
+  valueLabel?: string;
+};
+
+export type KpiGridProps = {
+  items: KpiCell[];
+  /** Mark shown in place of a figure the payload did not carry. */
+  missing?: string;
+  className?: string;
+};
+
+const read = (value: KpiCell["value"], missing: string): { text: string; absent: boolean } => {
+  if (value == null) return { text: missing, absent: true };
+  if (typeof value === "number") {
+    return Number.isFinite(value)
+      ? { text: String(value), absent: false }
+      : { text: missing, absent: true };
+  }
+  const text = value.trim();
+  return text ? { text, absent: false } : { text: missing, absent: true };
+};
+
+/**
+ * KpiGrid — a dense label / figure grid on hairlines, one `<dl>` so each figure
+ * is announced with its label. Figures are tabular, so a column of them lines up
+ * digit for digit. No motion, so reduced-motion needs no special case.
+ */
+export function KpiGrid({ items, missing = "—", className }: KpiGridProps) {
+  return (
+    <dl
+      className={cn(
+        "grid grid-cols-[repeat(auto-fit,minmax(8.5rem,1fr))] rounded-none border-t border-l border-hair",
+        className,
+      )}
+    >
+      {items.map((item) => {
+        const value = read(item.value, missing);
+        return (
+          <div key={item.label} className="border-r border-b border-hair px-3 py-2">
+            <dt className="font-mono text-[0.64rem] tracking-[0.08em] text-ink-mute uppercase">
+              {item.label}
+            </dt>
+            <dd
+              data-state={value.absent ? "missing" : "present"}
+              aria-label={item.valueLabel}
+              className={cn(
+                "mt-1 font-mono text-[1.15rem] leading-none [font-variant-numeric:tabular-nums]",
+                value.absent ? "text-ink-mute" : "text-ink",
+                item.tone === "pos" && !value.absent && "text-up",
+                item.tone === "neg" && !value.absent && "text-down",
+              )}
+            >
+              {value.text}
+              {item.note ? (
+                <span className="mt-1 block font-mono text-[0.68rem] text-ink-mute">
+                  {item.note}
+                </span>
+              ) : null}
+            </dd>
+          </div>
+        );
+      })}
+    </dl>
+  );
+}

package/src/components/desk/Sparkline.tsx

@@ -0,0 +1,63 @@
+export type SparklineProps = {
+  /** The series in reading order. Non-finite points are dropped, not zero-filled. */
+  values: (number | null | undefined)[];
+  height?: number;
+  /** Accessible name. Defaults to a summary derived from the points that are drawn. */
+  label?: string;
+  /** The figure is printed next to the line — hide the drawing from assistive tech. */
+  decorative?: boolean;
+  /** Shown when there are fewer than two finite points to draw. */
+  placeholder?: string;
+};
+
+/** Compact read of a plotted value: integers as-is, floats to four places with
+ *  trailing zeros stripped. Presentation only — no point is invented. */
+const read = (value: number): string =>
+  Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+
+export function Sparkline({
+  values: raw,
+  height = 56,
+  label,
+  decorative,
+  placeholder = "not enough points",
+}: SparklineProps) {
+  const values = (raw ?? []).filter(
+    (value): value is number => typeof value === "number" && Number.isFinite(value),
+  );
+  if (values.length < 2) {
+    return <p className="font-mono text-[0.72rem] text-ink-mute">{placeholder}</p>;
+  }
+
+  const low = Math.min(...values);
+  const high = Math.max(...values);
+  const span = high - low || 1;
+  const points = values
+    .map((value, index) => {
+      const x = (index / (values.length - 1)) * 100;
+      const y = 100 - ((value - low) / span) * 100;
+      return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+    .join(" ");
+  const summary = `sparkline, ${values.length} points, ${read(values[0])} to ${read(values[values.length - 1])}, low ${read(low)}, high ${read(high)}`;
+
+  return (
+    <svg
+      viewBox="0 0 100 100"
+      preserveAspectRatio="none"
+      role={decorative ? undefined : "img"}
+      aria-hidden={decorative || undefined}
+      aria-label={decorative ? undefined : (label ?? summary)}
+      style={{ height }}
+      className="block w-full overflow-visible text-accent"
+    >
+      <polyline
+        points={points}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.2"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}

package/src/components/desk/StateBlock.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { Component, type ReactNode } from "react";
+import { cn } from "../../lib/utils";
+import { Spinner } from "../Spinner";
+
+export type StateKind = "empty" | "loading" | "error" | "withheld";
+
+export type StateBlockProps = {
+  kind: StateKind;
+  /** One line naming the state; defaults per kind. */
+  title?: string;
+  /** Why the state is showing — the route, the failure, the missing input.
+   *  A withheld block without a reason is an unexplained blank. */
+  reason?: string;
+  /** Optional retry, rendered as a real button. Omit when the state is terminal. */
+  onRetry?: () => void;
+  retryLabel?: string;
+  className?: string;
+};
+
+const MARKER: Record<StateKind, string> = {
+  empty: "[empty]",
+  loading: "[loading]",
+  error: "[!]",
+  withheld: "[withheld]",
+};
+
+const TITLE: Record<StateKind, string> = {
+  empty: "Nothing here yet.",
+  loading: "Loading.",
+  error: "Could not load.",
+  withheld: "Withheld.",
+};
+
+/**
+ * StateBlock — one layout for the four states a data surface can be in.
+ *
+ * Loading is announced (`role="status"`, `aria-busy`) and its spinner stops under
+ * reduced motion. An error is announced (`role="alert"`) and carries a `[!]`
+ * marker, so its meaning survives someone who cannot see the danger colour.
+ * Withheld is a refusal, not a failure: it says why the figure is not shown.
+ */
+export function StateBlock({
+  kind,
+  title,
+  reason,
+  onRetry,
+  retryLabel = "retry",
+  className,
+}: StateBlockProps) {
+  const role =
+    kind === "error"
+      ? "alert"
+      : kind === "loading"
+        ? "status"
+        : kind === "withheld"
+          ? "note"
+          : undefined;
+  return (
+    <div
+      data-state={kind}
+      role={role}
+      aria-busy={kind === "loading" || undefined}
+      className={cn(
+        "rounded-none border border-hair bg-surface px-3 py-3",
+        kind === "error" && "border-l-danger",
+        kind === "withheld" && "bg-surface-2",
+        className,
+      )}
+    >
+      <p className="flex items-baseline gap-2 font-mono text-[0.72rem]">
+        {kind === "loading" ? <Spinner className="text-ink-mute" /> : null}
+        <span
+          aria-hidden="true"
+          className={cn(
+            "shrink-0 tracking-[0.06em]",
+            kind === "error" ? "text-danger" : kind === "withheld" ? "text-ink" : "text-ink-mute",
+          )}
+        >
+          {MARKER[kind]}
+        </span>
+        <span className={cn("text-[0.8125rem]", kind === "error" ? "text-danger" : "text-ink")}>
+          {title ?? TITLE[kind]}
+        </span>
+      </p>
+      {reason ? (
+        <p className="mt-1 font-mono text-[0.72rem] leading-relaxed text-ink-soft">{reason}</p>
+      ) : null}
+      {onRetry ? (
+        <button
+          type="button"
+          onClick={onRetry}
+          className={cn(
+            "mt-2 cursor-pointer rounded-none border border-hair px-2 py-1 font-mono text-[0.72rem] text-ink",
+            "hover:border-hair-2 focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-accent",
+          )}
+        >
+          {retryLabel}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export type BlockBoundaryProps = {
+  /** Names the source in the withheld reason — usually the API route. */
+  label?: string;
+  children: ReactNode;
+};
+
+type BoundaryState = { error: string | null };
+
+/**
+ * BlockBoundary — one block throwing on an odd payload must not take the page
+ * down. It is replaced by a withheld state that names the source and the fault.
+ * Remount it (`key`) when the payload changes to retry the block.
+ */
+export class BlockBoundary extends Component<BlockBoundaryProps, BoundaryState> {
+  state: BoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: unknown): BoundaryState {
+    return { error: error instanceof Error ? error.message : "render failed" };
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    const source = this.props.label ? `${this.props.label}: ` : "";
+    return <StateBlock kind="withheld" reason={`${source}unexpected response shape (${error})`} />;
+  }
+}

package/src/components/desk/index.ts

@@ -0,0 +1,18 @@
+export {
+  DataTable,
+  columnRoles,
+  type ColumnRole,
+  type DataTableColumn,
+  type DataTableProps,
+  type DataTableRowVariant,
+  type DataTableTone,
+} from "./DataTable";
+export { KpiGrid, type KpiCell, type KpiGridProps, type KpiTone } from "./KpiGrid";
+export { Sparkline, type SparklineProps } from "./Sparkline";
+export {
+  BlockBoundary,
+  StateBlock,
+  type BlockBoundaryProps,
+  type StateBlockProps,
+  type StateKind,
+} from "./StateBlock";