@terpjs/react-core 0.1.0

package/src/dataview/README.md

@@ -0,0 +1,138 @@
+# DataView
+
+The single sanctioned surface for rendering data collections in a Terp app: a
+repository-driven, token-styled table/card view with search, sorting, pagination,
+column management (show/hide, reorder, resize), selection with batch actions, per-row
+actions, expandable rows, a responsive card layout and persisted view preferences.
+
+`DataView` never fetches, never touches `localStorage`, and never knows whether data
+is client-side or server-side. All data access goes through a **data repository** and
+all preference persistence through a **view-state repository** — adding a new data
+source or preference store never requires modifying any component file (dependency
+inversion / open-closed).
+
+`variant="embedded"` removes pagination and view controls. When its repository
+is non-searchable and no selection, filter, or custom controls exist, DataView
+also omits the toolbar band entirely so related empty collections add no blank
+chrome.
+
+## Quick start (client-side data)
+
+```tsx
+import {
+  DataView,
+  InMemoryDataViewRepository,
+  LocalStorageViewStateRepository,
+} from "@terpjs/react-core";
+import type { DataViewColumn } from "@terpjs/react-core";
+
+interface Ticket { id: string; title: string; status: string; created: string }
+
+const columns: DataViewColumn<Ticket>[] = [
+  { id: "title", header: "Title", accessor: (t) => t.title, meta: { mobileSlot: "title" } },
+  { id: "status", header: "Status", accessor: (t) => t.status, meta: { mobileSlot: "status" } },
+  { id: "created", header: "Created", accessor: (t) => t.created, meta: { mobileSlot: "date", width: 120 } },
+];
+
+const repository = new InMemoryDataViewRepository(tickets, {
+  getRowId: (t) => t.id,
+  getValue: (t, col) => t[col as keyof Ticket],
+  searchFields: ["title", "status"],
+});
+
+<DataView<Ticket>
+  viewId="tickets.list"                                   // stable key for persisted preferences
+  repository={repository}
+  viewStateRepository={new LocalStorageViewStateRepository()}
+  columns={columns}
+  getRowLabel={(t) => t.title}                         // required with onRowClick (a11y name)
+  onRowClick={(t) => navigate(t.id)}
+  enableSelection
+  batchActions={[{ label: "Archive", onClick: archive, onSelectAll: archiveAll, inline: true }]}
+  rowActions={(t) => [
+    { label: "Delete", variant: "destructive", onClick: remove, disabled: (t) => t.status === "closed" },
+  ]}
+  searchDebounceMs={300}
+  pageSizeOptions={[10, 25, 50, 100]}
+  renderExpanded={(t) => <TicketPreview ticket={t} />}
+/>
+```
+
+## Server-side data
+
+Server-side views keep sorting/filter/pagination in the URL via `useServerDataView`
+(deep-linkable, survives reloads); the repository maps the emitted `DataViewQuery` to
+API parameters through an injectable request adapter:
+
+```tsx
+import { DataView, HttpDataViewRepository, useServerDataView, unwrap } from "@terpjs/react-core";
+
+const repository = new HttpDataViewRepository<NoteRead>({
+  getRowId: (n) => n.id,
+  request: async ({ skip, limit }, signal) => {
+    const page = unwrap(await client.GET("/api/v1/notes/", { params: { query: { skip, limit } }, signal }));
+    return { items: page.items, total: page.total };
+  },
+});
+
+function NotesPage() {
+  const serverQuery = useServerDataView({ initialPageSize: 25 });
+  return <DataView repository={repository} columns={columns} serverQuery={serverQuery} />;
+}
+```
+
+## The repository interfaces
+
+### `DataViewRepository<T>` (data access)
+
+| Member | Meaning |
+|---|---|
+| `query(q, signal?)` | Return one `{ rows, totalCount }` page for a `DataViewQuery` (pagination, sorting, filters, search, searchBroadened). |
+| `getRowId(row)` | Stable row identity — selection/expansion survive re-sorts and refetches. |
+| `capabilities.serverSide` | `true` → the repo does sorting/filtering/paging per query; `false` → it owns a full client-side data set. |
+| `capabilities.search` | Whether the toolbar search box renders. |
+| `capabilities.searchScope` | Whether the broadened "search everything" toggle is supported. |
+| `getFacetedValues?(columnId)` | Optional: distinct values of a column (client-side facets). |
+
+Implementations shipped: `InMemoryDataViewRepository` (wraps a plain array;
+filter/search/sort/page client-side) and `HttpDataViewRepository` (maps the query to
+`skip = pageIndex * pageSize`, `limit = pageSize`, sort/filter/search params and
+delegates the transport to an injectable adapter).
+
+### `ViewStateRepository` (persisted preferences)
+
+`load(viewId)` / `save(viewId, state)` for everything the user customises: column
+visibility, order, resized widths, and — for client-side views — sorting, filters and
+search. Implementations shipped: `LocalStorageViewStateRepository` (schema-validated,
+versioned envelope; corrupt data falls back to defaults) and
+`InMemoryViewStateRepository` (tests, or views without a `viewId`).
+
+## Behaviour notes
+
+- **System columns** are auto-injected in a fixed order — expand toggle, selection
+  checkbox, user columns, row-actions (sr-only header) — pinned to narrow widths and
+  never hideable/reorderable/resizable.
+- **Column resizing**: drag the header handle; widths update live with no persistence
+  writes per pointermove and are persisted once, on pointer-up. Width precedence:
+  pinned system columns → user-resized → static `meta.width` hint → auto.
+- **Select-all-across-pages**: after selecting the whole page the toolbar offers
+  "Select all N results"; batch actions then invoke their `onSelectAll` variant. The
+  mode resets whenever the page selection is broken.
+- **Responsive**: auto-switches to the stacked card layout at the mobile breakpoint
+  until the user chooses a layout explicitly (manual choice wins). Cards are composed
+  from `meta.mobileSlot` (`title` / `subtitle` / `status` / `date`), with
+  `renderCard(row)` as a full escape hatch; selection, actions and expansion keep
+  working in card view.
+- **Variants**: `variant="embedded"` renders a plain compact view (no view toggle, no
+  page-size selector, no pagination footer, all rows) for panels/detail sections.
+- **i18n**: no hard-coded user-facing strings — every label is a `UiText` routed
+  through the app's `UiTextProvider` resolver, with defaults overridable per instance
+  via the `strings` prop.
+
+## Files
+
+- `DataView.tsx` — composition only
+- `DataViewToolbar` / `DataViewPagination` / `DataViewColumnSettings` /
+  `DataViewRowActions` / `DataViewExpandableRow` / `DataViewCardList` / `DataViewTable`
+- `repositories/` — the interfaces' implementations
+- `hooks/` — `useDataViewState`, `useServerDataView`, `useViewSearch`, `useDataViewQuery`

