@eifi1/ui-kit 0.4.1 → 0.5.0

package/src/components/data-table-filters.ts

@@ -0,0 +1,176 @@
+import type { DataTableColumn } from "./data-table";
+
+/** How a column is filtered. `text`/`select`/`date`/`number` each read a value
+ *  off the row and compare it against the user's {@link FilterValue}. */
+export type ColumnFilter<T> =
+  | { type: "text"; getValue: (row: T) => string }
+  | { type: "select"; getValue: (row: T) => string; options?: { value: string; label?: string }[] }
+  | { type: "date"; getValue: (row: T) => string | null | undefined }
+  | { type: "number"; getValue: (row: T) => number | null | undefined };
+
+/** The current state of a column's filter (what the user has entered). */
+export type FilterValue =
+  | { type: "text"; q: string }
+  | { type: "select"; values: string[] }
+  | { type: "date"; from: string; to: string }
+  | { type: "number"; min: string; max: string; abs: boolean };
+
+/** A column's filter config, falling back to a plain text filter over `filterBy`. */
+export function resolveFilter<T>(col: DataTableColumn<T>): ColumnFilter<T> | null {
+  if (col.filter) return col.filter;
+  if (col.filterBy) return { type: "text", getValue: col.filterBy };
+  return null;
+}
+
+/** Whether a filter value is actually narrowing anything (vs its empty default). */
+export function isFilterActive(v: FilterValue | undefined): boolean {
+  if (!v) return false;
+  switch (v.type) {
+    case "text":
+      return v.q.trim().length > 0;
+    case "select":
+      return v.values.length > 0;
+    case "date":
+      return !!v.from || !!v.to;
+    case "number":
+      return v.min !== "" || v.max !== "" || v.abs;
+  }
+}
+
+/**
+ * Whether `row` passes column `col`'s filter given the user's `state`.
+ *
+ * `locale` is for the text filter's case folding. Plain `toLowerCase` folds by the
+ * root rules, under which a Turkish user typing "istanbul" does not find "İSTANBUL";
+ * `toLocaleLowerCase(locale)` does. Optional, and `undefined` is the runtime's default.
+ */
+export function rowMatches<T>(
+  col: DataTableColumn<T>,
+  row: T,
+  state: FilterValue,
+  locale?: string,
+): boolean {
+  const filter = resolveFilter(col);
+  if (!filter) return true;
+  switch (filter.type) {
+    case "text": {
+      if (state.type !== "text" || !state.q.trim()) return true;
+      return filter
+        .getValue(row)
+        .toLocaleLowerCase(locale)
+        .includes(state.q.trim().toLocaleLowerCase(locale));
+    }
+    case "select": {
+      if (state.type !== "select" || state.values.length === 0) return true;
+      return state.values.includes(filter.getValue(row));
+    }
+    case "date": {
+      if (state.type !== "date") return true;
+      const raw = filter.getValue(row);
+      if (!raw) return !state.from && !state.to;
+      const v = raw.slice(0, 10);
+      if (state.from && v < state.from) return false;
+      if (state.to && v > state.to) return false;
+      return true;
+    }
+    case "number": {
+      if (state.type !== "number") return true;
+      const raw = filter.getValue(row);
+      if (raw == null || Number.isNaN(raw)) return !state.min && !state.max;
+      const x = state.abs ? Math.abs(raw) : raw;
+      if (state.min !== "" && x < Number(state.min)) return false;
+      if (state.max !== "" && x > Number(state.max)) return false;
+      return true;
+    }
+  }
+}
+
+/** The empty filter state for a column's filter type. */
+export function defaultFilterState<T>(filter: ColumnFilter<T>): FilterValue {
+  switch (filter.type) {
+    case "text":
+      return { type: "text", q: "" };
+    case "select":
+      return { type: "select", values: [] };
+    case "date":
+      return { type: "date", from: "", to: "" };
+    case "number":
+      return { type: "number", min: "", max: "", abs: false };
+  }
+}
+
+/**
+ * Escape the ONE character the select codec uses as its separator, plus the escape
+ * marker itself so the transform is reversible.
+ *
+ * A minimal escape rather than `encodeURIComponent`, deliberately: these strings sit
+ * inside a query-parameter value that `URLSearchParams` already encodes, so a full
+ * percent-encode would double-encode every space into `%2520` and make shared links
+ * unreadable for no gain. Only `,` can be misread here.
+ *
+ * Backwards compatible with every link written before this existed: a value with
+ * neither `,` nor `%` passes through both directions untouched, and `%` on its own
+ * never matched `%25` either.
+ */
+function escapeSelectValue(v: string): string {
+  return v.replace(/%/g, "%25").replace(/,/g, "%2C");
+}
+
+/** Inverse of {@link escapeSelectValue}. The order matters and is the reverse of the
+ *  escape: undoing `%2C` first cannot see the `2C` inside an escaped `%252C`. */
+function unescapeSelectValue(v: string): string {
+  return v.replace(/%2C/g, ",").replace(/%25/g, "%");
+}
+
+/** URL-safe encoding of a filter value (`f.<column>` param), null when empty. */
+export function encodeFilterValue(v: FilterValue): string | null {
+  switch (v.type) {
+    case "text":
+      return v.q.trim() ? v.q : null;
+    case "select":
+      // Escaped before joining: an option value may legitimately contain the
+      // separator (a free-text title, a payee or category name), and without this it
+      // came back as two values and the filter silently matched nothing.
+      return v.values.length ? v.values.map(escapeSelectValue).join(",") : null;
+    case "date":
+      return v.from || v.to ? `${v.from}..${v.to}` : null;
+    case "number": {
+      const hasRange = v.min !== "" || v.max !== "";
+      if (!hasRange && !v.abs) return null;
+      return `${v.min}..${v.max}${v.abs ? "!" : ""}`;
+    }
+  }
+}
+
+/** Inverse of {@link encodeFilterValue} given just the filter type — for
+ *  callers that know a column's type without holding its full config. */
+export function decodeFilterValueOfType(type: FilterValue["type"], raw: string): FilterValue {
+  switch (type) {
+    case "text":
+      return { type: "text", q: raw };
+    case "select":
+      return {
+        type: "select",
+        values: raw
+          .split(",")
+          .filter((v) => v.length > 0)
+          .map(unescapeSelectValue),
+      };
+    case "date": {
+      const [from = "", to = ""] = raw.split("..");
+      return { type: "date", from, to };
+    }
+    case "number": {
+      let body = raw;
+      const abs = body.endsWith("!");
+      if (abs) body = body.slice(0, -1);
+      const [min = "", max = ""] = body.split("..");
+      return { type: "number", min, max, abs };
+    }
+  }
+}
+
+/** Inverse of {@link encodeFilterValue}, typed by the column's filter config. */
+export function decodeFilterValue<T>(filter: ColumnFilter<T>, raw: string): FilterValue {
+  return decodeFilterValueOfType(filter.type, raw);
+}

