@sheetxl/utils-react 0.7.12 → 0.7.14

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/utils-react",
3
3
  "description": "Utils React - Utilities for React capabilities needed for all SheetXL components.",
4
- "version": "0.7.12",
4
+ "version": "0.7.14",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -40,7 +40,7 @@
40
40
  "react"
41
41
  ],
42
42
  "dependencies": {
43
- "@sheetxl/utils": "^0.7.12",
43
+ "@sheetxl/utils": "^0.7.14",
44
44
  "clsx": "^2.1.1",
45
45
  "detect-it": "^4.0.1",
46
46
  "react-merge-refs": "^3.0.2",
@@ -48,7 +48,11 @@
48
48
  "tiny-invariant": "^1.3.3"
49
49
  },
50
50
  "peerDependencies": {
51
- "react": "^19.1.0",
52
- "react-dom": "^19.1.0"
51
+ "react": "^19.2.0",
52
+ "react-dom": "^19.2.0"
53
+ },
54
+ "devDependencies": {
55
+ "@types/react": "^19.2.0",
56
+ "@types/react-dom": "^19.2.0"
53
57
  }
54
58
  }
package/types/index.d.ts CHANGED
@@ -21,10 +21,6 @@ declare type BaseGlyph = {
21
21
 
22
22
  declare function boundPixel(cssPoint: number, _increase?: boolean, _absOffset?: number): number;
23
23
 
24
- export declare interface BusyNotifierOptions {
25
- icon?: default_2.ReactNode;
26
- }
27
-
28
24
  export declare type CellFinder = (activeCoords: CellCoords, isContentfulCell: IsContentfulCell | undefined, hiddenAt: HiddenHeadersAt | undefined, direction: Direction, first: boolean, limit: number) => number;
29
25
 
30
26
  export declare interface CellLayout {
@@ -316,17 +312,15 @@ export declare class DefaultReactNotifier extends DefaultNotifier implements IRe
316
312
  /** @inheritdoc IReactNotifier.showMessage */
317
313
  showMessage(message: string | default_2.ReactNode, options?: EnqueueNotifierOptions): void;
318
314
  /** @inheritdoc IReactNotifier.showBusy */
319
- showBusy(message: string | default_2.ReactNode, options?: BusyNotifierOptions): (Promise<() => void>) | (() => void);
315
+ showBusy(message: string | default_2.ReactNode, options?: ShowBusyOptions): (Promise<() => void>) | (() => void);
320
316
  /** @inheritdoc IReactNotifier.showWindow */
321
- showWindow(type: string, props?: any, options?: {
322
- disableAutoDestroy?: boolean;
323
- }): Promise<HTMLElement>;
317
+ showWindow(type: string, options?: ShowWindowOptions): Promise<HTMLElement>;
324
318
  /** @inheritdoc IReactNotifier.showError */
325
319
  showError(error: any): void;
326
320
  /** @inheritdoc IReactNotifier.showOptions */
327
- showOptions(options: OptionsNotifierOptions): Promise<string>;
328
- /** @inheritdoc IReactNotifier.showInputOptions */
329
- showInputOptions(options: InputOptionsNotifierOptions): Promise<InputResults>;
321
+ showOptions(options: ShowOptionsOptions): Promise<string>;
322
+ /** @inheritdoc IReactNotifier.showInput */
323
+ showInput(options: ShowInputOptions): Promise<InputResults>;
330
324
  }
331
325
 
332
326
  /**
@@ -438,6 +432,16 @@ export declare interface FocusKeyNavigationProps extends default_2.HTMLAttribute
438
432
  tabForward?: Direction;
439
433
  }
440
434
 
435
+ export declare interface FocusWindowOptions extends FocusOptions {
436
+ /**
437
+ * Allows for a specific component to be selected.
438
+ *
439
+ * @remarks
440
+ * If a string is provided this will be used as a querySelector to find the initial focusable component.
441
+ */
442
+ selection?: string;
443
+ }
444
+
441
445
  export declare interface FullscreenPortalRoot {
442
446
  getPortalContainer: () => Element;
443
447
  isFullscreen: boolean;
@@ -801,24 +805,15 @@ export declare interface IKeyStroke {
801
805
  readonly modifiers?: KeyModifiers[];
802
806
  }
803
807
 
804
- export declare interface InputOptionsNotifierOptions extends OptionsNotifierOptions {
805
- initialValue?: string;
806
- /**
807
- * Css style for input
808
- */
809
- inputProps?: default_2.HTMLAttributes<HTMLInputElement | HTMLTextAreaElement>;
810
- inputLabel?: string;
811
- inputType?: 'text' | 'password' | 'email' | 'number' | 'search' | 'tel' | 'url';
812
- inputPlaceHolder?: string;
813
- onInputOption?: (input?: string, option?: string) => void;
814
- /**
815
- * Call when an option is selected. If false is returned, the the
816
- * dialog will not close. INotifier is not provided but can
817
- * be supplied via the textFieldProps helperText property.
818
- * @remarks
819
- * Optional the textProps can be updated via the textFieldProps argument
820
- */
821
- onValidateInputOption?: (input?: string, option?: string) => InputValidationResults | Promise<InputValidationResults>;
808
+ /** In-memory state (default fallback / SSR-safe) */
809
+ export declare class InMemoryStore implements PersistenceStore {
810
+ private store;
811
+ /** {@inheritDoc PersistenceStore.getItem} */
812
+ getItem(k: string): Promise<string>;
813
+ /** {@inheritDoc PersistenceStore.setItem} */
814
+ setItem(k: string, v: string): Promise<void>;
815
+ /** {@inheritDoc PersistenceStore.removeItem} */
816
+ removeItem(k: string): Promise<void>;
822
817
  }
823
818
 
824
819
  export declare interface InputResults {
@@ -839,6 +834,12 @@ export declare interface IReactNotifier extends INotifier {
839
834
  * Useful when informing the user of something but are not expecting a response.
840
835
  */
841
836
  showMessage: (message: string | default_2.ReactNode, options?: EnqueueNotifierOptions) => void;
837
+ /**
838
+ * Should return error object exception.
839
+ *
840
+ * @param error
841
+ */
842
+ showError: (error: Error | string) => void;
842
843
  /**
843
844
  * Useful when performing a long running operation and you want to inform the user.
844
845
  *
@@ -846,33 +847,24 @@ export declare interface IReactNotifier extends INotifier {
846
847
  * If multiple calls are made the consumer should continue to indicated blocked
847
848
  * until all calls have been hideBusy.
848
849
  */
849
- showBusy: (message: string | default_2.ReactNode, options?: BusyNotifierOptions) => (Promise<() => void>) | (() => void);
850
+ showBusy: (message: string | default_2.ReactNode, options?: ShowBusyOptions) => (Promise<() => void>) | (() => void);
850
851
  /**
851
852
  * Show a dialog for a given type.
852
853
  *
853
854
  * @param type
854
- * @param props
855
855
  * @param options
856
856
  */
857
- showWindow: (type: string, props?: any, options?: {
858
- disableAutoDestroy?: boolean;
859
- }) => Promise<HTMLElement>;
860
- /**
861
- * Should return error object exception.
862
- *
863
- * @param error
864
- */
865
- showError: (error: Error | string) => void;
857
+ showWindow: (type: string, options?: ShowWindowOptions) => Promise<HTMLElement>;
866
858
  /**
867
859
  * Provide a user with a list of options to choose from.
868
860
  * @param options
869
861
  */
870
- showOptions: (options: OptionsNotifierOptions) => Promise<string>;
862
+ showOptions: (options: ShowOptionsOptions) => Promise<string>;
871
863
  /**
872
864
  * Provider a user with a way to enter a text input.
873
865
  * @param options
874
866
  */
875
- showInputOptions: (options: InputOptionsNotifierOptions) => Promise<InputResults>;
867
+ showInput: (options: ShowInputOptions) => Promise<InputResults>;
876
868
  }
877
869
 
878
870
  export declare interface IsContentfulCell {
@@ -973,6 +965,20 @@ export declare const KeyModifiers: {
973
965
 
974
966
  export declare type KeyModifiers = typeof KeyModifiers[keyof typeof KeyModifiers];
975
967
 
968
+ /** LocalStorage state with cross-tab sync */
969
+ export declare class LocalStorageStore implements PersistenceStore {
970
+ private storage;
971
+ constructor(storage?: Storage);
972
+ /** {@inheritDoc PersistenceStore.getItem} */
973
+ getItem(k: string): Promise<string>;
974
+ /** {@inheritDoc PersistenceStore.setItem} */
975
+ setItem(k: string, v: string): Promise<void>;
976
+ /** {@inheritDoc PersistenceStore.removeItem} */
977
+ removeItem(k: string): Promise<void>;
978
+ /** {@inheritDoc PersistenceStore.subscribe} */
979
+ subscribe?(onExternalChange: (changedKey: string) => void): () => void;
980
+ }
981
+
976
982
  export declare const MouseButtonCodes: {
977
983
  readonly Left: 1;
978
984
  readonly Middle: 2;
@@ -1020,67 +1026,90 @@ export declare type NotifierType = typeof NotifierType[keyof typeof NotifierType
1020
1026
 
1021
1027
  export declare type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
1022
1028
 
1023
- /**
1024
- * Configuration for an options dialog.
1025
- */
1026
- export declare interface OptionsNotifierOptions extends default_2.HTMLAttributes<HTMLDivElement> {
1027
- /**
1028
- * The options as a list of strings
1029
- */
1030
- options?: string[];
1029
+ declare type PackLoader = () => Promise<IconPack | IconPackInput | PackModule>;
1030
+
1031
+ declare type PackModule = {
1032
+ readonly default: IconPack | IconPackInput;
1033
+ } & Record<string, unknown>;
1034
+
1035
+ export declare type PersistenceProviderProps = {
1031
1036
  /**
1032
- * The title of the options panel
1037
+ * Storage backend to use
1033
1038
  */
1034
- title?: string;
1039
+ store: PersistenceStore;
1035
1040
  /**
1036
- * Display text information for the user to make a decision.
1041
+ * Namespace prefix for all keys
1042
+ *
1043
+ * @defaultValue none
1037
1044
  */
1038
- description?: string;
1045
+ namespace?: string;
1046
+ serializer?: PersistenceSerializer;
1047
+ debounceMs?: number;
1048
+ crossTabSync?: boolean;
1039
1049
  /**
1040
- * Display an icon next to the description for additional context
1050
+ * Children elements that will have access to the persistence context.
1041
1051
  *
1042
1052
  * @remarks
1043
- * Not yet implemented
1053
+ * Required for provider
1044
1054
  */
1045
- icon?: default_2.ReactNode;
1055
+ children: React.ReactNode;
1056
+ };
1057
+
1058
+ export declare type PersistenceSerializer<T = any> = {
1059
+ parse: (raw: string | null) => T;
1060
+ stringify: (val: T) => string;
1061
+ };
1062
+
1063
+ export declare type PersistenceStateOptions<T = any> = {
1046
1064
  /**
1047
- * Allows for the option will be the default selected option and the enter key trigger.
1048
- * @defaultValue The first option
1065
+ * Convert the value to/from a string for storage
1066
+ *
1067
+ * @defaultValue JSON
1049
1068
  */
1050
- defaultOption?: string;
1069
+ serializer?: PersistenceSerializer<T>;
1070
+ version?: number;
1071
+ migrate?: (oldValue: unknown, oldVersion: number | undefined) => T;
1072
+ lazy?: boolean;
1073
+ };
1074
+
1075
+ export declare function PersistenceStateProvider(props: PersistenceProviderProps): JSX.Element;
1076
+
1077
+ export declare type PersistenceStateSetter<T> = (next: T | ((prev: T) => T)) => void;
1078
+
1079
+ /**
1080
+ * Primary interface for storing retrieving key/value pairs
1081
+ */
1082
+ export declare interface PersistenceStore {
1051
1083
  /**
1052
- * Allows for the cancel option to be specified. Allow for special styling.
1053
- * @defaultValue 'Cancel'
1084
+ * Retrieves the value associated with the given key.
1085
+ *
1086
+ * @param key The key to retrieve.
1054
1087
  */
1055
- cancelOption?: string;
1088
+ getItem(key: string): Promise<string | null>;
1056
1089
  /**
1057
- * Call when an option is selected.
1058
- * @remarks
1059
- * It is possible that the option can be both a cancel and a default option.
1090
+ * Sets the value for the given key.
1091
+ *
1092
+ * @param key The key to set.
1093
+ * @param value The value to associate with the key.
1060
1094
  */
1061
- onOption?: (option: string, isCancel: boolean, isDefault: boolean) => void;
1095
+ setItem(key: string, value: string): Promise<void>;
1062
1096
  /**
1063
- * Hook for create custom options buttons
1064
- * @param props
1097
+ * Removes the value associated with the given key.
1065
1098
  *
1066
- * @remarks
1067
- * The option is passed as the `children` prop and as the second argument
1099
+ * @param key The key to remove.
1068
1100
  */
1069
- createOptionsButton?: (option: string, props: default_2.HTMLAttributes<HTMLButtonElement> & default_2.Attributes, isDefaultOption: boolean) => default_2.ReactNode;
1101
+ removeItem(key: string): Promise<void>;
1070
1102
  /**
1071
- * Call when an option is selected. If false is returned, the the
1072
- * dialog will not close. INotifier is not provided but can
1073
- * be supplied via the textFieldProps helperText property.
1103
+ * Subscribes to external changes for cross-tab synchronization.
1104
+ *
1105
+ * @param onExternalChange Callback invoked when a key changes externally.
1106
+ *
1107
+ * @remarks
1108
+ * Not all state implementations support cross-tab subscription (may no-op)
1074
1109
  */
1075
- onValidateOption?: (option?: string) => boolean | Promise<boolean>;
1110
+ subscribe?(onExternalChange: (changedKey: string) => void): () => void;
1076
1111
  }
1077
1112
 
1078
- declare type PackLoader = () => Promise<IconPack | IconPackInput | PackModule>;
1079
-
1080
- declare type PackModule = {
1081
- readonly default: IconPack | IconPackInput;
1082
- } & Record<string, unknown>;
1083
-
1084
1113
  /**
1085
1114
  * If returns false don't setup the other listeners
1086
1115
  */
@@ -1279,6 +1308,115 @@ export declare namespace ScrollUtils {
1279
1308
  }
1280
1309
  }
1281
1310
 
1311
+ export declare interface ShowBusyOptions {
1312
+ icon?: default_2.ReactNode;
1313
+ }
1314
+
1315
+ export declare interface ShowInputOptions<T = string, C = any> extends ShowOptionsOptions<T, C> {
1316
+ /**
1317
+ * Css style for input
1318
+ */
1319
+ inputProps?: default_2.HTMLAttributes<HTMLInputElement | HTMLTextAreaElement>;
1320
+ inputLabel?: string;
1321
+ inputType?: 'text' | 'password' | 'email' | 'number' | 'search' | 'tel' | 'url';
1322
+ inputPlaceHolder?: string;
1323
+ onInput?: (input?: T, option?: string) => void | Promise<void>;
1324
+ /**
1325
+ * Call when an option is selected. If false is returned, the the
1326
+ * dialog will not close. INotifier is not provided but can
1327
+ * be supplied via the textFieldProps helperText property.
1328
+ * @remarks
1329
+ * Optional the textProps can be updated via the textFieldProps argument
1330
+ */
1331
+ onValidateInput?: (input?: T, option?: string) => InputValidationResults | Promise<InputValidationResults>;
1332
+ }
1333
+
1334
+ /**
1335
+ * Configuration for an options dialog.
1336
+ */
1337
+ export declare interface ShowOptionsOptions<T = any, C = any> extends ShowWindowOptions<T, C> {
1338
+ /**
1339
+ * The options as a list of strings
1340
+ */
1341
+ options?: string[];
1342
+ /**
1343
+ * The title of the options panel
1344
+ */
1345
+ title?: string;
1346
+ /**
1347
+ * Display text information for the user to make a decision.
1348
+ */
1349
+ description?: string;
1350
+ /**
1351
+ * Display an icon next to the description for additional context
1352
+ *
1353
+ * @remarks
1354
+ * Not yet implemented
1355
+ */
1356
+ icon?: default_2.ReactNode | string;
1357
+ /**
1358
+ * Allows for the option will be the default selected option and the enter key trigger.
1359
+ * @defaultValue The first option
1360
+ */
1361
+ defaultOption?: string;
1362
+ /**
1363
+ * Allows for the cancel option to be specified. Allow for special styling.
1364
+ * @defaultValue 'Cancel'
1365
+ */
1366
+ cancelOption?: string;
1367
+ /**
1368
+ * Call when an option is selected.
1369
+ * @remarks
1370
+ * It is possible that the option can be both a cancel and a default option.
1371
+ */
1372
+ onOption?: (option: string, isCancel: boolean, isDefault: boolean) => void;
1373
+ /**
1374
+ * Hook for create custom options buttons
1375
+ * @param props
1376
+ *
1377
+ * @remarks
1378
+ * The option is passed as the `children` prop and as the second argument
1379
+ */
1380
+ createOptionsButton?: (option: string, props: default_2.HTMLAttributes<HTMLButtonElement> & default_2.Attributes, isDefaultOption: boolean) => default_2.ReactNode;
1381
+ /**
1382
+ * Call when an option is selected. If false is returned, the the
1383
+ * dialog will not close. INotifier is not provided but can
1384
+ * be supplied via the textFieldProps helperText property.
1385
+ */
1386
+ onValidateOption?: (option?: string) => boolean | Promise<boolean>;
1387
+ }
1388
+
1389
+ export declare interface ShowWindowOptions<T = any, C = any> {
1390
+ /**
1391
+ * A value the window can use to display.
1392
+ */
1393
+ initialValue?: T;
1394
+ context?: () => C;
1395
+ /**
1396
+ * Query selector for the element to focus on show.
1397
+ */
1398
+ autoFocus?: boolean | string | FocusWindowOptions;
1399
+ /**
1400
+ * Allow for tracking of key down events.
1401
+ *
1402
+ * @param e
1403
+ * @returns
1404
+ */
1405
+ onKeyDown?: (e: default_2.KeyboardEvent) => void;
1406
+ /**
1407
+ * If true show a backdrop.
1408
+ *
1409
+ * @remarks
1410
+ * Our movable menu achieves modality without a background by listens to global clicks (and focus)
1411
+ * @defaultValue false
1412
+ */
1413
+ isModal?: boolean;
1414
+ /**
1415
+ * If true the window will not be automatically destroyed when closed.
1416
+ */
1417
+ disableAutoDestroy?: boolean;
1418
+ }
1419
+
1282
1420
  export declare class SimpleCommand extends Command<void, void> {
1283
1421
  }
1284
1422
 
@@ -1615,6 +1753,8 @@ export declare const useNotifier: () => IReactNotifier;
1615
1753
 
1616
1754
  export declare function useOnClickOrFocusAway(ref: default_2.RefObject<any>, listenerArg: ClickOrFocusAwayListener, options?: ClickOrFocusAwayOptions): void;
1617
1755
 
1756
+ export declare function usePersistenceState<T = unknown>(key: string, defaultValue?: T | (() => T), opts?: PersistenceStateOptions<T>): [T, PersistenceStateSetter<T>, () => void];
1757
+
1618
1758
  /**
1619
1759
  * This hook will respond on Pointer down and then continue to fire events
1620
1760
  * until the Pointer is released.