@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/src/core/controlledState.ts

@@ -0,0 +1,179 @@
+import type { TableState } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+type GridState = TableState<TMDataGridFeatures>;
+
+/**
+ * Support for TanStack's `state` option (controlled state).
+ *
+ * table-core re-reads `options.state` on every render (`useTable` calls
+ * `setOptions` while rendering) and writes any slice whose value is not
+ * identical to the table's current value into the table's atom. The write
+ * publishes the store and re-renders the consumer, so a slice object built in
+ * the render body causes an infinite render loop.
+ *
+ * {@link stabilizeControlledState} prevents the loop by forwarding the
+ * previous render's value for a slice whose contents are unchanged.
+ * {@link findFrozenStateSlices} detects a controlled slice without its
+ * `onXChange` callback, which the grid cannot write to.
+ */
+
+/**
+ * The `onXChange` option that owns each controlled slice - every slice v9
+ * defines. `globalFilterFn` is not among them: in this beta it is a table
+ * option, not state.
+ */
+export const CONTROLLED_SLICE_HANDLERS = {
+  columnFilters: "onColumnFiltersChange",
+  columnOrder: "onColumnOrderChange",
+  columnPinning: "onColumnPinningChange",
+  columnResizing: "onColumnResizingChange",
+  columnSizing: "onColumnSizingChange",
+  columnVisibility: "onColumnVisibilityChange",
+  expanded: "onExpandedChange",
+  globalFilter: "onGlobalFilterChange",
+  grouping: "onGroupingChange",
+  pagination: "onPaginationChange",
+  rowPinning: "onRowPinningChange",
+  rowSelection: "onRowSelectionChange",
+  sorting: "onSortingChange",
+} as const satisfies Partial<Record<keyof GridState, string>>;
+
+export type TMDataGridControlledSlice = keyof typeof CONTROLLED_SLICE_HANDLERS;
+
+/** The options {@link findFrozenStateSlices} reads - a subset of `TableOptions`. */
+type ControlledOptions = {
+  state?: Partial<GridState>;
+  /**
+   * The v9 way of owning a slice: an atom the table writes through directly.
+   * It outranks `state`, so a slice backed by one is never frozen.
+   */
+  atoms?: Record<string, unknown>;
+} & Partial<
+  Record<(typeof CONTROLLED_SLICE_HANDLERS)[TMDataGridControlledSlice], unknown>
+>;
+
+const hasOwn = (value: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/**
+ * A plain data object: `Object.prototype` or null prototype. table-core builds
+ * its state maps with `Object.create(null)`, so null prototypes must compare
+ * as plain objects.
+ */
+function isDataObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Structural equality for state values.
+ *
+ * `Date`s compare by time; the built-in date filters hold them in filter
+ * values. `Map`s and class instances compare by identity, so a controlled
+ * slice containing one rebuilt each render reads as changed on every render
+ * and re-renders the table. Use primitives, plain objects, arrays or `Date`s
+ * in controlled state.
+ */
+export function sameStateValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date || b instanceof Date) {
+    return (
+      a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+    );
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b)) return false;
+    return (
+      a.length === b.length &&
+      a.every((item, index) => sameStateValue(item, b[index]))
+    );
+  }
+  if (!isDataObject(a) || !isDataObject(b)) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => hasOwn(b, key) && sameStateValue(a[key], b[key]));
+}
+
+/**
+ * Removes keys whose value is `undefined`, as in
+ * `state: { sorting: cond ? sorting : undefined }`.
+ *
+ * TanStack's sync writes every present key into the slice's atom, `undefined`
+ * included, which breaks everything that reads the slice. A key set to
+ * `undefined` is treated as not controlled: the key is removed and the slice
+ * falls back to the table's own state. Identity is preserved when there is
+ * nothing to remove; the stabilizer compares by it.
+ */
+export function withoutUndefinedSlices(
+  state: Partial<GridState> | undefined,
+): Partial<GridState> | undefined {
+  if (state === undefined) return state;
+  if (!Object.values(state).includes(undefined)) return state;
+  const compacted: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (value !== undefined) compacted[key] = value;
+  }
+  return compacted as Partial<GridState>;
+}
+
+/**
+ * Returns `next` with every slice that structurally equals its counterpart in
+ * `previous` replaced by the previous object, so table-core's identity-based
+ * sync finds nothing to write. Returns `previous` when nothing changed.
+ */
+export function stabilizeControlledState(
+  next: Partial<GridState> | undefined,
+  previous: Partial<GridState> | undefined,
+): Partial<GridState> | undefined {
+  if (next === undefined || previous === undefined || next === previous) {
+    return next;
+  }
+
+  const keys = Object.keys(next);
+  const stabilized: Record<string, unknown> = {};
+  let changed = keys.length !== Object.keys(previous).length;
+
+  for (const key of keys) {
+    const nextValue = (next as Record<string, unknown>)[key];
+    const previousValue = (previous as Record<string, unknown>)[key];
+    if (hasOwn(previous, key) && sameStateValue(nextValue, previousValue)) {
+      // Unchanged contents: keep the object the table already holds.
+      stabilized[key] = previousValue;
+    } else {
+      stabilized[key] = nextValue;
+      changed = true;
+    }
+  }
+
+  return changed ? (stabilized as Partial<GridState>) : previous;
+}
+
+/**
+ * Controlled slices without a write path: `state.x` is set but no `onXChange`
+ * was passed and no external atom owns the slice. TanStack routes every write
+ * through the callback, so such a slice cannot change. Reported so the hook
+ * can warn in development; `initialState` is the option for a starting value.
+ */
+export function findFrozenStateSlices(
+  options: ControlledOptions,
+): Array<{ slice: TMDataGridControlledSlice; handler: string }> {
+  const state = options.state;
+  if (state === undefined) return [];
+
+  return (
+    Object.entries(CONTROLLED_SLICE_HANDLERS) as Array<
+      [TMDataGridControlledSlice, string]
+    >
+  )
+    .filter(
+      ([slice, handler]) =>
+        // Undefined-valued keys are removed before the table sees them; the
+        // slice is not controlled.
+        (state as Record<string, unknown>)[slice] !== undefined &&
+        (options as Record<string, unknown>)[handler] === undefined &&
+        options.atoms?.[slice] === undefined,
+    )
+    .map(([slice, handler]) => ({ slice, handler }));
+}

