@terpjs/react-core 0.1.0

package/src/dataview/repositories/HttpDataViewRepository.ts

@@ -0,0 +1,110 @@
+import type {
+  DataViewQuery,
+  DataViewRepository,
+  DataViewResult,
+} from "../types";
+
+/**
+ * The request seam of {@link HttpDataViewRepository}: given already-mapped API
+ * parameters, perform the request (typically via the app's typed contract client)
+ * and return one raw page. Injecting it keeps the repository transport-agnostic —
+ * any REST/GraphQL backend plugs in without touching DataView.
+ */
+export type HttpRequestAdapter<T> = (
+  params: HttpDataViewParams,
+  signal?: AbortSignal,
+) => Promise<{ items: T[]; total: number }>;
+
+/** The flat API parameters an {@link HttpRequestAdapter} receives. */
+export interface HttpDataViewParams {
+  /** `pageIndex * pageSize`. */
+  skip: number;
+  /** `pageSize`. */
+  limit: number;
+  /** e.g. `["title", "-created_at"]` (leading `-` = descending). */
+  sort: string[];
+  /** Column filters keyed by column id. */
+  filters: Record<string, unknown>;
+  /** Free-text search term ("" when inactive). */
+  search: string;
+  /** The broadened "search everything" flag. */
+  searchBroadened: boolean;
+}
+
+export interface HttpDataViewRepositoryOptions<T> {
+  /** Performs the actual request from mapped parameters. */
+  request: HttpRequestAdapter<T>;
+  /** Stable row identity. */
+  getRowId: (row: T) => string;
+  /** Whether the backend supports free-text search (default true). */
+  search?: boolean;
+  /** Whether the backend supports the broadened search scope (default false). */
+  searchScope?: boolean;
+  /**
+   * The largest `limit` ever sent (default 200 — Terp's `PAGINATION_MAX_LIMIT`
+   * default, which the backend enforces with a 422). An embedded DataView asks its
+   * repository for "everything"; against a server-side source that request is
+   * clamped here so it degrades to the first `maxLimit` rows instead of failing.
+   * Raise it only in lockstep with the backend setting.
+   */
+  maxLimit?: number;
+}
+
+/**
+ * A server-side {@link DataViewRepository}: maps every {@link DataViewQuery} to flat
+ * API parameters (`skip = pageIndex * pageSize`, `limit = pageSize`, sort/filter/search)
+ * and delegates the transport to an injectable {@link HttpRequestAdapter}.
+ *
+ * @example
+ * ```ts
+ * const repo = 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 };
+ *   },
+ * });
+ * ```
+ */
+export class HttpDataViewRepository<T> implements DataViewRepository<T> {
+  readonly capabilities: DataViewRepository<T>["capabilities"];
+
+  private readonly options: HttpDataViewRepositoryOptions<T>;
+
+  constructor(options: HttpDataViewRepositoryOptions<T>) {
+    this.options = options;
+    this.capabilities = {
+      serverSide: true,
+      search: options.search ?? true,
+      searchScope: options.searchScope ?? false,
+    };
+  }
+
+  getRowId(row: T): string {
+    return this.options.getRowId(row);
+  }
+
+  async query(q: DataViewQuery, signal?: AbortSignal): Promise<DataViewResult<T>> {
+    const filters: Record<string, unknown> = {};
+    for (const filter of q.filters) {
+      filters[filter.id] = filter.value;
+    }
+    // Clamp the page size first and window with the clamped value, so page N is
+    // always the N-th `pageSize` window — never a far-flung skip with a smaller limit.
+    const pageSize = Math.min(q.pagination.pageSize, this.options.maxLimit ?? 200);
+    const page = await this.options.request(
+      {
+        skip: q.pagination.pageIndex * pageSize,
+        limit: pageSize,
+        sort: q.sorting.map((sort) => (sort.desc ? `-${sort.id}` : sort.id)),
+        filters,
+        search: q.search,
+        searchBroadened: q.searchBroadened,
+      },
+      signal,
+    );
+    return { rows: page.items, totalCount: page.total };
+  }
+}

package/src/dataview/repositories/InMemoryDataViewRepository.ts

