@datakable/react 0.0.0-stage → 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,242 @@
+import * as _datakable_core from '@datakable/core';
+import { TableState, InvalidRowsMode, CreateTableOptions, ColumnDef, SchemaRow, Table, RowModel, AnyFeature, TableSchema, TableStateFor, ApiOf, SearchStatus, RowModelStatus, RowIssue, DiagnosticMessages } from '@datakable/core';
+export * from '@datakable/core';
+import { ReactNode, ComponentType } from 'react';
+
+declare module '@datakable/core' {
+    interface DiagnosticCatalog {
+        DK_UNSTABLE_COLUMNS: {
+            /** Consecutive renders that passed a new `columns` array with the same shape. */
+            renders: number;
+        };
+        DK_UNSTABLE_OPTION: {
+            /** `data`, `fetcher`, `rowKey`, or a feature's function option: `features[2].searchFn`. */
+            option: string;
+            /** Consecutive renders that passed a new reference. */
+            renders: number;
+        };
+    }
+}
+/**
+ * Codes owned by `@datakable/react` (§8.3, react, dev only). Like core's dev checks, the
+ * definitions exist only in development: the NODE_ENV check is written out here (not an imported
+ * flag) so a consumer's bundler folds it while parsing and drops the text from production bundles
+ * (§8.2). They are never emitted in production, so `datakable/messages` has no text for them.
+ */
+declare const reactDiagnostics: (_datakable_core.DiagnosticDefinition<"DK_UNSTABLE_COLUMNS"> | _datakable_core.DiagnosticDefinition<"DK_UNSTABLE_OPTION">)[];
+
+/**
+ * `useDataTable` options: `createTable`'s (§3.2), with `cell` / `invalidCell` returning a
+ * `ReactNode` (§10). Read once, at creation: `features`, `schema`, `invalidRows`, `initialState`,
+ * `name`, `timeout`, `strict`, `diagnostics`. Every other option follows the latest render.
+ */
+type UseDataTableOptions<T, S extends TableState = TableState, Sch = undefined, M extends InvalidRowsMode = 'drop'> = Omit<CreateTableOptions<T, S, Sch, M>, 'columns'> & {
+    /**
+     * Compared by reference (§10): a new array tells the table the columns changed. Define them
+     * outside the component or memoise them (`DK_UNSTABLE_COLUMNS` in development).
+     */
+    columns?: readonly ColumnDef<SchemaRow<T, Sch>, ReactNode>[];
+};
+/**
+ * What `useDataTable` returns: the table (its methods and the installed features' APIs) with the
+ * `state` and `rowModel` of this render. A new object whenever the table notifies, so it can be a
+ * dependency of `useMemo` / `memo` children; the same object while nothing changed.
+ */
+type UseDataTableResult<T, S extends TableState = TableState, M extends InvalidRowsMode = 'drop', In = T, Api = unknown> = Table<T, S, M, In> & Api & {
+    /** The state snapshot of this render (`getState()`). */
+    readonly state: S;
+    /** The row model of this render (`getRowModel()`, §6.6): rows, counts, status. */
+    readonly rowModel: RowModel<T, M>;
+};
+/**
+ * Binds a table to a component (§10): the table is created once per component instance and
+ * destroyed on unmount; renders read it through `useSyncExternalStore` (with
+ * `getServerSnapshot`), and options are synced with `table.setOptions` in a layout effect, never
+ * during render.
+ *
+ * - `features` (and the other read-once options) are read at creation: a new inline `features`
+ *   array never recreates the table.
+ * - `fetcher`, `onStateChange` and `onDiagnostic` may be inline functions: the table always calls
+ *   the latest one, and a new reference never refetches (call `refetch()` when a value the fetcher
+ *   reads changes).
+ * - `columns`, `data` and a `rowKey` function are compared by reference: memoise them.
+ * - Controlled slices (§3.2): pass `state` and `onStateChange`; changes come back through `state`.
+ * - SSR (§7.2): rendering starts no async work. The fetcher's first request and a `searchFn` for an
+ *   initial query start after the commit (`status: 'pending'` until then; `DK_SSR_ASYNC_DEFERRED`
+ *   on the server), unless `initialData` already holds their result. `initialState` (e.g. parsed
+ *   from the URL) applies on the server: client-mode features filter / search / sort the HTML.
+ *   `getServerSnapshot` is the view at creation; a table that changed before the hydration commit
+ *   reports `DK_HYDRATION_MISMATCH`.
+ *
+ * `@datakable/react` installs no features by default; `datakable`'s `useDataTable` installs the
+ * default preset.
+ */
+declare function useDataTable<T, S extends TableState = never, const Fs extends readonly AnyFeature[] = [], const Sch extends TableSchema | undefined = undefined, const M extends InvalidRowsMode = 'drop'>(options: UseDataTableOptions<T, TableStateFor<S, Fs, SchemaRow<T, Sch>>, Sch, M> & {
+    features?: Fs;
+}): UseDataTableResult<SchemaRow<T, Sch>, TableStateFor<S, Fs, SchemaRow<T, Sch>>, M, [
+    Sch
+] extends [TableSchema] ? unknown : T, ApiOf<Fs, SchemaRow<T, Sch>>>;
+
+/** Props of `components.SearchInput`: the search feature's `input`, bound both ways. */
+interface SearchInputProps {
+    /** `state.search.input` (updates as the user types). */
+    value: string;
+    /** `state.search.status`: `pending` while a debounce waits, `searching` while a request runs. */
+    status: SearchStatus;
+    /** `setSearch(value)`. */
+    onChange(value: string): void;
+    /** `flushSearch()` (Enter). */
+    onSubmit(): void;
+    /** `clearSearch()` (Esc). */
+    onClear(): void;
+}
+/** Props of `components.Pagination` (the pagination feature's state and API). */
+interface PaginationProps {
+    pageIndex: number;
+    pageSize: number;
+    pageCount: number;
+    canPrev: boolean;
+    canNext: boolean;
+    prev(): void;
+    next(): void;
+    setPageIndex(index: number): void;
+    setPageSize(size: number): void;
+}
+/** Props of `components.Empty`: shown when the table has loaded and has no rows to show. */
+interface EmptyProps {
+    /** `true` when there is data but filters / search removed every row. */
+    filtered: boolean;
+}
+/** Props of `components.Loading`: the first load (`isInitialLoad`, nothing to show yet). */
+interface LoadingProps {
+    status: RowModelStatus;
+}
+/** Props of `components.Error`: the first load failed, or the body failed to render. */
+interface ErrorProps {
+    status: RowModelStatus;
+    /**
+     * `'load'`: `status === 'error'` on the first load. `'render'`: a component in the body outside
+     * the cells threw (a component inside a cell renders `⚠` in that cell only).
+     */
+    reason: 'load' | 'render';
+    /** `'load'`: `refetch()`. `'render'`: renders the body again. */
+    retry(): void;
+}
+/** `<DataTable components={...} />`: replaces the default parts (unstyled, `data-*` hooks only). */
+interface DataTableComponents {
+    SearchInput?: ComponentType<SearchInputProps>;
+    Pagination?: ComponentType<PaginationProps>;
+    Empty?: ComponentType<EmptyProps>;
+    Loading?: ComponentType<LoadingProps>;
+    Error?: ComponentType<ErrorProps>;
+}
+/** What `<DataTable table={...} />` reads: the value `useDataTable` returns. */
+interface DataTableSource {
+    readonly state: TableState;
+    readonly rowModel: {
+        readonly rows: readonly DataTableRow[];
+        readonly filteredCount: number;
+        readonly totalCount: number;
+        readonly status: RowModelStatus;
+        readonly isInitialLoad: boolean;
+    };
+    getOptions(): {
+        readonly columns?: readonly unknown[] | undefined;
+    };
+    getData(): readonly unknown[];
+    refetch(): Promise<unknown>;
+}
+/** The part of a `Row` (§6.6) `<DataTable />` renders from. */
+interface DataTableRow {
+    readonly key: string | number;
+    readonly index: number;
+    readonly original: unknown;
+    readonly valid: boolean;
+    readonly issues: readonly RowIssue[];
+    getValue(id: string): unknown;
+    getCellIssues(id: string): readonly RowIssue[];
+}
+/** `<DataTable />`'s own props, next to `table` or the `useDataTable` options. */
+interface DataTableOwnProps {
+    components?: DataTableComponents | undefined;
+    caption?: ReactNode;
+}
+/**
+ * `<DataTable table={useDataTable(...)} />`, or `<DataTable data={rows} />` with the
+ * `useDataTable` options as props (zero-config: columns derived from the data).
+ */
+type DataTableProps<T = unknown, Sch = undefined, M extends InvalidRowsMode = InvalidRowsMode> = DataTableOwnProps & ({
+    table: DataTableSource;
+} | (UseDataTableOptions<T, TableState, Sch, M> & {
+    features?: readonly AnyFeature[];
+    table?: undefined;
+}));
+/**
+ * The zero-config table (§10). Renders what the installed features provide: sort buttons with
+ * `aria-sort`, a search input bound to `input` (Enter = `flushSearch`, Esc = `clearSearch`),
+ * pagination, and the Loading / Error / Empty states from `status` + `isInitialLoad` (§6.6).
+ * Unstyled: style it through the `data-*` hooks (`data-status`, `data-initial-load`,
+ * `data-invalid`, `data-sort`, …) or replace parts with `components`.
+ *
+ * `@datakable/react`'s `DataTable` installs no features with `data`; `datakable`'s installs the
+ * default preset.
+ */
+declare function DataTable<T, const Sch extends TableSchema | undefined = undefined, const M extends InvalidRowsMode = 'drop'>(props: DataTableProps<T, Sch, M>): ReactNode;
+
+declare module '@datakable/core' {
+    interface DiagnosticCatalog {
+        DK_RENDER_FAILED: {
+            /**
+             * The render operation: `render:cell` (a cell's boundary: a component returned by `cell` /
+             * `invalidCell`) or `render:table` (the body boundary: a component outside the cells).
+             */
+            op: 'render:table' | 'render:cell';
+            /** `render:cell`: the slot whose component threw, `columns[1].cell`. */
+            slot?: string;
+            /** `render:cell`: the column id. */
+            column?: string;
+            /** `render:cell`: the row's index in the data (the first failure; later ones are deduped). */
+            row?: number;
+            /** `error.name` only; the full error is `context.cause`. */
+            errorName?: string;
+        };
+    }
+    /** §3.4: React error boundaries, not interceptor chains (nothing runs interceptors on them). */
+    interface Operations {
+        'render:table': {
+            kind: 'sync';
+            input: undefined;
+            output: undefined;
+        };
+        'render:cell': {
+            kind: 'sync';
+            input: {
+                column: string;
+                slot: 'cell' | 'invalidCell';
+                row: number;
+            };
+            output: undefined;
+        };
+    }
+}
+/**
+ * `columns[i].cell` (§4.1, §10): renders a React node synchronously. A thenable is a contract
+ * violation (`DK_CALLBACK_BAD_RETURN`); `<DataTable />` renders `⚠` instead.
+ */
+declare const cellSlot: {
+    readonly name: "cell";
+    readonly returns: "sync";
+    readonly fallback: "those cells rendered ⚠";
+};
+/** `columns[i].invalidCell` (§5.1): renders a flagged cell; same contract as `cell`. */
+declare const invalidCellSlot: {
+    readonly name: "invalidCell";
+    readonly returns: "sync";
+    readonly fallback: "those cells rendered ⚠";
+};
+/** Message text (§8.2): development builds, or production via `datakable/messages`. */
+declare const renderMessages: DiagnosticMessages<'DK_RENDER_FAILED'>;
+/** Codes owned by `<DataTable />` (§8.3, react). Emitted in production too; text behind NODE_ENV. */
+declare const renderDiagnostics: _datakable_core.DiagnosticDefinition<"DK_RENDER_FAILED">[];
+
+export { DataTable, type DataTableComponents, type DataTableOwnProps, type DataTableProps, type DataTableSource, type EmptyProps, type ErrorProps, type LoadingProps, type PaginationProps, type SearchInputProps, type UseDataTableOptions, type UseDataTableResult, cellSlot, invalidCellSlot, reactDiagnostics, renderDiagnostics, renderMessages, useDataTable };

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+import * as _datakable_core from '@datakable/core';
+import { TableState, InvalidRowsMode, CreateTableOptions, ColumnDef, SchemaRow, Table, RowModel, AnyFeature, TableSchema, TableStateFor, ApiOf, SearchStatus, RowModelStatus, RowIssue, DiagnosticMessages } from '@datakable/core';
+export * from '@datakable/core';
+import { ReactNode, ComponentType } from 'react';
+
+declare module '@datakable/core' {
+    interface DiagnosticCatalog {
+        DK_UNSTABLE_COLUMNS: {
+            /** Consecutive renders that passed a new `columns` array with the same shape. */
+            renders: number;
+        };
+        DK_UNSTABLE_OPTION: {
+            /** `data`, `fetcher`, `rowKey`, or a feature's function option: `features[2].searchFn`. */
+            option: string;
+            /** Consecutive renders that passed a new reference. */
+            renders: number;
+        };
+    }
+}
+/**
+ * Codes owned by `@datakable/react` (§8.3, react, dev only). Like core's dev checks, the
+ * definitions exist only in development: the NODE_ENV check is written out here (not an imported
+ * flag) so a consumer's bundler folds it while parsing and drops the text from production bundles
+ * (§8.2). They are never emitted in production, so `datakable/messages` has no text for them.
+ */
+declare const reactDiagnostics: (_datakable_core.DiagnosticDefinition<"DK_UNSTABLE_COLUMNS"> | _datakable_core.DiagnosticDefinition<"DK_UNSTABLE_OPTION">)[];
+
+/**
+ * `useDataTable` options: `createTable`'s (§3.2), with `cell` / `invalidCell` returning a
+ * `ReactNode` (§10). Read once, at creation: `features`, `schema`, `invalidRows`, `initialState`,
+ * `name`, `timeout`, `strict`, `diagnostics`. Every other option follows the latest render.
+ */
+type UseDataTableOptions<T, S extends TableState = TableState, Sch = undefined, M extends InvalidRowsMode = 'drop'> = Omit<CreateTableOptions<T, S, Sch, M>, 'columns'> & {
+    /**
+     * Compared by reference (§10): a new array tells the table the columns changed. Define them
+     * outside the component or memoise them (`DK_UNSTABLE_COLUMNS` in development).
+     */
+    columns?: readonly ColumnDef<SchemaRow<T, Sch>, ReactNode>[];
+};
+/**
+ * What `useDataTable` returns: the table (its methods and the installed features' APIs) with the
+ * `state` and `rowModel` of this render. A new object whenever the table notifies, so it can be a
+ * dependency of `useMemo` / `memo` children; the same object while nothing changed.
+ */
+type UseDataTableResult<T, S extends TableState = TableState, M extends InvalidRowsMode = 'drop', In = T, Api = unknown> = Table<T, S, M, In> & Api & {
+    /** The state snapshot of this render (`getState()`). */
+    readonly state: S;
+    /** The row model of this render (`getRowModel()`, §6.6): rows, counts, status. */
+    readonly rowModel: RowModel<T, M>;
+};
+/**
+ * Binds a table to a component (§10): the table is created once per component instance and
+ * destroyed on unmount; renders read it through `useSyncExternalStore` (with
+ * `getServerSnapshot`), and options are synced with `table.setOptions` in a layout effect, never
+ * during render.
+ *
+ * - `features` (and the other read-once options) are read at creation: a new inline `features`
+ *   array never recreates the table.
+ * - `fetcher`, `onStateChange` and `onDiagnostic` may be inline functions: the table always calls
+ *   the latest one, and a new reference never refetches (call `refetch()` when a value the fetcher
+ *   reads changes).
+ * - `columns`, `data` and a `rowKey` function are compared by reference: memoise them.
+ * - Controlled slices (§3.2): pass `state` and `onStateChange`; changes come back through `state`.
+ * - SSR (§7.2): rendering starts no async work. The fetcher's first request and a `searchFn` for an
+ *   initial query start after the commit (`status: 'pending'` until then; `DK_SSR_ASYNC_DEFERRED`
+ *   on the server), unless `initialData` already holds their result. `initialState` (e.g. parsed
+ *   from the URL) applies on the server: client-mode features filter / search / sort the HTML.
+ *   `getServerSnapshot` is the view at creation; a table that changed before the hydration commit
+ *   reports `DK_HYDRATION_MISMATCH`.
+ *
+ * `@datakable/react` installs no features by default; `datakable`'s `useDataTable` installs the
+ * default preset.
+ */
+declare function useDataTable<T, S extends TableState = never, const Fs extends readonly AnyFeature[] = [], const Sch extends TableSchema | undefined = undefined, const M extends InvalidRowsMode = 'drop'>(options: UseDataTableOptions<T, TableStateFor<S, Fs, SchemaRow<T, Sch>>, Sch, M> & {
+    features?: Fs;
+}): UseDataTableResult<SchemaRow<T, Sch>, TableStateFor<S, Fs, SchemaRow<T, Sch>>, M, [
+    Sch
+] extends [TableSchema] ? unknown : T, ApiOf<Fs, SchemaRow<T, Sch>>>;
+
+/** Props of `components.SearchInput`: the search feature's `input`, bound both ways. */
+interface SearchInputProps {
+    /** `state.search.input` (updates as the user types). */
+    value: string;
+    /** `state.search.status`: `pending` while a debounce waits, `searching` while a request runs. */
+    status: SearchStatus;
+    /** `setSearch(value)`. */
+    onChange(value: string): void;
+    /** `flushSearch()` (Enter). */
+    onSubmit(): void;
+    /** `clearSearch()` (Esc). */
+    onClear(): void;
+}
+/** Props of `components.Pagination` (the pagination feature's state and API). */
+interface PaginationProps {
+    pageIndex: number;
+    pageSize: number;
+    pageCount: number;
+    canPrev: boolean;
+    canNext: boolean;
+    prev(): void;
+    next(): void;
+    setPageIndex(index: number): void;
+    setPageSize(size: number): void;
+}
+/** Props of `components.Empty`: shown when the table has loaded and has no rows to show. */
+interface EmptyProps {
+    /** `true` when there is data but filters / search removed every row. */
+    filtered: boolean;
+}
+/** Props of `components.Loading`: the first load (`isInitialLoad`, nothing to show yet). */
+interface LoadingProps {
+    status: RowModelStatus;
+}
+/** Props of `components.Error`: the first load failed, or the body failed to render. */
+interface ErrorProps {
+    status: RowModelStatus;
+    /**
+     * `'load'`: `status === 'error'` on the first load. `'render'`: a component in the body outside
+     * the cells threw (a component inside a cell renders `⚠` in that cell only).
+     */
+    reason: 'load' | 'render';
+    /** `'load'`: `refetch()`. `'render'`: renders the body again. */
+    retry(): void;
+}
+/** `<DataTable components={...} />`: replaces the default parts (unstyled, `data-*` hooks only). */
+interface DataTableComponents {
+    SearchInput?: ComponentType<SearchInputProps>;
+    Pagination?: ComponentType<PaginationProps>;
+    Empty?: ComponentType<EmptyProps>;
+    Loading?: ComponentType<LoadingProps>;
+    Error?: ComponentType<ErrorProps>;
+}
+/** What `<DataTable table={...} />` reads: the value `useDataTable` returns. */
+interface DataTableSource {
+    readonly state: TableState;
+    readonly rowModel: {
+        readonly rows: readonly DataTableRow[];
+        readonly filteredCount: number;
+        readonly totalCount: number;
+        readonly status: RowModelStatus;
+        readonly isInitialLoad: boolean;
+    };
+    getOptions(): {
+        readonly columns?: readonly unknown[] | undefined;
+    };
+    getData(): readonly unknown[];
+    refetch(): Promise<unknown>;
+}
+/** The part of a `Row` (§6.6) `<DataTable />` renders from. */
+interface DataTableRow {
+    readonly key: string | number;
+    readonly index: number;
+    readonly original: unknown;
+    readonly valid: boolean;
+    readonly issues: readonly RowIssue[];
+    getValue(id: string): unknown;
+    getCellIssues(id: string): readonly RowIssue[];
+}
+/** `<DataTable />`'s own props, next to `table` or the `useDataTable` options. */
+interface DataTableOwnProps {
+    components?: DataTableComponents | undefined;
+    caption?: ReactNode;
+}
+/**
+ * `<DataTable table={useDataTable(...)} />`, or `<DataTable data={rows} />` with the
+ * `useDataTable` options as props (zero-config: columns derived from the data).
+ */
+type DataTableProps<T = unknown, Sch = undefined, M extends InvalidRowsMode = InvalidRowsMode> = DataTableOwnProps & ({
+    table: DataTableSource;
+} | (UseDataTableOptions<T, TableState, Sch, M> & {
+    features?: readonly AnyFeature[];
+    table?: undefined;
+}));
+/**
+ * The zero-config table (§10). Renders what the installed features provide: sort buttons with
+ * `aria-sort`, a search input bound to `input` (Enter = `flushSearch`, Esc = `clearSearch`),
+ * pagination, and the Loading / Error / Empty states from `status` + `isInitialLoad` (§6.6).
+ * Unstyled: style it through the `data-*` hooks (`data-status`, `data-initial-load`,
+ * `data-invalid`, `data-sort`, …) or replace parts with `components`.
+ *
+ * `@datakable/react`'s `DataTable` installs no features with `data`; `datakable`'s installs the
+ * default preset.
+ */
+declare function DataTable<T, const Sch extends TableSchema | undefined = undefined, const M extends InvalidRowsMode = 'drop'>(props: DataTableProps<T, Sch, M>): ReactNode;
+
+declare module '@datakable/core' {
+    interface DiagnosticCatalog {
+        DK_RENDER_FAILED: {
+            /**
+             * The render operation: `render:cell` (a cell's boundary: a component returned by `cell` /
+             * `invalidCell`) or `render:table` (the body boundary: a component outside the cells).
+             */
+            op: 'render:table' | 'render:cell';
+            /** `render:cell`: the slot whose component threw, `columns[1].cell`. */
+            slot?: string;
+            /** `render:cell`: the column id. */
+            column?: string;
+            /** `render:cell`: the row's index in the data (the first failure; later ones are deduped). */
+            row?: number;
+            /** `error.name` only; the full error is `context.cause`. */
+            errorName?: string;
+        };
+    }
+    /** §3.4: React error boundaries, not interceptor chains (nothing runs interceptors on them). */
+    interface Operations {
+        'render:table': {
+            kind: 'sync';
+            input: undefined;
+            output: undefined;
+        };
+        'render:cell': {
+            kind: 'sync';
+            input: {
+                column: string;
+                slot: 'cell' | 'invalidCell';
+                row: number;
+            };
+            output: undefined;
+        };
+    }
+}
+/**
+ * `columns[i].cell` (§4.1, §10): renders a React node synchronously. A thenable is a contract
+ * violation (`DK_CALLBACK_BAD_RETURN`); `<DataTable />` renders `⚠` instead.
+ */
+declare const cellSlot: {
+    readonly name: "cell";
+    readonly returns: "sync";
+    readonly fallback: "those cells rendered ⚠";
+};
+/** `columns[i].invalidCell` (§5.1): renders a flagged cell; same contract as `cell`. */
+declare const invalidCellSlot: {
+    readonly name: "invalidCell";
+    readonly returns: "sync";
+    readonly fallback: "those cells rendered ⚠";
+};
+/** Message text (§8.2): development builds, or production via `datakable/messages`. */
+declare const renderMessages: DiagnosticMessages<'DK_RENDER_FAILED'>;
+/** Codes owned by `<DataTable />` (§8.3, react). Emitted in production too; text behind NODE_ENV. */
+declare const renderDiagnostics: _datakable_core.DiagnosticDefinition<"DK_RENDER_FAILED">[];
+
+export { DataTable, type DataTableComponents, type DataTableOwnProps, type DataTableProps, type DataTableSource, type EmptyProps, type ErrorProps, type LoadingProps, type PaginationProps, type SearchInputProps, type UseDataTableOptions, type UseDataTableResult, cellSlot, invalidCellSlot, reactDiagnostics, renderDiagnostics, renderMessages, useDataTable };

