@datakable/react 1.0.1 → 1.1.0

package/README.md

@@ -16,6 +16,7 @@ React `>=18`. The modules of `<DataTable />` and `useDataTable` carry a `"use cl
 so the Next.js app router treats them as client code even when a server component imports them
 from here; the rest (core's `createTable`, …) stays usable on the server. Like core,
 it needs a bundler that replaces `process.env.NODE_ENV` (see [core](https://github.com/Ink01101011/datakable/tree/main/packages/core)).
+In Node.js (SSR, tests) it needs Node `>=18.18`. The types need TypeScript `>=5.4`.
 
 ## useDataTable
 
@@ -109,8 +110,8 @@ for the features installed (this package installs none by default). Pass `table=
 to render a table you set up yourself, `components` to replace the search input, pager or states,
 and style it through the `data-*` hooks (`data-status`, `data-initial-load`, `data-sort`,
 `data-invalid`), or import the optional `@datakable/react/styles.css` (zero-specificity rules,
-themed through `--dk-*` custom properties). A `cell` that throws renders `⚠` in that cell
-(`DK_CALLBACK_FAILED`); so does a component it returns that throws while rendering — each such cell
+themed through `--dk-*` custom properties). A `cell` that throws renders `⚠` in that cell (named
+"Could not display this value" for screen readers, `DK_CALLBACK_FAILED`); so does a component it returns that throws while rendering — each such cell
 has its own error boundary, and the other cells keep rendering (`DK_RENDER_FAILED`). A component
 that throws elsewhere in the body shows the Error state with a retry.
 

package/dist/data-table.cjs

@@ -29,7 +29,7 @@ var import_react = require("react");
 var import_render_codes = require("./render-codes.cjs");
 var import_use_data_table = require("./use-data-table.cjs");
 var import_jsx_runtime = require("react/jsx-runtime");
-(0, import_core.keepDiagnostics)(import_render_codes.renderDiagnostics, import_core.boundaryDiagnostics, import_core.slotDiagnostics);
+(0, import_core.keepDiagnostics)(import_render_codes.renderDiagnostics, import_core.boundaryDiagnostics, import_core.slotDiagnostics, import_core.pipelineDiagnostics);
 (0, import_render_codes.registerRenderOperations)();
 var useIsomorphicLayoutEffect = typeof window === "undefined" ? import_react.useEffect : import_react.useLayoutEffect;
 function DataTable(props) {
@@ -44,6 +44,7 @@ function ZeroConfig(props) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataTableView, { table: view, components, caption });
 }
 var WARN = "\u26A0";