@@ -0,0 +1,145 @@
+import type {
+  DataViewQuery,
+  DataViewRepository,
+  DataViewResult,
+} from "../types";
+
+/** How {@link InMemoryDataViewRepository} reads and matches rows. */
+export interface InMemoryDataViewRepositoryOptions<T> {
+  /** Stable row identity. */
+  getRowId: (row: T) => string;
+  /** The raw sortable/filterable value of a column for a row. */
+  getValue: (row: T, columnId: string) => unknown;
+  /**
+   * Column ids the free-text search matches against (case-insensitive substring).
+   * Omit to disable search (`capabilities.search` becomes false).
+   */
+  searchFields?: string[];
+  /**
+   * Custom filter match; the default is faceted equality (`value` is the filter value or,
+   * when an array, any-of).
+   */
+  matchesFilter?: (row: T, columnId: string, value: unknown) => boolean;
+}
+
+function defaultMatchesFilter(cell: unknown, value: unknown): boolean {
+  if (Array.isArray(value)) {
+    return value.length === 0 || value.some((candidate) => candidate === cell);
+  }
+  return cell === value;
+}
+
+function compareValues(a: unknown, b: unknown): number {
+  if (a === b) {
+    return 0;
+  }
+  if (a === null || a === undefined) {
+    return -1;
+  }
+  if (b === null || b === undefined) {
+    return 1;
+  }
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/**
+ * A {@link DataViewRepository} over a plain array: filtering, searching, sorting and
+ * paging all happen client-side inside the repository, so the DataView stays a pure
+ * renderer of {@link DataViewResult} pages.
+ *
+ * @example
+ * ```ts
+ * const repo = new InMemoryDataViewRepository(tickets, {
+ *   getRowId: (t) => t.id,
+ *   getValue: (t, col) => t[col as keyof Ticket],
+ *   searchFields: ["title", "assignee"],
+ * });
+ * ```
+ */
+export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
+  readonly capabilities: DataViewRepository<T>["capabilities"];
+
+  private rows: T[];
+  private readonly options: InMemoryDataViewRepositoryOptions<T>;
+
+  constructor(rows: T[], options: InMemoryDataViewRepositoryOptions<T>) {
+    this.rows = rows;
+    this.options = options;
+    this.capabilities = {
+      serverSide: false,
+      search: (options.searchFields ?? []).length > 0,
+      searchScope: false,
+    };
+  }
+
+  getRowId(row: T): string {
+    return this.options.getRowId(row);
+  }
+
+  /** Replace the backing rows (e.g. after a caller-side refetch). */
+  setRows(rows: T[]): void {
+    this.rows = rows;
+  }
+
+  /** Distinct values of one column across the full (unfiltered) data set. */
+  getFacetedValues(columnId: string): unknown[] {
+    const seen = new Set<unknown>();
+    for (const row of this.rows) {
+      seen.add(this.options.getValue(row, columnId));
+    }
+    return [...seen];
+  }
+
+  query(q: DataViewQuery): Promise<DataViewResult<T>> {
+    let result = this.rows;
+
+    for (const filter of q.filters) {
+      result = result.filter((row) => {
+        if (this.options.matchesFilter !== undefined) {
+          return this.options.matchesFilter(row, filter.id, filter.value);
+        }
+        return defaultMatchesFilter(this.options.getValue(row, filter.id), filter.value);
+      });
+    }
+
+    const search = q.search.trim().toLowerCase();
+    const searchFields = this.options.searchFields ?? [];
+    if (search !== "" && searchFields.length > 0) {
+      result = result.filter((row) =>
+        searchFields.some((field) =>
+          String(this.options.getValue(row, field) ?? "")
+            .toLowerCase()
+            .includes(search),
+        ),
+      );
+    }
+
+    if (q.sorting.length > 0) {
+      result = [...result].sort((a, b) => {
+        for (const sort of q.sorting) {
+          const order = compareValues(
+            this.options.getValue(a, sort.id),
+            this.options.getValue(b, sort.id),
+          );
+          if (order !== 0) {
+            return sort.desc ? -order : order;
+          }
+        }
+        return 0;
+      });
+    }
+
+    const totalCount = result.length;
+    const start = q.pagination.pageIndex * q.pagination.pageSize;
+    return Promise.resolve({
+      rows: result.slice(start, start + q.pagination.pageSize),
+      totalCount,
+    });
+  }
+}