package/dist/index.js

@@ -0,0 +1,18 @@
+// src/index.ts
+export * from "@datakable/core";
+import { reactDiagnostics } from "./codes.js";
+import {
+  DataTable
+} from "./data-table.js";
+import { cellSlot, invalidCellSlot, renderDiagnostics, renderMessages } from "./render-codes.js";
+import { useDataTable } from "./use-data-table.js";
+export {
+  DataTable,
+  cellSlot,
+  invalidCellSlot,
+  reactDiagnostics,
+  renderDiagnostics,
+  renderMessages,
+  useDataTable
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from '@datakable/core'\nexport { reactDiagnostics } from './codes'\nexport {\n  DataTable,\n  type DataTableComponents,\n  type DataTableOwnProps,\n  type DataTableProps,\n  type DataTableSource,\n  type EmptyProps,\n  type ErrorProps,\n  type LoadingProps,\n  type PaginationProps,\n  type SearchInputProps,\n} from './data-table'\nexport { cellSlot, invalidCellSlot, renderDiagnostics, renderMessages } from './render-codes'\nexport { type UseDataTableOptions, type UseDataTableResult, useDataTable } from './use-data-table'\n"],"mappings":";AAAA,cAAc;AACd,SAAS,wBAAwB;AACjC;AAAA,EACE;AAAA,OAUK;AACP,SAAS,UAAU,iBAAiB,mBAAmB,sBAAsB;AAC7E,SAA4D,oBAAoB;","names":[]}

package/dist/render-codes.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/render-codes.ts
+var render_codes_exports = {};
+__export(render_codes_exports, {
+  cellSlot: () => cellSlot,
+  invalidCellSlot: () => invalidCellSlot,
+  registerRenderOperations: () => registerRenderOperations,
+  renderDiagnostics: () => renderDiagnostics,
+  renderMessages: () => renderMessages
+});
+module.exports = __toCommonJS(render_codes_exports);
+var import_core = require("@datakable/core");
+function registerRenderOperations() {
+  (0, import_core.registerOperation)("render:table", { kind: "sync", hot: false });
+  (0, import_core.registerOperation)("render:cell", { kind: "sync", hot: false });
+}
+var cellSlot = (0, import_core.defineSlot)({
+  name: "cell",
+  returns: "sync",
+  fallback: "those cells rendered \u26A0"
+});
+var invalidCellSlot = (0, import_core.defineSlot)({
+  name: "invalidCell",
+  returns: "sync",
+  fallback: "those cells rendered \u26A0"
+});
+var renderMessages = {
+  DK_RENDER_FAILED: {
+    problem: (d) => d.op === "render:cell" ? `a component returned by ${d.slot} (column "${d.column}") threw${d.errorName ? ` ${d.errorName}` : ""} while rendering row #${d.row}` : `a component rendered inside the table body threw${d.errorName ? ` ${d.errorName}` : ""} (outside the cells: a components.Empty / Loading / Error part)`,
+    impact: (d) => d.op === "render:cell" ? "that cell renders \u26A0; the other cells and rows, the header, search, pagination and the table API keep working, and the cell renders again when its row's data or the columns change" : "the table body shows the Error state; the header, search and pagination keep working, and the body renders again on the next row model or Retry",
+    fix: (d) => d.op === "render:cell" ? [
+      `find the throwing component in context.cause (passed to onDiagnostic) and make it total: guard null / undefined / unexpected values of column "${d.column}" instead of throwing`,
+      `for your own fallback instead of \u26A0, wrap the component in an error boundary inside ${d.slot}`
+    ] : [
+      "find the throwing component in context.cause (passed to onDiagnostic) and make it total: guard null / undefined / unexpected values instead of throwing",
+      "a component returned by a column cell / invalidCell is caught per cell (\u26A0); a throw in the cell function itself is DK_CALLBACK_FAILED"
+    ]
+  }
+};
+var renderDiagnostics = [
+  (0, import_core.defineDiagnostic)(
+    {
+      code: "DK_RENDER_FAILED",
+      level: "error",
+      where: (d) => d.slot ? { kind: "operation", op: d.op, slot: d.slot } : { kind: "operation", op: d.op }
+    },
+    // Written out (not an imported flag) so a consumer's bundler folds it while parsing (§8.2).
+    process.env.NODE_ENV !== "production" && renderMessages.DK_RENDER_FAILED
+  )
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cellSlot,
+  invalidCellSlot,
+  registerRenderOperations,
+  renderDiagnostics,
+  renderMessages
+});
+//# sourceMappingURL=render-codes.cjs.map