+var FAILED = /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { role: "img", "aria-label": "Could not display this value", children: WARN });
 var BUSY = ["validating", "pending", "searching", "fetching"];
 var LOADING = ["validating", "searching", "fetching"];
 function hasAsyncSource(table) {
@@ -76,7 +77,7 @@ var tableOf = (view) => Object.hasOwn(view, "rowModel") ? Object.getPrototypeOf(
 function report(table, failures) {
   const bySlot = /* @__PURE__ */ new Map();
   for (const f of failures) {
-    const k = `${f.slot}\0${f.expected === void 0 ? "throw" : "return"}`;
+    const k = `${f.slot}\0${f.lost ? "" : f.expected === void 0 ? "throw" : "return"}`;
     const list = bySlot.get(k);
     if (list) list.push(f);
     else bySlot.set(k, [f]);
@@ -84,9 +85,17 @@ function report(table, failures) {
   for (const list of bySlot.values()) {
     const first = list[0];
     const rows = list.slice(0, 3).map((f) => f.row);
-    const fallback = "those cells rendered \u26A0";
+    const fallback = "cells-warn";
     try {
-      if (first.expected === void 0) {
+      if (first.lost !== void 0) {
+        (0, import_core.emitTableDiagnostic)(table, "DK_UNRENDERABLE_VALUE", {
+          column: first.column,
+          index: first.index,
+          count: list.length,
+          rows,
+          valueType: first.lost
+        });
+      } else if (first.expected === void 0) {
         const e = first.error;
         (0, import_core.emitTableDiagnostic)(
           table,
@@ -116,6 +125,10 @@ function report(table, failures) {
     }
   }
 }
+var lost;
+var onLost = (v) => {
+  lost = v;
+};
 function cellContent(col, row, failures, table) {
   const def = col.def;
   const value = row.getValue(col.id);
@@ -147,15 +160,33 @@ function cellContent(col, row, failures, table) {
       bad(failures, col, row, slot, "a string", out);
       return (0, import_core.defaultFormat)(value);
     }
-    return (0, import_core.defaultFormat)(value);
+    const text = (0, import_core.defaultFormat)(value, onLost);
+    if (lost !== void 0) {
+      const { id: column, index } = col;
+      const type = Array.isArray(lost) ? "array" : typeof lost;
+      failures.push({ slot: `columns[${index}]`, column, index, row: row.index, lost: type });
+      lost = void 0;
+    }
+    return text;
   } catch (error) {
     failures.push({ slot: `columns[${col.index}].${slot}`, column: col.id, row: row.index, error });
-    return WARN;
+    return FAILED;
   }
 }
 function guard(out, table, col, row, slot) {
   if (typeof out !== "object" || out === null) return out;
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CellBoundary, { table, col, slot, row: row.index, original: row.original, children: out });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    Boundary,
+    {
+      table,
+      col,
+      slot,
+      row: row.index,
+      resetKey: row.original,
+      fallback: failedCell,
+      children: out
+    }
+  );
 }
 function bad(failures, col, row, slot, expected, out) {
   failures.push({
@@ -165,7 +196,31 @@ function bad(failures, col, row, slot, expected, out) {
     expected,
     received: (0, import_core.describeReturn)(out)
   });
-  return WARN;
+  return FAILED;
+}
+var HIDDEN = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  overflow: "hidden",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap"
+};
+var serverPaged = (view) => view.getOptions().features?.some(
+  (f) => f?.stage === "paginate" && f.mode === "server"
+) === true;
+function pages(view, page, count, server) {
+  if (server) {
+    return {
+      ...page,
+      pageCount: view.getPageCount?.() ?? 0,
+      canPrev: view.canPrevPage?.() ?? false,
+      canNext: view.canNextPage?.() ?? false
+    };
+  }
+  const pageCount = Math.ceil(count / page.pageSize);
+  const index = Math.min(page.pageIndex, Math.max(pageCount - 1, 0));
+  return { ...page, pageCount, canPrev: index > 0, canNext: index + 1 < pageCount };
 }
 var ariaSort = (dir) => dir === "asc" ? "ascending" : dir === "desc" ? "descending" : "none";
 function DataTableView(props) {
@@ -186,14 +241,45 @@ function DataTableView(props) {
     if (failures.length > 0) report(table, failures);
   });
   const sortable = typeof view.toggleSort === "function";
+  const sortBy = state.sorting?.by;
   const searchState = state.search;
   const paged = typeof view.getPageCount === "function";
   const loading = isInitialLoad && (LOADING.includes(status) || status === "pending" && hasAsyncSource(view));
   const failed = isInitialLoad && status === "error";
   const span = Math.max(columns.length, 1);
-  const retryLoad = () => void view.refetch();
-  const Search = parts.SearchInput ?? DefaultSearchInput;
-  const Pager = parts.Pagination ?? DefaultPagination;
+  const tableEl = (0, import_react.useRef)(null);
+  const keepFocus = () => {
+    const t = tableEl.current;
+    const from = document.activeElement?.closest("[data-dk-state],[data-dk-refresh]");
+    if (t && from && t.parentElement?.contains(from)) {
+      t.tabIndex = -1;
+      t.focus();
+    }
+  };
+  const retryLoad = () => {
+    keepFocus();
+    void view.refetch();
+  };
+  const server = paged && serverPaged(view);
+  const pager = paged ? pages(view, state.pagination, rowModel.filteredCount, server) : null;
+  const n = rowModel.filteredCount;
+  const count = `${n} row${n === 1 ? "" : "s"}`;
+  const page = pager ? `${pager.pageIndex + 1} of ${Math.max(pager.pageCount, 1)}` : "";
+  let said = "";
+  if (searchState?.status === "pending" || searchState?.status === "searching") {
+    said = "Searching rows\u2026";
+  } else if (status === "idle" && !loading) {
+    said = server && n ? `Page ${page}` : page ? `${count}, page ${page}` : count;
+  }
+  const liveEl = (0, import_react.useRef)(null);
+  const saidBefore = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    const el = liveEl.current;
+    if (el && saidBefore.current !== null && saidBefore.current !== said) el.textContent = said;
+    saidBefore.current = said;
+  });
+  const cap = props.caption;
+  const named = typeof cap === "string" || typeof cap === "number" ? `${cap}` : "";
   const Empty = parts.Empty ?? DefaultEmpty;
   const Loading = parts.Loading ?? DefaultLoading;
   const ErrorState = parts.Error ?? DefaultError;
@@ -232,6 +318,7 @@ function DataTableView(props) {
       );
     });
   }
