@sheetxl/react 0.8.0-beta.6 → 0.8.0-beta.7

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/react",
3
3
  "description": "React - React components needed to build advanced grid and spreadsheet UIs.",
4
- "version": "0.8.0-beta.6",
4
+ "version": "0.8.0-beta.7",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -48,11 +48,11 @@
48
48
  "@dnd-kit/modifiers": "^9.0.0",
49
49
  "@dnd-kit/sortable": "^10.0.0",
50
50
  "@dnd-kit/utilities": "^3.2.2",
51
- "@sheetxl/grid-react": "^0.8.0-beta.6",
52
- "@sheetxl/io": "^0.8.0-beta.6",
53
- "@sheetxl/sdk": "^0.8.0-beta.6",
54
- "@sheetxl/utils": "^0.8.0-beta.6",
55
- "@sheetxl/utils-react": "^0.8.0-beta.6",
51
+ "@sheetxl/grid-react": "^0.8.0-beta.7",
52
+ "@sheetxl/io": "^0.8.0-beta.7",
53
+ "@sheetxl/sdk": "^0.8.0-beta.7",
54
+ "@sheetxl/utils": "^0.8.0-beta.7",
55
+ "@sheetxl/utils-react": "^0.8.0-beta.7",
56
56
  "clsx": "^2.1.1",
57
57
  "react-merge-refs": "^3.0.2",
58
58
  "react-moveable": "^0.56.0",
@@ -866,9 +866,6 @@
866
866
  "description": "Der Zelle eine Notiz hinzufügen oder die vorhandene bearbeiten.",
867
867
  "icon": "NoteInsert",
868
868
  "shortcut": "shift+F2",
869
- "tags": [
870
- "mutator"
871
- ],
872
869
  "params": {
873
870
  "note": "no"
874
871
  },
@@ -882,41 +879,49 @@
882
879
  "groupLabels": {
883
880
  "noteOptions": "Anzeigen"
884
881
  },
885
- "description": "Die Notiz auf dem Blatt belassen. Andernfalls erscheint sie nur, während auf ihre Zelle gezeigt wird.",
886
- "tags": [
887
- "mutator"
888
- ]
882
+ "description": "Die Notiz auf dem Blatt belassen. Andernfalls erscheint sie nur, während auf ihre Zelle gezeigt wird."
889
883
  },
890
884
  "showAllNotes": {
891
885
  "label": "Alle Notizen anzeigen",
892
- "description": "Alle Notizen auf dem Blatt belassen. Sind bereits alle sichtbar, werden alle ausgeblendet.",
893
- "tags": [
894
- "mutator"
895
- ]
886
+ "description": "Alle Notizen auf dem Blatt belassen. Sind bereits alle sichtbar, werden alle ausgeblendet."
896
887
  },
897
888
  "updateComments": {
898
- "label": "Kommentare",
889
+ "label": "{thread, select, yes{Kommentar anzeigen} other{Kommentar einfügen}}",
899
890
  "groupLabels": {
900
- "contextMenu": "Kommentar einfügen…"
891
+ "contextMenu": "{thread, select, yes{Kommentar anzeigen} other{Kommentar einfügen…}}"
901
892
  },
902
- "description": "Der aktuellen Zelle einen Kommentar hinzufügen.",
893
+ "description": "Der Zelle einen Kommentar hinzufügen oder auf den vorhandenen antworten.",
903
894
  "icon": "CommentInsert",
904
895
  "shortcut": "ctrl+alt+M",
905
- "tags": [
906
- "mutator"
907
- ]
896
+ "params": {
897
+ "thread": "no"
898
+ }
908
899
  },
909
900
  "deleteComments": {
910
901
  "label": "Kommentare löschen",
911
902
  "description": "Alle Kommentare entfernen.",
912
903
  "icon": "CommentDelete",
913
- "tags": [
914
- "mutator"
915
- ],
916
904
  "groupLabels": {
917
905
  "noteOptions": "Löschen"
918
906
  }
919
907
  },
