@extend-ai/react-xlsx 0.13.4 → 0.14.1

package/README.md

@@ -231,6 +231,26 @@ These hooks work inside `XlsxViewer` or `XlsxViewerProvider` context.
 - `useXlsxViewerCharts()` for chart, chart element, formula, and chartsheet state
 - `useXlsxViewerThumbnails(options)` for painting worksheet thumbnails into your own canvases
 
+## Form Control Editing
+
+When `readOnly={false}`, Duke-backed checkboxes, option buttons, dropdowns, list boxes, scrollbars, and spinners are interactive. Changes update linked cells immediately, participate in undo/redo, and are written by `exportXlsx()` / `download()`.
+
+Buttons do not execute Excel macros. Provide `onFormControlAction` to handle a button activation in your application. Labels and group boxes are display-only, and legacy edit boxes remain render-only because Duke Sheets does not expose them as editable form controls.
+
+```tsx
+<XlsxViewer
+  file={file}
+  onFormControlAction={({ control }) => {
+    console.log("Activated", control.name);
+  }}
+  onFormControlChange={({ control, previousControl }) => {
+    console.log(previousControl.state, "->", control.state);
+  }}
+/>
+```
+
+The controller also exposes `addFormControl(input, sheetIndex?)`, `updateFormControl(controlIndex, patch, sheetIndex?)`, `removeFormControl(controlIndex, sheetIndex?)`, and `getFormControlItems(controlIndex, sheetIndex?)`. Inputs use Duke's flat two-cell anchor and kind-specific form-control shape, exported as `XlsxFormControlInput` and related types.
+
 ## Chart Selection And Formulas
 
 Chart interactions follow Excel's selection progression: clicking a chart selects the chart frame, clicking a plotted item or legend entry again selects the series, and clicking an item in an already-selected series selects that point. `selectedChartElement` exposes the current chart, series, legend entry, or point selection through the controller and `useXlsxViewerCharts()`.
@@ -340,6 +360,31 @@ export function CustomWorkbook({ file }: { file: ArrayBuffer }) {
 
 Apply `triggerProps` to the table-header trigger button so clicks do not leak into grid selection.
 
+Use `renderFormControl` to replace the built-in worksheet widgets. The callback receives the parsed `control`, resolved `items` and `label`, calculated `style`, read-only state, and `activate`, `setState`, `setSelected`, and `setValue` helpers. Apply `style` to the custom root and call `stopPropagation` from pointer/click handlers. The helpers keep Duke mutations, linked cells, undo/redo, export, and `onFormControlChange` in sync.
+
+```tsx
+<XlsxViewer
+  file={file}
+  renderFormControl={({ checked, control, disabled, label, setState, stopPropagation, style }) => {
+    if (control.kind === "checkbox" || control.kind === "radio") {
+      return (
+        <label onPointerDown={stopPropagation} style={style}>
+          <input
+            checked={checked}
+            disabled={disabled}
+            onChange={(event) => setState(event.currentTarget.checked ? "checked" : "unchecked")}
+            type={control.kind === "radio" ? "radio" : "checkbox"}
+          />
+          {label}
+        </label>
+      );
+    }
+
+    return <div style={style}>{label}</div>;
+  }}
+/>
+```
+
 ## Large Files
 
 `XlsxViewer` includes guardrails for large workbooks.
@@ -417,6 +462,7 @@ Common rendering props:
 - `renderImage?: (props: XlsxImageRenderProps) => React.ReactNode`
 - `renderImageSelection?: (props: XlsxImageSelectionRenderProps) => React.ReactNode`
 - `renderChartLoading?: (props: XlsxChartLoadingRenderProps) => React.ReactNode`
+- `renderFormControl?: (props: XlsxFormControlRenderProps) => React.ReactNode`
 - `renderTableHeaderMenu?: (props: XlsxTableHeaderMenuRenderProps) => React.ReactNode`
 - `renderScroller?: (props: XlsxScrollerRenderProps) => React.ReactNode`
 
@@ -587,6 +633,7 @@ The package exports the main types you are likely to use for custom integrations
 - `XlsxChart`, `XlsxChartSeries`, `XlsxChartAxis`, `XlsxChartElementSelection`, `XlsxChartsheet`
 - `XlsxFormulaTarget`
 - `XlsxImage`, `XlsxImageRect`, `XlsxImageRenderProps`, `XlsxImageSelectionRenderProps`
+- `XlsxFormControl`, `XlsxFormControlRenderProps`
 - `XlsxTable`, `XlsxTableColumn`, `XlsxTableHeaderMenuRenderProps`
 - `XlsxWorkbookTab`, `XlsxCellAddress`, `XlsxCellRange`