package/src/core/controlledStateSync.ts

@@ -0,0 +1,108 @@
+import type { ReadonlyStore, Store } from "@tanstack/store";
+
+/**
+ * Timing repair for TanStack's controlled-state sync.
+ *
+ * `useTable` calls `table.setOptions` from its render body, and that syncs
+ * `options.state` into the table's atoms. An atom write publishes the store
+ * synchronously, so every component subscribed to `table.store` schedules a
+ * setState while the consumer's component is still rendering - which React
+ * reports as "Cannot update a component (X) while rendering a different
+ * component (Y)", pointing at the consumer's component rather than at the
+ * grid.
+ *
+ * The write has to stay where it is: the atoms must hold the controlled value
+ * before the table builds its row models for that render. Only the
+ * notification is early, so it moves to a microtask. `getSnapshot` already
+ * returns the new value, so a component reads the same state either way; the
+ * subscription is only what schedules a re-render for the components the
+ * consumer's own render does not reach.
+ *
+ * Scope and assumptions. Only `table.store` is patched: a subscription made
+ * on `table.atoms.*` or `table.baseAtoms.*` keeps the synchronous timing.
+ * The patch leans on three table-core 9.0.0-beta.21 internals - the store is
+ * created once in `constructTable`, `useTable` returns a shallow copy that
+ * shares it, and the sync runs inside `setOptions` during render. The
+ * publish test in controlledState.test.tsx fails loudly if any of them
+ * moves; it is the guard for this module, not a redundant check. The
+ * intended end state - owning the controlled slices through `options.atoms`,
+ * which removes the render-time sync entirely - is in the backlog.
+ */
+
+type Observer = ((value: unknown) => void) | { next?: (value: unknown) => void };
+
+type Subscribe = (observer: Observer) => { unsubscribe: () => void };
+
+/**
+ * True while `useTable` is syncing controlled state inside a render pass.
+ * Process-global, so while one grid is inside its `useTable` call a publish
+ * on any patched store is deferred too - harmless, since nothing else runs
+ * during a synchronous render pass.
+ */
+let syncing = false;
+
+/**
+ * Called immediately before the `useTable` call that performs the sync.
+ *
+ * The microtask is the backstop that bounds the flag to the current task: if
+ * `useTable` throws and an error boundary unmounts the grid, nothing after
+ * the call runs, and without it every patched store would keep deferring its
+ * notifications for the life of the page.
+ */
+export function beginControlledStateSync(): void {
+  syncing = true;
+  queueMicrotask(() => {
+    syncing = false;
+  });
+}
+
+/**
+ * Called immediately after it - the prompt clear; correctness rests on the
+ * backstop above. Not a `finally` around the call, because hooks inside
+ * `try` opt the whole hook out of the React Compiler.
+ */
+export function endControlledStateSync(): void {
+  syncing = false;
+}
+
+const patched = new WeakSet<object>();
+
+/**
+ * Wraps a table store's `subscribe` so notifications raised during the sync
+ * are delivered in a microtask. Idempotent, and installed on the store object
+ * itself rather than on a copy of the table - rows hold the original, so
+ * `row.table.store` has to be the patched one.
+ */
+export function deferControlledStateSyncPublishes<TState>(
+  store: Store<TState> | ReadonlyStore<TState>,
+): void {
+  if (patched.has(store)) return;
+  patched.add(store);
+
+  const subscribe = store.subscribe.bind(store) as Subscribe;
+
+  (store as unknown as { subscribe: Subscribe }).subscribe = (observer) => {
+    const next =
+      typeof observer === "function" ? observer : observer.next?.bind(observer);
+    if (next === undefined) return subscribe(observer);
+
+    let live = true;
+    const subscription = subscribe((value) => {
+      if (!syncing) {
+        next(value);
+        return;
+      }
+      queueMicrotask(() => {
+        // The subscriber may have unmounted between the write and the flush.
+        if (live) next(value);
+      });
+    });
+
+    return {
+      unsubscribe: () => {
+        live = false;
+        subscription.unsubscribe();
+      },
+    };
+  };
+}

