cortena-ui 1.3.0 → 1.4.0

package/dist/components/data-table/types.d.ts

@@ -0,0 +1,172 @@
+"use client";
+import { DataTableFeatures } from "./features.js";
+import { Cell, Column, ColumnDef, ReactTable, Row, RowData, TableState } from "@tanstack/react-table";
+//#region src/components/data-table/types.d.ts
+/**
+ * Data sources (the contract in cortenaUI&Design/04-data-tables.md).
+ *
+ * A client source hands the table every row and lets it filter, sort and page
+ * in memory. A server source hands the table one page at a time: the table
+ * owns the search box, filter, sort and page state, turns it into a
+ * `TableQuery`, and the app answers with the already filtered, sorted page and
+ * the total. `TableQuery` / `TableResult` are also the backend contract every
+ * extension's list endpoint is expected to speak.
+ */
+export type ClientSource<Row> = {
+  kind: "client";
+  rows: Row[];
+};
+export type ServerSource<Row> = {
+  kind: "server";
+  /**
+   * Fetch one page. The optional `signal` is aborted when the query changes
+   * before the request settles, so a fetch that forwards it to `fetch()` is
+   * cancelled rather than raced.
+   */
+  fetch: (query: TableQuery, signal?: AbortSignal) => Promise<TableResult<Row>>;
+  /**
+   * TanStack Query cache scope. Two tables that share a key share pages;
+   * defaults to a key private to the component instance.
+   */
+  queryKey?: readonly unknown[];
+};
+export type DataSource<Row> = ClientSource<Row> | ServerSource<Row>;
+export type TableQuery = {
+  q?: string;
+  filters?: Array<{
+    id: string;
+    value: unknown;
+  }>;
+  sort?: Array<{
+    id: string;
+    desc: boolean;
+  }>;
+  page: number;
+  pageSize: number;
+};
+export type TableResult<Row> = {
+  rows: Row[];
+  total: number;
+};
+/** Inline-editing options for a column (`meta.editable`). */
+export interface DataTableEditable {
+  /** Input type; `number` parses the draft with `Number()` before commit. */
+  type?: "text" | "number";
+  /** Turn the raw input string into the committed value. */
+  parse?: (raw: string) => unknown;
+}
+/**
+ * Per-column `meta`. Typed through the v9 `columnMeta` feature slot, so
+ * `helper.accessor("x", { meta: { ... } })` is checked without declaration
+ * merging.
+ */
+export interface DataTableColumnMeta<Row = unknown> {
+  /**
+   * Toolbar filter for this column. `faceted` renders a checkbox list of the
+   * column's distinct values (or `filterOptions`) and filters with `oneOf`.
+   */
+  filter?: "faceted" | "text";
+  /** Fixed facet options; required for a server source, where only one page is loaded. */
+  filterOptions?: Array<{
+    value: string | number | boolean;
+    label?: string;
+    icon?: React.ComponentType<{
+      className?: string;
+    }>;
+  }>;
+  /** Text alignment of the header and cells. Numbers usually want `end`. */
+  align?: "start" | "center" | "end";
+  /** Enter or double-click opens an editor; Enter commits, Escape cancels. */
+  editable?: boolean | DataTableEditable;
+  /** Receives the committed value. Falls back to the table's `onCellCommit`. */
+  onCommit?: (row: Row, columnId: string, value: unknown) => void | Promise<void>;
+  /** Column label for the view menu and exports when `header` is not a string. */
+  label?: string;
+  /** Set `false` to leave the column out of CSV / Excel exports. */
+  exportable?: boolean;
+  /** Value written to exports instead of the accessor value. */
+  exportValue?: (row: Row) => string | number | boolean | Date | null | undefined;
+  /** Extra classes for every cell in this column. */
+  cellClassName?: string;
+  /** Extra classes for the header cell. */
+  headerClassName?: string;
+}
+export type DataTableColumnDef<Row extends RowData, Value = unknown> = ColumnDef<DataTableFeatures<Row>, Row, Value>;
+export type DataTableColumn<Row extends RowData, Value = unknown> = Column<DataTableFeatures<Row>, Row, Value>;
+export type DataTableRow<Row$1 extends RowData> = Row<DataTableFeatures<Row$1>, Row$1>;
+export type DataTableCell<Row extends RowData, Value = unknown> = Cell<DataTableFeatures<Row>, Row, Value>;
+export type DataTableState<Row extends RowData> = TableState<DataTableFeatures<Row>>;
+/** The TanStack table instance every part takes as `table`. */
+export type DataTableTable<Row extends RowData> = ReactTable<DataTableFeatures<Row>, Row>;
+export type DataTablePaginationMode = "pages" | "infinite" | "none";
+export interface UseDataTableOptions<Row extends RowData> {
+  columns: ReadonlyArray<DataTableColumnDef<Row, any>>;
+  dataSource: DataSource<Row>;
+  /** Stable row identity; defaults to the row index. Needed for selection and editing to survive re-sorts. */
+  getRowId?: (row: Row, index: number) => string;
+  /** Tree data: return a row's children. */
+  getSubRows?: (row: Row, index: number) => Row[] | undefined;
+  /** `pages` (default) renders a pager; `infinite` appends pages on scroll; `none` shows every row. */
+  pagination?: DataTablePaginationMode;
+  /** @default 25 */
+  pageSize?: number;
+  /** Adds a checkbox column and enables `bulkActions`. */
+  enableRowSelection?: boolean | ((row: DataTableRow<Row>) => boolean);
+  /** Adds an expander column; set automatically by `renderSubComponent`. */
+  enableExpanding?: boolean;
+  getRowCanExpand?: (row: DataTableRow<Row>) => boolean;
+  /** @default true */
+  enableSorting?: boolean;
+  /** @default false */
+  enableMultiSort?: boolean;
+  /** @default true */
+  enableGlobalFilter?: boolean;
+  /** @default true */
+  enableColumnFilters?: boolean;
+  /** @default true */
+  enableHiding?: boolean;
+  /** @default true */
+  enableColumnPinning?: boolean;
+  /** @default false */
+  enableColumnResizing?: boolean;
+  /** Starting sort, filters, visibility, pinning, sizing. */
+  initialState?: Partial<DataTableState<Row>>;
+  /** Table-wide commit handler for editable cells without their own `meta.onCommit`. */
+  onCellCommit?: (row: Row, columnId: string, value: unknown) => void | Promise<void>;
+  /** Fires with the selected original rows whenever selection changes. */
+  onRowSelectionChange?: (rows: Row[]) => void;
+  /** Debounce applied to the search box before it reaches a server source. @default 250 */
+  searchDebounceMs?: number;
+}
+export interface DataTableEditingCell {
+  rowId: string;
+  columnId: string;
+}
+export interface DataTableInstance<Row extends RowData> {
+  table: DataTableTable<Row>;
+  dataSource: DataSource<Row>;
+  paginationMode: DataTablePaginationMode;
+  /** Rows currently in the table (the page, for a server source). */
+  rows: Row[];
+  /** Total matching rows (server `total`, or the filtered count for a client source). */
+  total: number;
+  /** True until the first server page arrives; never true for a client source. */
+  isLoading: boolean;
+  /** True while any server request is in flight, including background refetches. */
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => void;
+  /** Infinite mode: load the next page. No-op elsewhere. */
+  fetchNextPage: () => void;
+  hasNextPage: boolean;
+  /** Search text the server last received (debounced), for consumers rendering their own toolbar. */
+  searchQuery: string;
+  editing: {
+    cell: DataTableEditingCell | null;
+    start: (cell: DataTableEditingCell) => void;
+    stop: () => void;
+    commit: (row: DataTableRow<Row>, columnId: string, value: unknown) => Promise<void>;
+  };
+}
+//#endregion
+//# sourceMappingURL=types.d.ts.map

