@extend-ai/react-xlsx 0.14.0 → 0.15.0

package/README.md

@@ -235,7 +235,7 @@ These hooks work inside `XlsxViewer` or `XlsxViewerProvider` context.
 
 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.
+Buttons do not execute Excel macros. Provide `onFormControlAction` to handle a button activation in your application. Labels and group boxes are display-only.
 
 ```tsx
 <XlsxViewer
@@ -249,7 +249,32 @@ Buttons do not execute Excel macros. Provide `onFormControlAction` to handle a b
 />
 ```
 
-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.
+The controller also exposes `addFormControl(input, sheetIndex?)`, `updateFormControl(controlIndex, patch, sheetIndex?)`, `removeFormControl(controlIndex, sheetIndex?)`, and `getFormControlItems(controlIndex, sheetIndex?)`. `XlsxFormControlInput` uses the same `XlsxImageAnchor` union as images and charts, with an optional `editAs` value for two-cell anchors. Captions accept either a string or rich text runs:
+
+```ts
+const controlIndex = controller.addFormControl({
+  anchor: {
+    kind: "two-cell",
+    from: { col: 1, row: 1, colOffsetEmu: 0, rowOffsetEmu: 0 },
+    to: { col: 3, row: 2, colOffsetEmu: 0, rowOffsetEmu: 0 }
+  },
+  editAs: "twoCell",
+  kind: {
+    kind: "checkbox",
+    caption: {
+      runs: [{ text: "Include forecast", font: { bold: true, name: "Aptos", size: 10 } }]
+    },
+    state: "checked"
+  }
+});
+```
+
+### Migrating To 0.15
+
+- `XlsxFormControlAnchor` was removed. Pass an `XlsxImageAnchor` to `XlsxFormControlInput.anchor` instead.
+- Read controls now expose `caption` as `XlsxFormControlCaption`; use `label` when you only need flattened display text.
+- Mutation captions accept either a plain string or `XlsxFormControlCaption` rich text runs.
+- `firstInGroup` is read-only. Duke recomputes option-button grouping when controls are written.
 
 ## Chart Selection And Formulas
 
@@ -360,6 +385,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.
@@ -437,6 +487,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`
 
@@ -607,6 +658,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`, `XlsxFormControlInput`, `XlsxFormControlCaption`, `XlsxFormControlCaptionInput`, `XlsxFormControlCaptionRun`, `XlsxFormControlRenderProps`
 - `XlsxTable`, `XlsxTableColumn`, `XlsxTableHeaderMenuRenderProps`
 - `XlsxWorkbookTab`, `XlsxCellAddress`, `XlsxCellRange`