package/src/dataview/repositories/repositories.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { HttpDataViewRepository } from "./HttpDataViewRepository";
+import { InMemoryDataViewRepository } from "./InMemoryDataViewRepository";
+import type { DataViewQuery } from "../types";
+
+interface Ticket {
+  id: string;
+  title: string;
+  priority: number;
+  status: string;
+}
+
+const TICKETS: Ticket[] = [
+  { id: "1", title: "Broken printer", priority: 2, status: "open" },
+  { id: "2", title: "VPN access", priority: 1, status: "closed" },
+  { id: "3", title: "New laptop", priority: 3, status: "open" },
+  { id: "4", title: "Password reset", priority: 1, status: "open" },
+];
+
+function repo(rows: Ticket[] = TICKETS) {
+  return new InMemoryDataViewRepository(rows, {
+    getRowId: (t) => t.id,
+    getValue: (t, col) => t[col as keyof Ticket],
+    searchFields: ["title"],
+  });
+}
+
+function query(patch: Partial<DataViewQuery> = {}): DataViewQuery {
+  return {
+    pagination: { pageIndex: 0, pageSize: 10 },
+    sorting: [],
+    filters: [],
+    search: "",
+    searchBroadened: false,
+    ...patch,
+  };
+}
+
+describe("InMemoryDataViewRepository", () => {
+  it("returns all rows with the total count", async () => {
+    const result = await repo().query(query());
+    expect(result.rows).toHaveLength(4);
+    expect(result.totalCount).toBe(4);
+  });
+
+  it("pages with pageIndex/pageSize and keeps the filtered total", async () => {
+    const result = await repo().query(query({ pagination: { pageIndex: 1, pageSize: 3 } }));
+    expect(result.rows).toHaveLength(1);
+    expect(result.totalCount).toBe(4);
+  });
+
+  it("sorts ascending and descending", async () => {
+    const asc = await repo().query(query({ sorting: [{ id: "priority", desc: false }] }));
+    expect(asc.rows.map((t) => t.priority)).toEqual([1, 1, 2, 3]);
+    const desc = await repo().query(query({ sorting: [{ id: "title", desc: true }] }));
+    expect(desc.rows[0]?.title).toBe("VPN access");
+  });
+
+  it("searches case-insensitively across the configured fields", async () => {
+    const result = await repo().query(query({ search: "LAPTOP" }));
+    expect(result.rows.map((t) => t.id)).toEqual(["3"]);
+    expect(result.totalCount).toBe(1);
+  });
+
+  it("applies faceted-equality filters (single and any-of)", async () => {
+    const single = await repo().query(query({ filters: [{ id: "status", value: "closed" }] }));
+    expect(single.rows.map((t) => t.id)).toEqual(["2"]);
+    const anyOf = await repo().query(query({ filters: [{ id: "priority", value: [1, 3] }] }));
+    expect(anyOf.rows.map((t) => t.id)).toEqual(["2", "3", "4"]);
+  });
+
+  it("exposes faceted unique values across the full data set", () => {
+    expect(repo().getFacetedValues("status")).toEqual(["open", "closed"]);
+  });
+
+  it("advertises client-side capabilities (search only when fields are configured)", () => {
+    expect(repo().capabilities).toEqual({ serverSide: false, search: true, searchScope: false });
+    const noSearch = new InMemoryDataViewRepository(TICKETS, {
+      getRowId: (t) => t.id,
+      getValue: (t, col) => t[col as keyof Ticket],
+    });
+    expect(noSearch.capabilities.search).toBe(false);
+  });
+});
+
+describe("HttpDataViewRepository", () => {
+  it("maps the query to skip/limit/sort/filter/search params", async () => {
+    const request = vi.fn().mockResolvedValue({ items: [TICKETS[0]], total: 41 });
+    const http = new HttpDataViewRepository<Ticket>({ request, getRowId: (t) => t.id });
+
+    const result = await http.query(
+      query({
+        pagination: { pageIndex: 2, pageSize: 25 },
+        sorting: [
+          { id: "title", desc: false },
+          { id: "priority", desc: true },
+        ],
+        filters: [{ id: "status", value: "open" }],
+        search: "printer",
+        searchBroadened: true,
+      }),
+    );
+
+    expect(request).toHaveBeenCalledWith(
+      {
+        skip: 50,
+        limit: 25,
+        sort: ["title", "-priority"],
+        filters: { status: "open" },
+        search: "printer",
+        searchBroadened: true,
+      },
+      undefined,
+    );
+    expect(result).toEqual({ rows: [TICKETS[0]], totalCount: 41 });
+  });
+
+  it("forwards the abort signal to the adapter", async () => {
+    const request = vi.fn().mockResolvedValue({ items: [], total: 0 });
+    const http = new HttpDataViewRepository<Ticket>({ request, getRowId: (t) => t.id });
+    const controller = new AbortController();
+    await http.query(query(), controller.signal);
+    expect(request.mock.calls[0]?.[1]).toBe(controller.signal);
+  });
+
+  it("advertises server-side capabilities from its options", () => {
+    const http = new HttpDataViewRepository<Ticket>({
+      request: vi.fn(),
+      getRowId: (t) => t.id,
+      search: false,
+      searchScope: true,
+    });
+    expect(http.capabilities).toEqual({ serverSide: true, search: false, searchScope: true });
+  });
+
+  it("clamps the limit at the platform pagination cap (embedded views ask for everything)", async () => {
+    // The backend refuses limit > PAGINATION_MAX_LIMIT (default 200) with a 422; an
+    // embedded DataView's render-all page size must degrade, not fail.
+    const request = vi.fn().mockResolvedValue({ items: [], total: 0 });
+    const http = new HttpDataViewRepository<Ticket>({ request, getRowId: (t) => t.id });
+    await http.query(query({ pagination: { pageIndex: 0, pageSize: 10_000 } }));
+    expect(request.mock.calls[0]?.[0].limit).toBe(200);
+
+    // Windows stay consistent past page 0: skip is computed from the CLAMPED page
+    // size, so page N is the N-th 200-row window (never skip=10000&limit=200).
+    await http.query(query({ pagination: { pageIndex: 1, pageSize: 10_000 } }));
+    expect(request.mock.calls[1]?.[0]).toMatchObject({ skip: 200, limit: 200 });
+
+    const widened = new HttpDataViewRepository<Ticket>({
+      request,
+      getRowId: (t) => t.id,
+      maxLimit: 500,
+    });
+    await widened.query(query({ pagination: { pageIndex: 0, pageSize: 10_000 } }));
+    expect(request.mock.calls[2]?.[0].limit).toBe(500);
+  });
+});