package/src/core/deletedRows.ts

@@ -0,0 +1,34 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * Which rows of a table carry a deletion mark, for readers that hold the
+ * table and nothing else - `exportGrid`, `buildGridCellMatrix` and the
+ * export data they build on. The marks live in the edit engine, which those
+ * readers cannot reach; the hook registers the engine's answer per table
+ * instead. A table built without the grid has no marks.
+ */
+// Keyed on the store, not the table: `useTable` hands out a fresh shallow
+// copy of the table on every render, and every copy shares the one store.
+const sources = new WeakMap<object, (rowId: string) => boolean>();
+
+/** Registers the answer for one table; returns the unregister. */
+export function registerDeletedRows<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  isRowDeleted: (rowId: string) => boolean,
+): () => void {
+  sources.set(table.store, isRowDeleted);
+  return () => {
+    if (sources.get(table.store) === isRowDeleted) {
+      sources.delete(table.store);
+    }
+  };
+}
+
+/** Whether the row is marked for deletion under `editing.draft`. */
+export function isRowMarkedDeleted<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  rowId: string,
+): boolean {
+  return sources.get(table.store)?.(rowId) ?? false;
+}

package/src/core/dom.ts

@@ -0,0 +1,74 @@
+/**
+ * DOM checks that survive a second realm.
+ *
+ * The grid can be rendered through a portal into a window opened with
+ * `window.open`. That window is a separate JavaScript realm: its nodes and
+ * events are instances of *its* `Node`, `Element`, `HTMLInputElement` and
+ * `MouseEvent`, not the opener's. A plain `x instanceof HTMLInputElement`
+ * is therefore false for an input sitting in the grid's own window, and the
+ * check silently takes the wrong branch.
+ *
+ * Every helper here answers the same question either by duck-typing, or by
+ * taking the constructor from the realm the value itself came from.
+ */
+
+/**
+ * The window a node lives in - the realm to take its constructors from.
+ *
+ * A document made by `createHTMLDocument` has no window of its own, so the
+ * global one is the fallback.
+ */
+export function windowOf(node: Node): Window & typeof globalThis {
+  return node.ownerDocument?.defaultView ?? window;
+}
+
+/**
+ * Whether a value is a DOM node.
+ *
+ * Duck-typed on `nodeType`, because `instanceof Node` is false for a node
+ * from another realm.
+ */
+export function isNode(value: unknown): value is Node {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Node).nodeType === "number"
+  );
+}
+
+/**
+ * Whether a value is an element - a node whose `nodeType` is 1
+ * (`Node.ELEMENT_NODE`), read as a number so no realm's constant is needed.
+ */
+export function isElement(value: unknown): value is Element {
+  return isNode(value) && value.nodeType === 1;
+}
+
+/** Whether a value is an HTML element, asked of its own realm's constructor. */
+export function isHTMLElement(value: unknown): value is HTMLElement {
+  return isElement(value) && value instanceof windowOf(value).HTMLElement;
+}
+
+/** Whether a value is an `<input>`, asked of its own realm's constructor. */
+export function isInputElement(value: unknown): value is HTMLInputElement {
+  return isElement(value) && value instanceof windowOf(value).HTMLInputElement;
+}
+
+/** Whether a value is a `<button>`, asked of its own realm's constructor. */
+export function isButtonElement(value: unknown): value is HTMLButtonElement {
+  return isElement(value) && value instanceof windowOf(value).HTMLButtonElement;
+}
+
+/**
+ * Whether an event is a mouse event, asked of the constructor in the event's
+ * own window.
+ *
+ * A browser-dispatched event carries that window in `view`; one built by hand
+ * may not, and its target still knows the window.
+ */
+export function isMouseEvent(event: Event): event is MouseEvent {
+  const view =
+    (event as UIEvent).view ??
+    (isNode(event.target) ? windowOf(event.target) : window);
+  return event instanceof (view as Window & typeof globalThis).MouseEvent;
+}