package/dist/components/data-table/use-data-table.d.ts

@@ -0,0 +1,19 @@
+"use client";
+import { DataTableInstance, UseDataTableOptions } from "./types.js";
+import { RowData } from "@tanstack/react-table";
+//#region src/components/data-table/use-data-table.d.ts
+/**
+ * Builds the table for a `dataSource`. This is where the design decision's
+ * "the component sets the manual flags itself" lives: a server source flips
+ * `manualFiltering`, `manualSorting` and `manualPagination` and feeds the
+ * table's own filter / sort / page state back out as a `TableQuery`; a client
+ * source leaves every row model in memory. Everything else (selection,
+ * expansion, visibility, pinning, sizing) is owned by the table.
+ *
+ * Use it directly when the default layout is not enough: pass the returned
+ * `table` to `DataTableToolbar`, `DataTablePagination` and friends, or the
+ * whole instance to `<DataTable instance={...} />`.
+ */
+export declare function useDataTable<Row extends RowData>(options: UseDataTableOptions<Row>): DataTableInstance<Row>;
+//#endregion
+//# sourceMappingURL=use-data-table.d.ts.map

package/dist/components/data-table/use-data-table.js

@@ -0,0 +1,171 @@
+"use client";
+"use client";
+import { createColumnHelper as createColumnHelper$1, dataTableFeatures } from "./features.js";
+import { expandColumn, selectColumn } from "./system-columns.js";
+import { useServerSource } from "./use-server-source.js";
+import * as React from "react";
+import { useTable } from "@tanstack/react-table";
+//#region src/components/data-table/use-data-table.ts
+const EMPTY_ROWS = [];
+function useDebounced(value, ms) {
+	const [debounced, setDebounced] = React.useState(value);
+	React.useEffect(() => {
+		if (ms <= 0) {
+			setDebounced(value);
+			return;
+		}
+		const id = setTimeout(() => setDebounced(value), ms);
+		return () => clearTimeout(id);
+	}, [value, ms]);
+	return ms <= 0 ? value : debounced;
+}
+/**
+* Builds the table for a `dataSource`. This is where the design decision's
+* "the component sets the manual flags itself" lives: a server source flips
+* `manualFiltering`, `manualSorting` and `manualPagination` and feeds the
+* table's own filter / sort / page state back out as a `TableQuery`; a client
+* source leaves every row model in memory. Everything else (selection,
+* expansion, visibility, pinning, sizing) is owned by the table.
+*
+* Use it directly when the default layout is not enough: pass the returned
+* `table` to `DataTableToolbar`, `DataTablePagination` and friends, or the
+* whole instance to `<DataTable instance={...} />`.
+*/
+function useDataTable(options) {
+	const { columns, dataSource, getRowId, getSubRows, pagination: paginationMode = "pages", pageSize = 25, enableRowSelection = false, enableExpanding = false, getRowCanExpand, enableSorting = true, enableMultiSort = false, enableGlobalFilter = true, enableColumnFilters = true, enableHiding = true, enableColumnPinning = true, enableColumnResizing = false, initialState, onCellCommit, onRowSelectionChange, searchDebounceMs = 250 } = options;
+	const isServer = dataSource.kind === "server";
+	const [globalFilter, setGlobalFilter] = React.useState(initialState?.globalFilter ?? "");
+	const [columnFilters, setColumnFilters] = React.useState(initialState?.columnFilters ?? []);
+	const [sorting, setSorting] = React.useState(initialState?.sorting ?? []);
+	const [pagination, setPagination] = React.useState(initialState?.pagination ?? {
+		pageIndex: 0,
+		pageSize
+	});
+	const searchQuery = useDebounced(globalFilter, isServer ? searchDebounceMs : 0);
+	const scopeKey = JSON.stringify([
+		searchQuery,
+		columnFilters,
+		sorting
+	]);
+	const lastScope = React.useRef(scopeKey);
+	React.useEffect(() => {
+		if (lastScope.current === scopeKey) return;
+		lastScope.current = scopeKey;
+		setPagination((p) => p.pageIndex === 0 ? p : {
+			...p,
+			pageIndex: 0
+		});
+	}, [scopeKey]);
+	const query = React.useMemo(() => ({
+		q: searchQuery.trim() || void 0,
+		filters: columnFilters.length ? columnFilters : void 0,
+		sort: sorting.length ? sorting : void 0,
+		page: pagination.pageIndex,
+		pageSize: pagination.pageSize
+	}), [
+		searchQuery,
+		columnFilters,
+		sorting,
+		pagination.pageIndex,
+		pagination.pageSize
+	]);
+	const server = useServerSource(isServer ? dataSource : void 0, query, paginationMode);
+	const data = isServer ? server.rows : dataSource.rows;
+	const resolvedColumns = React.useMemo(() => {
+		const helper = createColumnHelper$1();
+		const out = [];
+		if (enableRowSelection && !columns.some((c) => c.id === "select")) out.push(selectColumn(helper));
+		if (enableExpanding && !columns.some((c) => c.id === "expand")) out.push(expandColumn(helper));
+		for (const column of columns) {
+			const filter = column.meta?.filter;
+			if (filter === "faceted" && column.filterFn === void 0) out.push({
+				...column,
+				filterFn: "oneOf"
+			});
+			else if (filter === "text" && column.filterFn === void 0) out.push({
+				...column,
+				filterFn: "includesString"
+			});
+			else out.push(column);
+		}
+		return out;
+	}, [
+		columns,
+		enableRowSelection,
+		enableExpanding
+	]);
+	const table = useTable({
+		features: dataTableFeatures(),
+		columns: resolvedColumns,
+		data: data.length ? data : EMPTY_ROWS,
+		getRowId,
+		getSubRows,
+		initialState,
+		state: {
+			globalFilter,
+			columnFilters,
+			sorting,
+			pagination
+		},
+		onGlobalFilterChange: setGlobalFilter,
+		onColumnFiltersChange: setColumnFilters,
+		onSortingChange: setSorting,
+		onPaginationChange: setPagination,
+		manualFiltering: isServer,
+		manualSorting: isServer,
+		manualPagination: isServer || paginationMode !== "pages",
+		rowCount: isServer ? server.total : void 0,
+		enableRowSelection,
+		enableExpanding,
+		getRowCanExpand: getRowCanExpand ?? (enableExpanding ? () => true : void 0),
+		enableSorting,
+		enableMultiSort,
+		enableGlobalFilter,
+		enableColumnFilters,
+		enableHiding,
+		enableColumnPinning,
+		enableColumnResizing,
+		columnResizeMode: "onChange",
+		globalFilterFn: "search"
+	});
+	const rowSelection = table.state.rowSelection;
+	const onSelectionRef = React.useRef(onRowSelectionChange);
+	onSelectionRef.current = onRowSelectionChange;
+	const firstSelection = React.useRef(true);
+	React.useEffect(() => {
+		if (firstSelection.current) {
+			firstSelection.current = false;
+			return;
+		}
+		onSelectionRef.current?.(table.getSelectedRowModel().rows.map((r) => r.original));
+	}, [rowSelection]);
+	const [editingCell, setEditingCell] = React.useState(null);
+	const commit = React.useCallback(async (row, columnId, value) => {
+		await ((table.getColumn(columnId)?.columnDef.meta)?.onCommit ?? onCellCommit)?.(row.original, columnId, value);
+	}, [table, onCellCommit]);
+	const editing = React.useMemo(() => ({
+		cell: editingCell,
+		start: (cell) => setEditingCell(cell),
+		stop: () => setEditingCell(null),
+		commit
+	}), [editingCell, commit]);
+	return {
+		table,
+		dataSource,
+		paginationMode,
+		rows: data,
+		total: isServer ? server.total ?? 0 : paginationMode === "pages" ? table.getPrePaginatedRowModel().rows.length : table.getRowModel().rows.length,
+		isLoading: server.isLoading,
+		isFetching: server.isFetching,
+		error: server.error,
+		refetch: server.refetch,
+		fetchNextPage: server.fetchNextPage,
+		hasNextPage: server.hasNextPage,
+		searchQuery,
+		editing
+	};
+}
+//#endregion
+export { useDataTable };
+
+//# sourceMappingURL=use-data-table.js.map