package/src/dataview/repositories/viewState.test.ts

@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  InMemoryViewStateRepository,
+  LocalStorageViewStateRepository,
+} from "./viewState";
+import { emptyDataViewState } from "../types";
+import type { DataViewState } from "../types";
+
+function sampleState(): DataViewState {
+  return {
+    columnVisibility: { status: false },
+    columnOrder: ["title", "status"],
+    columnSizing: { title: 240 },
+    sorting: [{ id: "title", desc: true }],
+    filters: [{ id: "status", value: "open" }],
+    search: "printer",
+  };
+}
+
+describe("LocalStorageViewStateRepository", () => {
+  beforeEach(() => window.localStorage.clear());
+  afterEach(() => window.localStorage.clear());
+
+  it("round-trips a state per viewId", () => {
+    const repo = new LocalStorageViewStateRepository();
+    repo.save("tickets.list", sampleState());
+    expect(repo.load("tickets.list")).toEqual(sampleState());
+  });
+
+  it("isolates views from each other", () => {
+    const repo = new LocalStorageViewStateRepository();
+    repo.save("a", sampleState());
+    repo.save("b", { ...emptyDataViewState(), search: "other" });
+    expect(repo.load("a")?.search).toBe("printer");
+    expect(repo.load("b")?.search).toBe("other");
+  });
+
+  it("returns undefined when nothing was persisted", () => {
+    expect(new LocalStorageViewStateRepository().load("missing")).toBeUndefined();
+  });
+
+  it("falls back to defaults on corrupt JSON", () => {
+    window.localStorage.setItem("terp.dataview.bad", "{not json");
+    expect(new LocalStorageViewStateRepository().load("bad")).toBeUndefined();
+  });
+
+  it("falls back to defaults on a wrong envelope version", () => {
+    window.localStorage.setItem(
+      "terp.dataview.old",
+      JSON.stringify({ version: 999, state: sampleState() }),
+    );
+    expect(new LocalStorageViewStateRepository().load("old")).toBeUndefined();
+  });
+
+  it("falls back to defaults on schema-invalid state shapes", () => {
+    window.localStorage.setItem(
+      "terp.dataview.shape",
+      JSON.stringify({
+        version: 1,
+        state: { ...sampleState(), columnSizing: { title: "wide" } },
+      }),
+    );
+    expect(new LocalStorageViewStateRepository().load("shape")).toBeUndefined();
+  });
+
+  it("supports a custom key prefix", () => {
+    const repo = new LocalStorageViewStateRepository("myapp.views");
+    repo.save("v", sampleState());
+    expect(window.localStorage.getItem("myapp.views.v")).not.toBeNull();
+  });
+});
+
+describe("InMemoryViewStateRepository", () => {
+  it("round-trips per viewId and isolates views", () => {
+    const repo = new InMemoryViewStateRepository();
+    repo.save("a", sampleState());
+    expect(repo.load("a")).toEqual(sampleState());
+    expect(repo.load("b")).toBeUndefined();
+  });
+
+  it("returns copies so stored state cannot be mutated in place", () => {
+    const repo = new InMemoryViewStateRepository();
+    repo.save("a", sampleState());
+    const loaded = repo.load("a");
+    loaded!.columnSizing.title = 1;
+    expect(repo.load("a")?.columnSizing.title).toBe(240);
+  });
+});

