@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/components/use-mobile-reveal.ts

@@ -0,0 +1,54 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * The phone's endless scroll, in place of the desktop pager (feedback #232).
+ *
+ * A client-side table already holds every row, so there is nothing to fetch — it simply
+ * reveals more of the sorted list as a sentinel scrolls into view. A SERVER-paginated
+ * table keeps its pager instead, because the rest of the rows genuinely are not here.
+ *
+ * The reveal count only ever grows and self-caps at the (re-filtered) list length, which
+ * is why nothing resets it: narrowing a filter cannot leave the limit pointing past the
+ * end, and widening one does not have to re-reveal what the user already scrolled past.
+ *
+ * Lifted out of `DataTable` with the rest of its state; the sentinel ref belongs to the
+ * caller's `<li>`.
+ */
+export function useMobileReveal<T>({
+  rows,
+  slice,
+  isServer,
+  isMdUp,
+  defaultPageSize,
+}: {
+  /** The whole sorted list — what there is to reveal. */
+  rows: T[];
+  /** What a server-paginated table shows instead. */
+  slice: T[];
+  isServer: boolean;
+  isMdUp: boolean;
+  defaultPageSize: number;
+}) {
+  const [mobileLimit, setMobileLimit] = useState(defaultPageSize);
+  const mobileSlice = isServer ? slice : rows.slice(0, mobileLimit);
+  const canRevealMoreMobile = !isServer && !isMdUp && mobileLimit < rows.length;
+  const loadMoreRef = useRef<HTMLLIElement | null>(null);
+
+  useEffect(() => {
+    if (!canRevealMoreMobile) return;
+    const el = loadMoreRef.current;
+    if (!el || typeof IntersectionObserver === "undefined") return;
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          setMobileLimit((n) => n + (defaultPageSize || 25));
+        }
+      },
+      { rootMargin: "300px" },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [canRevealMoreMobile, mobileLimit, defaultPageSize]);
+
+  return { mobileSlice, canRevealMoreMobile, loadMoreRef };
+}

package/src/components/use-table-state.ts

