@zvndev/yable-react 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Table as Table$1, RowData, Cell, Header, Row, TableOptions, ColumnDef, SortDirection, CellContext, ClipboardOptions, CellFlashInfo } from '@zvndev/yable-core';
-export { AccessorFnColumnDef, AccessorKeyColumnDef, AggregationFn, Cell, CellStatus as CellCommitStatus, CellContext, CellFlashEvent, CellPatch, ClipboardOptions, Column, ColumnDef, ColumnDefBase, ColumnFiltersState, ColumnMeta, ColumnOrderState, ColumnPinningState, ColumnSizingInfoState, ColumnSizingState, CommitError, CommitErrorCells, CommitRecord, CommitResult, CommitsSlice, DisplayColumnDef, EditingState, ExpandedState, FillHandleState, FilterFn, FormulaState, GroupColumnDef, Header, HeaderContext, HeaderGroup, KeyboardNavigationAction, KeyboardNavigationCell, KeyboardNavigationDirection, KeyboardNavigationState, OnChangeFn, OnCommitFn, PaginationState, PartialLocale, PivotConfig, PivotState, Row, RowData, RowDragEndEvent, RowDragEvent, RowDragState, RowEditCommitEvent, RowEditEvent, RowPinningState, RowReorderEvent, RowSelectionState, SortDirection, SortingFn, SortingState, Table as TableInstance, TableOptions, TableOptionsResolved, TableState, UndoAction, UndoRedoState, Updater, VisibilityState, YableLocale, aggregationFns, createColumnHelper, createLocale, en, filterFns, functionalUpdate, getDefaultLocale, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
+export { AccessorFnColumnDef, AccessorKeyColumnDef, AggregationFn, Cell, CellStatus as CellCommitStatus, CellContext, CellFlashEvent, CellPatch, ClipboardOptions, Column, ColumnDef, ColumnDefBase, ColumnFiltersState, ColumnMeta, ColumnOrderState, ColumnPinningState, ColumnSizingInfoState, ColumnSizingState, CommitError, CommitErrorCells, CommitRecord, CommitResult, CommitsSlice, DisplayColumnDef, EditingState, ExpandedState, FillHandleState, FilterFn, FormulaEngine, FormulaError, FormulaFunction, FormulaState, GroupColumnDef, Header, HeaderContext, HeaderGroup, KeyboardNavigationAction, KeyboardNavigationCell, KeyboardNavigationDirection, KeyboardNavigationState, OnChangeFn, OnCommitFn, PaginationState, PartialLocale, PivotColumn, PivotConfig, PivotEngine, PivotFieldConfig, PivotRow, PivotState, PivotValueConfig, Row, RowData, RowDragEndEvent, RowDragEvent, RowDragState, RowEditCommitEvent, RowEditEvent, RowPinningState, RowReorderEvent, RowSelectionState, SortDirection, SortingFn, SortingState, Table as TableInstance, TableOptions, TableOptionsResolved, TableState, UndoAction, UndoRedoOptions, UndoRedoState, UndoStack, Updater, VisibilityState, YableLocale, aggregationFns, createColumnHelper, createLocale, createUndoRedoIntegration, en, filterFns, formulaFunctions, functionalUpdate, generatePivotColumnDefs, getDefaultLocale, getInitialPivotState, getPivotRowModel, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
 import * as React$1 from 'react';
 import React__default, { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -75,6 +75,20 @@ interface TableHeaderCellProps<TData extends RowData, TValue = unknown> extends
     header: Header<TData, TValue>;
 }
 
+/**
+ * React hook that wraps the framework-agnostic core table engine.
+ *
+ * Returns a stable {@link Table} instance whose `state` reflects either
+ * the consumer's controlled `options.state` or the hook's internal state.
+ *
+ * Re-renders are triggered by `setState` from the default `onStateChange`
+ * implementation. Consumers may pass their own `onStateChange` to control
+ * state externally.
+ *
+ * Gotcha: `options.onStateChange` is captured via a latest-ref, so a fresh
+ * function identity from the parent is always invoked — even if every other
+ * option key is shallow-equal to the previous render.
+ */
 declare function useTable<TData extends RowData>(options: TableOptions<TData>): Table$1<TData>;
 
 interface VirtualRow {
@@ -104,7 +118,12 @@ interface UseVirtualizationResult {
  * Computes which rows are visible in a scrollable container and returns
  * positioning data so only those rows (plus an overscan buffer) are rendered.
  *
- * Supports both fixed and variable row heights.
+ * Returns `{ virtualRows, totalHeight, startIndex, endIndex, scrollTo }`.
+ * Re-renders are triggered by scroll (rAF-throttled) and ResizeObserver
+ * container resize. Supports fixed, variable, and Pretext-pre-measured heights.
+ *
+ * Gotcha: variable-height mode caches measured heights per index — pass new
+ * `pretextHeights` arrays (or change `totalRows`) to invalidate the cache.
  */
 declare function useVirtualization({ containerRef, totalRows, rowHeight, overscan, estimateRowHeight: _estimateRowHeight, pretextHeights, pretextPrefixSums, }: UseVirtualizationOptions): UseVirtualizationResult;
 
@@ -154,11 +173,15 @@ interface UsePretextMeasurementResult {
 }
 /**
  * Pre-computes exact pixel heights for every row using Pretext's
- * DOM-free text measurement. Returns typed arrays for cache-friendly
- * access by the virtualizer.
+ * DOM-free text measurement.
+ *
+ * Returns `{ rowHeights, prefixSums, totalHeight, ready, ... }` as typed
+ * arrays for cache-friendly access by the virtualizer. `prepare()` re-runs
+ * when `data` or fonts change; `layout()` re-runs only when column widths
+ * change (pure math, ~0.0003ms per cell).
  *
- * layout() is pure arithmetic (~0.0003ms per cell) so column resizing
- * re-computes all heights near-instantly.
+ * Gotcha: pretext is loaded lazily — `ready` flips to true on the first
+ * render after the dynamic import resolves and heights are computed.
  */
 declare function usePretextMeasurement({ data, columns, getCellText, minRowHeight, enabled, }: UsePretextMeasurementOptions): UsePretextMeasurementResult;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Table as Table$1, RowData, Cell, Header, Row, TableOptions, ColumnDef, SortDirection, CellContext, ClipboardOptions, CellFlashInfo } from '@zvndev/yable-core';
-export { AccessorFnColumnDef, AccessorKeyColumnDef, AggregationFn, Cell, CellStatus as CellCommitStatus, CellContext, CellFlashEvent, CellPatch, ClipboardOptions, Column, ColumnDef, ColumnDefBase, ColumnFiltersState, ColumnMeta, ColumnOrderState, ColumnPinningState, ColumnSizingInfoState, ColumnSizingState, CommitError, CommitErrorCells, CommitRecord, CommitResult, CommitsSlice, DisplayColumnDef, EditingState, ExpandedState, FillHandleState, FilterFn, FormulaState, GroupColumnDef, Header, HeaderContext, HeaderGroup, KeyboardNavigationAction, KeyboardNavigationCell, KeyboardNavigationDirection, KeyboardNavigationState, OnChangeFn, OnCommitFn, PaginationState, PartialLocale, PivotConfig, PivotState, Row, RowData, RowDragEndEvent, RowDragEvent, RowDragState, RowEditCommitEvent, RowEditEvent, RowPinningState, RowReorderEvent, RowSelectionState, SortDirection, SortingFn, SortingState, Table as TableInstance, TableOptions, TableOptionsResolved, TableState, UndoAction, UndoRedoState, Updater, VisibilityState, YableLocale, aggregationFns, createColumnHelper, createLocale, en, filterFns, functionalUpdate, getDefaultLocale, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
+export { AccessorFnColumnDef, AccessorKeyColumnDef, AggregationFn, Cell, CellStatus as CellCommitStatus, CellContext, CellFlashEvent, CellPatch, ClipboardOptions, Column, ColumnDef, ColumnDefBase, ColumnFiltersState, ColumnMeta, ColumnOrderState, ColumnPinningState, ColumnSizingInfoState, ColumnSizingState, CommitError, CommitErrorCells, CommitRecord, CommitResult, CommitsSlice, DisplayColumnDef, EditingState, ExpandedState, FillHandleState, FilterFn, FormulaEngine, FormulaError, FormulaFunction, FormulaState, GroupColumnDef, Header, HeaderContext, HeaderGroup, KeyboardNavigationAction, KeyboardNavigationCell, KeyboardNavigationDirection, KeyboardNavigationState, OnChangeFn, OnCommitFn, PaginationState, PartialLocale, PivotColumn, PivotConfig, PivotEngine, PivotFieldConfig, PivotRow, PivotState, PivotValueConfig, Row, RowData, RowDragEndEvent, RowDragEvent, RowDragState, RowEditCommitEvent, RowEditEvent, RowPinningState, RowReorderEvent, RowSelectionState, SortDirection, SortingFn, SortingState, Table as TableInstance, TableOptions, TableOptionsResolved, TableState, UndoAction, UndoRedoOptions, UndoRedoState, UndoStack, Updater, VisibilityState, YableLocale, aggregationFns, createColumnHelper, createLocale, createUndoRedoIntegration, en, filterFns, formulaFunctions, functionalUpdate, generatePivotColumnDefs, getDefaultLocale, getInitialPivotState, getPivotRowModel, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
 import * as React$1 from 'react';
 import React__default, { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -75,6 +75,20 @@ interface TableHeaderCellProps<TData extends RowData, TValue = unknown> extends
     header: Header<TData, TValue>;
 }
 
+/**
+ * React hook that wraps the framework-agnostic core table engine.
+ *
+ * Returns a stable {@link Table} instance whose `state` reflects either
+ * the consumer's controlled `options.state` or the hook's internal state.
+ *
+ * Re-renders are triggered by `setState` from the default `onStateChange`
+ * implementation. Consumers may pass their own `onStateChange` to control
+ * state externally.
+ *
+ * Gotcha: `options.onStateChange` is captured via a latest-ref, so a fresh
+ * function identity from the parent is always invoked — even if every other
+ * option key is shallow-equal to the previous render.
+ */
 declare function useTable<TData extends RowData>(options: TableOptions<TData>): Table$1<TData>;
 
 interface VirtualRow {
@@ -104,7 +118,12 @@ interface UseVirtualizationResult {
  * Computes which rows are visible in a scrollable container and returns
  * positioning data so only those rows (plus an overscan buffer) are rendered.
  *
- * Supports both fixed and variable row heights.
+ * Returns `{ virtualRows, totalHeight, startIndex, endIndex, scrollTo }`.
+ * Re-renders are triggered by scroll (rAF-throttled) and ResizeObserver
+ * container resize. Supports fixed, variable, and Pretext-pre-measured heights.
+ *
+ * Gotcha: variable-height mode caches measured heights per index — pass new
+ * `pretextHeights` arrays (or change `totalRows`) to invalidate the cache.
  */
 declare function useVirtualization({ containerRef, totalRows, rowHeight, overscan, estimateRowHeight: _estimateRowHeight, pretextHeights, pretextPrefixSums, }: UseVirtualizationOptions): UseVirtualizationResult;
 
@@ -154,11 +173,15 @@ interface UsePretextMeasurementResult {
 }
 /**
  * Pre-computes exact pixel heights for every row using Pretext's
- * DOM-free text measurement. Returns typed arrays for cache-friendly
- * access by the virtualizer.
+ * DOM-free text measurement.
+ *
+ * Returns `{ rowHeights, prefixSums, totalHeight, ready, ... }` as typed
+ * arrays for cache-friendly access by the virtualizer. `prepare()` re-runs
+ * when `data` or fonts change; `layout()` re-runs only when column widths
+ * change (pure math, ~0.0003ms per cell).
  *
- * layout() is pure arithmetic (~0.0003ms per cell) so column resizing
- * re-computes all heights near-instantly.
+ * Gotcha: pretext is loaded lazily — `ready` flips to true on the first
+ * render after the dynamic import resolves and heights are computed.
  */
 declare function usePretextMeasurement({ data, columns, getCellText, minRowHeight, enabled, }: UsePretextMeasurementOptions): UsePretextMeasurementResult;
 

package/dist/index.js

@@ -1,5 +1,5 @@
-import { canCellEnterEditMode, functionalUpdate, createTable, getFirstKeyboardCell, getResolvedFocusedCell, detectCellChanges } from '@zvndev/yable-core';
-export { CommitError, aggregationFns, createColumnHelper, createLocale, en, filterFns, functionalUpdate, getDefaultLocale, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
+import { canCellEnterEditMode, functionalUpdate, createTable, getDefaultLocale, getFirstKeyboardCell, getResolvedFocusedCell, detectCellChanges } from '@zvndev/yable-core';
+export { CommitError, FormulaEngine, FormulaError, PivotEngine, UndoStack, aggregationFns, createColumnHelper, createLocale, createUndoRedoIntegration, en, filterFns, formulaFunctions, functionalUpdate, generatePivotColumnDefs, getDefaultLocale, getInitialPivotState, getPivotRowModel, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
 import React3, { createContext, useCallback, useMemo, useState, useRef, useEffect, useContext } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { getInitialRowDragState, moveRow } from '@zvndev/yable-core/features/rowDragging';
@@ -64,6 +64,8 @@ function useTable(options) {
     prevOptionsRef.current = options;
     return options;
   }, [options]);
+  const onStateChangeRef = useRef(options.onStateChange);
+  onStateChangeRef.current = options.onStateChange;
   const resolvedState = useMemo(
     () => ({
       ...state,
@@ -73,13 +75,14 @@ function useTable(options) {
   );
   const onStateChange = useCallback(
     (updater) => {
-      if (stableOptions.onStateChange) {
-        stableOptions.onStateChange(updater);
+      const latest = onStateChangeRef.current;
+      if (latest) {
+        latest(updater);
       } else {
         setState((prev) => functionalUpdate(updater, prev));
       }
     },
-    [stableOptions.onStateChange]
+    []
   );
   const resolvedOptions = useMemo(
     () => ({
@@ -1715,19 +1718,20 @@ function Spinner() {
 function LoadingOverlay({
   loading,
   loadingComponent,
-  loadingText = "Loading..."
+  loadingText
 }) {
   if (!loading) return null;
+  const resolvedText = loadingText ?? getDefaultLocale().loadingText;
   return /* @__PURE__ */ jsx(
     "div",
     {
       className: "yable-overlay-loading",
       role: "alert",
       "aria-busy": "true",
-      "aria-label": loadingText,
+      "aria-label": resolvedText,
       children: /* @__PURE__ */ jsx("div", { className: "yable-overlay-loading-content", children: loadingComponent ?? /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx(Spinner, {}),
-        loadingText && /* @__PURE__ */ jsx("span", { className: "yable-overlay-loading-text", children: loadingText })
+        resolvedText && /* @__PURE__ */ jsx("span", { className: "yable-overlay-loading-text", children: resolvedText })
       ] }) })
     }
   );
@@ -1845,8 +1849,9 @@ function NoRowsOverlay({
   if (emptyComponent) {
     return /* @__PURE__ */ jsx("div", { className: "yable-overlay-empty", children: emptyComponent });
   }
-  const defaultMessage = isFiltered ? "No results found" : "No data";
-  const defaultDetail = isFiltered ? "Try adjusting your search or filter criteria." : "There are no rows to display.";
+  const locale = getDefaultLocale();
+  const defaultMessage = isFiltered ? locale.emptyNoResults : locale.emptyNoData;
+  const defaultDetail = isFiltered ? locale.emptyNoResultsDetail : locale.emptyNoDataDetail;
   const icon = emptyIcon ?? (isFiltered ? /* @__PURE__ */ jsx(DefaultFilteredIcon, {}) : /* @__PURE__ */ jsx(DefaultEmptyIcon, {}));
   return /* @__PURE__ */ jsxs("div", { className: "yable-overlay-empty", role: "status", children: [
     /* @__PURE__ */ jsx("div", { className: "yable-overlay-empty-icon-wrapper", children: icon }),
@@ -2835,7 +2840,7 @@ function Table({
   loading,
   loadingComponent,
   loadingText,
-  emptyMessage = "No data",
+  emptyMessage,
   emptyComponent,
   emptyIcon,
   emptyDetail,
@@ -2987,9 +2992,10 @@ function Pagination({
   const to = Math.min((pageIndex + 1) * pageSize, totalRows);
   const canPrev = table.getCanPreviousPage();
   const canNext = table.getCanNextPage();
+  const locale = getDefaultLocale();
   return /* @__PURE__ */ jsxs("nav", { className: "yable-pagination", role: "navigation", "aria-label": "Table pagination", children: [
     showInfo && /* @__PURE__ */ jsxs("div", { className: "yable-pagination-info", children: [
-      /* @__PURE__ */ jsx("span", { className: "yable-pagination-info-text", children: totalRows > 0 ? `${from}\u2013${to} of ${totalRows}` : "No results" }),
+      /* @__PURE__ */ jsx("span", { className: "yable-pagination-info-text", children: totalRows > 0 ? `${from}\u2013${to} ${locale.paginationOf} ${totalRows}` : locale.paginationNoResults }),
       showPageSize && /* @__PURE__ */ jsxs("div", { className: "yable-pagination-select-wrapper", children: [
         /* @__PURE__ */ jsx(
           "select",
@@ -3002,7 +3008,8 @@ function Pagination({
             "aria-label": "Rows per page",
             children: pageSizes.map((size) => /* @__PURE__ */ jsxs("option", { value: size, children: [
               size,
-              " rows"
+              " ",
+              locale.paginationRows
             ] }, size))
           }
         ),
@@ -3017,8 +3024,8 @@ function Pagination({
           className: "yable-pagination-btn yable-pagination-btn--nav",
           onClick: () => table.setPageIndex(0),
           disabled: !canPrev,
-          "aria-label": "First page",
-          title: "First page",
+          "aria-label": locale.paginationFirstPage,
+          title: locale.paginationFirstPage,
           children: /* @__PURE__ */ jsx(ChevronFirstIcon, {})
         }
       ),
@@ -3029,8 +3036,8 @@ function Pagination({
           className: "yable-pagination-btn yable-pagination-btn--nav",
           onClick: () => table.previousPage(),
           disabled: !canPrev,
-          "aria-label": "Previous page",
-          title: "Previous page",
+          "aria-label": locale.paginationPreviousPage,
+          title: locale.paginationPreviousPage,
           children: /* @__PURE__ */ jsx(ChevronLeftIcon, {})
         }
       ),
@@ -3054,7 +3061,7 @@ function Pagination({
             className: `yable-pagination-btn yable-pagination-btn--page${page === pageIndex ? " yable-pagination-btn--active" : ""}`,
             "data-active": page === pageIndex ? "true" : void 0,
             onClick: () => table.setPageIndex(page),
-            "aria-label": `Page ${page + 1}`,
+            "aria-label": `${locale.paginationPage} ${page + 1}`,
             "aria-current": page === pageIndex ? "page" : void 0,
             children: page + 1
           },
@@ -3068,8 +3075,8 @@ function Pagination({
           className: "yable-pagination-btn yable-pagination-btn--nav",
           onClick: () => table.nextPage(),
           disabled: !canNext,
-          "aria-label": "Next page",
-          title: "Next page",
+          "aria-label": locale.paginationNextPage,
+          title: locale.paginationNextPage,
           children: /* @__PURE__ */ jsx(ChevronRightIcon, {})
         }
       ),
@@ -3080,8 +3087,8 @@ function Pagination({
           className: "yable-pagination-btn yable-pagination-btn--nav",
           onClick: () => table.setPageIndex(pageCount - 1),
           disabled: !canNext,
-          "aria-label": "Last page",
-          title: "Last page",
+          "aria-label": locale.paginationLastPage,
+          title: locale.paginationLastPage,
           children: /* @__PURE__ */ jsx(ChevronLastIcon, {})
         }
       )
@@ -3130,10 +3137,12 @@ function ClearIcon() {
 }
 function GlobalFilter({
   table,
-  placeholder = "Search...",
+  placeholder,
   debounce = 300,
   className
 }) {
+  const locale = getDefaultLocale();
+  const resolvedPlaceholder = placeholder ?? locale.searchPlaceholder;
   const [value, setValue] = useState(
     table.getState().globalFilter ?? ""
   );
@@ -3190,8 +3199,8 @@ function GlobalFilter({
         value,
         onChange: handleChange,
         onKeyDown: handleKeyDown,
-        placeholder,
-        "aria-label": "Search table",
+        placeholder: resolvedPlaceholder,
+        "aria-label": locale.searchAriaLabel,
         role: "searchbox"
       }
     ),
@@ -3278,10 +3287,25 @@ function CellSelect({
   const isAlwaysEditable = cell.getIsAlwaysEditable();
   const pending = table.getPendingValue(row.id, column.id);
   const currentValue = pending !== void 0 ? pending : cell.getValue();
+  const commitTimerRef = useRef(null);
+  useEffect(() => {
+    return () => {
+      if (commitTimerRef.current !== null) {
+        clearTimeout(commitTimerRef.current);
+        commitTimerRef.current = null;
+      }
+    };
+  }, []);
   const handleChange = (e) => {
     table.setPendingValue(row.id, column.id, e.target.value);
     if (isEditing && !isAlwaysEditable) {
-      setTimeout(() => table.commitEdit(), 0);
+      if (commitTimerRef.current !== null) {
+        clearTimeout(commitTimerRef.current);
+      }
+      commitTimerRef.current = setTimeout(() => {
+        commitTimerRef.current = null;
+        table.commitEdit();
+      }, 0);
     }
   };
   return /* @__PURE__ */ jsxs(