908
+ "previousComment": {
909
+ "label": "Vorheriger Kommentar",
910
+ "description": "Zum Kommentar vor der ausgewählten Zelle wechseln."
911
+ },
912
+ "nextComment": {
913
+ "label": "Nächster Kommentar",
914
+ "description": "Zum Kommentar nach der ausgewählten Zelle wechseln."
915
+ },
916
+ "showCommentsPane": {
917
+ "label": "Kommentare anzeigen",
918
+ "description": "Alle Kommentare des Blatts in einem Bereich auflisten.",
919
+ "icon": "CommentEdit"
920
+ },
921
+ "convertNotesToComments": {
922
+ "label": "In Kommentare umwandeln",
923
+ "description": "Alle Notizen des Blatts in Kommentare umwandeln, auf die geantwortet werden kann."
924
+ },
920
925
  "insertImageFromFile": {
921
926
  "label": "Bild einfügen",
922
927
  "groupLabels": {
@@ -151,6 +151,7 @@
151
151
  "picker.noValues": "Keine Werte",
152
152
  "picker.search": "Suchen",
153
153
  "reason.alreadyTable": "Die Auswahl befindet sich bereits in einer Tabelle.",
154
+ "reason.cellHasNote": "Die Zelle hat eine Notiz.",
154
155
  "reason.cellHasThread": "Die Zelle hat einen Kommentar mit Antworten.",
155
156
  "reason.continuousSpan": "Nicht verfügbar bei fortlaufender Ausrichtung oder Ausfüllen.",
156
157
  "reason.entireColumn": "Nicht verfügbar, wenn ganze Spalten ausgewählt sind.",
@@ -158,9 +159,11 @@
158
159
  "reason.freezeOrigin": "Wählen Sie eine Zelle unterhalb und/oder rechts der zu fixierenden Stelle aus.",
159
160
  "reason.mergeUnavailable": "Verbinden ist für diese Auswahl nicht verfügbar.",
160
161
  "reason.mixedSelection": "Nicht verfügbar bei gemischter vollständiger/teilweiser Auswahl.",
162
+ "reason.noComments": "Das Blatt hat keine Kommentare.",
161
163
  "reason.noFreeze": "Keine fixierten Bereiche.",
162
164
  "reason.noMerge": "Keine verbundenen Zellen in der Auswahl.",
163
165
  "reason.noNote": "Die Zelle hat keine Notiz.",
166
+ "reason.noNotes": "Das Blatt hat keine Notizen.",
164
167
  "reason.noPreviousSearch": "Es wurde noch nicht gesucht.",
165
168
  "reason.noSelection": "Nichts ausgewählt.",
166
169
  "reason.noSheetBackground": "Das Blatt hat keinen Hintergrund.",
@@ -867,9 +867,6 @@
867
867
  "description": "Add a note to the cell, or edit the one it has.",
868
868
  "icon": "NoteInsert",
869
869
  "shortcut": "shift+F2",
870
- "tags": [
871
- "mutator"
872
- ],
873
870
  "params": {
874
871
  "note": "no"
875
872
  },
@@ -881,43 +878,51 @@
881
878
  "showHideNote": {
882
879
  "label": "Show Note",
883
880
  "description": "Keep the note on the sheet. Otherwise it shows only while its cell is pointed at.",
884
- "tags": [
885
- "mutator"
886
- ],
887
881
  "groupLabels": {
888
882
  "noteOptions": "Show"
889
883
  }
890
884
  },
891
885
  "showAllNotes": {
892
886
  "label": "Show All Notes",
893
- "description": "Keep every note on the sheet. When every note is already shown, hide them all.",
894
- "tags": [
895
- "mutator"
896
- ]
887
+ "description": "Keep every note on the sheet. When every note is already shown, hide them all."
897
888
  },
898
889
  "updateComments": {
899
- "label": "Comments",
900
- "description": "Add a comment to the current cell.",
890
+ "label": "{thread, select, yes{Show Comment} other{Insert Comment}}",
891
+ "description": "Add a comment to the cell, or reply to the one it has.",
901
892
  "groupLabels": {
902
- "contextMenu": "Insert Comment…"
893
+ "contextMenu": "{thread, select, yes{Show Comment} other{Insert Comment…}}"
903
894
  },
904
895
  "icon": "CommentInsert",
905
896
  "shortcut": "ctrl+alt+M",
906
- "tags": [
907
- "mutator"
908
- ]
897
+ "params": {
898
+ "thread": "no"
899
+ }
909
900
  },
910
901
  "deleteComments": {
911
902
  "label": "Delete Comments",
912
903
  "description": "Remove any comments.",
913
904
  "icon": "CommentDelete",
914
- "tags": [
915
- "mutator"
916
- ],
917
905
  "groupLabels": {
918
906
  "noteOptions": "Delete"
919
907
  }
920
908
  },
909
+ "previousComment": {
910
+ "label": "Previous Comment",
911
+ "description": "Go to the comment before the selected cell."
912
+ },
913
+ "nextComment": {
914
+ "label": "Next Comment",
915
+ "description": "Go to the comment after the selected cell."
916
+ },
917
+ "showCommentsPane": {
918
+ "label": "Show Comments",
919
+ "description": "List every comment on the sheet in a pane.",
920
+ "icon": "CommentEdit"
921
+ },
922
+ "convertNotesToComments": {
923
+ "label": "Convert to Comments",
924
+ "description": "Convert every note on the sheet to a comment that can be replied to."
925
+ },
921
926
  "insertImageFromFile": {
922
927
  "label": "Insert Image",
923
928
  "description": "Insert a picture from your device.",
@@ -151,6 +151,7 @@
151
151
  "picker.noValues": "No values",
152
152
  "picker.search": "Search",
153
153
  "reason.alreadyTable": "The selection is already in a table.",
154
+ "reason.cellHasNote": "The cell has a note.",
154
155
  "reason.cellHasThread": "The cell has a threaded comment.",
155
156
  "reason.continuousSpan": "Not available with continuous / fill alignment.",
156
157
  "reason.entireColumn": "Not available when entire columns are selected.",
@@ -158,9 +159,11 @@
158
159
  "reason.freezeOrigin": "Select a cell below and/or right of where the panes should freeze.",
159
160
  "reason.mergeUnavailable": "Merge is not available for this selection.",
160
161
  "reason.mixedSelection": "Not available for a mixed full / partial selection.",
162
+ "reason.noComments": "The sheet has no comments.",
161
163
  "reason.noFreeze": "No frozen panes.",
162
164
  "reason.noMerge": "No merged cells in the selection.",
163
165
  "reason.noNote": "The cell has no note.",
166
+ "reason.noNotes": "The sheet has no notes.",
164
167
  "reason.noPreviousSearch": "Nothing has been searched for yet.",
165
168
  "reason.noSelection": "Nothing is selected.",
166
169
  "reason.noSheetBackground": "The sheet has no background.",
@@ -21,6 +21,12 @@ export interface CornerTriangleProps extends React.SVGProps<SVGSVGElement> {
21
21
  inset?: number;
22
22
  cellWidth?: number;
23
23
  cellHeight?: number;
24
+ /**
25
+ * `'bubble'` draws a speech-bubble corner, Excel's mark for a threaded comment, in place of the
26
+ * triangle. Top right only.
27
+ * @defaultValue 'triangle'
28
+ */
29
+ shape?: 'triangle' | 'bubble';
24
30
  propsPath?: React.SVGProps<SVGPathElement>;
25
31
  }
26
32
  export declare const CornerTriangle: React.MemoExoticComponent<(props: CornerTriangleProps) => React.JSX.Element>;
@@ -0,0 +1,94 @@
1
+ import { CellCoords } from '@sheetxl/utils';
2
+ import { IComment, ISheet } from '@sheetxl/sdk';
3
+ /**
4
+ * What a comments task pane is asked to open on — `activateTaskPane('comments', { args })`.
5
+ */
6
+ export interface CommentsPaneArgs {
7
+ /**
8
+ * Scroll to this thread and put the caret in its reply box.
9
+ */
10
+ focus?: IComment;
11
+ /**
12
+ * Open a draft on the active cell. Nothing is written until it is posted.
13
+ */
14
+ insert?: boolean;
15
+ }
16
+ /**
17
+ * What a comment card is rendered from.
18
+ */
19
+ export interface CommentCardRenderProps {
20
+ /** The sheet the card's cell is on. */
21
+ sheet: ISheet;
22
+ /** The cell the card belongs to. */
23
+ coords: CellCoords;
24
+ /** The thread on the cell, or `null` for a draft: a comment that has not been posted. */
25
+ comment: IComment | null;
26
+ /**
27
+ * A new value each time a command asks for the card, whose text then takes the caret; `0` when
28
+ * none has.
29
+ */
30
+ focusRequest: number;
31
+ /** Dismisses the card; a draft that was not posted is dropped. */
32
+ onClose: () => void;
33
+ }
34
+ /**
35
+ * A cell whose comment card is asked to stay beside it with the caret in its text: a draft when the
36
+ * cell has no thread, the thread's reply box when it has one.
37
+ */
38
+ export interface CommentCardRequest extends CellCoords {
39
+ /**
40
+ * A new value each time the card's text is asked to take the caret; `0` when the card is only
41
+ * asked to stay.
42
+ */
43
+ focusRequest: number;
44
+ }
45
+ /**
46
+ * Options for {@link requestCommentCard}.
47
+ */
48
+ export interface RequestCommentCardOptions {
49
+ /**
50
+ * Whether the card's text takes the caret.
51
+ * @defaultValue true
52
+ */
53
+ autoFocus?: boolean;
54
+ }
55
+ /**
56
+ * Asks for the comment card of a cell: a draft when the cell has no thread, its thread otherwise.
57
+ *
58
+ * @remarks
59
+ * This is how a command reaches a card it cannot see. The card floats beside the cell until the
60
+ * request is {@link clearCommentCard | cleared}, which the layer drawing it does when the selection
61
+ * leaves the cell. A draft writes nothing until it is posted.
62
+ */
63
+ export declare const requestCommentCard: (sheet: ISheet, coords: CellCoords, options?: RequestCommentCardOptions) => void;
64
+ /**
65
+ * Takes back a {@link requestCommentCard | request}; a draft that was not posted is dropped.
66
+ */
67
+ export declare const clearCommentCard: (sheet: ISheet) => void;
68
+ /**
69
+ * The cell whose card is asked for on the sheet, or `null` for none.
70
+ */
71
+ export declare const getCommentCardRequest: (sheet: ISheet) => CommentCardRequest | null;
72
+ /**
73
+ * Whether anything draws the sheet's comment cards. A command falls back to the comments task pane
74
+ * when nothing does.
75
+ */
76
+ export declare const hasCommentCard: (sheet: ISheet) => boolean;
77
+ /**
78
+ * Listens for the sheet's card request changing. Whatever draws the cards listens; the returned
79
+ * function stops listening.
80
+ */
81
+ export declare const addCommentCardListener: (sheet: ISheet, listener: () => void) => (() => void);
82
+ /**
83
+ * The cell a draft is open on: a requested card whose cell has no comment yet. `null` for none.
84
+ *
85
+ * @remarks
86
+ * For what marks the cell while its comment is being written. Following this does not count as
87
+ * drawing the cards, so {@link hasCommentCard} is unchanged by it.
88
+ */
89
+ export declare const useCommentDraftCell: (sheet: ISheet) => CommentCardRequest | null;
90
+ /**
91
+ * {@link getCommentCardRequest}, kept current.
92
+ */
93
+ export declare const useCommentCardRequest: (sheet: ISheet) => CommentCardRequest | null;
94
+ //# sourceMappingURL=CommentCardRequest.d.ts.map
@@ -0,0 +1,43 @@
1
+ import { CellCoords } from '@sheetxl/utils';
2
+ import { IComment } from '@sheetxl/sdk';
3
+ /**
4
+ * The cell a comment is on, as plain coordinates.
5
+ *
6
+ * @remarks
7
+ * A comment's own range is anchored (`$B$2`); selecting or comparing cells wants the plain cell.
8
+ */
9
+ export declare const getCommentCoords: (comment: IComment) => CellCoords;
10
+ /**
11
+ * Orders comments as they are read on the sheet: by row, then by column.
12
+ */
13
+ export declare const compareComments: (a: IComment, b: IComment) => number;
14
+ /**
15
+ * The initials shown in a person's avatar: the first letter of the first and of the last word of
16
+ * their name, or of the one word it has.
17
+ */
18
+ export declare const getPersonInitials: (displayName: string | null | undefined) => string;
19
+ /**
20
+ * Options for {@link formatCommentTime}.
21
+ */
22
+ export interface FormatCommentTimeOptions {
23
+ /** The moment the time is relative to. Defaults to now. */
24
+ now?: Date;
25
+ /** A BCP 47 language tag. Defaults to the runtime's. */
26
+ locale?: string;
27
+ }
28
+ /**
29
+ * When a comment was written, as a card shows it.
30
+ */
31
+ export interface CommentTime {
32
+ /** How long ago, in words: `2 hours ago`, `yesterday`. */
33
+ relative: string;
34
+ /** The full date and time, for a tooltip. */
35
+ absolute: string;
36
+ }
37
+ /**
38
+ * Formats when a comment was written: relative for the card, absolute for its tooltip.
39
+ *
40
+ * @returns `null` for no date, which is what a note converted to a comment has.
41
+ */
42
+ export declare const formatCommentTime: (date: Date | null | undefined, options?: FormatCommentTimeOptions) => CommentTime | null;
43
+ //# sourceMappingURL=CommentUtils.d.ts.map
@@ -1,2 +1,6 @@
1
1
  export * from './NoteEditor';
2
+ export * from './CommentUtils';
3
+ export * from './CommentCardRequest';
4
+ export * from './useSheetComments';
5
+ export * from './useCommentThread';
2
6
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,37 @@
1
+ import { IComment, IPerson } from '@sheetxl/sdk';
2
+ /**
3
+ * One thread as a card shows it: the comment's current values, read once per change.
4
+ */
5
+ export interface CommentThread {
6
+ /** The comment's text. */
7
+ content: string;
8
+ /** Who wrote it, or `null` if the workbook does not know them. */
9
+ author: IPerson | null;
10
+ /** When it was written, or `null` if it carries no date. */
11
+ date: Date | null;
12
+ /** Whether the thread is resolved. */
13
+ resolved: boolean;
14
+ /** The replies, oldest first. */
15
+ replies: IComment.IReply[];
16
+ /** `true` once the comment has been deleted; the other values are then empty. */
17
+ deleted: boolean;
18
+ }
19
+ /**
20
+ * A comment's thread, kept current: its text, author, replies and resolved state.
21
+ *
22
+ * @param comment The comment, or `null` for none (a draft that has not been posted).
23
+ * @returns The thread, or `null` when there is no comment.
24
+ *
25
+ * @remarks
26
+ * The object keeps its identity until the comment's content, replies or resolved state changes,
27
+ * or the comment is deleted.
28
+ *
29
+ * @example
30
+ * ```tsx
31
+ * const thread = useCommentThread(comment);
32
+ * if (!thread || thread.deleted) return null;
33
+ * return <p>{thread.author?.getDisplayName()}: {thread.content} ({thread.replies.length} replies)</p>;
34
+ * ```
35
+ */
36
+ export declare const useCommentThread: (comment: IComment | null) => CommentThread | null;
37
+ //# sourceMappingURL=useCommentThread.d.ts.map
@@ -0,0 +1,28 @@
1
+ import { IComment, ISheet } from '@sheetxl/sdk';
2
+ /**
3
+ * Options for {@link useSheetComments}.
4
+ */
5
+ export interface UseSheetCommentsOptions {
6
+ /**
7
+ * Only threads with this resolved state. Omit for every thread.
8
+ */
9
+ resolved?: boolean;
10
+ }
11
+ /**
12
+ * The threaded comments on a sheet, in reading order, kept current.
13
+ *
14
+ * @param sheet The sheet, or `null` for none.
15
+ * @param options {@link UseSheetCommentsOptions}
16
+ *
17
+ * @remarks
18
+ * Notes are not threads and are left out. The array keeps its identity until a comment on the
19
+ * sheet is added, removed, moved, edited, replied to or resolved.
20
+ *
21
+ * @example
22
+ * ```tsx
23
+ * const open = useSheetComments(sheet, { resolved: false });
24
+ * return <ul>{open.map((comment) => <li key={comment.getId()}>{comment.getContent()}</li>)}</ul>;
25
+ * ```
26
+ */
27
+ export declare const useSheetComments: (sheet: ISheet | null, options?: UseSheetCommentsOptions) => IComment[];
28
+ //# sourceMappingURL=useSheetComments.d.ts.map
@@ -0,0 +1,45 @@
1
+ import { default as React } from 'react';
2
+ import { ISheet } from '@sheetxl/sdk';
3
+ import { LayerProps } from '@sheetxl/grid-react';
4
+ import { CommentCardRenderProps } from '../comment/CommentCardRequest';
5
+ export interface CommentCardLayerProps extends Omit<LayerProps, 'children'> {
6
+ /** Class for the floated card container. */
7
+ className?: string;
8
+ /** Style for the floated card container. */
9
+ style?: React.CSSProperties;
10
+ /** The sheet whose threads are shown. */
11
+ sheet: ISheet;
12
+ /**
13
+ * Renders the card. The layer places it, keeps it open and keeps its keystrokes and presses from
14
+ * the grid; what it looks like is the renderer's.
15
+ */
16
+ renderCard: (props: CommentCardRenderProps) => React.ReactNode;
17
+ /**
18
+ * The task pane that lists the sheet's threads. While it is the active pane the cards are shown
19
+ * there and this layer shows none.
20
+ * @defaultValue 'comments'
21
+ */
22
+ paneKey?: string;
23
+ /** Gap (px) between the cell's right edge and the card. @defaultValue 18 */
24
+ offset?: number;
25
+ /** Dwell (ms) on a thread's cell before its card shows. @defaultValue 300 */
26
+ openDelay?: number;
27
+ /** Grace (ms) after leaving the cell and its card before the card hides. @defaultValue 250 */
28
+ closeDelay?: number;
29
+ }
30
+ /**
31
+ * The **comment card** beside a cell — a {@link RangeFloatLayer} showing the thread of the cell the
32
+ * pointer rests on, and the card a command {@link requestCommentCard | asked for}: a draft on a
33
+ * cell with no thread, or the thread a command went to. Selecting a cell shows nothing by itself,
34
+ * as in Excel.
35
+ *
36
+ * @remarks
37
+ * A note has a box of its own and is not shown here. The card of a requested cell stays until the
38
+ * selection leaves the cell or the card is dismissed; a card that takes the focus is kept the same
39
+ * way, so a reply being typed does not close when the pointer wanders off.
40
+ *
41
+ * The float portals out of the pane, but React events still bubble through the React tree to the
42
+ * grid, so the layer stops the card's keystrokes, presses, clipboard and context-menu events there.
43
+ */
44
+ export declare const CommentCardLayer: React.MemoExoticComponent<(props: CommentCardLayerProps) => React.JSX.Element>;
45
+ //# sourceMappingURL=CommentCardLayer.d.ts.map
@@ -25,7 +25,7 @@ export interface ValidationPromptLayerProps extends Omit<LayerProps, 'children'>
25
25
  style?: React.CSSProperties;
26
26
  /** The sheet whose selection is followed. */
27
27
  sheet: ISheet;
28
- /** Gap (px) between the cell's bottom edge and the prompt. @defaultValue 2 */
28
+ /** Gap (px) between the cell's bottom edge and the prompt. @defaultValue 4 */
29
29
  offset?: number;
30
30
  /**
31
31
  * Render the prompt yourself. Spread `floatProps` on the returned element. Omit for the default
@@ -35,7 +35,7 @@ export interface ValidationPromptLayerProps extends Omit<LayerProps, 'children'>
35
35
  }
36
36
  /**
37
37
  * The **input prompt** of a data validation — a {@link RangeFloatLayer} activated by the selection,
38
- * placed under the selected cell (or its merge) with left edges aligned.
38
+ * placed under the selected cell (or its merge), starting at its horizontal midpoint.
39
39
  *
40
40
  * @remarks
41
41
  * Shows the title and message of the first covering rule that has a prompt to show
@@ -23,6 +23,7 @@ export * from './ValidationPromptLayer';
23
23
  export * from './useValidationPicker';
24
24
  export * from './CircularIndicatorLayer';
25
25
  export * from './CommentsLayer';
26
+ export * from './CommentCardLayer';
26
27
  export * from './ProtectionLayer';
27
28
  export * from './HeaderSelectionLayer';
28
29
  export * from './HeaderResizerLayer';
@@ -28,7 +28,7 @@ export interface ModelListenerOptions extends Omit<IListener.Options, 'once'> {
28
28
  * @template SOURCE - The model type (e.g., IWorkbook, ISheet)
29
29
  * @template EVENTS - The listener interface type (e.g., ISheet.IListeners)
30
30
  *
31
- * @param source - The model instance to listen to
31
+ * @param source - The model instance to listen to, or `null` to listen to nothing
32
32
  * @param listeners - Object containing listener callbacks for various events
33
33
  * @param options - Optional configuration
34
34
  *
@@ -56,12 +56,12 @@ export interface ModelListenerOptions extends Omit<IListener.Options, 'once'> {
56
56
  * }
57
57
  * ```
58
58
  */
59
- export declare const useModelListener: <SOURCE, EVENTS>(source: IListener.ISource<SOURCE>, listeners: IListener.Callbacks<SOURCE, EVENTS>, options?: ModelListenerOptions) => void;
59
+ export declare const useModelListener: <SOURCE, EVENTS>(source: IListener.ISource<SOURCE> | null | undefined, listeners: IListener.Callbacks<SOURCE, EVENTS>, options?: ModelListenerOptions) => void;
60
60
  /**
61
61
  * Used for syncing with model state that causes a rerenders.
62
62
  *
63
- * @param source The source of the model
63
+ * @param source The source of the model, or `null` to listen to nothing.
64
64
  * @param eventNames The name of the event or events to listen for.
65
65
  */
66
- export declare function useModelSync<EVENTS>(source: IListener.ISource<any>, eventNames: keyof EVENTS | Array<keyof EVENTS>): void;
66
+ export declare function useModelSync<EVENTS>(source: IListener.ISource<any> | null | undefined, eventNames: keyof EVENTS | Array<keyof EVENTS>): void;
67
67
  //# sourceMappingURL=useModelListener.d.ts.map
@@ -3,18 +3,27 @@ import { IMovable } from '@sheetxl/sdk';
3
3
  * Props a movable renderer receives from its frame.
4
4
  *
5
5
  * @remarks
6
- * Spread `style` onto the root element. It positions and sizes the drawing in its frame AND carries
7
- * its hit-testing: the frame itself is pointer-transparent, so `style.pointerEvents` (`'auto'` by
8
- * default, `'none'` while the frame is hidden) is what makes the drawing clickable. A drawing that
9
- * is not solid — a no-fill shape — overrides it with `'none'` on its root and sets `pointerEvents`
10
- * back on its painted parts only (e.g. `visibleStroke` on an SVG path), so a click in its unfilled
11
- * interior reaches the cell beneath, exactly as in Excel.
6
+ * Spread `style` onto the root element. It fills the frame, which owns the drawing's bounds (zoom
7
+ * included), AND carries its hit-testing: the frame itself is pointer-transparent, so
8
+ * `style.pointerEvents` (`'auto'` by default, `'none'` while the frame is hidden) is what makes the
9
+ * drawing clickable. A drawing that is not solid — a no-fill shape — overrides it with `'none'` on
10
+ * its root and sets `pointerEvents` back on its painted parts only (e.g. `visibleStroke` on an SVG
11
+ * path), so a click in its unfilled interior reaches the cell beneath, exactly as in Excel.
12
+ *
13
+ * The drawing never sizes itself. `zoom` is given only so that it can scale what it draws inside
14
+ * the frame (text, borders, padding), for example with the CSS `zoom` property; a drawing that
15
+ * stretches to its box, such as a picture, ignores it.
12
16
  */
13
17
  export interface MovableElementProps extends React.HTMLAttributes<HTMLElement> {
14
18
  /**
15
19
  * The movable associated with this element.
16
20
  */
17
21
  movable?: IMovable;
22
+ /**
23
+ * The scale of the view the movable is drawn in, where `1` is unscaled.
24
+ * @defaultValue 1
25
+ */
26
+ zoom?: number;
18
27
  /**
19
28
  * Called when the movable is hidden from view.
20
29
  *
@@ -4,6 +4,7 @@ import { ViewportMetrics, IShowToolTipProperties, ScrollPaneProps, Viewport, The
4
4
  import { GridSurfaceProps, IGridSurface, IEditable, LayerNode } from '@sheetxl/grid-react';
5
5
  import { SheetCellRendererProps, ColumnButtonConfigProps } from '../cell';
6
6
  import { MovableElementProps } from '../movable';
7
+ import { CommentCardRenderProps } from '../comment';
7
8
  import { CommandContext } from '../frame';
8
9
  import { ISheetHeaderElement, SheetHeaderProps } from './ISheetHeaderElement';
9
10
  /**
@@ -161,6 +162,13 @@ export interface SheetElementProps extends React.HTMLAttributes<HTMLDivElement>,
161
162
  * @returns A React Element representing the IMovable.
162
163
  */
163
164
  renderMovable?: (props: MovableElementProps) => React.ReactElement;
165
+ /**
166
+ * Renders the card of a threaded comment beside its cell: on hover, on selection, and as a draft
167
+ * when a command asks for one. Omit to show no card; the indicators are drawn either way.
168
+ *
169
+ * @param props - {@link CommentCardRenderProps}
170
+ */
171
+ renderCommentCard?: (props: CommentCardRenderProps) => React.ReactNode;
164
172
  /**
165
173
  * Render element(s) directly onto the `GridSurface`, bottom → top — the same {@link LayerNode} the
166
174
  * grid takes for its children (a node or an array of them). Each layer reads its pane from context