@terpjs/react-core 0.1.0

package/src/dataview/hooks/useDataViewState.ts

@@ -0,0 +1,310 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+
+import type {
+  DataViewColumn,
+  DataViewState,
+  ViewStateRepository,
+} from "../types";
+import { emptyDataViewState } from "../types";
+
+export type DataViewSorting = { id: string; desc: boolean }[];
+export type DataViewFilters = { id: string; value: unknown }[];
+export interface DataViewPaginationState {
+  pageIndex: number;
+  pageSize: number;
+}
+
+/**
+ * Externally controlled query state (server-side views): {@link useServerDataView}
+ * produces this shape from the URL; passing it makes the hook delegate sorting /
+ * filters / search / pagination instead of owning them.
+ */
+export interface DataViewControlledQuery {
+  sorting: DataViewSorting;
+  filters: DataViewFilters;
+  search: string;
+  pagination: DataViewPaginationState;
+  onSortingChange: (sorting: DataViewSorting) => void;
+  onFiltersChange: (filters: DataViewFilters) => void;
+  onSearchChange: (search: string) => void;
+  onPaginationChange: (pagination: DataViewPaginationState) => void;
+}
+
+export interface UseDataViewStateOptions<T> {
+  /** Stable key for persisted preferences; omit to keep preferences in memory only. */
+  viewId?: string;
+  columns: DataViewColumn<T>[];
+  /** Persistence seam; without it (or without a viewId) nothing is persisted. */
+  viewStateRepository?: ViewStateRepository;
+  /** Server-side views keep sorting/filters/search out of the persisted state. */
+  serverSide: boolean;
+  initialPageSize: number;
+  /** Present for server-side views driven by {@link useServerDataView}. */
+  controlledQuery?: DataViewControlledQuery;
+}
+
+export interface UseDataViewStateResult<T> {
+  sorting: DataViewSorting;
+  /** 3-state toggle for one column: asc → desc → none. */
+  toggleSort: (columnId: string) => void;
+  filters: DataViewFilters;
+  setFilter: (columnId: string, value: unknown) => void;
+  clearFilters: () => void;
+  search: string;
+  setSearch: (search: string) => void;
+  pagination: DataViewPaginationState;
+  setPagination: (pagination: DataViewPaginationState) => void;
+  columnVisibility: Record<string, boolean>;
+  setColumnVisible: (columnId: string, visible: boolean) => void;
+  columnOrder: string[];
+  /** Reorder a user column one step (system columns are not part of this order). */
+  moveColumn: (columnId: string, direction: -1 | 1) => void;
+  columnSizing: Record<string, number>;
+  /** Commit resized widths (called once per drag, on pointer-up). */
+  commitColumnSizing: (sizing: Record<string, number>) => void;
+  /** The user columns in effective order (persisted order first, new columns appended). */
+  orderedColumns: DataViewColumn<T>[];
+  /** The ordered columns that are currently visible. */
+  visibleColumns: DataViewColumn<T>[];
+}
+
+function orderColumns<T>(columns: DataViewColumn<T>[], order: string[]): DataViewColumn<T>[] {
+  if (order.length === 0) {
+    return columns;
+  }
+  const byId = new Map(columns.map((column) => [column.id, column]));
+  const ordered: DataViewColumn<T>[] = [];
+  for (const id of order) {
+    const column = byId.get(id);
+    if (column !== undefined) {
+      ordered.push(column);
+      byId.delete(id);
+    }
+  }
+  // Columns added after the order was persisted keep their declared position at the end.
+  ordered.push(...byId.values());
+  return ordered;
+}
+
+/**
+ * The headless state engine behind {@link DataView}: view preferences (column
+ * visibility / order / sizing) always live here and persist through the
+ * {@link ViewStateRepository}; the query state (sorting / filters / search /
+ * pagination) is owned here for client-side views and delegated to
+ * `controlledQuery` for server-side ones.
+ */
+export function useDataViewState<T>({
+  viewId,
+  columns,
+  viewStateRepository,
+  serverSide,
+  initialPageSize,
+  controlledQuery,
+}: UseDataViewStateOptions<T>): UseDataViewStateResult<T> {
+  // Load persisted state exactly once (lazy initializer); corrupt data already fell
+  // back to `undefined` inside the repository.
+  const [persisted] = useState<DataViewState | undefined>(() =>
+    viewId !== undefined && viewStateRepository !== undefined
+      ? viewStateRepository.load(viewId)
+      : undefined,
+  );
+
+  const [ownSorting, setOwnSorting] = useState<DataViewSorting>(
+    serverSide ? [] : (persisted?.sorting ?? []),
+  );
+  const [ownFilters, setOwnFilters] = useState<DataViewFilters>(
+    serverSide ? [] : (persisted?.filters ?? []),
+  );
+  const [ownSearch, setOwnSearch] = useState<string>(serverSide ? "" : (persisted?.search ?? ""));
+  const [ownPagination, setOwnPagination] = useState<DataViewPaginationState>({
+    pageIndex: 0,
+    pageSize: initialPageSize,
+  });
+  const [columnVisibility, setColumnVisibility] = useState<Record<string, boolean>>(
+    persisted?.columnVisibility ?? {},
+  );
+  const [columnOrder, setColumnOrder] = useState<string[]>(persisted?.columnOrder ?? []);
+  const [columnSizing, setColumnSizing] = useState<Record<string, number>>(
+    persisted?.columnSizing ?? {},
+  );
+
+  const sorting = controlledQuery?.sorting ?? ownSorting;
+  const filters = controlledQuery?.filters ?? ownFilters;
+  const search = controlledQuery?.search ?? ownSearch;
+  const pagination = controlledQuery?.pagination ?? ownPagination;
+
+  // Persist through a ref-held snapshot so the callbacks below stay stable and each
+  // save writes the full, current state.
+  const stateRef = useRef<DataViewState>(emptyDataViewState());
+  stateRef.current = {
+    columnVisibility,
+    columnOrder,
+    columnSizing,
+    sorting: serverSide ? [] : sorting,
+    filters: serverSide ? [] : filters,
+    search: serverSide ? "" : search,
+  };
+  const persistRef = useRef<(patch: Partial<DataViewState>) => void>(() => undefined);
+  persistRef.current = (patch) => {
+    if (viewId !== undefined && viewStateRepository !== undefined) {
+      viewStateRepository.save(viewId, { ...stateRef.current, ...patch });
+    }
+  };
+
+  const controlledRef = useRef(controlledQuery);
+  controlledRef.current = controlledQuery;
+  const queryRef = useRef({ sorting, filters, search, pagination });
+  queryRef.current = { sorting, filters, search, pagination };
+
+  const setSorting = useCallback(
+    (next: DataViewSorting) => {
+      if (controlledRef.current !== undefined) {
+        controlledRef.current.onSortingChange(next);
+        return;
+      }
+      setOwnSorting(next);
+      if (!serverSide) {
+        persistRef.current({ sorting: next });
+      }
+    },
+    [serverSide],
+  );
+
+  const toggleSort = useCallback(
+    (columnId: string) => {
+      const current = queryRef.current.sorting.find((sort) => sort.id === columnId);
+      const next: DataViewSorting =
+        current === undefined
+          ? [{ id: columnId, desc: false }]
+          : current.desc
+            ? []
+            : [{ id: columnId, desc: true }];
+      setSorting(next);
+    },
+    [setSorting],
+  );
+
+  const setPagination = useCallback((next: DataViewPaginationState) => {
+    if (controlledRef.current !== undefined) {
+      controlledRef.current.onPaginationChange(next);
+    } else {
+      setOwnPagination(next);
+    }
+  }, []);
+
+  const setFilters = useCallback(
+    (next: DataViewFilters) => {
+      if (controlledRef.current !== undefined) {
+        controlledRef.current.onFiltersChange(next);
+      } else {
+        setOwnFilters(next);
+        if (!serverSide) {
+          persistRef.current({ filters: next });
+        }
+      }
+      // A changed filter invalidates the current page position.
+      setPagination({ ...queryRef.current.pagination, pageIndex: 0 });
+    },
+    [serverSide, setPagination],
+  );
+
+  const setFilter = useCallback(
+    (columnId: string, value: unknown) => {
+      const rest = queryRef.current.filters.filter((filter) => filter.id !== columnId);
+      const cleared =
+        value === undefined || value === null || value === "" ||
+        (Array.isArray(value) && value.length === 0);
+      setFilters(cleared ? rest : [...rest, { id: columnId, value }]);
+    },
+    [setFilters],
+  );
+
+  const clearFilters = useCallback(() => {
+    setFilters([]);
+  }, [setFilters]);
+
+  const setSearch = useCallback(
+    (next: string) => {
+      if (controlledRef.current !== undefined) {
+        controlledRef.current.onSearchChange(next);
+      } else {
+        setOwnSearch(next);
+        if (!serverSide) {
+          persistRef.current({ search: next });
+        }
+      }
+      setPagination({ ...queryRef.current.pagination, pageIndex: 0 });
+    },
+    [serverSide, setPagination],
+  );
+
+  const setColumnVisible = useCallback((columnId: string, visible: boolean) => {
+    setColumnVisibility((current) => {
+      const next = { ...current, [columnId]: visible };
+      persistRef.current({ columnVisibility: next });
+      return next;
+    });
+  }, []);
+
+  const columnIds = useMemo(() => columns.map((column) => column.id), [columns]);
+
+  const moveColumn = useCallback(
+    (columnId: string, direction: -1 | 1) => {
+      setColumnOrder((current) => {
+        const effective = current.length > 0 ? [...current] : [...columnIds];
+        // Only known user columns take part; stale persisted ids are dropped.
+        const order = effective.filter((id) => columnIds.includes(id));
+        for (const id of columnIds) {
+          if (!order.includes(id)) {
+            order.push(id);
+          }
+        }
+        const from = order.indexOf(columnId);
+        const to = from + direction;
+        if (from === -1 || to < 0 || to >= order.length) {
+          return current;
+        }
+        const next = [...order];
+        next.splice(from, 1);
+        next.splice(to, 0, columnId);
+        persistRef.current({ columnOrder: next });
+        return next;
+      });
+    },
+    [columnIds],
+  );
+
+  const commitColumnSizing = useCallback((sizing: Record<string, number>) => {
+    setColumnSizing((current) => {
+      const next = { ...current, ...sizing };
+      persistRef.current({ columnSizing: next });
+      return next;
+    });
+  }, []);
+
+  const orderedColumns = useMemo(() => orderColumns(columns, columnOrder), [columns, columnOrder]);
+  const visibleColumns = useMemo(
+    () => orderedColumns.filter((column) => columnVisibility[column.id] !== false),
+    [orderedColumns, columnVisibility],
+  );
+
+  return {
+    sorting,
+    toggleSort,
+    filters,
+    setFilter,
+    clearFilters,
+    search,
+    setSearch,
+    pagination,
+    setPagination,
+    columnVisibility,
+    setColumnVisible,
+    columnOrder,
+    moveColumn,
+    columnSizing,
+    commitColumnSizing,
+    orderedColumns,
+    visibleColumns,
+  };
+}