package/src/components/data-table-labels.ts

@@ -0,0 +1,190 @@
+// All user-facing strings for the DataTable system — the `dataTable` namespace of
+// `<UiKitProvider labels>`, and per table the `labels` prop over that. The package
+// ships no translations; the English defaults below make the table usable with no
+// wiring.
+
+export interface DataTableLabels {
+  // Table chrome
+  columns: string;
+  selectAllRows: string;
+  sortHint: string;
+  filter: string;
+  close: string;
+  selectRow: string;
+  autoSize: string;
+  loading: string;
+  filters: string;
+  clearAll: string;
+  done: string;
+  // Pagination
+  pageSize: string;
+  pageSizeAll: string;
+  prevPage: string;
+  nextPage: string;
+  // Filter popover
+  clearFilter: string;
+  filterPlaceholder: string;
+  selectFilter: string;
+  selectAll: string;
+  selectNone: string;
+  dateFrom: string;
+  dateTo: string;
+  numberMin: string;
+  numberMax: string;
+  numberAbs: string;
+  // Date-range preset labels, keyed by preset key (see dateRangePresets()).
+  presets: Record<string, string>;
+
+  /**
+   * The table's own accessible name. Deliberately a label rather than a second,
+   * parallel `tableLabel` prop: the audit already records "three different prop
+   * names for the accessible name" as a finding, and a table that is not "Data
+   * table" says so with `labels={{ table: "Transactions" }}` at the call site.
+   */
+  table: string;
+
+  // ---- Announcements ----
+  // Spoken through the live region, never rendered. Each takes its numbers as
+  // ARGUMENTS: a count glued into an English template literal is untranslatable,
+  // and the grammar around it moves with the number in most languages.
+
+  /** After a filter changes: "12 of 137 rows". */
+  filterResults: (shown: number, total: number) => string;
+  /** After a header is activated: "Sorted by Name, ascending". */
+  sortedAscending: (column: string) => string;
+  sortedDescending: (column: string) => string;
+  /** The third click, which removes the column from the sort entirely. */
+  sortCleared: (column: string) => string;
+  /** After paging: "Page 3 of 14". `page` is 1-BASED, as spoken. */
+  pageChanged: (page: number, totalPages: number) => string;
+
+  // ---- Counted chrome ----
+  // Visible text that interpolates numbers. These were template literals until the
+  // audit flagged them: a consumer could translate every key in this file and still
+  // be left with English (and with ASCII digit grouping) in the footer.
+
+  /** The pagination range summary: "1–25 / 137". */
+  pageRange: (from: number, to: number, total: number) => string;
+  /** The same summary when the page size is "all" — just the row count. */
+  rowCount: (total: number) => string;
+  /** The column-settings rail and its heading: "Columns (4/9)". */
+  columnsCount: (visible: number, total: number) => string;
+}
+
+export const DEFAULT_DATA_TABLE_LABELS: DataTableLabels = {
+  columns: "Columns",
+  selectAllRows: "Select all rows",
+  sortHint: "Click to sort · Shift-click to add a sort",
+  filter: "Filter",
+  close: "Close",
+  selectRow: "Select row",
+  autoSize: "Auto-size columns",
+  loading: "Loading…",
+  filters: "Filters",
+  clearAll: "Clear all",
+  done: "Done",
+  pageSize: "Rows per page",
+  pageSizeAll: "All",
+  prevPage: "Previous page",
+  nextPage: "Next page",
+  clearFilter: "Clear filter",
+  filterPlaceholder: "Filter…",
+  selectFilter: "Select",
+  selectAll: "All",
+  selectNone: "None",
+  dateFrom: "From",
+  dateTo: "To",
+  numberMin: "Min",
+  numberMax: "Max",
+  numberAbs: "Absolute value",
+  presets: {
+    today: "Today",
+    yesterday: "Yesterday",
+    this_week: "This week",
+    last_week: "Last week",
+    last_7_days: "Last 7 days",
+    last_30_days: "Last 30 days",
+    this_month: "This month",
+    last_month: "Last month",
+    last_3_months: "Last 3 months",
+    ytd: "Year to date",
+    last_year: "Last year",
+  },
+  table: "Data table",
+  filterResults: (shown, total) => `${shown} of ${total} rows`,
+  sortedAscending: (column) => `Sorted by ${column}, ascending`,
+  sortedDescending: (column) => `Sorted by ${column}, descending`,
+  sortCleared: (column) => `Sort cleared on ${column}`,
+  pageChanged: (page, totalPages) => `Page ${page} of ${totalPages}`,
+  // The separators are the ones that shipped, so adding the seam changes no screen.
+  pageRange: (from, to, total) => `${from}–${to} / ${total}`,
+  rowCount: (total) => `${total}`,
+  columnsCount: (visible, total) => `Columns (${visible}/${total})`,
+};
+
+/**
+ * Merge caller overrides onto the English defaults (presets merged too).
+ *
+ * The parameter is `Partial` on purpose — a table with no labels at all still
+ * renders — but that is also how a translated app ends up half English and never
+ * hears about it: lenkbank ships nineteen of these keys in English in a German UI
+ * today, because every one of them is backfilled silently. The kit will not start
+ * throwing over it (three apps depend on the lenient merge), so
+ * {@link missingDataTableLabels} is the other half: it answers which keys fell back,
+ * and an app asserts on that in its OWN test, where the answer is actionable.
+ */
+export function resolveDataTableLabels(partial?: Partial<DataTableLabels>): DataTableLabels {
+  if (!partial) return DEFAULT_DATA_TABLE_LABELS;
+  const merged: DataTableLabels = {
+    ...DEFAULT_DATA_TABLE_LABELS,
+    ...partial,
+    presets: { ...DEFAULT_DATA_TABLE_LABELS.presets, ...(partial.presets ?? {}) },
+  };
+  // `columnsCount` was split out of `columns` + a template literal. Consumers have
+  // been translating `columns` since 0.1, and backfilling the English default over
+  // that would hand them "Columns (4/9)" back for having translated the key that
+  // existed at the time — the same silent-English failure the audit records against
+  // this file. So the count is derived from the RESOLVED `columns` unless the caller
+  // states the whole sentence, which is the escape hatch for a language where the
+  // parenthetical does not fit.
+  if (partial.columns !== undefined && partial.columnsCount === undefined) {
+    merged.columnsCount = (visible, total) => `${merged.columns} (${visible}/${total})`;
+  }
+  return merged;
+}
+
+/**
+ * The label keys `labels` does not supply, and which therefore come back English
+ * from {@link resolveDataTableLabels}.
+ *
+ * For a consumer's own test:
+ *
+ * ```ts
+ * expect(missingDataTableLabels(de.dataTable)).toEqual([]);
+ * ```
+ *
+ * which fails the day the kit adds a key — which is the point. Adding a label is
+ * additive here and a silent regression in a translated app, and nothing else in
+ * either repository can tell the two apart.
+ *
+ * Preset labels are reported one at a time (`presets.yesterday`), because `presets`
+ * is a `Record` merged key by key: answering `"presets"` would say nothing about
+ * which of the eleven are still English.
+ */
+export function missingDataTableLabels(labels?: Partial<DataTableLabels>): string[] {
+  const missing: string[] = [];
+  for (const key of Object.keys(DEFAULT_DATA_TABLE_LABELS) as Array<keyof DataTableLabels>) {
+    if (key === "presets") continue;
+    if (labels?.[key] !== undefined) continue;
+    // `columnsCount` is DERIVED from a translated `columns` by the resolver above,
+    // so a caller who set that one is not leaking English here. Reporting it would
+    // send them to translate a key they have already covered, and an `toEqual([])`
+    // assertion built on this would never go green.
+    if (key === "columnsCount" && labels?.columns !== undefined) continue;
+    missing.push(key);
+  }
+  for (const preset of Object.keys(DEFAULT_DATA_TABLE_LABELS.presets)) {
+    if (labels?.presets?.[preset] === undefined) missing.push(`presets.${preset}`);
+  }
+  return missing;
+}