+  if (typeof window === "undefined" && failures.length > 0) report(table, failures);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
     "div",
     {
@@ -240,22 +327,21 @@ function DataTableView(props) {
       "data-initial-load": isInitialLoad ? "true" : "false",
       "aria-busy": BUSY.includes(status) ? "true" : void 0,
       children: [
-        searchState && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-dk-search": "", "data-status": searchState.status, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-          Search,
-          {
-            value: searchState.input,
-            status: searchState.status,
-            onChange: (q) => void view.setSearch?.(q),
-            onSubmit: () => void view.flushSearch?.(),
-            onClear: () => view.clearSearch?.()
-          }
-        ) }),
+        searchState && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-dk-search": "", "data-status": searchState.status, children: part(table, "SearchInput", parts.SearchInput, DefaultSearchInput, {
+          value: searchState.input,
+          status: searchState.status,
+          onChange: (q) => void view.setSearch?.(q),
+          onSubmit: () => void view.flushSearch?.(),
+          onClear: () => view.clearSearch?.(),
+          label: named ? `Search ${named}` : "Search"
+        }) }),
         !loading && !failed && status !== "idle" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RefreshIndicator, { status, retry: retryLoad }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("table", { children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("table", { ref: tableEl, children: [
           props.caption != null && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("caption", { children: props.caption }),
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("thead", { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { children: columns.map((col) => {
             const canSort = sortable && col.def.sortable !== false;
-            const dir = canSort ? view.getSortDirection?.(col.id) ?? false : false;
+            const e = canSort ? sortBy?.find((x) => x.id === col.id) : void 0;
+            const dir = e ? e.desc ? "desc" : "asc" : false;
             return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
               "th",
               {
@@ -266,7 +352,7 @@ function DataTableView(props) {
                   "button",
                   {
                     type: "button",
-                    onClick: (e) => view.toggleSort?.(col.id, { multi: e.shiftKey }),
+                    onClick: (e2) => view.toggleSort?.(col.id, { multi: e2.shiftKey }),
                     children: [
                       col.header,
                       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "data-dk-sort-indicator": "", "aria-hidden": "true", children: dir === "asc" ? " \u25B2" : dir === "desc" ? " \u25BC" : "" })
@@ -278,77 +364,74 @@ function DataTableView(props) {
             );
           }) }) }),
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tbody", { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-            BodyBoundary,
+            Boundary,
             {
               table,
               resetKey: rowModel,
-              fallback: (retry) => stateRow(span, "error", /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ErrorState, { status, reason: "render", retry })),
+              fallback: (retry) => stateRow(
+                span,
+                "error",
+                /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  ErrorState,
+                  {
+                    status,
+                    reason: "render",
+                    retry: () => {
+                      keepFocus();
+                      retry();
+                    }
+                  }
+                )
+              ),
               children: body
             }
           ) })
         ] }),
-        paged && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-          Pager,
-          {
-            pageIndex: state.pagination.pageIndex,
-            pageSize: state.pagination.pageSize,
-            pageCount: view.getPageCount?.() ?? 0,
-            canPrev: view.canPrevPage?.() ?? false,
-            canNext: view.canNextPage?.() ?? false,
-            prev: () => view.prevPage?.(),
-            next: () => view.nextPage?.(),
-            setPageIndex: (i) => view.setPageIndex?.(i),
-            setPageSize: (n) => view.setPageSize?.(n)
-          }
-        )
+        pager && part(table, "Pagination", parts.Pagination, DefaultPagination, {
+          ...pager,
+          prev: () => view.prevPage?.(),
+          next: () => view.nextPage?.(),
+          setPageIndex: (i) => view.setPageIndex?.(i),
+          setPageSize: (n2) => view.setPageSize?.(n2),
+          label: named ? `${named} pagination` : "Pagination"
+        }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "aria-live": "polite", style: HIDDEN, ref: liveEl })
       ]
     }
   );
 }
+function part(table, name, Custom, Default, props) {
+  if (!Custom) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Default, { ...props });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    Boundary,
+    {
+      table,
+      slot: `components.${name}`,
+      resetKey: Custom,
+      fallback: () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Default, { ...props }),
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Custom, { ...props })
+    }
+  );
+}
 function stateRow(span, kind, content) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { "data-dk-state": kind, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("td", { colSpan: span, children: content }) });
 }