package/dist/components/data-table/use-data-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-data-table.js","names":["createColumnHelper"],"sources":["../../../src/components/data-table/use-data-table.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useTable,\n  type ColumnFiltersState,\n  type PaginationState,\n  type RowData,\n  type SortingState,\n} from \"@tanstack/react-table\";\nimport * as React from \"react\";\nimport { createColumnHelper, dataTableFeatures } from \"./features\";\nimport { expandColumn, selectColumn } from \"./system-columns\";\nimport type {\n  DataSource,\n  DataTableColumnDef,\n  DataTableEditingCell,\n  DataTableInstance,\n  DataTableRow,\n  DataTableTable,\n  TableQuery,\n  UseDataTableOptions,\n} from \"./types\";\nimport { useServerSource } from \"./use-server-source\";\n\nconst EMPTY_ROWS: never[] = [];\n\nfunction useDebounced<T>(value: T, ms: number): T {\n  const [debounced, setDebounced] = React.useState(value);\n  React.useEffect(() => {\n    if (ms <= 0) {\n      setDebounced(value);\n      return;\n    }\n    const id = setTimeout(() => setDebounced(value), ms);\n    return () => clearTimeout(id);\n  }, [value, ms]);\n  return ms <= 0 ? value : debounced;\n}\n\n/**\n * Builds the table for a `dataSource`. This is where the design decision's\n * \"the component sets the manual flags itself\" lives: a server source flips\n * `manualFiltering`, `manualSorting` and `manualPagination` and feeds the\n * table's own filter / sort / page state back out as a `TableQuery`; a client\n * source leaves every row model in memory. Everything else (selection,\n * expansion, visibility, pinning, sizing) is owned by the table.\n *\n * Use it directly when the default layout is not enough: pass the returned\n * `table` to `DataTableToolbar`, `DataTablePagination` and friends, or the\n * whole instance to `<DataTable instance={...} />`.\n */\nexport function useDataTable<Row extends RowData>(\n  options: UseDataTableOptions<Row>,\n): DataTableInstance<Row> {\n  const {\n    columns,\n    dataSource,\n    getRowId,\n    getSubRows,\n    pagination: paginationMode = \"pages\",\n    pageSize = 25,\n    enableRowSelection = false,\n    enableExpanding = false,\n    getRowCanExpand,\n    enableSorting = true,\n    enableMultiSort = false,\n    enableGlobalFilter = true,\n    enableColumnFilters = true,\n    enableHiding = true,\n    enableColumnPinning = true,\n    enableColumnResizing = false,\n    initialState,\n    onCellCommit,\n    onRowSelectionChange,\n    searchDebounceMs = 250,\n  } = options;\n\n  const isServer = dataSource.kind === \"server\";\n\n  // Slices the server query is built from are React state; the table mirrors\n  // them through `state` + `on*Change`, which v9 still supports alongside atoms.\n  const [globalFilter, setGlobalFilter] = React.useState<string>(\n    (initialState?.globalFilter as string | undefined) ?? \"\",\n  );\n  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(\n    initialState?.columnFilters ?? [],\n  );\n  const [sorting, setSorting] = React.useState<SortingState>(initialState?.sorting ?? []);\n  const [pagination, setPagination] = React.useState<PaginationState>(\n    initialState?.pagination ?? { pageIndex: 0, pageSize },\n  );\n\n  const searchQuery = useDebounced(globalFilter, isServer ? searchDebounceMs : 0);\n\n  // A new search, filter or sort starts from page one again. Client sources\n  // get this from `autoResetPageIndex`; manual pagination has to do it here.\n  const scopeKey = JSON.stringify([searchQuery, columnFilters, sorting]);\n  const lastScope = React.useRef(scopeKey);\n  React.useEffect(() => {\n    if (lastScope.current === scopeKey) return;\n    lastScope.current = scopeKey;\n    setPagination((p) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }));\n  }, [scopeKey]);\n\n  const query = React.useMemo<TableQuery>(\n    () => ({\n      // Trimmed for the same reason the client filter trims (features.ts): a\n      // backend asked for `q: \" \"` returns nothing, and the user sees an empty\n      // table with no explanation. Whitespace-only means no search term.\n      q: searchQuery.trim() || undefined,\n      filters: columnFilters.length ? columnFilters : undefined,\n      sort: sorting.length ? sorting : undefined,\n      page: pagination.pageIndex,\n      pageSize: pagination.pageSize,\n    }),\n    [searchQuery, columnFilters, sorting, pagination.pageIndex, pagination.pageSize],\n  );\n\n  const server = useServerSource<Row>(isServer ? dataSource : undefined, query, paginationMode);\n\n  const data: ReadonlyArray<Row> = isServer ? server.rows : dataSource.rows;\n\n  // System columns first; then each consumer column with its meta defaults\n  // applied (a faceted column filters with `oneOf` unless told otherwise).\n  const resolvedColumns = React.useMemo(() => {\n    const helper = createColumnHelper<Row>();\n    const out: DataTableColumnDef<Row, any>[] = [];\n    if (enableRowSelection && !columns.some((c) => c.id === \"select\")) out.push(selectColumn(helper));\n    if (enableExpanding && !columns.some((c) => c.id === \"expand\")) out.push(expandColumn(helper));\n    for (const column of columns) {\n      const filter = column.meta?.filter;\n      if (filter === \"faceted\" && column.filterFn === undefined) {\n        out.push({ ...column, filterFn: \"oneOf\" });\n      } else if (filter === \"text\" && column.filterFn === undefined) {\n        out.push({ ...column, filterFn: \"includesString\" });\n      } else {\n        out.push(column);\n      }\n    }\n    return out;\n  }, [columns, enableRowSelection, enableExpanding]);\n\n  const table: DataTableTable<Row> = useTable({\n    features: dataTableFeatures<Row>(),\n    columns: resolvedColumns,\n    data: data.length ? data : EMPTY_ROWS,\n    getRowId,\n    getSubRows,\n    initialState,\n    state: { globalFilter, columnFilters, sorting, pagination },\n    onGlobalFilterChange: setGlobalFilter,\n    onColumnFiltersChange: setColumnFilters,\n    onSortingChange: setSorting,\n    onPaginationChange: setPagination,\n    manualFiltering: isServer,\n    manualSorting: isServer,\n    manualPagination: isServer || paginationMode !== \"pages\",\n    rowCount: isServer ? server.total : undefined,\n    enableRowSelection,\n    enableExpanding,\n    getRowCanExpand: getRowCanExpand ?? (enableExpanding ? () => true : undefined),\n    enableSorting,\n    enableMultiSort,\n    enableGlobalFilter,\n    enableColumnFilters,\n    enableHiding,\n    enableColumnPinning,\n    enableColumnResizing,\n    columnResizeMode: \"onChange\",\n    // `search`, not `includesString`: it trims the query, so a box holding only\n    // whitespace filters nothing rather than emptying the grid. See features.ts.\n    globalFilterFn: \"search\",\n  });\n\n  // Selection callback with original rows, for consumers that keep selection outside.\n  const rowSelection = table.state.rowSelection;\n  const onSelectionRef = React.useRef(onRowSelectionChange);\n  onSelectionRef.current = onRowSelectionChange;\n  const firstSelection = React.useRef(true);\n  React.useEffect(() => {\n    if (firstSelection.current) {\n      firstSelection.current = false;\n      return;\n    }\n    onSelectionRef.current?.(table.getSelectedRowModel().rows.map((r) => r.original));\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [rowSelection]);\n\n  const [editingCell, setEditingCell] = React.useState<DataTableEditingCell | null>(null);\n  const commit = React.useCallback(\n    async (row: DataTableRow<Row>, columnId: string, value: unknown) => {\n      const meta = table.getColumn(columnId)?.columnDef.meta;\n      const handler = meta?.onCommit ?? onCellCommit;\n      await handler?.(row.original, columnId, value);\n    },\n    [table, onCellCommit],\n  );\n  const editing = React.useMemo(\n    () => ({\n      cell: editingCell,\n      start: (cell: DataTableEditingCell) => setEditingCell(cell),\n      stop: () => setEditingCell(null),\n      commit,\n    }),\n    [editingCell, commit],\n  );\n\n  const total = isServer\n    ? (server.total ?? 0)\n    : paginationMode === \"pages\"\n      ? table.getPrePaginatedRowModel().rows.length\n      : table.getRowModel().rows.length;\n\n  return {\n    table,\n    dataSource: dataSource as DataSource<Row>,\n    paginationMode,\n    rows: data as Row[],\n    total,\n    isLoading: server.isLoading,\n    isFetching: server.isFetching,\n    error: server.error,\n    refetch: server.refetch,\n    fetchNextPage: server.fetchNextPage,\n    hasNextPage: server.hasNextPage,\n    searchQuery,\n    editing,\n  };\n}\n"],"mappings":"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"}