@@ -0,0 +1,295 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { useSearchParams } from "react-router";
+import { readStored, writeStored } from "../lib/safe-storage";
+import {
+  decodeFilterValue,
+  encodeFilterValue,
+  isFilterActive,
+  resolveFilter,
+} from "./data-table-filters";
+import { decodeSorts, encodeSorts, normalizeSorts, type SortState } from "./data-table-sort";
+import type { DataTableColumn, FilterState } from "./data-table";
+
+// ---------- Persisted + URL-encoded view state ----------
+//
+// Moved here with `useTableState` when `DataTable` was split: these are what the hook
+// reads and writes, and nothing else in the table ever called them.
+
+interface PersistedState {
+  // Multi-sort array; blobs from before the upgrade hold a single {key, dir}
+  // object (or null) — read back through normalizeSorts.
+  sort: SortState[] | { key: string; dir: string } | null;
+  filters: FilterState;
+  pageSize: number | "all";
+  widths?: Record<string, number>;
+  hidden?: string[];
+}
+
+export const DEFAULT_PERSIST_PREFIX = "hbui-table:";
+
+function loadPersisted(storageKey: string | undefined, prefix: string): Partial<PersistedState> {
+  if (!storageKey) return {};
+  const raw = readStored(prefix + storageKey);
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as Partial<PersistedState>;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {}; // corrupt JSON — the storage access itself is guarded by readStored
+  }
+}
+
+/** The blob that would be stored — also the value the effect below compares by, so
+ *  the comparison and the write can never disagree about what "unchanged" means. */
+function serializePersisted(state: PersistedState): string {
+  return JSON.stringify(state);
+}
+
+// ---------- URL sync helpers ----------
+
+const URL_FILTER_PREFIX = "f.";
+const URL_SORT_KEY = "sort";
+const URL_PAGE_KEY = "p";
+const URL_PAGE_SIZE_KEY = "ps";
+
+interface UrlState {
+  sorts?: SortState[];
+  filters?: FilterState;
+  pageSize?: number; // Infinity for "all"
+  page?: number; // 0-based
+}
+
+function readUrlState<T>(columns: DataTableColumn<T>[]): UrlState {
+  if (typeof window === "undefined") return {};
+  const sp = new URLSearchParams(window.location.search);
+  const out: UrlState = {};
+
+  const filters: FilterState = {};
+  for (const col of columns) {
+    const filter = resolveFilter(col);
+    if (!filter) continue;
+    const raw = sp.get(URL_FILTER_PREFIX + col.key);
+    if (raw == null) continue;
+    filters[col.key] = decodeFilterValue(filter, raw);
+  }
+  if (Object.keys(filters).length) out.filters = filters;
+
+  const sortRaw = sp.get(URL_SORT_KEY);
+  if (sortRaw) {
+    const decoded = decodeSorts(sortRaw, new Set(columns.map((c) => c.key)));
+    if (decoded.length) out.sorts = decoded;
+  }
+
+  const psRaw = sp.get(URL_PAGE_SIZE_KEY);
+  if (psRaw === "all") out.pageSize = Infinity;
+  else if (psRaw && Number(psRaw) > 0) out.pageSize = Number(psRaw);
+
+  const pRaw = sp.get(URL_PAGE_KEY);
+  if (pRaw && Number(pRaw) >= 1) out.page = Number(pRaw) - 1;
+
+  return out;
+}
+
+/**
+ * The managed part of the query string, as a string, for comparing by VALUE.
+ *
+ * Everything the table puts in the address and nothing else, in a fixed order.
+ * `columns` is walked for its keys only, which is why it can be left out of the
+ * effect's dependencies without lying: a new column ARRAY carrying the same keys
+ * produces the same signature, and a genuinely different set of filterable columns
+ * produces a different one.
+ */
+function urlSignature<T>(
+  columns: DataTableColumn<T>[],
+  sorts: SortState[],
+  filters: FilterState,
+  pageSize: number,
+  page: number,
+  defaultPageSize: number,
+): string {
+  const parts: string[] = [];
+  for (const col of columns) {
+    const state = filters[col.key];
+    if (!state || !isFilterActive(state)) continue;
+    const enc = encodeFilterValue(state);
+    if (enc != null) parts.push(`${URL_FILTER_PREFIX}${col.key}=${enc}`);
+  }
+  parts.push(`${URL_SORT_KEY}=${encodeSorts(sorts)}`);
+  parts.push(
+    `${URL_PAGE_SIZE_KEY}=${
+      pageSize === Infinity ? "all" : pageSize === defaultPageSize ? "" : String(pageSize)
+    }`,
+  );
+  parts.push(`${URL_PAGE_KEY}=${page > 0 ? String(page + 1) : ""}`);
+  return parts.join("&");
+}
+
+function writeUrlState<T>(
+  setSearchParams: ReturnType<typeof useSearchParams>[1],
+  columns: DataTableColumn<T>[],
+  sorts: SortState[],
+  filters: FilterState,
+  pageSize: number,
+  page: number,
+  defaultPageSize: number,
+): void {
+  setSearchParams(
+    (prev) => {
+      const next = new URLSearchParams(prev);
+      // clear managed keys
+      for (const col of columns) next.delete(URL_FILTER_PREFIX + col.key);
+      next.delete(URL_SORT_KEY);
+      next.delete(URL_PAGE_KEY);
+      next.delete(URL_PAGE_SIZE_KEY);
+      // write filters
+      for (const col of columns) {
+        const state = filters[col.key];
+        if (!state || !isFilterActive(state)) continue;
+        const enc = encodeFilterValue(state);
+        if (enc != null) next.set(URL_FILTER_PREFIX + col.key, enc);
+      }
+      // write sort
+      const sortEnc = encodeSorts(sorts);
+      if (sortEnc) next.set(URL_SORT_KEY, sortEnc);
+      // write page size if non-default
+      if (pageSize === Infinity) next.set(URL_PAGE_SIZE_KEY, "all");
+      else if (pageSize !== defaultPageSize) next.set(URL_PAGE_SIZE_KEY, String(pageSize));
+      // write page if not first
+      if (page > 0) next.set(URL_PAGE_KEY, String(page + 1));
+      return next;
+    },
+    { replace: true },
+  );
+}
+
+/**
+ * Where a table's view lives: what it is sorted and filtered by, which page, how wide
+ * the columns are and which are hidden — plus the two places that outlives a render.
+ *
+ * Lifted out of `DataTable`, which was 984 lines and twenty hooks in one function. This
+ * is the part that is genuinely about STATE rather than about drawing, and the three
+ * rules it encodes are easy to lose among the markup:
+ *
+ * * **The URL is read once, on mount.** A shared or deep link populates the initial view;
+ *   after that the state is local, or the browser's own history would fight the user's
+ *   next click.
+ * * **Sorting and filtering are optionally CONTROLLED.** A server-driven table passes
+ *   state and a callback and owns them; everything else is self-owned. That is the
+ *   `sortsProp ?? internalSorts` pair, and it is why the setters are exposed separately.
+ * * **Persistence writes on every change, the URL only when asked.** `storageKey` is the
+ *   per-table identity; `urlSync` is opt-in because only some tables want their view in
+ *   a shareable address.
+ */
+export function useTableState<T>({
+  columns,
+  storageKey,
+  storageKeyPrefix,
+  urlSync,
+  setSearchParams,
+  defaultPageSize,
+  sortsProp,
+  filtersProp,
+}: {
+  columns: DataTableColumn<T>[];
+  storageKey?: string;
+  storageKeyPrefix: string;
+  urlSync?: boolean;
+  setSearchParams: ReturnType<typeof useSearchParams>[1];
+  defaultPageSize: number;
+  sortsProp?: SortState[];
+  filtersProp?: FilterState;
+}) {
+  // Read URL once on mount so URL-encoded views (e.g. shared links, deep links from
+  // other pages) populate initial state. After mount, state is local.
+  const [urlInitial] = useState<UrlState>(() => (urlSync ? readUrlState(columns) : {}));
+  const initial = useMemo(
+    () => loadPersisted(storageKey, storageKeyPrefix),
+    [storageKey, storageKeyPrefix],
+  );
+  const [internalSorts, setInternalSorts] = useState<SortState[]>(() =>
+    urlInitial.sorts !== undefined ? urlInitial.sorts : normalizeSorts(initial.sort),
+  );
+  const [internalFilters, setInternalFilters] = useState<FilterState>(
+    () => urlInitial.filters ?? initial.filters ?? {},
+  );
+  // Controlled when the owner passes state + callback (server-driven tables);
+  // self-owned otherwise.
+  const sorts = sortsProp ?? internalSorts;
+  const filters = filtersProp ?? internalFilters;
+  const [page, setPage] = useState(() => urlInitial.page ?? 0);
+  const [pageSize, setPageSize] = useState<number>(() => {
+    if (urlInitial.pageSize !== undefined) return urlInitial.pageSize;
+    if (initial.pageSize === "all") return Infinity;
+    if (typeof initial.pageSize === "number" && initial.pageSize > 0) return initial.pageSize;
+    return defaultPageSize;
+  });
+  const [widths, setWidths] = useState<Record<string, number>>(() => initial.widths ?? {});
+  const [hiddenCols, setHiddenCols] = useState<Set<string>>(() => new Set(initial.hidden ?? []));
+  const [showSettings, setShowSettings] = useState(false);
+  const headRefs = useMemo(() => new Map<string, HTMLTableCellElement>(), []);
+
+  // ---- Writing out: both of these compare by VALUE ----
+  //
+  // A CONTROLLED table (`sorts`/`filters` props plus callbacks — every server-driven
+  // one) receives a freshly-built object on every render of the page around it, and
+  // `{}` is never `===` the `{}` before it. Keyed on identity, both effects below
+  // therefore fired on every unrelated parent render: persistence wrote the same JSON
+  // into `localStorage` each time — a synchronous main-thread write, on a page whose
+  // other half may be a form being typed into — and the URL one handed react-router a
+  // `replace` it answers with a render, which is the loop the audit records. A `ref`
+  // holding what was last written is what makes "changed" mean changed.
+  const lastPersisted = useRef<string | null>(null);
+  const persisted = !storageKey
+    ? ""
+    : serializePersisted({
+        sort: sorts,
+        filters,
+        pageSize: pageSize === Infinity ? "all" : pageSize,
+        widths,
+        hidden: Array.from(hiddenCols),
+      });
+  useEffect(() => {
+    if (!storageKey) return;
+    // The destination is part of the signature: two tables can hold identical state,
+    // and a table that swaps `storageKey` has to write under the new one even though
+    // nothing about the view changed.
+    const target = storageKeyPrefix + storageKey;
+    const sig = `${target}\u0000${persisted}`;
+    if (lastPersisted.current === sig) return;
+    lastPersisted.current = sig;
+    writeStored(target, persisted);
+  }, [storageKey, storageKeyPrefix, persisted]);
+
+  const lastUrl = useRef<string | null>(null);
+  const urlSig = urlSync
+    ? urlSignature(columns, sorts, filters, pageSize, page, defaultPageSize)
+    : "";
+  useEffect(() => {
+    if (!urlSync) return;
+    if (lastUrl.current === urlSig) return;
+    lastUrl.current = urlSig;
+    // `columns` is deliberately not a dependency and does not need to be: the
+    // signature above is computed from it, so a column set that would produce a
+    // different address produces a different signature first.
+    writeUrlState(setSearchParams, columns, sorts, filters, pageSize, page, defaultPageSize);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [urlSync, urlSig]);
+
+  return {
+    sorts,
+    filters,
+    setInternalSorts,
+    setInternalFilters,
+    page,
+    setPage,
+    pageSize,
+    setPageSize,
+    widths,
+    setWidths,
+    hiddenCols,
+    setHiddenCols,
+    showSettings,
+    setShowSettings,
+    headRefs,
+  };
+}

package/src/components/user-avatar.tsx

@@ -0,0 +1,61 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+
+/** Initials from a display name (first + last) or, failing that, an email —
+ *  e.g. "Marcel Eifert" → "ME", "marcel@x.com" → "MA". App-agnostic.
+ *
+ *  "Failing that" means BLANK, not merely absent. This was `name ?? email ?? "?"`,
+ *  and `??` falls through on null/undefined alone — so an empty or whitespace-only
+ *  display name short-circuited the email it had in hand and landed on the guard
+ *  below, returning "?" for a user whose address says "MA" perfectly well. Keksdose
+ *  cannot reach it (its `display_name` has `min_length=1`), but this is exported as
+ *  app-agnostic, and any consumer whose profile name is optional free text got a wall
+ *  of "?" chips. The guard is what shows the empty case was foreseen; it just
+ *  answered it at the wrong end. */
+export function avatarInitials(name?: string | null, email?: string | null): string {
+  const source = [name, email].map((s) => s?.trim()).find(Boolean) ?? "?";
+  const parts = source.split(/\s+/).filter(Boolean);
+  if (parts.length >= 2) return (parts[0][0] + parts[1][0]).toUpperCase();
+  return source.slice(0, 2).toUpperCase();
+}
+
+const AVATAR_SIZES = {
+  sm: "size-7 text-[11px]",
+  md: "size-8 text-xs",
+  lg: "size-12 text-base",
+} as const;
+
+/** A `<span>`'s props, minus `children`: the content is the initials this computes
+ *  from `name`/`email`, so there is nothing for a caller to put inside. */
+export interface UserAvatarProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {
+  name?: string | null;
+  email?: string | null;
+  size?: keyof typeof AVATAR_SIZES;
+}
+
+/**
+ * A round initials avatar — the common user chip shared across apps (feedback
+ * #333). Purely presentational; wrap it in a button for the account menu trigger.
+ */
+export function UserAvatar({ name, email, size = "md", className, ...rest }: UserAvatarProps) {
+  return (
+    <span
+      // `aria-hidden` sits BEFORE the spread, unlike the structural attributes on the
+      // other components here, because it is a DEFAULT rather than an invariant. The
+      // avatar is decorative next to the name it belongs to — which is where all three
+      // apps render it — so hiding it stops a screen reader saying "ME" after the word
+      // "Marcel Eifert". A caller who renders one ALONE (an assignee column, a
+      // presence dot) needs the opposite, and now has it: `aria-hidden={false}` plus an
+      // `aria-label` arrives through `...rest` and wins.
+      aria-hidden
+      {...rest}
+      className={cn(
+        "inline-flex shrink-0 items-center justify-center rounded-full bg-[var(--bg-inverse)] font-semibold text-[var(--text-inverse)]",
+        AVATAR_SIZES[size],
+        className,
+      )}
+    >
+      {avatarInitials(name, email)}
+    </span>
+  );
+}

package/src/components/wizard-stepper.tsx

@@ -0,0 +1,37 @@
+import { cn } from "../lib/cn";
+
+/** Compact step indicator for the import wizards. Past steps are plain, the
+ * current one is highlighted, future ones muted. */
+export function WizardStepper({
+  steps,
+  current,
+  ariaLabel,
+}: {
+  steps: { key: string; label: string }[];
+  current: string;
+  ariaLabel?: string;
+}) {
+  const currentIndex = steps.findIndex((s) => s.key === current);
+  return (
+    <ol className="flex items-center gap-1 text-xs" aria-label={ariaLabel}>
+      {steps.map((step, i) => (
+        <li key={step.key} className="flex items-center gap-1">
+          {i > 0 && <span className="w-4 border-t border-[var(--border)]" />}
+          <span
+            aria-current={step.key === current ? "step" : undefined}
+            className={cn(
+              "rounded-full px-2 py-0.5",
+              i === currentIndex
+                ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)] font-medium"
+                : i < currentIndex
+                  ? "text-[var(--text-secondary)]"
+                  : "text-[var(--text-placeholder)]",
+            )}
+          >
+            {step.label}
+          </span>
+        </li>
+      ))}
+    </ol>
+  );
+}

package/src/data-table.ts

@@ -0,0 +1,19 @@
+// `@eifi1/ui-kit/data-table` — the table suite.
+//
+// A re-slicing of the main barrel, not a new API. This entry point requires
+// `react-router`: DataTable calls useSearchParams unconditionally, above any `urlSync`
+// branch, so a Router is needed even with URL sync switched off.
+export * from "./components/data-table-labels";
+export * from "./components/data-table-sort";
+export * from "./components/data-table-filters";
+export * from "./components/data-table-pagination";
+export { FilterPopover } from "./components/data-table-filter-popover";
+// `SortState` comes from data-table-sort above; re-exporting the module wholesale
+// would collide with it, which is why the main barrel names these explicitly too.
+export { DataTable } from "./components/data-table";
+export type {
+  DataTableColumn,
+  DataTableProps,
+  ServerPagination,
+  FilterState,
+} from "./components/data-table";