package/src/dataview/hooks/useServerDataView.ts

@@ -0,0 +1,154 @@
+import { useCallback, useEffect, useState } from "react";
+
+import type {
+  DataViewControlledQuery,
+  DataViewFilters,
+  DataViewPaginationState,
+  DataViewSorting,
+} from "./useDataViewState";
+
+export interface UseServerDataViewOptions {
+  /** Prefix for the URL parameters, so several views can share one page. */
+  paramPrefix?: string;
+  initialPageSize?: number;
+}
+
+interface UrlQueryState {
+  sorting: DataViewSorting;
+  filters: DataViewFilters;
+  search: string;
+  pagination: DataViewPaginationState;
+}
+
+function readUrlState(prefix: string, initialPageSize: number): UrlQueryState {
+  const params = new URLSearchParams(window.location.search);
+  const read = (key: string) => params.get(prefix === "" ? key : `${prefix}.${key}`);
+
+  const page = Number(read("page") ?? "1");
+  const size = Number(read("size") ?? String(initialPageSize));
+  const sorting: DataViewSorting = (read("sort") ?? "")
+    .split(",")
+    .filter((entry) => entry !== "")
+    .map((entry) =>
+      entry.startsWith("-") ? { id: entry.slice(1), desc: true } : { id: entry, desc: false },
+    );
+
+  let filters: DataViewFilters = [];
+  const rawFilters = read("filters");
+  if (rawFilters !== null) {
+    try {
+      const parsed: unknown = JSON.parse(rawFilters);
+      if (Array.isArray(parsed)) {
+        filters = parsed.filter(
+          (entry): entry is { id: string; value: unknown } =>
+            typeof entry === "object" && entry !== null && typeof (entry as { id?: unknown }).id === "string",
+        );
+      }
+    } catch {
+      // A malformed filters param falls back to no filters.
+    }
+  }
+
+  return {
+    sorting,
+    filters,
+    search: read("q") ?? "",
+    pagination: {
+      pageIndex: Number.isFinite(page) && page >= 1 ? page - 1 : 0,
+      pageSize: Number.isFinite(size) && size > 0 ? size : initialPageSize,
+    },
+  };
+}
+
+function writeUrlState(prefix: string, state: UrlQueryState, initialPageSize: number): void {
+  const params = new URLSearchParams(window.location.search);
+  const set = (key: string, value: string | undefined) => {
+    const name = prefix === "" ? key : `${prefix}.${key}`;
+    if (value === undefined) {
+      params.delete(name);
+    } else {
+      params.set(name, value);
+    }
+  };
+
+  set("page", state.pagination.pageIndex > 0 ? String(state.pagination.pageIndex + 1) : undefined);
+  set(
+    "size",
+    state.pagination.pageSize !== initialPageSize ? String(state.pagination.pageSize) : undefined,
+  );
+  set(
+    "sort",
+    state.sorting.length > 0
+      ? state.sorting.map((sort) => (sort.desc ? `-${sort.id}` : sort.id)).join(",")
+      : undefined,
+  );
+  set("filters", state.filters.length > 0 ? JSON.stringify(state.filters) : undefined);
+  set("q", state.search !== "" ? state.search : undefined);
+
+  const query = params.toString();
+  const url = `${window.location.pathname}${query === "" ? "" : `?${query}`}${window.location.hash}`;
+  window.history.replaceState(window.history.state, "", url);
+}
+
+/**
+ * Query state for **server-side** views, kept in the URL (page, size, sort, filters,
+ * search) so a view survives reloads and can be deep-linked — the server-side analog
+ * of the client-side persistence a {@link ViewStateRepository} provides.
+ *
+ * @example
+ * ```tsx
+ * const server = useServerDataView({ initialPageSize: 25 });
+ * <DataView repository={httpRepo} columns={columns} serverQuery={server} />
+ * ```
+ */
+export function useServerDataView({
+  paramPrefix = "",
+  initialPageSize = 10,
+}: UseServerDataViewOptions = {}): DataViewControlledQuery {
+  const [state, setState] = useState<UrlQueryState>(() =>
+    readUrlState(paramPrefix, initialPageSize),
+  );
+
+  // Re-read on history navigation so back/forward restores the view.
+  useEffect(() => {
+    const onPopState = () => setState(readUrlState(paramPrefix, initialPageSize));
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [paramPrefix, initialPageSize]);
+
+  const update = useCallback(
+    (patch: Partial<UrlQueryState>) => {
+      setState((current) => {
+        const next = { ...current, ...patch };
+        writeUrlState(paramPrefix, next, initialPageSize);
+        return next;
+      });
+    },
+    [paramPrefix, initialPageSize],
+  );
+
+  const onSortingChange = useCallback(
+    (sorting: DataViewSorting) => update({ sorting }),
+    [update],
+  );
+  const onFiltersChange = useCallback(
+    (filters: DataViewFilters) => update({ filters }),
+    [update],
+  );
+  const onSearchChange = useCallback((search: string) => update({ search }), [update]);
+  const onPaginationChange = useCallback(
+    (pagination: DataViewPaginationState) => update({ pagination }),
+    [update],
+  );
+
+  return {
+    sorting: state.sorting,
+    filters: state.filters,
+    search: state.search,
+    pagination: state.pagination,
+    onSortingChange,
+    onFiltersChange,
+    onSearchChange,
+    onPaginationChange,
+  };
+}

package/src/dataview/hooks/useViewSearch.ts

@@ -0,0 +1,68 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseViewSearchResult {
+  /** The immediate input value (what the user is typing). */
+  inputValue: string;
+  /** Update the input; the outer `onChange` fires after the debounce window. */
+  setInputValue: (value: string) => void;
+  /** Clear the input and emit "" immediately (the × button). */
+  clear: () => void;
+}
+
+/**
+ * Controlled search-input state with an optional debounce: the input updates
+ * immediately, the outer `onChange` (which typically triggers a repository query)
+ * fires only after `debounceMs` of quiet. External changes to `value` (e.g. a
+ * "clear filters" reset) sync back into the input.
+ */
+export function useViewSearch(
+  value: string,
+  onChange: (value: string) => void,
+  debounceMs = 0,
+): UseViewSearchResult {
+  const [inputValue, setInput] = useState(value);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  // Track the last value we emitted, so an echo of our own change does not clobber
+  // what the user typed since.
+  const lastEmittedRef = useRef(value);
+
+  useEffect(() => {
+    if (value !== lastEmittedRef.current) {
+      // An external reset wins: cancel any pending debounced emit so it cannot
+      // resurrect the value the caller just cleared.
+      clearTimeout(timerRef.current);
+      lastEmittedRef.current = value;
+      setInput(value);
+    }
+  }, [value]);
+
+  useEffect(() => () => clearTimeout(timerRef.current), []);
+
+  const emit = useCallback((next: string) => {
+    lastEmittedRef.current = next;
+    onChangeRef.current(next);
+  }, []);
+
+  const setInputValue = useCallback(
+    (next: string) => {
+      setInput(next);
+      clearTimeout(timerRef.current);
+      if (debounceMs <= 0) {
+        emit(next);
+      } else {
+        timerRef.current = setTimeout(() => emit(next), debounceMs);
+      }
+    },
+    [debounceMs, emit],
+  );
+
+  const clear = useCallback(() => {
+    setInput("");
+    clearTimeout(timerRef.current);
+    emit("");
+  }, [emit]);
+
+  return { inputValue, setInputValue, clear };
+}

package/src/dataview/index.ts

@@ -0,0 +1,62 @@
+// The DataView family — the single sanctioned surface for rendering data collections.
+// See ./README.md for usage.
+export { DataView } from "./DataView";
+export type { DataViewProps } from "./DataView";
+export { DataViewToolbar } from "./DataViewToolbar";
+export type { DataViewToolbarProps } from "./DataViewToolbar";
+export { DataViewPagination } from "./DataViewPagination";
+export type { DataViewPaginationProps } from "./DataViewPagination";
+export { DataViewColumnSettings } from "./DataViewColumnSettings";
+export type { DataViewColumnSettingsProps } from "./DataViewColumnSettings";
+export { DataViewRowActions } from "./DataViewRowActions";
+export type { DataViewRowActionsLayout, DataViewRowActionsProps } from "./DataViewRowActions";
+export { DataViewExpandableRow, DataViewExpandToggle } from "./DataViewExpandableRow";
+export { DataViewCardList } from "./DataViewCardList";
+export type { DataViewCardListProps } from "./DataViewCardList";
+export { DataViewTable } from "./DataViewTable";
+export type { DataViewTableProps } from "./DataViewTable";
+
+export type {
+  DataViewQuery,
+  DataViewResult,
+  DataViewRepository,
+  DataViewState,
+  ViewStateRepository,
+  DataViewColumn,
+  DataViewColumnMeta,
+  DataViewMobileSlot,
+  DataViewRowAction,
+  DataViewBatchAction,
+  DataViewSearchScope,
+  DataViewStrings,
+} from "./types";
+export { DEFAULT_DATA_VIEW_STRINGS, emptyDataViewState } from "./types";
+
+export { InMemoryDataViewRepository } from "./repositories/InMemoryDataViewRepository";
+export type { InMemoryDataViewRepositoryOptions } from "./repositories/InMemoryDataViewRepository";
+export { HttpDataViewRepository } from "./repositories/HttpDataViewRepository";
+export type {
+  HttpDataViewParams,
+  HttpDataViewRepositoryOptions,
+  HttpRequestAdapter,
+} from "./repositories/HttpDataViewRepository";
+export {
+  InMemoryViewStateRepository,
+  LocalStorageViewStateRepository,
+} from "./repositories/viewState";
+
+export { useDataViewState } from "./hooks/useDataViewState";
+export type {
+  DataViewControlledQuery,
+  DataViewFilters,
+  DataViewPaginationState,
+  DataViewSorting,
+  UseDataViewStateOptions,
+  UseDataViewStateResult,
+} from "./hooks/useDataViewState";
+export { useServerDataView } from "./hooks/useServerDataView";
+export type { UseServerDataViewOptions } from "./hooks/useServerDataView";
+export { useViewSearch } from "./hooks/useViewSearch";
+export type { UseViewSearchResult } from "./hooks/useViewSearch";
+export { useDataViewQuery } from "./hooks/useDataViewQuery";
+export type { UseDataViewQueryResult } from "./hooks/useDataViewQuery";

package/src/dataview/internal.tsx

@@ -0,0 +1,96 @@
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { Menu, MenuItem } from "../ui/Menu";
+import { useUiText } from "../uiText";
+import type { ResolveUiText, UiText } from "../uiText";
+import { DEFAULT_DATA_VIEW_STRINGS, formatDataViewString } from "./types";
+import type { DataViewStrings } from "./types";
+
+injectTerpStyles();
+
+/** Internal: merged strings + resolver every DataView sub-component reads. */
+export interface DataViewTextApi {
+  strings: DataViewStrings;
+  resolve: ResolveUiText;
+  /** Resolve a countable string and fill its `{placeholder}`s. */
+  format: (text: UiText, values: Record<string, string | number>) => string;
+}
+
+const DataViewTextContext = createContext<DataViewTextApi>({
+  strings: DEFAULT_DATA_VIEW_STRINGS,
+  resolve: (text) => (typeof text === "string" ? text : text.message),
+  format: (text, values) =>
+    formatDataViewString(typeof text === "string" ? text : text.message, values),
+});
+
+export function useDataViewText(): DataViewTextApi {
+  return useContext(DataViewTextContext);
+}
+
+export function DataViewTextProvider({
+  overrides,
+  children,
+}: {
+  overrides?: Partial<DataViewStrings>;
+  children: ReactNode;
+}) {
+  const resolve = useUiText();
+  const strings: DataViewStrings = { ...DEFAULT_DATA_VIEW_STRINGS, ...overrides };
+  const api: DataViewTextApi = {
+    strings,
+    resolve,
+    format: (text, values) => formatDataViewString(resolve(text), values),
+  };
+  return <DataViewTextContext.Provider value={api}>{children}</DataViewTextContext.Provider>;
+}
+
+/**
+ * Internal DataView wrapper over the shared react-core Menu primitive.
+ */
+export function DataViewMenu({
+  trigger,
+  triggerLabel,
+  align = "end",
+  children,
+}: {
+  /** Trigger content (an icon or a label). */
+  trigger: ReactNode;
+  /** Accessible name of the trigger button. */
+  triggerLabel: string;
+  align?: "start" | "end";
+  /** Panel content; render-prop so items can close the menu after acting. */
+  children: (close: () => void) => ReactNode;
+}) {
+  return (
+    <Menu trigger={trigger} triggerLabel={triggerLabel} align={align}>
+      {({ close }) => children(() => close(false))}
+    </Menu>
+  );
+}
+
+/** Internal: one item inside a {@link DataViewMenu}. */
+export function DataViewMenuItem({
+  label,
+  destructive = false,
+  disabled = false,
+  icon,
+  onSelect,
+}: {
+  label: string;
+  destructive?: boolean;
+  disabled?: boolean;
+  icon?: ReactNode;
+  onSelect: () => void;
+}) {
+  return (
+    <MenuItem
+      label={label}
+      icon={icon}
+      destructive={destructive}
+      disabled={disabled}
+      onSelect={onSelect}
+    />
+  );
+}