package/dist/components/data-table/use-server-source.js

@@ -0,0 +1,200 @@
+"use client";
+"use client";
+import * as React from "react";
+import { QueryClientContext, keepPreviousData, useInfiniteQuery, useQuery } from "@tanstack/react-query";
+//#region src/components/data-table/use-server-source.ts
+const EMPTY = [];
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/** The part of a query that identifies a result set; the page is separate so infinite mode can append. */
+function scopeOf(query) {
+	const { page: _page, ...scope } = query;
+	return scope;
+}
+/**
+* Runs a server source. With a `QueryClientProvider` above the table, pages
+* go through TanStack Query: cached by query, previous page kept on screen
+* while the next loads, and the in-flight request aborted through `signal`
+* when the query changes. Without one, a small local fetch state does the
+* same minus the cache, so the table never requires the optional peer to be
+* wired up.
+*
+* The strategy is chosen once per mount: a provider appearing or vanishing
+* mid-life would change the hook order, which React forbids, and is not a
+* real scenario.
+*/
+function useServerSource(source, query, mode) {
+	const client = React.useContext(QueryClientContext);
+	const [strategy] = React.useState(() => client ? "query" : "local");
+	return strategy === "query" ? useQueryStrategy(source, query, mode) : useLocalStrategy(source, query, mode);
+}
+function useQueryStrategy(source, query, mode) {
+	const id = React.useId();
+	const base = source?.queryKey ?? ["cortena-data-table", id];
+	const infinite = mode === "infinite";
+	const fetch = source?.fetch;
+	const page = useQuery({
+		queryKey: [
+			...base,
+			"page",
+			query
+		],
+		queryFn: ({ signal }) => fetch(query, signal),
+		enabled: Boolean(fetch) && !infinite,
+		placeholderData: keepPreviousData
+	});
+	const scope = scopeOf(query);
+	const pages = useInfiniteQuery({
+		queryKey: [
+			...base,
+			"infinite",
+			scope
+		],
+		queryFn: ({ pageParam, signal }) => fetch({
+			...scope,
+			page: pageParam
+		}, signal),
+		initialPageParam: 0,
+		getNextPageParam: (last, all) => {
+			return all.reduce((n, p) => n + p.rows.length, 0) < last.total && last.rows.length > 0 ? all.length : void 0;
+		},
+		enabled: Boolean(fetch) && infinite,
+		placeholderData: keepPreviousData
+	});
+	const flatRows = React.useMemo(() => pages.data ? pages.data.pages.flatMap((p) => p.rows) : EMPTY, [pages.data]);
+	if (!fetch) return {
+		rows: EMPTY,
+		total: void 0,
+		isLoading: false,
+		isFetching: false,
+		error: null,
+		refetch: () => {},
+		fetchNextPage: () => {},
+		hasNextPage: false
+	};
+	if (infinite) return {
+		rows: flatRows,
+		total: pages.data?.pages.at(-1)?.total,
+		isLoading: pages.isPending,
+		isFetching: pages.isFetching,
+		error: pages.error ? toError(pages.error) : null,
+		refetch: () => void pages.refetch(),
+		fetchNextPage: () => {
+			if (pages.hasNextPage && !pages.isFetchingNextPage) pages.fetchNextPage();
+		},
+		hasNextPage: pages.hasNextPage
+	};
+	return {
+		rows: page.data?.rows ?? EMPTY,
+		total: page.data?.total,
+		isLoading: page.isPending,
+		isFetching: page.isFetching,
+		error: page.error ? toError(page.error) : null,
+		refetch: () => void page.refetch(),
+		fetchNextPage: () => {},
+		hasNextPage: false
+	};
+}
+function useLocalStrategy(source, query, mode) {
+	const infinite = mode === "infinite";
+	const fetch = source?.fetch;
+	const scope = scopeOf(query);
+	const scopeKey = JSON.stringify(scope);
+	const [tick, setTick] = React.useState(0);
+	const [wanted, setWanted] = React.useState({
+		scopeKey,
+		n: 1
+	});
+	const wantedPages = wanted.scopeKey === scopeKey ? wanted.n : 1;
+	const [state, setState] = React.useState({
+		pages: [],
+		scopeKey,
+		page: -1,
+		isFetching: false,
+		error: null
+	});
+	const loadedForScope = state.scopeKey === scopeKey ? state.pages : EMPTY;
+	const targetPage = infinite ? loadedForScope.length : query.page;
+	const needs = infinite ? loadedForScope.length < wantedPages : !(state.scopeKey === scopeKey && state.page === query.page && state.pages.length > 0);
+	const requestKey = `${scopeKey}|${targetPage}|${tick}`;
+	const fetchRef = React.useRef(fetch);
+	React.useEffect(() => {
+		fetchRef.current = fetch;
+	});
+	const hasFetch = Boolean(fetch);
+	React.useEffect(() => {
+		const run = fetchRef.current;
+		if (!run || !needs) return;
+		const controller = new AbortController();
+		setState((s) => ({
+			...s,
+			isFetching: true
+		}));
+		run({
+			...scope,
+			page: targetPage
+		}, controller.signal).then((result) => {
+			if (controller.signal.aborted) return;
+			setState((s) => ({
+				pages: infinite && s.scopeKey === scopeKey ? [...s.pages, result] : [result],
+				scopeKey,
+				page: targetPage,
+				isFetching: false,
+				error: null
+			}));
+		}, (err) => {
+			if (controller.signal.aborted) return;
+			setState((s) => ({
+				...s,
+				isFetching: false,
+				error: toError(err)
+			}));
+		});
+		return () => controller.abort();
+	}, [
+		hasFetch,
+		requestKey,
+		needs
+	]);
+	const rows = React.useMemo(() => infinite ? state.pages.flatMap((p) => p.rows) : state.pages[0]?.rows ?? EMPTY, [state.pages, infinite]);
+	const total = state.pages.at(-1)?.total;
+	const hasNextPage = infinite && total !== void 0 && rows.length < total;
+	if (!fetch) return {
+		rows: EMPTY,
+		total: void 0,
+		isLoading: false,
+		isFetching: false,
+		error: null,
+		refetch: () => {},
+		fetchNextPage: () => {},
+		hasNextPage: false
+	};
+	return {
+		rows,
+		total,
+		isLoading: state.pages.length === 0 && !state.error,
+		isFetching: state.isFetching,
+		error: state.error,
+		refetch: () => {
+			setState((s) => ({
+				...s,
+				pages: [],
+				page: -1,
+				error: null
+			}));
+			setTick((t) => t + 1);
+		},
+		fetchNextPage: () => {
+			if (hasNextPage && !state.isFetching) setWanted({
+				scopeKey,
+				n: loadedForScope.length + 1
+			});
+		},
+		hasNextPage
+	};
+}
+//#endregion
+export { useServerSource };
+
+//# sourceMappingURL=use-server-source.js.map