package/src/dataview/glyphs.tsx

@@ -0,0 +1,175 @@
+import type { CSSProperties } from "react";
+
+// Decorative inline SVG glyphs for the DataView family (react-core ships no icon
+// library). All are aria-hidden; interactive wrappers carry the accessible names.
+
+interface GlyphProps {
+  size?: number;
+  style?: CSSProperties;
+}
+
+function glyphProps({ size = 16, style }: GlyphProps) {
+  return {
+    width: size,
+    height: size,
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 2,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": true,
+    focusable: false,
+    style,
+  } as const;
+}
+
+export function ChevronDownGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
+export function ChevronRightGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="9 6 15 12 9 18" />
+    </svg>
+  );
+}
+
+export function SortAscGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <path d="M12 19V5" />
+      <polyline points="5 12 12 5 19 12" />
+    </svg>
+  );
+}
+
+export function SortDescGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <path d="M12 5v14" />
+      <polyline points="19 12 12 19 5 12" />
+    </svg>
+  );
+}
+
+export function SortNoneGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="8 9 12 5 16 9" />
+      <polyline points="8 15 12 19 16 15" />
+    </svg>
+  );
+}
+
+export function SearchGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <circle cx="11" cy="11" r="7" />
+      <line x1="21" y1="21" x2="16.65" y2="16.65" />
+    </svg>
+  );
+}
+
+export function CloseGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+export function EllipsisGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <circle cx="5" cy="12" r="1.5" fill="currentColor" stroke="none" />
+      <circle cx="12" cy="12" r="1.5" fill="currentColor" stroke="none" />
+      <circle cx="19" cy="12" r="1.5" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
+export function ColumnsGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <rect x="3" y="4" width="18" height="16" rx="2" />
+      <line x1="9" y1="4" x2="9" y2="20" />
+      <line x1="15" y1="4" x2="15" y2="20" />
+    </svg>
+  );
+}
+
+export function TableGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <rect x="3" y="4" width="18" height="16" rx="2" />
+      <line x1="3" y1="10" x2="21" y2="10" />
+      <line x1="3" y1="15" x2="21" y2="15" />
+    </svg>
+  );
+}
+
+export function CardsGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <rect x="3" y="4" width="18" height="7" rx="2" />
+      <rect x="3" y="14" width="18" height="7" rx="2" />
+    </svg>
+  );
+}
+
+export function ArrowUpGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="6 14 12 8 18 14" />
+    </svg>
+  );
+}
+
+export function ArrowDownGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="6 10 12 16 18 10" />
+    </svg>
+  );
+}
+
+export function PageFirstGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="11 17 6 12 11 7" />
+      <polyline points="18 17 13 12 18 7" />
+    </svg>
+  );
+}
+
+export function PagePrevGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="15 18 9 12 15 6" />
+    </svg>
+  );
+}
+
+export function PageNextGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="9 18 15 12 9 6" />
+    </svg>
+  );
+}
+
+export function PageLastGlyph(props: GlyphProps) {
+  return (
+    <svg {...glyphProps(props)}>
+      <polyline points="13 17 18 12 13 7" />
+      <polyline points="6 17 11 12 6 7" />
+    </svg>
+  );
+}