package/src/components/data-table-pagination.tsx

@@ -0,0 +1,126 @@
+import { useMemo } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { cn } from "../lib/cn";
+import { DEFAULT_DATA_TABLE_LABELS, type DataTableLabels } from "./data-table-labels";
+import { useKitLocale } from "../i18n/kit-labels";
+
+export const PAGE_SIZE_OPTIONS = [10, 25, 50, 100, 200] as const;
+
+interface PaginationProps {
+  page: number;
+  totalPages: number;
+  pageSize: number;
+  total: number;
+  onPage: (p: number) => void;
+  onPageSize: (n: number) => void;
+  labels?: DataTableLabels;
+  /** For the page numbers and page-size options; falls back to the provider's. */
+  locale?: string;
+}
+
+/** Footer for {@link DataTable}: range summary, page-size select, and a
+ *  windowed page-number strip (first/last + ±2 around the current page). */
+export function Pagination({
+  page,
+  totalPages,
+  pageSize,
+  total,
+  onPage,
+  onPageSize,
+  labels = DEFAULT_DATA_TABLE_LABELS,
+  locale: localeProp,
+}: PaginationProps) {
+  const locale = useKitLocale(localeProp);
+  // The bare numbers on the strip and in the select are text too: `String(n)` is
+  // always ASCII digits, which is wrong for a locale that writes its own. The range
+  // summary is not formatted here — `pageRange` / `rowCount` take NUMBERS so the
+  // translation can format them itself, alongside the words around them.
+  const num = useMemo(() => new Intl.NumberFormat(locale), [locale]);
+  const visible = useMemo(() => {
+    if (totalPages <= 7) return Array.from({ length: totalPages }, (_, i) => i);
+    const set = new Set<number>([0, totalPages - 1, page]);
+    for (let d = 1; d <= 2; d++) {
+      if (page - d >= 0) set.add(page - d);
+      if (page + d <= totalPages - 1) set.add(page + d);
+    }
+    return Array.from(set).sort((a, b) => a - b);
+  }, [page, totalPages]);
+
+  const items: (number | "ellipsis")[] = [];
+  visible.forEach((p, idx) => {
+    if (idx > 0 && p - visible[idx - 1] > 1) items.push("ellipsis");
+    items.push(p);
+  });
+
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-2 border-t border-[var(--border)] px-3 py-2 text-xs text-[var(--text-secondary)]">
+      <div className="flex items-center gap-2">
+        <span>
+          {pageSize === Infinity
+            ? labels.rowCount(total)
+            : labels.pageRange(page * pageSize + 1, Math.min(total, (page + 1) * pageSize), total)}
+        </span>
+        <select
+          value={pageSize === Infinity ? "all" : pageSize}
+          onChange={(e) => onPageSize(e.target.value === "all" ? Infinity : Number(e.target.value))}
+          className="rounded border border-[var(--border)] bg-[var(--bg-surface)] px-1 py-0.5 text-xs"
+          aria-label={labels.pageSize}
+        >
+          {PAGE_SIZE_OPTIONS.map((n) => (
+            <option key={n} value={n}>
+              {num.format(n)}
+            </option>
+          ))}
+          <option value="all">{labels.pageSizeAll}</option>
+        </select>
+      </div>
+      {pageSize !== Infinity && totalPages > 1 && (
+        <div className="flex items-center gap-1">
+          <button
+            type="button"
+            onClick={() => onPage(Math.max(0, page - 1))}
+            disabled={page === 0}
+            className="rounded p-1 hover:bg-[var(--bg-hover)] disabled:opacity-40"
+            aria-label={labels.prevPage}
+          >
+            <ChevronLeft className="size-4" />
+          </button>
+          {items.map((it, i) =>
+            it === "ellipsis" ? (
+              <span key={`e${i}`} className="px-1 text-[var(--text-placeholder)]">
+                …
+              </span>
+            ) : (
+              <button
+                key={it}
+                type="button"
+                onClick={() => onPage(it)}
+                // Which page you are on is carried only by a background colour
+                // otherwise, and the strip is a row of bare numbers with nothing
+                // else to tell them apart.
+                aria-current={it === page ? "page" : undefined}
+                className={cn(
+                  "min-w-7 rounded px-2 py-0.5",
+                  it === page
+                    ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
+                    : "hover:bg-[var(--bg-hover)]",
+                )}
+              >
+                {num.format(it + 1)}
+              </button>
+            ),
+          )}
+          <button
+            type="button"
+            onClick={() => onPage(Math.min(totalPages - 1, page + 1))}
+            disabled={page >= totalPages - 1}
+            className="rounded p-1 hover:bg-[var(--bg-hover)] disabled:opacity-40"
+            aria-label={labels.nextPage}
+          >
+            <ChevronRight className="size-4" />
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/data-table-sort.ts

@@ -0,0 +1,70 @@
+/** Multi-column sort state for DataTable: ordered by priority (index 0 is the
+ *  primary sort). Encoded as `sort=date.desc,amount` in URLs and the server's
+ *  transactions `sort` param — the pre-multi-sort single-value format
+ *  (`sort=date.desc`) decodes as a one-element list. */
+
+export type SortDir = "asc" | "desc";
+export interface SortState {
+  key: string;
+  dir: SortDir;
+}
+
+/** Coerce any persisted/URL-derived shape into a `SortState[]`. The
+ *  pre-multi-sort localStorage format stored one `{key, dir}` object (or
+ *  null); arrays pass through with junk entries dropped. */
+export function normalizeSorts(raw: unknown): SortState[] {
+  const one = (v: unknown): SortState | null => {
+    if (!v || typeof v !== "object") return null;
+    const { key, dir } = v as { key?: unknown; dir?: unknown };
+    if (typeof key !== "string" || !key) return null;
+    return { key, dir: dir === "desc" ? "desc" : "asc" };
+  };
+  if (Array.isArray(raw)) {
+    const out: SortState[] = [];
+    for (const entry of raw) {
+      const s = one(entry);
+      if (s && !out.some((e) => e.key === s.key)) out.push(s);
+    }
+    return out;
+  }
+  const single = one(raw);
+  return single ? [single] : [];
+}
+
+export function encodeSorts(sorts: SortState[]): string | null {
+  if (!sorts.length) return null;
+  return sorts.map((s) => (s.dir === "desc" ? `${s.key}.desc` : s.key)).join(",");
+}
+
+/** Decode a `sort` URL param, dropping unknown and duplicated keys. */
+export function decodeSorts(raw: string | null, validKeys: ReadonlySet<string>): SortState[] {
+  if (!raw) return [];
+  const out: SortState[] = [];
+  for (const part of raw.split(",")) {
+    const desc = part.endsWith(".desc");
+    const asc = part.endsWith(".asc");
+    const key = desc ? part.slice(0, -".desc".length) : asc ? part.slice(0, -".asc".length) : part;
+    if (!validKeys.has(key) || out.some((s) => s.key === key)) continue;
+    out.push({ key, dir: desc ? "desc" : "asc" });
+  }
+  return out;
+}
+
+/** Header-click semantics. Plain click: make `key` the only sort — cycling
+ *  asc → desc → none when it already is the sole criterion. Shift-click
+ *  (`additive`): append `key` as the next-priority sort, or cycle an existing
+ *  entry's direction in place (asc → desc → removed). */
+export function nextSorts(prev: SortState[], key: string, additive: boolean): SortState[] {
+  const idx = prev.findIndex((s) => s.key === key);
+  if (!additive) {
+    if (prev.length === 1 && idx === 0) {
+      return prev[0].dir === "asc" ? [{ key, dir: "desc" }] : [];
+    }
+    return [{ key, dir: "asc" }];
+  }
+  if (idx === -1) return [...prev, { key, dir: "asc" }];
+  if (prev[idx].dir === "asc") {
+    return prev.map((s, i) => (i === idx ? { key, dir: "desc" as SortDir } : s));
+  }
+  return prev.filter((_, i) => i !== idx);
+}