package/dist/components/data-table/use-server-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-server-source.js","names":[],"sources":["../../../src/components/data-table/use-server-source.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  keepPreviousData,\n  QueryClientContext,\n  useInfiniteQuery,\n  useQuery,\n} from \"@tanstack/react-query\";\nimport * as React from \"react\";\nimport type { ServerSource, TableQuery, TableResult } from \"./types\";\n\nexport interface ServerSourceState<Row> {\n  rows: Row[];\n  total: number | undefined;\n  isLoading: boolean;\n  isFetching: boolean;\n  error: Error | null;\n  refetch: () => void;\n  fetchNextPage: () => void;\n  hasNextPage: boolean;\n}\n\nconst EMPTY: never[] = [];\n\nfunction toError(value: unknown): Error {\n  return value instanceof Error ? value : new Error(String(value));\n}\n\n/** The part of a query that identifies a result set; the page is separate so infinite mode can append. */\nfunction scopeOf(query: TableQuery): Omit<TableQuery, \"page\"> {\n  const { page: _page, ...scope } = query;\n  return scope;\n}\n\n/**\n * Runs a server source. With a `QueryClientProvider` above the table, pages\n * go through TanStack Query: cached by query, previous page kept on screen\n * while the next loads, and the in-flight request aborted through `signal`\n * when the query changes. Without one, a small local fetch state does the\n * same minus the cache, so the table never requires the optional peer to be\n * wired up.\n *\n * The strategy is chosen once per mount: a provider appearing or vanishing\n * mid-life would change the hook order, which React forbids, and is not a\n * real scenario.\n */\nexport function useServerSource<Row>(\n  source: ServerSource<Row> | undefined,\n  query: TableQuery,\n  mode: \"pages\" | \"infinite\" | \"none\",\n): ServerSourceState<Row> {\n  const client = React.useContext(QueryClientContext);\n  const [strategy] = React.useState<\"query\" | \"local\">(() => (client ? \"query\" : \"local\"));\n  // Hook order is stable for the life of the component because `strategy` is.\n  return strategy === \"query\"\n    ? useQueryStrategy(source, query, mode)\n    : useLocalStrategy(source, query, mode);\n}\n\nfunction useQueryStrategy<Row>(\n  source: ServerSource<Row> | undefined,\n  query: TableQuery,\n  mode: \"pages\" | \"infinite\" | \"none\",\n): ServerSourceState<Row> {\n  const id = React.useId();\n  const base = source?.queryKey ?? [\"cortena-data-table\", id];\n  const infinite = mode === \"infinite\";\n  const fetch = source?.fetch;\n\n  const page = useQuery({\n    queryKey: [...base, \"page\", query],\n    queryFn: ({ signal }) => fetch!(query, signal),\n    enabled: Boolean(fetch) && !infinite,\n    placeholderData: keepPreviousData,\n  });\n\n  const scope = scopeOf(query);\n  const pages = useInfiniteQuery({\n    queryKey: [...base, \"infinite\", scope],\n    queryFn: ({ pageParam, signal }) => fetch!({ ...scope, page: pageParam }, signal),\n    initialPageParam: 0,\n    getNextPageParam: (last: TableResult<Row>, all: TableResult<Row>[]) => {\n      const loaded = all.reduce((n, p) => n + p.rows.length, 0);\n      return loaded < last.total && last.rows.length > 0 ? all.length : undefined;\n    },\n    enabled: Boolean(fetch) && infinite,\n    placeholderData: keepPreviousData,\n  });\n\n  const flatRows = React.useMemo(\n    () => (pages.data ? pages.data.pages.flatMap((p) => p.rows) : EMPTY),\n    [pages.data],\n  );\n\n  if (!fetch) {\n    return {\n      rows: EMPTY,\n      total: undefined,\n      isLoading: false,\n      isFetching: false,\n      error: null,\n      refetch: () => {},\n      fetchNextPage: () => {},\n      hasNextPage: false,\n    };\n  }\n\n  if (infinite) {\n    return {\n      rows: flatRows,\n      total: pages.data?.pages.at(-1)?.total,\n      isLoading: pages.isPending,\n      isFetching: pages.isFetching,\n      error: pages.error ? toError(pages.error) : null,\n      refetch: () => void pages.refetch(),\n      fetchNextPage: () => {\n        if (pages.hasNextPage && !pages.isFetchingNextPage) void pages.fetchNextPage();\n      },\n      hasNextPage: pages.hasNextPage,\n    };\n  }\n\n  return {\n    rows: page.data?.rows ?? EMPTY,\n    total: page.data?.total,\n    isLoading: page.isPending,\n    isFetching: page.isFetching,\n    error: page.error ? toError(page.error) : null,\n    refetch: () => void page.refetch(),\n    fetchNextPage: () => {},\n    hasNextPage: false,\n  };\n}\n\ninterface LocalState<Row> {\n  pages: TableResult<Row>[];\n  scopeKey: string;\n  page: number;\n  isFetching: boolean;\n  error: Error | null;\n}\n\nfunction useLocalStrategy<Row>(\n  source: ServerSource<Row> | undefined,\n  query: TableQuery,\n  mode: \"pages\" | \"infinite\" | \"none\",\n): ServerSourceState<Row> {\n  const infinite = mode === \"infinite\";\n  const fetch = source?.fetch;\n  const scope = scopeOf(query);\n  const scopeKey = JSON.stringify(scope);\n  const [tick, setTick] = React.useState(0);\n  // Pages wanted in infinite mode, scoped so a new query starts over at one.\n  const [wanted, setWanted] = React.useState({ scopeKey, n: 1 });\n  const wantedPages = wanted.scopeKey === scopeKey ? wanted.n : 1;\n  const [state, setState] = React.useState<LocalState<Row>>({\n    pages: [],\n    scopeKey,\n    page: -1,\n    isFetching: false,\n    error: null,\n  });\n\n  const loadedForScope = state.scopeKey === scopeKey ? state.pages : EMPTY;\n  const targetPage = infinite ? loadedForScope.length : query.page;\n  const needs = infinite\n    ? loadedForScope.length < wantedPages\n    : !(state.scopeKey === scopeKey && state.page === query.page && state.pages.length > 0);\n  const requestKey = `${scopeKey}|${targetPage}|${tick}`;\n\n  // The consumer's `fetch` is usually an inline arrow — `fetch: q => api.list(q)`\n  // is the documented call — so it is a new function on every parent render.\n  // Depending on it would abort and refire the request each time; the request's\n  // identity is `requestKey`, so the latest function is read from a ref instead.\n  const fetchRef = React.useRef(fetch);\n  React.useEffect(() => {\n    fetchRef.current = fetch;\n  });\n\n  const hasFetch = Boolean(fetch);\n\n  React.useEffect(() => {\n    const run = fetchRef.current;\n    if (!run || !needs) return;\n    const controller = new AbortController();\n    setState((s) => ({ ...s, isFetching: true }));\n    run({ ...scope, page: targetPage }, controller.signal).then(\n      (result) => {\n        if (controller.signal.aborted) return;\n        setState((s) => ({\n          pages: infinite && s.scopeKey === scopeKey ? [...s.pages, result] : [result],\n          scopeKey,\n          page: targetPage,\n          isFetching: false,\n          error: null,\n        }));\n      },\n      (err: unknown) => {\n        if (controller.signal.aborted) return;\n        setState((s) => ({ ...s, isFetching: false, error: toError(err) }));\n      },\n    );\n    return () => controller.abort();\n    // `requestKey` is the identity of the request; `scope` and `targetPage` derive\n    // from it. `fetch` itself is held in a ref, so only its presence is a dep.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [hasFetch, requestKey, needs]);\n\n  // Like keepPreviousData: the last result stays on screen while the next loads.\n  const rows = React.useMemo(\n    () => (infinite ? state.pages.flatMap((p) => p.rows) : (state.pages[0]?.rows ?? EMPTY)),\n    [state.pages, infinite],\n  );\n  const total = state.pages.at(-1)?.total;\n  const hasNextPage = infinite && total !== undefined && rows.length < total;\n\n  if (!fetch) {\n    return {\n      rows: EMPTY,\n      total: undefined,\n      isLoading: false,\n      isFetching: false,\n      error: null,\n      refetch: () => {},\n      fetchNextPage: () => {},\n      hasNextPage: false,\n    };\n  }\n\n  return {\n    rows,\n    total,\n    isLoading: state.pages.length === 0 && !state.error,\n    isFetching: state.isFetching,\n    error: state.error,\n    refetch: () => {\n      setState((s) => ({ ...s, pages: [], page: -1, error: null }));\n      setTick((t) => t + 1);\n    },\n    fetchNextPage: () => {\n      if (hasNextPage && !state.isFetching) setWanted({ scopeKey, n: loadedForScope.length + 1 });\n    },\n    hasNextPage,\n  };\n}\n"],"mappings":"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"}

