@sheetxl/react 0.7.18 → 0.7.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/types/index.d.ts CHANGED
@@ -1,7 +1,6 @@
1
1
  import { AnchorLocation } from '@sheetxl/utils';
2
2
  import { Bounds } from '@sheetxl/utils';
3
3
  import { CellEditorProps } from '@sheetxl/grid-react';
4
- import { CellEditorRefAttribute } from '@sheetxl/grid-react';
5
4
  import { CellLayout } from '@sheetxl/utils-react';
6
5
  import { CellRendererProps } from '@sheetxl/grid-react';
7
6
  import { CommandButtonProps } from '@sheetxl/utils-react';
@@ -20,6 +19,7 @@ import { GridView } from '@sheetxl/grid-react';
20
19
  import { IAutoFilter } from '@sheetxl/sdk';
21
20
  import { IBorder } from '@sheetxl/sdk';
22
21
  import { ICell } from '@sheetxl/sdk';
22
+ import { ICellEditorElement } from '@sheetxl/grid-react';
23
23
  import { ICellRange } from '@sheetxl/sdk';
24
24
  import { ICellRanges } from '@sheetxl/sdk';
25
25
  import { IChart } from '@sheetxl/sdk';
@@ -304,7 +304,7 @@ export declare interface DocThemesProviderProps {
304
304
  children: default_2.ReactElement<any, string | default_2.JSXElementConstructor<any>>;
305
305
  }
306
306
 
307
- export declare const EditableLabel: default_2.FC<EditableLabelProps & EditableLabelRefAttribute>;
307
+ export declare const EditableLabel: default_2.NamedExoticComponent<Omit<EditableLabelProps, "ref"> & default_2.RefAttributes<IEditableLabelElement>>;
308
308
 
309
309
  export declare interface EditableLabelAttributes {
310
310
  startEdit(): void;
@@ -322,11 +322,11 @@ export declare interface EditableLabelProps extends Omit<default_2.HTMLAttribute
322
322
  onSubmit?: (value: string) => boolean | void;
323
323
  onCancel?: () => void;
324
324
  createInput?: (props: any) => default_2.ReactElement<HTMLInputElement>;
325
- }
326
-
327
- export declare type EditableLabelRefAttribute = {
325
+ /**
326
+ * Reference to the HTMLInputElement (or other) used for editing
327
+ */
328
328
  ref?: default_2.Ref<IEditableLabelElement>;
329
- };
329
+ }
330
330
 
