@ricsam/react-spreadsheets 0.0.11 → 0.0.13

package/README.md

@@ -344,6 +344,32 @@ Wheel events originating inside a floating overlay are left to that overlay, so
 scrollable editors and other interactive overlay content keep their native
 scroll behavior.
 
+## Accessibility and browser automation
+
+Pass `aria-label`, `aria-labelledby`, and/or `aria-describedby` directly to
+`Spreadsheet`, `FormulaSheet`, or `FormulaWorkbook` to name/describe the inner
+keyboard grid. The default label is `Spreadsheet`; `containerProps` still targets
+the outer wrapper. Tab focus activates the existing selection-manager keyboard
+navigation without adding every virtual cell to the tab order.
+
+Mounted cells expose `role="gridcell"`, `aria-selected`, and stable-within-view
+IDs. Their accessible names come from rendered content (including custom
+renderers); use `[data-cell-address="B2"]` for an unambiguous A1 locator. Inline
+editors are named `Edit B2`. Headers expose `columnheader` / `rowheader` roles.
+ARIA coordinates/counts include the header row and column: A1 is row 2, column 2;
+unknown/unbounded counts are `-1`. Logical rows own their cells with `aria-owns`
+because frozen headers and cells render in separate clipping layers.
+
+Only mounted cells are exposed. Reveal offscreen cells with `scrollToCell`,
+`scrollToRange`, or `WorkbookSelectionManager.focusRange` before locating them.
+`aria-activedescendant` is omitted when the selection anchor is not mounted.
+With selection-manager versions providing `setInputCaptureAccessibility`, the
+same active-cell relationship and grid label are forwarded to its focused
+keyboard-capture textarea. Older peers keep grid semantics and keyboard behavior
+but do not announce this relationship from that textarea. This is not a claim
+of complete screen-reader support; custom overlays and renderers must supply
+their own accessible controls.
+
 ## Development
 
 ```bash

package/dist/cjs/lib.cjs

@@ -18,7 +18,7 @@ var __toESM = (mod, isNodeMode, target) => {
       return cached;
   }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  const to = isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   if (mod && typeof mod === "object" || typeof mod === "function") {
     for (let key of __getOwnPropNames(mod))
       if (!__hasOwnProp.call(to, key))
@@ -119,7 +119,7 @@ module.exports = __toCommonJS(exports_lib);
 
 // src/spreadsheet/spreadsheet.tsx
 var import_selection_manager = require("@ricsam/selection-manager");
-var import_react4 = __toESM(require("react"));
+var import_react4 = __toESM(require("react"), 1);
 
 // src/utils/use-resize-observer.ts
 var import_react = require("react");
@@ -1580,6 +1580,7 @@ var CellComponent = import_react4.default.memo(({
   value,
   row,
   col,
+  domId,
   selectionManager,
   cellToPixelBase,
   getColumnWidth,
@@ -1593,11 +1594,11 @@ var CellComponent = import_react4.default.memo(({
 }) => {
   const cellRef = import_react4.useCallback((el) => {
     if (el) {
-      const rowIndex2 = row - 1;
-      const colIndex2 = columnToIndex(col);
+      const rowIndex = row - 1;
+      const colIndex = columnToIndex(col);
       return selectionManager.setupCellElement(el, {
-        row: rowIndex2,
-        col: colIndex2
+        row: rowIndex,
+        col: colIndex
       });
     }
   }, [row, col, selectionManager]);
@@ -1625,16 +1626,22 @@ var CellComponent = import_react4.default.memo(({
   });
   const inputRef = import_react4.useCallback((el) => {
     if (el) {
-      const rowIndex2 = row - 1;
-      const colIndex2 = columnToIndex(col);
+      const rowIndex = row - 1;
+      const colIndex = columnToIndex(col);
       return selectionManager.setupInputElement(el, {
-        rowIndex: rowIndex2,
-        colIndex: colIndex2
+        rowIndex,
+        colIndex
       });
     }
   }, [row, col, selectionManager]);
   return /* @__PURE__ */ jsx_runtime3.jsxs("div", {
     ref: cellRef,
+    id: domId,
+    role: "gridcell",
+    "aria-rowindex": row + 1,
+    "aria-colindex": colIndex + 2,
+    "aria-selected": isSelected,
+    "data-cell-address": `${col}${row}`,
     className: cn("rsp-cell", {
       "rsp-cell-multiline": typeof value === "string" && value.includes(`
 `),
@@ -1654,6 +1661,7 @@ var CellComponent = import_react4.default.memo(({
     children: [
       isBeingEdited ? /* @__PURE__ */ jsx_runtime3.jsx("textarea", {
         className: "rsp-cell-editor",
+        "aria-label": `Edit ${col}${row}`,
         "data-testid": `spreadsheet-cell-input-${col}${row}`,
         ref: inputRef,
         defaultValue: inputValue?.toString() ?? "",
@@ -1732,6 +1740,10 @@ var HeaderComponent = import_react4.default.memo(({
   const content = type === "col" ? reverseHeaders ? index + 1 : indexToColumn(index) : reverseHeaders ? rowToLetter(index + 1) : index + 1;
   return /* @__PURE__ */ jsx_runtime3.jsxs("div", {
     ref: headerRef,
+    role: type === "col" ? "columnheader" : "rowheader",
+    "aria-colindex": type === "col" ? index + 2 : 1,
+    "aria-rowindex": type === "row" ? index + 2 : 1,
+    "aria-selected": isSelected,
     className: cn("rsp-header", `rsp-header-${type}`, {
       "rsp-header-selected": isSelected
     }),
@@ -1876,6 +1888,9 @@ var Spreadsheet = import_react4.forwardRef(({
   style,
   className,
   containerProps,
+  "aria-label": ariaLabel = "Spreadsheet",
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
   cellData: controlledCellData,
   onCellDataChange,
   onCellDataChangeError,
@@ -1898,6 +1913,7 @@ var Spreadsheet = import_react4.forwardRef(({
   parentSelected = true,
   disableClipboard = false
 }, ref) => {
+  const gridId = import_react4.useId();
   const [{ width, height }, containerRef] = useResizeObserver();
   const [containerDivRef, setContainerDivRef] = import_react4.useState(null);
   const colorScheme = useColorScheme(containerDivRef);
@@ -2091,15 +2107,15 @@ var Spreadsheet = import_react4.forwardRef(({
   };
   const effectsRef = import_react4.useRef(effectsRefOb);
   effectsRef.current = effectsRefOb;
-  const setupCanvas = import_react4.useCallback((canvas, width2, height2) => {
+  const setupCanvas = import_react4.useCallback((canvas, width, height) => {
     const ctx = canvas.getContext("2d");
     if (!ctx)
       return null;
     const devicePixelRatio = window.devicePixelRatio || 1;
-    canvas.width = width2 * devicePixelRatio;
-    canvas.height = height2 * devicePixelRatio;
-    canvas.style.width = width2 + "px";
-    canvas.style.height = height2 + "px";
+    canvas.width = width * devicePixelRatio;
+    canvas.height = height * devicePixelRatio;
+    canvas.style.width = width + "px";
+    canvas.style.height = height + "px";
     ctx.scale(devicePixelRatio, devicePixelRatio);
     return ctx;
   }, []);
@@ -2327,36 +2343,36 @@ var Spreadsheet = import_react4.forwardRef(({
     return selectionManager.listenToUpdateData((updates) => {
       const editingState = selectionManager.isEditing;
       try {
-        const { cellData: cellData2, onCellDataChange: onCellDataChange2 } = effectsRef.current;
-        const newData = new Map(cellData2);
+        const { cellData, onCellDataChange } = effectsRef.current;
+        const newData = new Map(cellData);
         updates.forEach(({ value, rowIndex, colIndex }) => {
           const key = `${indexToColumn(colIndex)}${rowIndex + 1}`;
-          const parseValue2 = effectsRef.current.parseValue;
+          const parseValue = effectsRef.current.parseValue;
           if (value === "") {
             newData.delete(key);
           } else {
             let parsedValue = value;
-            if (parseValue2 && typeof value === "string") {
+            if (parseValue && typeof value === "string") {
               const match = key.match(/^([A-Z]+)(\d+)$/);
               const col = match?.[1];
               const rowText = match?.[2];
               if (col && rowText) {
                 const row = parseInt(rowText, 10);
-                const colIndex2 = columnToIndex(col);
-                const rowIndex2 = row - 1;
-                parsedValue = parseValue2(value, {
+                const colIndex = columnToIndex(col);
+                const rowIndex = row - 1;
+                parsedValue = parseValue(value, {
                   id: key,
                   row,
                   col,
-                  rowIndex: rowIndex2,
-                  colIndex: colIndex2
+                  rowIndex,
+                  colIndex
                 });
               }
             }
             newData.set(key, parsedValue);
           }
         });
-        onCellDataChange2?.(newData);
+        onCellDataChange?.(newData);
         setInternalCellData(newData);
       } catch (error) {
         console.error("Failed to update spreadsheet cell data:", error);
@@ -2539,13 +2555,13 @@ var Spreadsheet = import_react4.forwardRef(({
   const handleColumnResizeDoubleClick = import_react4.useCallback((e, col) => {
     e.preventDefault();
     e.stopPropagation();
-    const { viewport: viewport2, gridDims: gridDims2, height: height2, cellData: cellData2 } = effectsRef.current;
+    const { viewport, gridDims, height, cellData } = effectsRef.current;
     let maxWidth = 50;
-    const startRow = Math.max(0, Math.floor(viewport2.scrollY / gridDims2.cellHeight));
-    const endRow = Math.ceil((viewport2.scrollY + height2) / gridDims2.cellHeight) + 1;
+    const startRow = Math.max(0, Math.floor(viewport.scrollY / gridDims.cellHeight));
+    const endRow = Math.ceil((viewport.scrollY + height) / gridDims.cellHeight) + 1;
     for (let row = startRow;row <= endRow; row++) {
       const cellKey = `${col}${getRowNumber(row)}`;
-      const content = cellData2.get(cellKey) ?? "";
+      const content = cellData.get(cellKey) ?? "";
       if (content) {
         const estimatedWidth = String(content).length * 8 + 20;
         maxWidth = Math.max(maxWidth, estimatedWidth);
@@ -2814,8 +2830,8 @@ var Spreadsheet = import_react4.forwardRef(({
     return editingCleanup;
   }, [selectionManager]);
   import_react4.default.useEffect(() => {
-    return selectionManager.observeStateChange((state) => state.hasFocus, (hasFocus2) => {
-      if (hasFocus2 && selectedOverlayId) {
+    return selectionManager.observeStateChange((state) => state.hasFocus, (hasFocus) => {
+      if (hasFocus && selectedOverlayId) {
         setSelectedOverlay(null);
       }
     });
@@ -2918,6 +2934,21 @@ var Spreadsheet = import_react4.forwardRef(({
   const visibleCells = import_react4.default.useMemo(() => getVisibleCells(), [getVisibleCells]);
   const visibleColumnHeaders = import_react4.default.useMemo(() => getVisibleColumnHeaders(), [getVisibleColumnHeaders]);
   const visibleRowHeaders = import_react4.default.useMemo(() => getVisibleRowHeaders(), [getVisibleRowHeaders]);
+  const activeAddress = import_selection_manager.useSelectionManager(selectionManager, () => {
+    const cell = selectionManager.getTopLeftCellInSelection();
+    return cell ? `${indexToColumn(cell.col)}${cell.row + 1}` : undefined;
+  });
+  const activeCellId = visibleCells.some((cell) => `${cell.col}${cell.row}` === activeAddress) ? `${gridId}-cell-${activeAddress}` : undefined;
+  const accessibilityManager = selectionManager;
+  import_react4.useLayoutEffect(() => {
+    accessibilityManager.setInputCaptureAccessibility?.({
+      label: `${ariaLabel} keyboard input`,
+      controls: gridId,
+      activeDescendant: activeCellId,
+      describedBy: ariaDescribedBy
+    });
+    return () => accessibilityManager.setInputCaptureAccessibility?.({});
+  }, [accessibilityManager, ariaLabel, ariaDescribedBy, gridId, activeCellId]);
   const hasFocus = import_selection_manager.useSelectionManager(selectionManager, () => selectionManager.hasFocus);
   const referenceSelection = import_selection_manager.useSelectionManager(selectionManager, () => selectionManager.referenceSelection);
   const referenceSelectionRect = import_react4.useMemo(() => {
@@ -2993,7 +3024,21 @@ var Spreadsheet = import_react4.forwardRef(({
           width,
           height
         },
+        id: gridId,
+        role: "grid",
+        "aria-activedescendant": activeCellId,
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledBy,
+        "aria-describedby": ariaDescribedBy,
+        "aria-rowcount": finiteRowCount === undefined ? -1 : finiteRowCount + 1,
+        "aria-colcount": finiteColumnCount === undefined ? -1 : finiteColumnCount + 1,
+        "aria-multiselectable": "true",
         tabIndex: 0,
+        onFocus: (event) => {
+          if (event.target === event.currentTarget && !selectionManager.hasFocus) {
+            selectionManager.focus();
+          }
+        },
         children: [
           /* @__PURE__ */ jsx_runtime3.jsx("span", {
             ref: gridLineProbeRef,
@@ -3009,12 +3054,15 @@ var Spreadsheet = import_react4.forwardRef(({
           }),
           /* @__PURE__ */ jsx_runtime3.jsx("canvas", {
             ref: canvasRef,
+            "aria-hidden": "true",
             className: "rsp-canvas",
             "data-testid": "spreadsheet-canvas",
             style: { width, height }
           }),
           /* @__PURE__ */ jsx_runtime3.jsx("div", {
             className: "rsp-column-headers",
+            role: "row",
+            "aria-rowindex": 1,
             "data-testid": "spreadsheet-column-headers",
             style: {
               left: gridDims.headerWidth,
@@ -3057,16 +3105,21 @@ var Spreadsheet = import_react4.forwardRef(({
                 transformOrigin: "0 0"
               },
               children: visibleRowHeaders.map(({ row, rowIndex }) => {
-                return /* @__PURE__ */ jsx_runtime3.jsx(HeaderComponent, {
-                  index: rowIndex,
-                  type: "row",
-                  selectionManager,
-                  getColumnWidth,
-                  getRowHeight,
-                  handleColumnResizeStart,
-                  handleColumnResizeDoubleClick,
-                  handleRowResizeStart,
-                  handleRowResizeDoubleClick
+                return /* @__PURE__ */ jsx_runtime3.jsx("div", {
+                  role: "row",
+                  "aria-rowindex": row + 1,
+                  "aria-owns": visibleCells.filter((cell) => cell.row === row).map((cell) => `${gridId}-cell-${cell.col}${cell.row}`).join(" ") || undefined,
+                  children: /* @__PURE__ */ jsx_runtime3.jsx(HeaderComponent, {
+                    index: rowIndex,
+                    type: "row",
+                    selectionManager,
+                    getColumnWidth,
+                    getRowHeight,
+                    handleColumnResizeStart,
+                    handleColumnResizeDoubleClick,
+                    handleRowResizeStart,
+                    handleRowResizeDoubleClick
+                  })
                 }, row);
               })
             })
@@ -3089,6 +3142,7 @@ var Spreadsheet = import_react4.forwardRef(({
             },
             children: [
               visibleCells.map((cell) => /* @__PURE__ */ jsx_runtime3.jsx(CellComponent, {
+                domId: `${gridId}-cell-${cell.col}${cell.row}`,
                 value: cellData.get(`${cell.col}${cell.row}`) ?? "",
                 row: cell.row,
                 col: cell.col,
@@ -3194,7 +3248,7 @@ var Spreadsheet = import_react4.forwardRef(({
 Spreadsheet.displayName = "Spreadsheet";
 // src/workbook/workbook.tsx
 var import_formula_engine2 = require("@ricsam/formula-engine");
-var import_react6 = __toESM(require("react"));
+var import_react6 = __toESM(require("react"), 1);
 
 // src/utils/use-scheme-root.ts
 var import_react5 = require("react");
@@ -3419,13 +3473,21 @@ class WorkbookSelectionManager {
     if (cachedSelections && manager.getState().selections.length === 0) {
       manager.replaceSelections(cachedSelections);
     }
+    let previousFocus = manager.getState().hasFocus;
+    let previousSelections = JSON.stringify(manager.getState().selections);
     const focusCleanup = manager.observeStateChange((state) => state.hasFocus, (hasFocus) => {
+      if (hasFocus === previousFocus)
+        return;
+      previousFocus = hasFocus;
       if (hasFocus && !this.applyingRangeFocus.has(manager)) {
         this.rememberSelections(manager, registeredContext);
         this.emitChange();
       }
     });
     const selectionCleanup = manager.observeStateChange((state) => JSON.stringify(state.selections), (selectionsJson) => {
+      if (selectionsJson === previousSelections)
+        return;
+      previousSelections = selectionsJson;
       if (this.applyingRangeFocus.has(manager))
         return;
       const selections = JSON.parse(selectionsJson);
@@ -3920,11 +3982,11 @@ function FormulaSheet({
           });
         }
       }),
-      spreadsheetSelectionManager.observeStateChange((state2) => {
-        const currentSelection = state2.selections.length === 1 ? state2.selections[0] : undefined;
+      spreadsheetSelectionManager.observeStateChange((state) => {
+        const currentSelection = state.selections.length === 1 ? state.selections[0] : undefined;
         return currentSelection;
-      }, (selection2) => {
-        setSelectedArea(selection2 ?? null);
+      }, (selection) => {
+        setSelectedArea(selection ?? null);
       })
     ];
     const handleUndoRedoKeyDown = (event) => {
@@ -4040,7 +4102,7 @@ function FormulaSheet({
               workbookName
             });
             if (!tableInfo) {
-              const style2 = conditionalStyle ? {
+              const style = conditionalStyle ? {
                 ...conditionalStyle.backgroundColor && {
                   backgroundColor: conditionalStyle.backgroundColor
                 },
@@ -4062,7 +4124,7 @@ function FormulaSheet({
                 ...getBorderCellStyle(conditionalStyle),
                 ...getWrapCellStyle(conditionalStyle)
               } : {};
-              return customCellStyle ? customCellStyle(cell, style2) : style2;
+              return customCellStyle ? customCellStyle(cell, style) : style;
             }
             const isHeaderRow = cell.rowIndex === tableInfo.start.rowIndex;
             const isFirstColumn = cell.colIndex === tableInfo.start.colIndex;
@@ -4561,4 +4623,4 @@ var useClickAway = (ref, callback) => {
   }, [ref, callback]);
 };
 
-//# debugId=64201658718498BD64756E2164756E21
+//# debugId=422BCC484554257364756E2164756E21