package/dist/components/date-field.d.ts

@@ -0,0 +1,54 @@
+"use client";
+import { CalendarProps } from "./calendar.js";
+import * as React from "react";
+//#region src/components/date-field.d.ts
+/** `2026-01-05`. */
+declare function formatDateISO(date: Date): string;
+/** `5 Jan 2026` for en-GB; other locales via `Intl.DateTimeFormat`. */
+declare function formatDateShort(date: Date, locale?: string): string;
+/** `5 January 2026` for en-GB; other locales via `Intl.DateTimeFormat`. */
+declare function formatDateLong(date: Date, locale?: string): string;
+/**
+ * Calendar-day distance in words: `today`, `yesterday`, `tomorrow`, `3 days
+ * ago`, `in 2 weeks`, `4 months ago`, `in 2 years`. Compares local calendar
+ * days, so 23:59 to 00:01 is `tomorrow`. Other locales use
+ * `Intl.RelativeTimeFormat`.
+ */
+declare function formatRelative(date: Date, options?: {
+  now?: Date;
+  locale?: string;
+}): string;
+/** Strict `yyyy-mm-dd`; rejects impossible days such as `2026-02-30`. */
+declare function parseDateISO(text: string): Date | undefined;
+/** ISO first, then the English `5 Jan 2026` / `5 January 2026` shapes. */
+declare function parseDateDefault(text: string): Date | undefined;
+type CalendarPassthrough = Omit<CalendarProps, "mode" | "selected" | "onSelect" | "required" | "disabled">;
+export interface DateFieldProps extends Omit<React.ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "min" | "max" | "type"> {
+  /** The date (controlled). */
+  value?: Date | undefined;
+  /** The initial date (uncontrolled). */
+  defaultValue?: Date | undefined;
+  /** Called with the parsed or picked date, or `undefined` when the text is cleared or invalid. */
+  onValueChange?: (date: Date | undefined) => void;
+  /** Input placeholder; defaults to the ISO shape. */
+  placeholder?: string;
+  /** Formats the date into the input; defaults to ISO `yyyy-mm-dd`. */
+  formatDate?: (date: Date) => string;
+  /** Parses typed text; defaults to ISO plus the English day-month-year shapes. */
+  parseDate?: (text: string) => Date | undefined;
+  /** Earliest selectable day. */
+  min?: Date;
+  /** Latest selectable day. */
+  max?: Date;
+  disabled?: boolean;
+  /** Force the invalid look (e.g. from a form validator). */
+  invalid?: boolean;
+  /** Extra props for the Calendar (e.g. `captionLayout`, `today`). */
+  calendarProps?: CalendarPassthrough;
+  /** Class name for the wrapper; use `className` for the input itself. */
+  wrapperClassName?: string;
+}
+declare function DateField(props: DateFieldProps): React.JSX.Element;
+//#endregion
+export { DateField, formatDateISO, formatDateLong, formatDateShort, formatRelative, parseDateDefault, parseDateISO };
+//# sourceMappingURL=date-field.d.ts.map