-var BodyBoundary = class extends import_react.Component {
-  constructor() {
-    super(...arguments);
-    this.state = { failed: false, key: this.props.resetKey };
-    this.retry = () => this.setState({ failed: false });
-  }
-  static getDerivedStateFromError() {
-    return { failed: true };
-  }
-  static getDerivedStateFromProps(props, state) {
-    return props.resetKey === state.key ? null : { failed: false, key: props.resetKey };
-  }
-  componentDidCatch(error) {
-    try {
-      (0, import_core.emitTableDiagnostic)(
-        this.props.table,
-        "DK_RENDER_FAILED",
-        { op: "render:table", ...error instanceof Error ? { errorName: error.name } : {} },
-        { cause: error }
-      );
-    } catch {
-    }
-  }
-  render() {
-    return this.state.failed ? this.props.fallback(this.retry) : this.props.children;
-  }
-};
-var CellBoundary = class extends import_react.Component {
+var Boundary = class extends import_react.Component {
   constructor() {
     super(...arguments);
     this.state = {
       failed: false,
-      original: this.props.original,
-      def: this.props.col.def
+      key: this.props.resetKey,
+      def: this.props.col?.def
     };
+    this.retry = () => this.setState({ failed: false });
   }
   static getDerivedStateFromError() {
     return { failed: true };
   }
   static getDerivedStateFromProps(props, state) {
-    return props.original === state.original && props.col.def === state.def ? null : { failed: false, original: props.original, def: props.col.def };
+    const def = props.col?.def;
+    return props.resetKey === state.key && def === state.def ? null : { failed: false, key: props.resetKey, def };
   }
   componentDidCatch(error) {
     const { table, col, slot, row } = this.props;
@@ -357,10 +440,9 @@ var CellBoundary = class extends import_react.Component {
         table,
         "DK_RENDER_FAILED",
         {
-          op: "render:cell",
-          slot: `columns[${col.index}].${slot}`,
-          column: col.id,
-          row,
+          op: col ? "render:cell" : "render:table",
+          ...slot ? { slot: col ? `columns[${col.index}].${slot}` : slot } : {},
+          ...col ? { column: col.id, row } : {},
           ...error instanceof Error ? { errorName: error.name } : {}
         },
         { cause: error }
@@ -369,16 +451,24 @@ var CellBoundary = class extends import_react.Component {
     }
   }
   render() {
-    return this.state.failed ? WARN : this.props.children;
+    return this.state.failed ? this.props.fallback(this.retry) : this.props.children;
   }
 };
-function DefaultSearchInput({ value, status, onChange, onSubmit, onClear }) {
+var failedCell = () => FAILED;
+function DefaultSearchInput({
+  value,
+  status,
+  onChange,
+  onSubmit,
+  onClear,
+  label
+}) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       "input",
       {
         type: "search",
-        "aria-label": "Search",
+        "aria-label": label,
         value,
         onChange: (e) => onChange(e.target.value),
         onKeyDown: (e) => {
@@ -387,19 +477,38 @@ function DefaultSearchInput({ value, status, onChange, onSubmit, onClear }) {
         }
       }
     ),
-    (status === "pending" || status === "searching") && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { role: "status", "data-dk-spinner": "", "aria-label": "Searching" })
+    (status === "pending" || status === "searching") && // Decorative: the live region says "Searching…" (an empty status announces nothing).
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "data-dk-spinner": "", "aria-hidden": "true" })
   ] });
 }
 function DefaultPagination(p) {
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("nav", { "aria-label": "Pagination", "data-dk-pagination": "", children: [
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", "aria-label": "Previous page", disabled: !p.canPrev, onClick: p.prev, children: "\u2039" }),
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("nav", { "aria-label": p.label, "data-dk-pagination": "", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        "aria-label": "Previous page",
+        "aria-disabled": !p.canPrev || void 0,
+        onClick: p.canPrev ? p.prev : void 0,
+        children: "\u2039"
+      }
+    ),
     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { "data-dk-page": "", children: [
       "Page ",
       p.pageIndex + 1,
       " of ",
       Math.max(p.pageCount, 1)
     ] }),
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", "aria-label": "Next page", disabled: !p.canNext, onClick: p.next, children: "\u203A" })
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        "aria-label": "Next page",
+        "aria-disabled": !p.canNext || void 0,
+        onClick: p.canNext ? p.next : void 0,
+        children: "\u203A"
+      }
+    )
   ] });
 }
 var DefaultEmpty = ({ filtered }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: filtered ? "No matching rows" : "No rows" });