package/src/dataview/hooks/hooks.test.tsx

@@ -0,0 +1,240 @@
+// @vitest-environment jsdom
+import { cleanup, renderHook, act } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useViewSearch } from "./useViewSearch";
+import { useDataViewState } from "./useDataViewState";
+import { useServerDataView } from "./useServerDataView";
+import { InMemoryViewStateRepository } from "../repositories/viewState";
+import type { DataViewColumn } from "../types";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  window.history.replaceState(null, "", "/");
+});
+
+describe("useViewSearch", () => {
+  it("emits immediately without a debounce", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useViewSearch("", onChange));
+    act(() => result.current.setInputValue("a"));
+    expect(onChange).toHaveBeenCalledWith("a");
+  });
+
+  it("debounces emissions while keeping the input immediate", () => {
+    vi.useFakeTimers();
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useViewSearch("", onChange, 300));
+
+    act(() => result.current.setInputValue("p"));
+    act(() => result.current.setInputValue("pr"));
+    expect(result.current.inputValue).toBe("pr");
+    expect(onChange).not.toHaveBeenCalled();
+
+    act(() => vi.advanceTimersByTime(300));
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("pr");
+  });
+
+  it("clear() cancels the pending debounce and emits \"\" immediately", () => {
+    vi.useFakeTimers();
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useViewSearch("", onChange, 300));
+    act(() => result.current.setInputValue("x"));
+    act(() => result.current.clear());
+    expect(onChange).toHaveBeenCalledWith("");
+    act(() => vi.advanceTimersByTime(500));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("syncs external value changes back into the input", () => {
+    const { result, rerender } = renderHook(
+      ({ value }: { value: string }) => useViewSearch(value, () => undefined),
+      { initialProps: { value: "" } },
+    );
+    rerender({ value: "reset" });
+    expect(result.current.inputValue).toBe("reset");
+  });
+
+  it("an external reset cancels a pending debounced emit", () => {
+    vi.useFakeTimers();
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }: { value: string }) => useViewSearch(value, onChange, 300),
+      { initialProps: { value: "x" } },
+    );
+    act(() => result.current.setInputValue("xy"));
+    rerender({ value: "" }); // e.g. a caller-driven "clear filters"
+    act(() => vi.advanceTimersByTime(300));
+    expect(onChange).not.toHaveBeenCalled(); // "xy" never resurrects the cleared search
+    expect(result.current.inputValue).toBe("");
+  });
+});
+
+interface Row {
+  id: string;
+  title: string;
+  status: string;
+}
+
+const COLUMNS: DataViewColumn<Row>[] = [
+  { id: "title", header: "Title" },
+  { id: "status", header: "Status" },
+  { id: "created", header: "Created" },
+];
+
+function renderState(viewStateRepository: InMemoryViewStateRepository, viewId = "v") {
+  return renderHook(() =>
+    useDataViewState<Row>({
+      viewId,
+      columns: COLUMNS,
+      viewStateRepository,
+      serverSide: false,
+      initialPageSize: 10,
+    }),
+  );
+}
+
+describe("useDataViewState", () => {
+  it("toggles sort asc → desc → none", () => {
+    const { result } = renderState(new InMemoryViewStateRepository());
+    act(() => result.current.toggleSort("title"));
+    expect(result.current.sorting).toEqual([{ id: "title", desc: false }]);
+    act(() => result.current.toggleSort("title"));
+    expect(result.current.sorting).toEqual([{ id: "title", desc: true }]);
+    act(() => result.current.toggleSort("title"));
+    expect(result.current.sorting).toEqual([]);
+  });
+
+  it("persists column sizing once per commit and restores it", () => {
+    const store = new InMemoryViewStateRepository();
+    const save = vi.spyOn(store, "save");
+    const first = renderState(store);
+    act(() => first.result.current.commitColumnSizing({ title: 240, status: 120 }));
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(first.result.current.columnSizing).toEqual({ title: 240, status: 120 });
+
+    const second = renderState(store);
+    expect(second.result.current.columnSizing).toEqual({ title: 240, status: 120 });
+  });
+
+  it("persists visibility and ordering, and restores effective column order", () => {
+    const store = new InMemoryViewStateRepository();
+    const first = renderState(store);
+    act(() => first.result.current.setColumnVisible("status", false));
+    act(() => first.result.current.moveColumn("created", -1));
+
+    const second = renderState(store);
+    expect(second.result.current.orderedColumns.map((c) => c.id)).toEqual([
+      "title",
+      "created",
+      "status",
+    ]);
+    expect(second.result.current.visibleColumns.map((c) => c.id)).toEqual(["title", "created"]);
+  });
+
+  it("clamps reordering at the edges", () => {
+    const { result } = renderState(new InMemoryViewStateRepository());
+    act(() => result.current.moveColumn("title", -1));
+    expect(result.current.orderedColumns.map((c) => c.id)).toEqual(["title", "status", "created"]);
+  });
+
+  it("resets the page index when search or filters change", () => {
+    const { result } = renderState(new InMemoryViewStateRepository());
+    act(() => result.current.setPagination({ pageIndex: 3, pageSize: 10 }));
+    act(() => result.current.setSearch("printer"));
+    expect(result.current.pagination.pageIndex).toBe(0);
+
+    act(() => result.current.setPagination({ pageIndex: 2, pageSize: 10 }));
+    act(() => result.current.setFilter("status", "open"));
+    expect(result.current.pagination.pageIndex).toBe(0);
+    expect(result.current.filters).toEqual([{ id: "status", value: "open" }]);
+  });
+
+  it("persists search/sorting/filters for client-side views and restores them", () => {
+    const store = new InMemoryViewStateRepository();
+    const first = renderState(store);
+    act(() => first.result.current.setSearch("vpn"));
+    act(() => first.result.current.toggleSort("title"));
+
+    const second = renderState(store);
+    expect(second.result.current.search).toBe("vpn");
+    expect(second.result.current.sorting).toEqual([{ id: "title", desc: false }]);
+  });
+
+  it("keeps sorting/filters/search out of persistence for server-side views", () => {
+    const store = new InMemoryViewStateRepository();
+    const save = vi.spyOn(store, "save");
+    const { result } = renderHook(() =>
+      useDataViewState<Row>({
+        viewId: "v",
+        columns: COLUMNS,
+        viewStateRepository: store,
+        serverSide: true,
+        initialPageSize: 10,
+      }),
+    );
+    act(() => result.current.toggleSort("title"));
+    act(() => result.current.setColumnVisible("status", false));
+    const persisted = save.mock.calls.at(-1)?.[1];
+    expect(persisted?.sorting).toEqual([]);
+    expect(persisted?.search).toBe("");
+  });
+
+  it("delegates query state to a controlled query when provided", () => {
+    const onSortingChange = vi.fn();
+    const { result } = renderHook(() =>
+      useDataViewState<Row>({
+        columns: COLUMNS,
+        serverSide: true,
+        initialPageSize: 10,
+        controlledQuery: {
+          sorting: [{ id: "status", desc: true }],
+          filters: [],
+          search: "",
+          pagination: { pageIndex: 4, pageSize: 25 },
+          onSortingChange,
+          onFiltersChange: vi.fn(),
+          onSearchChange: vi.fn(),
+          onPaginationChange: vi.fn(),
+        },
+      }),
+    );
+    expect(result.current.sorting).toEqual([{ id: "status", desc: true }]);
+    expect(result.current.pagination).toEqual({ pageIndex: 4, pageSize: 25 });
+    act(() => result.current.toggleSort("status"));
+    expect(onSortingChange).toHaveBeenCalledWith([]);
+  });
+});
+
+describe("useServerDataView", () => {
+  it("reads its initial state from the URL", () => {
+    window.history.replaceState(null, "", "/?page=3&size=25&sort=-title&q=vpn");
+    const { result } = renderHook(() => useServerDataView());
+    expect(result.current.pagination).toEqual({ pageIndex: 2, pageSize: 25 });
+    expect(result.current.sorting).toEqual([{ id: "title", desc: true }]);
+    expect(result.current.search).toBe("vpn");
+  });
+
+  it("writes state changes back into the URL", () => {
+    const { result } = renderHook(() => useServerDataView());
+    act(() => result.current.onSearchChange("printer"));
+    act(() => result.current.onPaginationChange({ pageIndex: 1, pageSize: 10 }));
+    const params = new URLSearchParams(window.location.search);
+    expect(params.get("q")).toBe("printer");
+    expect(params.get("page")).toBe("2");
+  });
+
+  it("prefixes parameters so several views share one page", () => {
+    const { result } = renderHook(() => useServerDataView({ paramPrefix: "t" }));
+    act(() => result.current.onSearchChange("x"));
+    expect(new URLSearchParams(window.location.search).get("t.q")).toBe("x");
+  });
+
+  it("ignores a malformed filters parameter", () => {
+    window.history.replaceState(null, "", "/?filters=%7Bnot-json");
+    const { result } = renderHook(() => useServerDataView());
+    expect(result.current.filters).toEqual([]);
+  });
+});