package/dist/render-codes.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/render-codes.ts"],"sourcesContent":["import {\n  type DiagnosticMessages,\n  defineDiagnostic,\n  defineSlot,\n  registerOperation,\n} from '@datakable/core'\n\ndeclare module '@datakable/core' {\n  interface DiagnosticCatalog {\n    DK_RENDER_FAILED: {\n      /**\n       * The render operation: `render:cell` (a cell's boundary: a component returned by `cell` /\n       * `invalidCell`) or `render:table` (the body boundary: a component outside the cells).\n       */\n      op: 'render:table' | 'render:cell'\n      /** `render:cell`: the slot whose component threw, `columns[1].cell`. */\n      slot?: string\n      /** `render:cell`: the column id. */\n      column?: string\n      /** `render:cell`: the row's index in the data (the first failure; later ones are deduped). */\n      row?: number\n      /** `error.name` only; the full error is `context.cause`. */\n      errorName?: string\n    }\n  }\n\n  /** §3.4: React error boundaries, not interceptor chains (nothing runs interceptors on them). */\n  interface Operations {\n    'render:table': { kind: 'sync'; input: undefined; output: undefined }\n    'render:cell': {\n      kind: 'sync'\n      input: { column: string; slot: 'cell' | 'invalidCell'; row: number }\n      output: undefined\n    }\n  }\n}\n\n/**\n * Registers `render:table` / `render:cell` (§3.4: owned by `@datakable/react`, not core). Neither\n * is hot: no interceptor chain runs per cell, so `on: '*'` interceptors get no hot-op warning for\n * them. Idempotent (an identical re-registration is a no-op).\n */\nexport function registerRenderOperations(): void {\n  registerOperation('render:table', { kind: 'sync', hot: false })\n  registerOperation('render:cell', { kind: 'sync', hot: false })\n}\n\n// No @types/node here: declare just what is read.\ndeclare const process: { env: { NODE_ENV?: string } }\n\n/**\n * `columns[i].cell` (§4.1, §10): renders a React node synchronously. A thenable is a contract\n * violation (`DK_CALLBACK_BAD_RETURN`); `<DataTable />` renders `⚠` instead.\n */\nexport const cellSlot = defineSlot({\n  name: 'cell',\n  returns: 'sync',\n  fallback: 'those cells rendered ⚠',\n})\n\n/** `columns[i].invalidCell` (§5.1): renders a flagged cell; same contract as `cell`. */\nexport const invalidCellSlot = defineSlot({\n  name: 'invalidCell',\n  returns: 'sync',\n  fallback: 'those cells rendered ⚠',\n})\n\n/** Message text (§8.2): development builds, or production via `datakable/messages`. */\nexport const renderMessages: DiagnosticMessages<'DK_RENDER_FAILED'> = {\n  DK_RENDER_FAILED: {\n    problem: (d) =>\n      d.op === 'render:cell'\n        ? `a component returned by ${d.slot} (column \"${d.column}\") threw` +\n          `${d.errorName ? ` ${d.errorName}` : ''} while rendering row #${d.row}`\n        : `a component rendered inside the table body threw${d.errorName ? ` ${d.errorName}` : ''} ` +\n          '(outside the cells: a components.Empty / Loading / Error part)',\n    impact: (d) =>\n      d.op === 'render:cell'\n        ? 'that cell renders ⚠; the other cells and rows, the header, search, pagination and the ' +\n          \"table API keep working, and the cell renders again when its row's data or the columns \" +\n          'change'\n        : 'the table body shows the Error state; the header, search and pagination keep working, ' +\n          'and the body renders again on the next row model or Retry',\n    fix: (d) =>\n      d.op === 'render:cell'\n        ? [\n            `find the throwing component in context.cause (passed to onDiagnostic) and make it ` +\n              `total: guard null / undefined / unexpected values of column \"${d.column}\" ` +\n              'instead of throwing',\n            'for your own fallback instead of ⚠, wrap the component in an error boundary inside ' +\n              `${d.slot}`,\n          ]\n        : [\n            'find the throwing component in context.cause (passed to onDiagnostic) and make it ' +\n              'total: guard null / undefined / unexpected values instead of throwing',\n            'a component returned by a column cell / invalidCell is caught per cell (⚠); a throw in ' +\n              'the cell function itself is DK_CALLBACK_FAILED',\n          ],\n  },\n}\n\n/** Codes owned by `<DataTable />` (§8.3, react). Emitted in production too; text behind NODE_ENV. */\nexport const renderDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_RENDER_FAILED',\n      level: 'error',\n      where: (d) =>\n        d.slot ? { kind: 'operation', op: d.op, slot: d.slot } : { kind: 'operation', op: d.op },\n    },\n    // Written out (not an imported flag) so a consumer's bundler folds it while parsing (§8.2).\n    process.env.NODE_ENV !== 'production' && renderMessages.DK_RENDER_FAILED,\n  ),\n]\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAKO;AAqCA,SAAS,2BAAiC;AAC/C,qCAAkB,gBAAgB,EAAE,MAAM,QAAQ,KAAK,MAAM,CAAC;AAC9D,qCAAkB,eAAe,EAAE,MAAM,QAAQ,KAAK,MAAM,CAAC;AAC/D;AASO,IAAM,eAAW,wBAAW;AAAA,EACjC,MAAM;AAAA,EACN,SAAS;AAAA,EACT,UAAU;AACZ,CAAC;AAGM,IAAM,sBAAkB,wBAAW;AAAA,EACxC,MAAM;AAAA,EACN,SAAS;AAAA,EACT,UAAU;AACZ,CAAC;AAGM,IAAM,iBAAyD;AAAA,EACpE,kBAAkB;AAAA,IAChB,SAAS,CAAC,MACR,EAAE,OAAO,gBACL,2BAA2B,EAAE,IAAI,aAAa,EAAE,MAAM,WACnD,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE,yBAAyB,EAAE,GAAG,KACrE,mDAAmD,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE;AAAA,IAE7F,QAAQ,CAAC,MACP,EAAE,OAAO,gBACL,4LAGA;AAAA,IAEN,KAAK,CAAC,MACJ,EAAE,OAAO,gBACL;AAAA,MACE,kJACkE,EAAE,MAAM;AAAA,MAE1E,2FACK,EAAE,IAAI;AAAA,IACb,IACA;AAAA,MACE;AAAA,MAEA;AAAA,IAEF;AAAA,EACR;AACF;AAGO,IAAM,oBAAoB;AAAA,MAC/B;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,CAAC,MACN,EAAE,OAAO,EAAE,MAAM,aAAa,IAAI,EAAE,IAAI,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,aAAa,IAAI,EAAE,GAAG;AAAA,IAC3F;AAAA;AAAA,IAEA,QAAQ,IAAI,aAAa,gBAAgB,eAAe;AAAA,EAC1D;AACF;","names":[]}