package/src/dataview/repositories/viewState.ts

@@ -0,0 +1,128 @@
+import type { DataViewState, ViewStateRepository } from "../types";
+import { emptyDataViewState } from "../types";
+
+/** Version of the persisted envelope; bump when {@link DataViewState}'s shape changes. */
+const ENVELOPE_VERSION = 1;
+
+interface Envelope {
+  version: number;
+  state: DataViewState;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isSorting(value: unknown): value is { id: string; desc: boolean }[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (entry) =>
+        isRecord(entry) && typeof entry.id === "string" && typeof entry.desc === "boolean",
+    )
+  );
+}
+
+function isFilters(value: unknown): value is { id: string; value: unknown }[] {
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => isRecord(entry) && typeof entry.id === "string" && "value" in entry)
+  );
+}
+
+function isRecordOf(value: unknown, kind: "boolean" | "number"): boolean {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === kind);
+}
+
+/** Validate a parsed envelope; anything malformed falls back to `undefined` (defaults). */
+function parseEnvelope(raw: string): DataViewState | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || parsed.version !== ENVELOPE_VERSION || !isRecord(parsed.state)) {
+    return undefined;
+  }
+  const state = parsed.state;
+  if (
+    !isRecordOf(state.columnVisibility, "boolean") ||
+    !isStringArray(state.columnOrder) ||
+    !isRecordOf(state.columnSizing, "number") ||
+    !isSorting(state.sorting) ||
+    !isFilters(state.filters) ||
+    typeof state.search !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    columnVisibility: state.columnVisibility as Record<string, boolean>,
+    columnOrder: state.columnOrder,
+    columnSizing: state.columnSizing as Record<string, number>,
+    sorting: state.sorting,
+    filters: state.filters,
+    search: state.search,
+  };
+}
+
+/**
+ * {@link ViewStateRepository} over `localStorage`, storing a schema-validated, versioned
+ * envelope per `viewId`. Corrupt or outdated data (bad JSON, wrong version, wrong shapes)
+ * is treated as "nothing persisted" so the view falls back to its defaults; storage
+ * failures (quota, privacy mode) are swallowed — preferences are best-effort.
+ */
+export class LocalStorageViewStateRepository implements ViewStateRepository {
+  private readonly prefix: string;
+
+  constructor(prefix = "terp.dataview") {
+    this.prefix = prefix;
+  }
+
+  private key(viewId: string): string {
+    return `${this.prefix}.${viewId}`;
+  }
+
+  load(viewId: string): DataViewState | undefined {
+    let raw: string | null;
+    try {
+      raw = window.localStorage.getItem(this.key(viewId));
+    } catch {
+      return undefined;
+    }
+    return raw === null ? undefined : parseEnvelope(raw);
+  }
+
+  save(viewId: string, state: DataViewState): void {
+    const envelope: Envelope = { version: ENVELOPE_VERSION, state };
+    try {
+      window.localStorage.setItem(this.key(viewId), JSON.stringify(envelope));
+    } catch {
+      // Best-effort persistence: never let a full/blocked storage break the view.
+    }
+  }
+}
+
+/**
+ * {@link ViewStateRepository} in memory — for tests and for views without a `viewId`
+ * (preferences last for the component's lifetime only).
+ */
+export class InMemoryViewStateRepository implements ViewStateRepository {
+  private readonly store = new Map<string, DataViewState>();
+
+  load(viewId: string): DataViewState | undefined {
+    const state = this.store.get(viewId);
+    // Return a copy so callers can't mutate the stored state in place.
+    return state === undefined ? undefined : structuredClone(state);
+  }
+
+  save(viewId: string, state: DataViewState): void {
+    this.store.set(viewId, structuredClone(state));
+  }
+}
+
+export { emptyDataViewState };