package/src/dataview/hooks/useDataViewQuery.ts

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { DataViewQuery, DataViewRepository } from "../types";
+
+export interface UseDataViewQueryResult<T> {
+  rows: T[];
+  totalCount: number;
+  /** True until the first page for this repository has resolved (skeleton state). */
+  isLoading: boolean;
+  /** True while any query is in flight (subtle refresh indicator; stale data stays). */
+  isFetching: boolean;
+  error: unknown;
+  /** Re-run the current query. */
+  refresh: () => void;
+}
+
+/**
+ * Runs `repository.query` whenever the query changes, with abort-on-supersede:
+ * a newer query cancels the in-flight one, and stale results never land. Data from
+ * the previous query stays visible while the next one loads (`isFetching`).
+ */
+export function useDataViewQuery<T>(
+  repository: DataViewRepository<T>,
+  query: DataViewQuery,
+): UseDataViewQueryResult<T> {
+  const [rows, setRows] = useState<T[]>([]);
+  const [totalCount, setTotalCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isFetching, setIsFetching] = useState(true);
+  const [error, setError] = useState<unknown>(null);
+  const [refreshToken, setRefreshToken] = useState(0);
+
+  // Serialize the query so effect deps are value-based (no refetch loop when the
+  // caller rebuilds an identical query object each render).
+  const queryKey = JSON.stringify(query);
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  useEffect(() => {
+    const controller = new AbortController();
+    let active = true;
+    setIsFetching(true);
+    repository
+      .query(queryRef.current, controller.signal)
+      .then((result) => {
+        if (!active) {
+          return;
+        }
+        setRows(result.rows);
+        setTotalCount(result.totalCount);
+        setError(null);
+        setIsLoading(false);
+        setIsFetching(false);
+      })
+      .catch((caught: unknown) => {
+        if (!active || controller.signal.aborted) {
+          return;
+        }
+        setError(caught);
+        setIsLoading(false);
+        setIsFetching(false);
+      });
+    return () => {
+      active = false;
+      controller.abort();
+    };
+  }, [repository, queryKey, refreshToken]);
+
+  const refresh = useCallback(() => setRefreshToken((token) => token + 1), []);
+
+  return { rows, totalCount, isLoading, isFetching, error, refresh };
+}