package/dist/render-codes.js

@@ -0,0 +1,52 @@
+// src/render-codes.ts
+import {
+  defineDiagnostic,
+  defineSlot,
+  registerOperation
+} from "@datakable/core";
+function registerRenderOperations() {
+  registerOperation("render:table", { kind: "sync", hot: false });
+  registerOperation("render:cell", { kind: "sync", hot: false });
+}
+var cellSlot = defineSlot({
+  name: "cell",
+  returns: "sync",
+  fallback: "those cells rendered \u26A0"
+});
+var invalidCellSlot = defineSlot({
+  name: "invalidCell",
+  returns: "sync",
+  fallback: "those cells rendered \u26A0"
+});
+var renderMessages = {
+  DK_RENDER_FAILED: {
+    problem: (d) => d.op === "render:cell" ? `a component returned by ${d.slot} (column "${d.column}") threw${d.errorName ? ` ${d.errorName}` : ""} while rendering row #${d.row}` : `a component rendered inside the table body threw${d.errorName ? ` ${d.errorName}` : ""} (outside the cells: a components.Empty / Loading / Error part)`,
+    impact: (d) => d.op === "render:cell" ? "that cell renders \u26A0; the other cells and rows, the header, search, pagination and the table API keep working, and the cell renders again when its row's data or the columns change" : "the table body shows the Error state; the header, search and pagination keep working, and the body renders again on the next row model or Retry",
+    fix: (d) => d.op === "render:cell" ? [
+      `find the throwing component in context.cause (passed to onDiagnostic) and make it total: guard null / undefined / unexpected values of column "${d.column}" instead of throwing`,
+      `for your own fallback instead of \u26A0, wrap the component in an error boundary inside ${d.slot}`
+    ] : [
+      "find the throwing component in context.cause (passed to onDiagnostic) and make it total: guard null / undefined / unexpected values instead of throwing",
+      "a component returned by a column cell / invalidCell is caught per cell (\u26A0); a throw in the cell function itself is DK_CALLBACK_FAILED"
+    ]
+  }
+};
+var renderDiagnostics = [
+  defineDiagnostic(
+    {
+      code: "DK_RENDER_FAILED",
+      level: "error",
+      where: (d) => d.slot ? { kind: "operation", op: d.op, slot: d.slot } : { kind: "operation", op: d.op }
+    },
+    // Written out (not an imported flag) so a consumer's bundler folds it while parsing (§8.2).
+    process.env.NODE_ENV !== "production" && renderMessages.DK_RENDER_FAILED
+  )
+];
+export {
+  cellSlot,
+  invalidCellSlot,
+  registerRenderOperations,
+  renderDiagnostics,
+  renderMessages
+};
+//# sourceMappingURL=render-codes.js.map