331
331
  export declare interface EditorStateAndCoords<CT, DT> {
332
332
  sheet: ISheet;
@@ -444,7 +444,11 @@ export declare interface IFrameContainerListener {
444
444
  export declare interface IMovableAreaElement extends HTMLDivElement, MovableAreaAttributes {
445
445
  }
446
446
 
447
- export declare interface IPictureEditorElement extends HTMLDivElement, PictureEditorAttributes {
447
+ export declare interface IPictureEditorAttributes {
448
+ isPictureEditor: () => true;
449
+ }
450
+
451
+ export declare interface IPictureEditorElement extends HTMLDivElement, IPictureEditorAttributes {
448
452
  }
449
453
 
450
454
  /**
@@ -579,16 +583,56 @@ export declare namespace IScriptEditor {
579
583
  export declare interface IScriptEditorElement extends ScriptEditorAttributes, HTMLDivElement {
580
584
  }
581
585
 
586
+ /**
587
+ * Attributes and methods available on the sheet element beyond the HTMLDivElement.
588
+ */
589
+ export declare type ISheetAttributes = {
590
+ getGridElement: () => IGridElement;
591
+ getRowHeaderElement: () => ISheetHeaderElement;
592
+ getColumnHeaderElement: () => ISheetHeaderElement;
593
+ rowHeaderHeight: () => number;
594
+ colHeaderWidth: () => number;
595
+ startEdit(event?: StartEditEvent): void;
596
+ submitEdit(): void;
597
+ cancelEdit(): void;
598
+ isEditing: boolean;
599
+ contains(element: Node | null): boolean;
600
+ invalidate: (coords?: ICell.Coords | null) => void;
601
+ /**
602
+ * Focus the sheet
603
+ */
604
+ focusSheet(options?: FocusOptions): void;
605
+ /**
606
+ * Focus a specific float.
607
+ * If not provided will focus the first selected float.
608
+ *
609
+ * @remarks
610
+ * The focusMovable does not scroll.
611
+ * TODO - have this honor focus scroll options.
612
+ */
613
+ focusMovable(movable?: IMovable): Promise<boolean>;
614
+ getSheet: () => ISheet;
615
+ /**
616
+ * For runtime introspection
617
+ */
618
+ isSheetElement: () => true;
619
+ };
620
+
582
621
  /**
583
622
  * Type returned via ref property
584
623
  */
585
- export declare interface ISheetElement extends HTMLDivElement, SheetAttributes {
624
+ export declare interface ISheetElement extends HTMLDivElement, ISheetAttributes {
586
625
  }
587
626
 
627
+ declare type ISheetHeaderAttributes = {
628
+ forceRender: () => void;
629
+ getGridElement: () => IGridElement;
630
+ };
631
+
588
632
  /**
589
633
  * Type returned via ref property
590
634
  */
591
- declare interface ISheetHeaderElement extends HTMLDivElement, SheetHeaderAttributes {
635
+ declare interface ISheetHeaderElement extends HTMLDivElement, ISheetHeaderAttributes {
592
636
  }
593
637
 
594
638
  export declare interface ITaskPaneArea {
@@ -778,10 +822,6 @@ export declare const PictureEditor: default_2.FC<PictureEditorProps & {
778
822
  ref?: default_2.Ref<IPictureEditorElement>;
779
823
  }>;
780
824
 
781
- export declare interface PictureEditorAttributes {
782
- isPictureEditor: () => true;
783
- }
784
-
785
825
  export declare interface PictureEditorProps extends MovableElementProps {
786
826
  /**
787
827
  * The underlying model for the picture.
@@ -908,43 +948,11 @@ declare interface SelectedRange {
908
948
  cell?: ICell.Address;
909
949
  }
910
950
 
911
- export declare type SheetAttributes = {
912
- getGridElement: () => IGridElement;
913
- getRowHeaderElement: () => ISheetHeaderElement;
914
- getColumnHeaderElement: () => ISheetHeaderElement;
915
- rowHeaderHeight: () => number;
916
- colHeaderWidth: () => number;
917
- startEdit(event?: StartEditEvent): void;
918
- submitEdit(): void;
919
- cancelEdit(): void;
920
- isEditing: boolean;
921
- contains(element: Node | null): boolean;
922
- invalidate: (coords?: ICell.Coords | null) => void;
923
- /**
924
- * Focus the sheet
925
- */
926
- focusSheet(options?: FocusOptions): void;
927
- /**
928
- * Focus a specific float.
929
- * If not provided will focus the first selected float.
930
- *
931
- * @remarks
932
- * The focusMovable does not scroll.
933
- * TODO - have this honor focus scroll options.
934
- */
935
- focusMovable(movable?: IMovable): Promise<boolean>;
936
- getSheet: () => ISheet;
937
- /**
938
- * For runtime introspection
939
- */
940
- isSheetElement: () => true;
941
- };
942
-
943
951
  /**
944
952
  * SheetCellEditor
945
953
  * Controlled cell editor for updating state.
946
954
  */
947
- export declare const SheetCellEditor: default_2.FC<SheetCellEditorProps & CellEditorRefAttribute>;
955
+ export declare const SheetCellEditor: default_2.NamedExoticComponent<Omit<SheetCellEditorProps, "ref"> & default_2.RefAttributes<ICellEditorElement>>;
948
956
 
949
957
  export declare interface SheetCellEditorProps extends CellEditorProps<() => ICell, string> {
950
958
  /**
@@ -1080,12 +1088,7 @@ export declare interface SheetCopyPasteResults extends CopyPasteResults {
1080
1088
  * UI representation for ISheet.
1081
1089
  *
1082
1090
  */
1083
- export declare const SheetElement: default_2.FC<SheetProps & SheetRefAttribute>;
1084
-
1085
- declare type SheetHeaderAttributes = {
1086
- forceRender: () => void;
1087
- getGridElement: () => IGridElement;
1088
- };
1091
+ export declare const SheetElement: default_2.NamedExoticComponent<Omit<SheetProps, "ref"> & default_2.RefAttributes<ISheetElement>>;
1089
1092
 
1090
1093
  /**
1091
1094
  * TODO - We may not need the grid ref if we use the headers directly to measure.
@@ -1167,6 +1170,10 @@ declare interface SheetHeaderProps extends default_2.HTMLAttributes<HTMLDivEleme
1167
1170
  * Callback when selection is manually changed
1168
1171
  */
1169
1172
  onSelectionEnd?: () => void;
1173
+ /**
1174
+ * Ref for the HTMLDivElement
1175
+ */
1176
+ ref?: default_2.Ref<ISheetHeaderElement>;
1170
1177
  }
1171
1178
 
1172
1179
  export declare interface SheetLocation {
@@ -1183,8 +1190,17 @@ export declare interface SheetPasteOptions extends ReferenceableClipboard.PasteO
1183
1190
  }
1184
1191
 
1185
1192
  export declare interface SheetProps extends React.HTMLAttributes<HTMLDivElement> {
1193
+ /**
1194
+ * The `ISheet` to render.
1195
+ */
1186
1196
  sheet: ISheet;
1197
+ /**
1198
+ * Style used for grid
1199
+ */
1187
1200
  gridStyle?: GridStyle;
1201
+ /**
1202
+ * Style used for headers
1203
+ */
1188
1204
  headersStyle?: GridStyle;
1189
1205
  /**
1190
1206
  * Fire when a contentMenu is requested
@@ -1232,7 +1248,7 @@ export declare interface SheetProps extends React.HTMLAttributes<HTMLDivElement>
1232
1248
  * This should not return null but rather can canEdit.
1233
1249
  * This is called during placement after scrolling and other bookkeeping has occurred
1234
1250
  */
1235
- getCellEditor?: (props: CellEditorProps<() => ICell, string> & CellEditorRefAttribute, coords: ICell.Coords) => React.ReactElement<CellEditorProps<() => ICell, string> & CellEditorRefAttribute>;
1251
+ getCellEditor?: (props: CellEditorProps<() => ICell, string>, coords: ICell.Coords) => React.ReactElement<CellEditorProps<() => ICell, string>>;
1236
1252
  /**
1237
1253
  * Parent commands for the sheet
1238
1254
  */
@@ -1275,22 +1291,16 @@ export declare interface SheetProps extends React.HTMLAttributes<HTMLDivElement>
1275
1291
  gridProps: GridProps;
1276
1292
  /**
1277
1293
  * Allow for custom rendering of cell props.
1294
+ *
1278
1295
  * @remarks
1279
1296
  * This is used to customize filterButton popup action and any other customizations desired.
1280
1297
  * This does not invalidate the rendering
1281
1298
  */
1282
1299
  cellRenderProps: Partial<SheetCellRendererProps>;
1283
- }
1284
-
1285
- export declare type SheetRefAttribute = {
1300
+ /**
1301
+ * Ref to the sheet element.
1302
+ */
1286
1303
  ref?: React.Ref<ISheetElement>;
1287
- };
1288
-
1289
- /**
1290
- * For elements that also need the ref. Less common but some factory renderers
1291
- */
1292
- export declare interface SheetRefProps extends SheetProps {
1293
- ref?: React.Ref<HTMLDivElement>;
1294
1304
  }
1295
1305
 
1296
1306
  export declare const SheetScrollbar: default_2.NamedExoticComponent<SheetScrollbarProps & default_2.RefAttributes<HTMLDivElement>>;
@@ -1391,6 +1401,9 @@ export declare interface TabProps extends Omit<default_2.HTMLAttributes<HTMLElem
1391
1401
  dragging: boolean;
1392
1402
  }
1393
1403
 
1404
+ /**
1405
+ * TabStrip component for displaying and managing tabs.
1406
+ */
1394
1407
  export declare const TabStrip: default_2.NamedExoticComponent<TabStripProps & default_2.RefAttributes<TabStripRef>>;
1395
1408
 
1396
1409
  export declare interface TabStripProps extends Omit<default_2.HTMLAttributes<HTMLDivElement>, "onSubmit" | "onChange"> {
@@ -1483,12 +1496,12 @@ export declare interface TaskPaneAreaProps<T = any> extends default_2.HTMLAttrib
1483
1496
  * @remarks
1484
1497
  * If the registry also provides a custom title renderer that will be used instead.
1485
1498
  */
1486
- renderTaskPanelTitle?(props: TaskPaneTitleProps, ref: default_2.Ref<HTMLDivElement>): default_2.ReactElement;
1499
+ renderTaskPanelTitle?(props: TaskPaneTitleProps): default_2.ReactElement;
1487
1500
  /**
1488
1501
  * Override the default task pane strip renderer.
1489
1502
  *
1490
1503
  */
1491
- renderTaskPaneStrip?(props: TaskPaneStripProps, ref: default_2.Ref<ITaskPaneStrip>): default_2.ReactElement;
1504
+ renderTaskPaneStrip?(props: TaskPaneStripProps): default_2.ReactElement;
1492
1505
  /**
1493
1506
  * Allow for custom registry of task panes.
1494
1507
  */
@@ -1540,7 +1553,7 @@ export declare interface TaskPaneEntry {
1540
1553
  /**
1541
1554
  * Optional function to render a custom title for the task pane.
1542
1555
  */
1543
- renderTaskPanelTitle?(props: TaskPaneTitleProps, ref: React.Ref<HTMLDivElement>): React.ReactElement;
1556
+ renderTaskPanelTitle?(props: TaskPaneTitleProps): React.ReactElement;
1544
1557
  createCommand?(taskPaneArea: ITaskPaneArea): ICommand;
1545
1558
  /**
1546
1559
  * Optional function to create a button that can be placed in the command bar.
@@ -1594,7 +1607,7 @@ declare class TaskPaneRegistry implements ITaskPaneRegistry {
1594
1607
  findContributions(contributionKey: string): TaskPaneEntry[];
1595
1608
  }
1596
1609
 
1597
- export declare const TaskPaneStrip: default_2.NamedExoticComponent<TaskPaneStripProps & default_2.RefAttributes<ITaskPaneStrip>>;
1610
+ export declare const TaskPaneStrip: default_2.NamedExoticComponent<Omit<TaskPaneStripProps, "ref"> & default_2.RefAttributes<ITaskPaneStrip>>;
1598
1611
 
1599
1612
  export declare interface TaskPaneStripAttributes {
1600
1613
  isTaskPaneStrip: () => true;
@@ -1612,6 +1625,10 @@ export declare interface TaskPaneStripProps extends Omit<default_2.HTMLAttribute
1612
1625
  * If true, only show icons in the strip (no text).
1613
1626
  */
1614
1627
  iconsOnly?: boolean;
1628
+ /**
1629
+ * Ref to the task pane strip element.
1630
+ */
1631
+ ref?: default_2.Ref<ITaskPaneStrip>;
1615
1632
  }
1616
1633
 
1617
1634
  export declare const TaskPaneTitle: default_2.FC<TaskPaneTitleProps & {
@@ -1627,6 +1644,10 @@ export declare interface TaskPaneTitleProps extends Omit<default_2.HTMLAttribute
1627
1644
  * If the task pane is focused
1628
1645
  */
1629
1646
  focused: boolean;
1647
+ /**
1648
+ * Reference to the underlying element.
1649
+ */
1650
+ ref?: default_2.Ref<HTMLDivElement>;
1630
1651
  }
1631
1652
 
1632
1653
  declare interface Theme {
@@ -1644,21 +1665,54 @@ export declare const useBordersOverlay: ({ getBorderAt, borderRenderer, getVisib
1644
1665
  export declare const useDocThemes: () => IThemeCollection;
1645
1666
 
1646
1667
  /**
1647
- * React hook that subscribes IModel.addListeners.
1648
- * This also ensures that it a listener object is passed in that was dynamically recreated it will
1649
- * not deregister on each render.
1668
+ * React hook for subscribing to model-level events (workbooks, sheets, etc.).
1669
+ *
1670
+ * @template SOURCE - The model type (e.g., IWorkbook, ISheet)
1671
+ * @template EVENTS - The listener interface type (e.g., ISheet.IListeners)
1650
1672
  *
1651
- * @param source
1652
- * @param listeners
1673
+ * @param source - The model instance to listen to
1674
+ * @param listeners - Object containing listener callbacks for various events
1675
+ * @param options - Optional configuration
1653
1676
  *
1654
1677
  * @remarks
1655
- * **IMPORTANT** This assumes that while the listeners object may change the shape does not.
1678
+ * This hook automatically manages the listener lifecycle:
1679
+ * - Subscribes when the component mounts or `source` changes
1680
+ * - Unsubscribes when the component unmounts or `source` changes
1681
+ * - Prevents unnecessary re-subscriptions when the `listeners` object reference changes
1682
+ * (as long as the shape/keys remain consistent)
1683
+ *
1684
+ * By default (`fireOnModelChange: true`), all listeners are called once immediately
1685
+ * on mount with the current source state, allowing you to initialize component state
1686
+ * based on the model's current values.
1687
+ *
1688
+ * @example
1689
+ * ```tsx
1690
+ * function SheetComponent({ sheet }: { sheet: ISheet }) {
1691
+ * useModelListener<ISheet, ISheet.IListeners>(sheet, {
1692
+ * onSave(source, json) {
1693
+ * console.log('Sheet saved:', json);
1694
+ * },
1695
+ * });
1696
+ *
1697
+ * return <div>Sheet: {sheet.getName()}</div>;
1698
+ * }
1699
+ * ```
1656
1700
  */
1657
1701
  export declare const useModelListener: <SOURCE, EVENTS>(source: IListener.ISource<SOURCE>, listeners: IListener.Callbacks<SOURCE, EVENTS>, options?: useModelListenerOptions) => void;
1658
1702
 
1659
- export declare interface useModelListenerOptions extends IListener.Options {
1703
+ /**
1704
+ * Options for `useModelListener` hook.
1705
+ *
1706
+ * @remarks
1707
+ * This is extends IListener.Options but removes 'once' since hooks are
1708
+ * evaluated on render and adds a `fireOnModelChange` option.
1709
+ */
1710
+ export declare interface useModelListenerOptions extends Omit<IListener.Options, 'once'> {
1660
1711
  /**
1661
- * Will also fire the listener when the model changes. (with a null event)
1712
+ * If `true` (default), fires all listeners once immediately when the component mounts
1713
+ * or when the source changes, allowing initialization based on current model state.
1714
+ *
1715
+ * @defaultValue true
1662
1716
  */
1663
1717
  fireOnModelChange?: boolean;
1664
1718
  }
@@ -1691,7 +1745,8 @@ export declare interface useMovableCommandsOptions {
1691
1745
  }
1692
1746
 
1693
1747
  /**
1694
- * This hook delegates to the model getRange(address).addListener.
1748
+ * This hook delegates to the an model that contains a getRange(address) method.
1749
+ *
1695
1750
  * @param model
1696
1751
  * @param listener
1697
1752
  */