@datalking/begonia-browser-sdk 0.1.1 → 0.3.0

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.
Files changed (60) hide show
  1. package/dist/browser-command-table-state.d.ts +5 -0
  2. package/dist/browser-command-types.d.ts +3 -1
  3. package/dist/browser-comment-range-point.d.ts +56 -0
  4. package/dist/browser-editor-comments-controller.d.ts +2 -1
  5. package/dist/browser-editor-context-menu-open-at.d.ts +15 -0
  6. package/dist/browser-editor-contracts.d.ts +6 -0
  7. package/dist/browser-editor-domain-types.d.ts +48 -1
  8. package/dist/browser-editor-host.d.ts +0 -2
  9. package/dist/browser-editor-selection-geometry.d.ts +135 -1
  10. package/dist/browser-editor-types-controller.d.ts +46 -1
  11. package/dist/browser-editor-types-shared.d.ts +17 -0
  12. package/dist/browser-editor-viewport/browser-editor-viewport-bounds.d.ts +1 -1
  13. package/dist/browser-editor-viewport-session-state-types.d.ts +15 -0
  14. package/dist/browser-history-shortcut.d.ts +31 -0
  15. package/dist/browser-image-command-types.d.ts +28 -0
  16. package/dist/browser-insert-command-types.d.ts +5 -0
  17. package/dist/browser-page-review-target.d.ts +44 -0
  18. package/dist/browser-paginated-preview-controller.d.ts +6 -0
  19. package/dist/browser-paginated-preview-editor-binding.d.ts +76 -1
  20. package/dist/browser-paginated-preview-key-selection.d.ts +48 -0
  21. package/dist/browser-paginated-preview-position-hit.d.ts +28 -0
  22. package/dist/browser-paginated-preview-ui-controller.d.ts +1 -0
  23. package/dist/browser-table-target-resolution.d.ts +59 -0
  24. package/dist/command.js +5 -5
  25. package/dist/editor.d.ts +8 -0
  26. package/dist/editor.js +5 -4
  27. package/dist/header-footer/header-footer-band-geometry.d.ts +70 -0
  28. package/dist/header-footer/header-footer-band-press.d.ts +51 -0
  29. package/dist/header-footer/header-footer-edit-state.d.ts +44 -0
  30. package/dist/header-footer/header-footer-edit-target.d.ts +54 -0
  31. package/dist/header-footer/header-footer-editing-controller.d.ts +133 -0
  32. package/dist/header-footer/header-footer-exit-press.d.ts +54 -0
  33. package/dist/header-footer/header-footer-slot.d.ts +38 -0
  34. package/dist/header-footer/header-footer-story-blocks.d.ts +71 -0
  35. package/dist/header-footer/section-header-footer-links.d.ts +60 -0
  36. package/dist/header-footer/section-header-footer-variants.d.ts +55 -0
  37. package/dist/index.d.ts +35 -1
  38. package/dist/index.js +60 -5
  39. package/dist/ooxml.js +4 -4
  40. package/dist/paginated-editing/index.d.ts +7 -0
  41. package/dist/paginated-editing/paginated-caret-reveal.d.ts +51 -0
  42. package/dist/paginated-editing/paginated-column-keyboard.d.ts +50 -0
  43. package/dist/paginated-editing/paginated-editing-session.d.ts +8 -0
  44. package/dist/paginated-editing/paginated-editing-types.d.ts +169 -0
  45. package/dist/paginated-editing/paginated-ime-caret-measure.d.ts +26 -0
  46. package/dist/paginated-editing/paginated-input-anchor.d.ts +116 -0
  47. package/dist/paginated-editing/paginated-input-bridge.d.ts +169 -0
  48. package/dist/paginated-editing/paginated-table-boundary-keyboard.d.ts +24 -0
  49. package/dist/paginated-editing/paginated-table-boundary-keys.d.ts +33 -0
  50. package/dist/paginated-preview-selection-table/preview-selection-table-exit.d.ts +61 -0
  51. package/dist/paginated-preview-selection-table/preview-selection-table-resolve.d.ts +7 -2
  52. package/dist/preview.js +1 -1
  53. package/dist/theme/theme-presets.d.ts +14 -0
  54. package/dist/theme/theme-resolve.d.ts +21 -0
  55. package/dist/theme/theme-tokens.d.ts +118 -0
  56. package/dist/theme.js +1 -1
  57. package/dist/v1.d.ts +6 -0
  58. package/dist/v1.js +9 -9
  59. package/package.json +14 -14
  60. package/dist/browser-theme.d.ts +0 -26
@@ -0,0 +1,5 @@
1
+ type EditorState = any;
2
+
3
+ export declare function isCaretInTable(state: EditorState | null | undefined): boolean;
4
+ export declare function isCaretInTableCell(state: EditorState | null | undefined): boolean;
5
+ export declare function selectionSpansMultipleCells(state: EditorState | null | undefined): boolean;
@@ -1,10 +1,12 @@
1
1
  import type { EditorCommandId, EditorCommandState, EditorSessionHost, EditorSessionSnapshot } from '@datalking/begonia-editor-contracts';
2
2
  import type { DocumentApiCommentThreadPermissions as CommentThreadPermissions, DocumentApiContract as DocumentApi, DocumentApiReviewPermissionRecord as ReviewPermissionRecord } from '@datalking/begonia-document-api/core';
3
3
  import type { BrowserAdvancedOoxmlCommandId } from './browser-advanced-ooxml-command-types.ts';
4
+ import type { BrowserImageCommandId } from './browser-image-command-types.ts';
5
+ import type { BrowserInsertCommandId } from './browser-insert-command-types.ts';
4
6
  import type { BrowserEditorSelectionSnapshot } from './browser-editor-selection-snapshot.ts';
5
7
  import type { BrowserCommentsDisplayState, BrowserDocumentMode, BrowserEditorFlowMode, BrowserEditorLayoutMode, BrowserEditorZoomState, BrowserPreviewNavigationRequest, BrowserTrackChangesDisplayState, BrowserViewportRequestKey, BrowserViewportState } from './browser-editor-types-shared.ts';
6
8
  import type { BrowserEditorCollaborationState } from './browser-editor-collaboration-state-types.ts';
7
- export type BrowserCommandId = EditorCommandId | BrowserAdvancedOoxmlCommandId;
9
+ export type BrowserCommandId = EditorCommandId | BrowserAdvancedOoxmlCommandId | BrowserImageCommandId | BrowserInsertCommandId;
8
10
  export interface BrowserCommandEditorSnapshot extends BrowserEditorSessionSnapshot {
9
11
  trackChanges?: BrowserTrackChangesDisplayState;
10
12
  viewportRequestKey?: BrowserViewportRequestKey;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Resolving a comment click in the *flowing* editor.
3
+ *
4
+ * Comments are modelled as boundary nodes, so the DOM for a commented run looks like
5
+ *
6
+ * This<span data-thread-id=c1 data-ald-comment-range-start></span>clean-room<span ...end></span>
7
+ *
8
+ * The text between the boundaries is a bare text node - it carries no attribute and no
9
+ * wrapper - and the boundary spans are zero-width. A click on the highlighted words
10
+ * therefore reports the surrounding paragraph as `event.target`, which is why asking the
11
+ * DOM for `closest('[data-thread-id]')` never found a thread.
12
+ *
13
+ * The boundaries do still *have* a position, so the run can be recovered geometrically:
14
+ * collect the markers inside the clicked paragraph, keep the ones whose vertical band
15
+ * covers the pointer, and pick the narrowest start/end pair that straddles it. That also
16
+ * handles nesting, where an outer thread starts before and ends after an inner one.
17
+ */
18
+ export interface BrowserCommentBoundaryMarker {
19
+ /** Thread the boundary belongs to. */
20
+ threadId: string;
21
+ /** `start` opens a run, `end` closes it. */
22
+ edge: 'start' | 'end';
23
+ /** Horizontal position of the zero-width boundary. */
24
+ x: number;
25
+ /** Vertical span of the line the boundary sits on. */
26
+ top: number;
27
+ bottom: number;
28
+ }
29
+ /**
30
+ * The innermost thread whose highlighted run contains the point.
31
+ *
32
+ * "Innermost" is the narrowest straddling pair: with `[c1 [c2 ]c2 ]c1` a click inside the
33
+ * inner run must select `c2`, not the thread that merely encloses it. Ties fall back to
34
+ * the later start, which is the one painted on top.
35
+ */
36
+ export declare function resolveBrowserCommentAtPoint(markers: readonly BrowserCommentBoundaryMarker[] | null | undefined, point: {
37
+ x: number;
38
+ y: number;
39
+ } | null | undefined): string | null;
40
+ /**
41
+ * Read the comment boundaries rendered inside a container.
42
+ *
43
+ * Kept separate from the resolution above so the geometry rule can be unit tested
44
+ * without a DOM.
45
+ */
46
+ export declare function readBrowserCommentBoundaryMarkers(container: {
47
+ querySelectorAll(selector: string): ArrayLike<{
48
+ getAttribute(name: string): string | null;
49
+ getBoundingClientRect(): {
50
+ left: number;
51
+ right: number;
52
+ top: number;
53
+ bottom: number;
54
+ };
55
+ }>;
56
+ } | null | undefined): BrowserCommentBoundaryMarker[];
@@ -1,4 +1,5 @@
1
1
  import type { EditorCommentsController } from '@datalking/begonia-editor-contracts';
2
- import type { BrowserEditorCommentsController } from './browser-editor-comments-types.ts';
2
+ import type { BrowserEditorCommentsController, BrowserEditorCommentsSnapshot } from './browser-editor-comments-types.ts';
3
3
  import type { BrowserEditorUiHost } from './browser-editor-ui-types.ts';
4
+ export declare function normalizeBrowserEditorCommentsSnapshot(snapshot: ReturnType<EditorCommentsController['getSnapshot']> | null | undefined): BrowserEditorCommentsSnapshot;
4
5
  export declare function createBrowserEditorCommentsController(host: BrowserEditorUiHost, base: EditorCommentsController): BrowserEditorCommentsController;
@@ -0,0 +1,15 @@
1
+ import type { BrowserContextMenuState, BrowserDocumentMode, BrowserEditorController, BrowserEditorModules, BrowserTrackChangesDisplayState } from './browser-editor-types.ts';
2
+ export interface BrowserEditorContextMenuPoint {
3
+ clientX: number;
4
+ clientY: number;
5
+ }
6
+ export declare function createOpenBrowserEditorContextMenuAt(args: {
7
+ getController: () => BrowserEditorController;
8
+ getDocumentMode: () => BrowserDocumentMode;
9
+ getResolvedModules: () => BrowserEditorModules;
10
+ readTrackChangesDisplayState: () => BrowserTrackChangesDisplayState;
11
+ setContextMenu: (state: BrowserContextMenuState | null) => void;
12
+ closeContextMenu: () => void;
13
+ closeLinkPopover: () => void;
14
+ emit: () => void;
15
+ }): (point: BrowserEditorContextMenuPoint) => boolean;
@@ -21,6 +21,12 @@ export interface BrowserEditorCommentActions {
21
21
  setCommentInternal(commentId: string, isInternal: boolean): ReturnType<BrowserDocumentApi['comments']['patch']>;
22
22
  resolveComment(commentId: string): ReturnType<BrowserDocumentApi['comments']['resolve']>;
23
23
  reopenComment(commentId: string): ReturnType<BrowserDocumentApi['comments']['reopen']>;
24
+ /**
25
+ * Removes a thread and everything in it. Resolving keeps a thread for the
26
+ * record; deleting is the only way to take a mistaken one off the document, and
27
+ * without it a sidebar could only ever grow.
28
+ */
29
+ removeComment(commentId: string): ReturnType<BrowserDocumentApi['comments']['remove']>;
24
30
  }
25
31
  export interface BrowserEditorCommentFocusActions {
26
32
  setActiveComment(commentId: string | null): boolean;
@@ -4,7 +4,7 @@ import type { BrowserEditorSessionSnapshot } from './browser-command-types.ts';
4
4
  import type { BrowserEditorSelectionSnapshot } from './browser-editor-selection-snapshot.ts';
5
5
  import type { BrowserEditorCommentsDisplayActions, BrowserEditorDocumentModeActions, BrowserEditorViewStateActions } from './browser-editor-contracts.ts';
6
6
  import type { BrowserEditorPositionAtPoint, ResolveBrowserEditorPositionAtPointInput } from './browser-editor-point-types.ts';
7
- import type { BrowserEditorCaretRect, BrowserEditorSelectionAnchorRectOptions, BrowserEditorSelectionCaretRectOptions, BrowserEditorSelectionRect, BrowserEditorViewportRect } from './browser-editor-selection-geometry.ts';
7
+ import type { BrowserEditorCaretRect, BrowserEditorCellSelectionOptions, BrowserEditorCellSelectionRect, BrowserEditorSelectionAnchorRectOptions, BrowserEditorSelectionCaretRectOptions, BrowserEditorRangeBounds, BrowserEditorSelectionRect, BrowserEditorViewportRect } from './browser-editor-selection-geometry.ts';
8
8
  import type { BrowserEditorViewportGeometryEvent, BrowserEditorViewportGetRectInput, BrowserEditorViewportRectResult } from './browser-editor-viewport-geometry.ts';
9
9
  import type { BrowserEditorViewportScrollIntoViewInput, BrowserEditorViewportScrollIntoViewResult } from './browser-editor-viewport-scroll-into-view.ts';
10
10
  import type { BrowserEditorViewportContext, BrowserEditorViewportEntityHit } from './browser-editor-viewport-context-types.ts';
@@ -21,8 +21,55 @@ export interface BrowserEditorSelectionController extends Omit<EditorSelectionCo
21
21
  subscribe(listener: (snapshot: BrowserEditorSelectionSnapshot | null) => void): () => void;
22
22
  observe(listener: (snapshot: BrowserEditorSelectionSnapshot | null) => void): () => void;
23
23
  getRects(): BrowserEditorSelectionRect[];
24
+ /**
25
+ * Whole-cell boxes for the table cells the selection touches.
26
+ *
27
+ * Empty for a selection that never enters a table. Separate from `getRects`
28
+ * because a cell box covers the cell - padding and empty space included -
29
+ * while a text rect stops at the last glyph.
30
+ *
31
+ * Also empty while the selection stays inside ONE cell: there the text rects
32
+ * already express it, and a second box only rings highlighted text in a paler
33
+ * blue. Pass `paintSingleCellBox` to keep that box.
34
+ */
35
+ getCellSelectionRects(options?: BrowserEditorCellSelectionOptions): BrowserEditorCellSelectionRect[];
24
36
  getAnchorRect(options?: BrowserEditorSelectionAnchorRectOptions): BrowserEditorViewportRect | null;
25
37
  getCaretRect(options?: BrowserEditorSelectionCaretRectOptions): BrowserEditorCaretRect | null;
38
+ /**
39
+ * Selection boxes for an arbitrary document range.
40
+ *
41
+ * getRects() can only answer "what is selected right now". This answers
42
+ * "where would this range be", which is what a host needs to place a comment
43
+ * anchor, highlight a search hit, or preview a pending revision before it is
44
+ * applied.
45
+ *
46
+ * Offsets are document positions (the same space a selection snapshot uses),
47
+ * not projection offsets.
48
+ */
49
+ getRangeRects(range: {
50
+ from: number;
51
+ to: number;
52
+ }): BrowserEditorSelectionRect[];
53
+ /**
54
+ * Caret rectangle for an arbitrary document position.
55
+ *
56
+ * getCaretRect() only answers for the live selection. A host placing its own
57
+ * chrome (a comment pin, a collaborator label, a spellcheck popover) needs to
58
+ * ask where position N is, which superdoc answers with coordsAtPos.
59
+ */
60
+ getCaretRectAtPosition(position: number, options?: BrowserEditorSelectionCaretRectOptions): BrowserEditorCaretRect | null;
61
+ /**
62
+ * One box enclosing every box of a document range.
63
+ *
64
+ * A range that wraps across columns or pages produces several rects.
65
+ * getRangeRects returns them all; this returns the single box a floating
66
+ * toolbar or highlight marker can be anchored to, so a caller does not have
67
+ * to pick a line and ignore the rest.
68
+ */
69
+ getRangeBounds(range: {
70
+ from: number;
71
+ to: number;
72
+ }): BrowserEditorRangeBounds | null;
26
73
  }
27
74
  export interface BrowserEditorViewController extends BrowserEditorViewStateActions {
28
75
  getSnapshot(): BrowserEditorViewSnapshot;
@@ -1,10 +1,8 @@
1
- import type { EditorUiStateSnapshot } from '@datalking/begonia-editor-contracts';
2
1
  import type { BrowserCommandCatalogEntry, BrowserEditorSessionSnapshot } from './browser-command-types.ts';
3
2
  import type { BrowserEditorOverlayHost, BrowserEditorSessionHost, BrowserEditorUi, BrowserEditorUiHost } from './browser-editor-ui-types.ts';
4
3
  import type { BrowserEditorController } from './browser-editor-types-controller.ts';
5
4
  export declare function projectBrowserEditorSessionSnapshot(editor: BrowserEditorController, catalog?: readonly BrowserCommandCatalogEntry[]): BrowserEditorSessionSnapshot;
6
5
  export declare function createBrowserEditorHost(editor: BrowserEditorController): BrowserEditorSessionHost;
7
- export declare function createBrowserEditorUiStateHost(editor: BrowserEditorController): EditorUiStateSnapshot;
8
6
  export declare function createBrowserEditorUiHost(editor: BrowserEditorController): BrowserEditorUiHost;
9
7
  export declare function createBrowserEditorOverlayHost(editor: BrowserEditorController): BrowserEditorOverlayHost;
10
8
  export declare function resolveBrowserEditorOverlayController(host: BrowserEditorOverlayHost | null | undefined): BrowserEditorController | null;
@@ -1,5 +1,5 @@
1
1
  import { type EditorSelectionSnapshot } from '@datalking/begonia-editor-contracts';
2
- import { type ProjectionCaretBoundaryBias, type ProjectionCaretRect, type ProjectionSelectionRect } from '@datalking/begonia-page-layout';
2
+ import { type ProjectionCaretBoundaryBias, type ProjectionCaretRect, type ProjectionSelectionRect, type ProjectionTableCellSelectionBox } from '@datalking/begonia-page-layout';
3
3
  import { type BrowserPaginatedPreviewEditorBinding } from './browser-paginated-preview-editor-binding.ts';
4
4
  export interface BrowserEditorViewportRect {
5
5
  left: number;
@@ -8,6 +8,38 @@ export interface BrowserEditorViewportRect {
8
8
  height: number;
9
9
  }
10
10
  export type BrowserEditorSelectionRect = ProjectionSelectionRect;
11
+ /**
12
+ * A whole-cell selection box.
13
+ *
14
+ * Structurally a selection rectangle for the overlay's purposes (page, region,
15
+ * block, and left/top/width/height), but it is not a text range: it carries the
16
+ * grid coordinates of the cell it covers instead of a `from`/`to` offset pair.
17
+ */
18
+ export type BrowserEditorCellSelectionRect = ProjectionTableCellSelectionBox;
19
+ /**
20
+ * How many distinct table cells a box list covers.
21
+ *
22
+ * Counted by grid address rather than by box count: a cell that spans a page
23
+ * break is reported once per fragment, and two fragments of one cell must still
24
+ * read as a single-cell selection.
25
+ */
26
+ export declare function countDistinctSelectedCells(boxes: readonly ProjectionTableCellSelectionBox[]): number;
27
+ /**
28
+ * Whether whole-cell boxes are worth painting on top of the text rects.
29
+ *
30
+ * False for a selection that stays inside one cell: the text rects already cover
31
+ * it, so the box adds only a translucent ring around already-highlighted text.
32
+ */
33
+ export declare function shouldPaintCellSelectionBoxes(boxes: readonly ProjectionTableCellSelectionBox[], options?: BrowserEditorCellSelectionOptions): boolean;
34
+ export interface BrowserEditorCellSelectionOptions {
35
+ /**
36
+ * Paint a whole-cell box even when the selection stays inside one cell.
37
+ *
38
+ * Off by default: in that case the text rects already cover the selection, so
39
+ * the box only draws a redundant outline around already-highlighted text.
40
+ */
41
+ paintSingleCellBox?: boolean;
42
+ }
11
43
  export type BrowserEditorCaretRect = ProjectionCaretRect;
12
44
  export type BrowserEditorSelectionAnchorPlacement = 'start' | 'end' | 'union';
13
45
  export interface BrowserEditorSelectionAnchorRectOptions {
@@ -16,7 +48,82 @@ export interface BrowserEditorSelectionAnchorRectOptions {
16
48
  export interface BrowserEditorSelectionCaretRectOptions {
17
49
  bias?: ProjectionCaretBoundaryBias;
18
50
  }
51
+ /**
52
+ * Aggregated geometry for a document range.
53
+ *
54
+ * `bounds` wraps every rect, so a floating toolbar can be placed without
55
+ * deciding which line to hang it from. `rects` carries the per-line boxes for
56
+ * callers that draw each of them. `pageIndex` is the page the range starts on,
57
+ * which is the page a caller should scroll to before showing the range.
58
+ */
59
+ export interface BrowserEditorRangeBounds {
60
+ bounds: BrowserEditorViewportRect;
61
+ rects: BrowserEditorSelectionRect[];
62
+ pageIndex: number;
63
+ }
64
+ /**
65
+ * Selection snapshots carry document positions, but projection geometry indexes
66
+ * block-local text offsets. Map the range before handing it to the layout so a
67
+ * caret cannot land past the character under the pointer.
68
+ */
69
+ export declare function resolveSelectionProjectionRange(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, offsets: {
70
+ from: number;
71
+ to: number;
72
+ }): {
73
+ from: number;
74
+ to: number;
75
+ } | null;
76
+ export declare function createViewportUnionRect(rects: readonly BrowserEditorSelectionRect[]): BrowserEditorViewportRect | null;
19
77
  export declare function resolveBrowserEditorSelectionRects(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, selection: EditorSelectionSnapshot | null | undefined): ProjectionSelectionRect[];
78
+ /**
79
+ * Selection boxes for an arbitrary document range.
80
+ *
81
+ * Differs from {@link resolveBrowserEditorSelectionRects} in what it takes: that
82
+ * one reads the live selection, so it can only ever answer "what is selected
83
+ * right now". This answers "where would *this* range be" - which is what a host
84
+ * needs to place a comment anchor, highlight a search hit, or draw a pending
85
+ * revision before it is applied.
86
+ *
87
+ * Offsets are document positions (the same space a selection snapshot uses),
88
+ * not projection offsets; the mapping happens here so callers never have to know
89
+ * about the difference.
90
+ */
91
+ export declare function resolveBrowserEditorRangeRects(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, range: {
92
+ from: number;
93
+ to: number;
94
+ } | null | undefined): ProjectionSelectionRect[];
95
+ /**
96
+ * One box enclosing every box of a document range.
97
+ *
98
+ * A range that wraps across columns or pages produces several rects. A host
99
+ * that needs a single anchor - a floating toolbar, a highlight marker, a
100
+ * tooltip - cannot use the rect list directly, and picking rects[0] silently
101
+ * ignores everything after the first line break.
102
+ *
103
+ * Returns null for a range with no geometry, which a caller can distinguish
104
+ * from an empty result at the origin.
105
+ */
106
+ export declare function resolveBrowserEditorRangeBounds(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, range: {
107
+ from: number;
108
+ to: number;
109
+ } | null | undefined): {
110
+ bounds: BrowserEditorViewportRect;
111
+ rects: ProjectionSelectionRect[];
112
+ pageIndex: number;
113
+ } | null;
114
+ /**
115
+ * Selection boxes for the table cells a text range reaches into.
116
+ *
117
+ * A page hit-tests and carets one cell at a time, but a drag that starts in one
118
+ * cell and ends in another is a *cell range*: the reviewer expects whole cells
119
+ * highlighted, including the padded area and any empty cell the rectangle
120
+ * crosses. Text-range rects cannot express that - they stop at the last glyph -
121
+ * so the cells covered by the range are reported as boxes too.
122
+ *
123
+ * Returns an empty array when the range never enters a table, which is the
124
+ * common case.
125
+ */
126
+ export declare function resolveBrowserEditorCellSelectionRects(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, selection: EditorSelectionSnapshot | null | undefined, options?: BrowserEditorCellSelectionOptions): ProjectionTableCellSelectionBox[];
20
127
  export declare function resolveBrowserEditorCaretRect(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, selection: EditorSelectionSnapshot | null | undefined, options?: BrowserEditorSelectionCaretRectOptions): {
21
128
  pageIndex: number;
22
129
  pageNumber: number;
@@ -28,6 +135,33 @@ export declare function resolveBrowserEditorCaretRect(preview: BrowserPaginatedP
28
135
  lineIndex: number;
29
136
  lineCount: number;
30
137
  pos: number;
138
+ rowOffset?: number;
139
+ left: number;
140
+ top: number;
141
+ height: number;
142
+ } | null;
143
+ /**
144
+ * Caret rectangle for an arbitrary document position.
145
+ *
146
+ * resolveBrowserEditorCaretRect only answers for the live selection. A host
147
+ * placing its own chrome - a comment pin, a collaborator label, a spellcheck
148
+ * popover - needs to ask "where is position N", which is the same question
149
+ * superdoc answers with coordsAtPos(pos).
150
+ *
151
+ * Positions are document positions, not projection offsets.
152
+ */
153
+ export declare function resolveBrowserEditorCaretRectAtPosition(preview: BrowserPaginatedPreviewEditorBinding | null | undefined, position: number, options?: BrowserEditorSelectionCaretRectOptions): {
154
+ pageIndex: number;
155
+ pageNumber: number;
156
+ sectionId?: string | null;
157
+ region: import("@datalking/begonia-layout-contracts").ProjectionPlacementRegion;
158
+ blockIndex: number;
159
+ fragmentIndex: number;
160
+ columnIndex: number;
161
+ lineIndex: number;
162
+ lineCount: number;
163
+ pos: number;
164
+ rowOffset?: number;
31
165
  left: number;
32
166
  top: number;
33
167
  height: number;
@@ -6,7 +6,7 @@ type DocumentSurfaceOptions = any;
6
6
  type SurfaceFeatureDefinition = any;
7
7
  import type { SelectionCurrentInput } from '@datalking/begonia-document-api/core';
8
8
 
9
- import type { EditorSessionController, EditorSessionHost } from '@datalking/begonia-editor-contracts';
9
+ import type { EditorSessionController, EditorSessionHost, EditorTrackChangesDisplayMode } from '@datalking/begonia-editor-contracts';
10
10
  import type { DocumentPermissionActor, DocumentPermissionResolver } from '@datalking/begonia-document-api/review';
11
11
 
12
12
 
@@ -27,6 +27,13 @@ export interface BrowserEditorController extends BrowserEditorAdvancedOoxmlActio
27
27
  documentApi: DocumentApi;
28
28
  surface: DocumentSurface;
29
29
  documentFontCatalog?: DocumentFontCatalog;
30
+ /**
31
+ * Families the document declares that have neither an embedded face nor a
32
+ * resolvable alias, so measurement falls back to a substitute and the rendered
33
+ * pages drift from what Word shows. Empty for a document whose fonts all
34
+ * resolve. Exposed as data only; how a host surfaces it is a product decision.
35
+ */
36
+ documentMissingFonts?: readonly string[];
30
37
  documentFontsReady?: Promise<DocumentFontRegistration | null>;
31
38
  editorHost: EditorSessionHost<DocumentApi, BrowserCommandId, ReturnType<DocumentApi['selection']['current']>>;
32
39
  editor: EditorSessionController<DocumentApi, BrowserCommandId, ReturnType<DocumentApi['selection']['current']>>;
@@ -46,6 +53,27 @@ export interface BrowserEditorController extends BrowserEditorAdvancedOoxmlActio
46
53
  setZoomViewportMetrics(metrics: BrowserEditorZoomViewportMetrics | null): void;
47
54
  setTrackChangesReplacementMode(mode: BrowserTrackChangesReplacementMode): void;
48
55
  setTrackChangesVisible(visible: boolean): void;
56
+ setTrackChangesEnabled(enabled: boolean): void;
57
+ /**
58
+ * Applies { mode, enabled } together, mirroring the superdoc
59
+ * PresentationEditor method of the same name.
60
+ */
61
+ setTrackChangesOverrides(overrides: {
62
+ mode?: EditorTrackChangesDisplayMode;
63
+ enabled?: boolean;
64
+ }): void;
65
+ /**
66
+ * superdoc-compatible alias for {@link setTrackChangesOverrides}.
67
+ *
68
+ * superdoc spells this method "Tracked" (PresentationEditor
69
+ * .setTrackedChangesOverrides) while the surrounding begonia API says
70
+ * "TrackChanges". Both spellings resolve to the same mutation so a host
71
+ * ported from superdoc does not have to rename the call.
72
+ */
73
+ setTrackedChangesOverrides(overrides: {
74
+ mode?: EditorTrackChangesDisplayMode;
75
+ enabled?: boolean;
76
+ }): void;
49
77
  setCommentsReadOnly(readOnly: boolean): void;
50
78
  setActor(actor?: DocumentPermissionActor | null): void;
51
79
  setParticipant(participant: DocumentSurface['participant']): void;
@@ -85,6 +113,13 @@ export interface BrowserEditorController extends BrowserEditorAdvancedOoxmlActio
85
113
  clearSearch(): void;
86
114
  replaceSearchHit(hitId: string, text: string): ReturnType<DocumentApi['search']['replace']>;
87
115
  replaceAllSearchHits(text: string): ReturnType<DocumentApi['search']['replaceAll']>;
116
+ /**
117
+ * Changes proofing switches and returns the config now in force.
118
+ *
119
+ * Named after the superdoc PresentationEditor method it replaces. Partial by
120
+ * design: a caller flips one switch without restating the rest.
121
+ */
122
+ updateProofingConfig(patch: Parameters<DocumentApi['proofing']['updateConfig']>[0]): ReturnType<DocumentApi['proofing']['updateConfig']>;
88
123
  ignoreProofingDiagnostic(diagnosticId: string): ReturnType<DocumentApi['proofing']['ignore']>;
89
124
  acceptProofingSuggestion(diagnosticId: string): ReturnType<DocumentApi['proofing']['acceptSuggestion']>;
90
125
  replaceProofingDiagnosticTracked(diagnosticId: string, text: string): ReturnType<DocumentApi['proofing']['replaceTracked']>;
@@ -116,6 +151,16 @@ export interface BrowserEditorController extends BrowserEditorAdvancedOoxmlActio
116
151
  clearActiveLink(): boolean;
117
152
  closeLinkPopover(): void;
118
153
  closeContextMenu(): void;
154
+ /**
155
+ * Opens the context menu for the live selection at a viewport point.
156
+ *
157
+ * Paginated surfaces resolve their own pointer hits, so they cannot rely on
158
+ * `contextmenu` reaching the (off-screen) editor host.
159
+ */
160
+ openContextMenuAt(point: {
161
+ clientX: number;
162
+ clientY: number;
163
+ }): boolean;
119
164
  destroy(): void;
120
165
  }
121
166
  export type CreateBrowserEditorOptions = Omit<DocumentSurfaceOptions, 'element'> & {
@@ -33,9 +33,26 @@ export interface BrowserPreviewNavigationRequestInput {
33
33
  export interface BrowserViewStatePatch {
34
34
  flowMode?: BrowserEditorFlowMode;
35
35
  layoutMode?: BrowserEditorLayoutMode;
36
+ /**
37
+ * The layout to fall back to when flow leaves `paginated`.
38
+ *
39
+ * Kept separate from `layoutMode` because the two answer different questions:
40
+ * `layoutMode` is the page arrangement in force right now, while this is the
41
+ * arrangement the editor returns to after a pass through continuous flow.
42
+ * Without it a layout chosen while paginated is lost on the first toggle,
43
+ * since continuous flow renders from this value rather than from `layoutMode`.
44
+ */
45
+ preferredPaginatedLayoutMode?: BrowserEditorLayoutMode;
36
46
  zoomPercent?: number;
37
47
  viewport?: BrowserViewportState | null;
38
48
  viewportRequestKey?: BrowserViewportRequestKey;
49
+ /**
50
+ * Toggle non-printing marks. Additive: an absent field leaves the current
51
+ * setting alone, so existing callers keep their behaviour untouched.
52
+ */
53
+ showFormattingMarks?: boolean;
54
+ /** Toggle bookmark markers. Additive, like showFormattingMarks. */
55
+ showBookmarks?: boolean;
39
56
  }
40
57
  export type BrowserEditorFitWidthOptions = ViewportFitWidthOptions;
41
58
  export type BrowserEditorZoomViewportMetrics = EditorZoomViewportMetrics & ViewportFitMetrics;
@@ -29,7 +29,7 @@ export declare function isBrowserViewportStateCompatibleWithLayoutMode(viewport:
29
29
  export declare function isBrowserViewportStateCompatibleWithModes(viewport: Pick<BrowserViewportState, 'flowMode' | 'layoutMode'> | null | undefined, flowMode: BrowserEditorFlowMode, layoutMode: BrowserEditorLayoutMode): boolean;
30
30
  export declare function sameBrowserViewportAnchor(left: BrowserViewportState['viewportAnchor'], right: BrowserViewportState['viewportAnchor']): boolean;
31
31
  export declare function normalizeBrowserViewportAnchor(value: BrowserViewportState['viewportAnchor'] | null | undefined, fallbackPageAddress?: BrowserViewportAnchorPageAddress | null | undefined): import("@datalking/begonia-layout-renderer").PageViewportAnchor | null;
32
- export declare function resolveCompatibleBrowserPreviewViewportAnchor(viewport: Pick<BrowserViewportState, 'viewportAnchor' | 'anchorPageIndex' | 'anchorPageNumber' | 'currentPageIndex' | 'currentPageNumber'> | null | undefined): import("@datalking/begonia-layout-renderer").PageViewportAnchor | null;
32
+ export declare function resolveCompatibleBrowserPreviewViewportAnchor(viewport: Pick<BrowserViewportState, 'viewportAnchor' | 'anchorPageIndex' | 'anchorPageNumber' | 'currentPageIndex' | 'currentPageNumber' | 'visiblePageNumbers' | 'mountedPageNumbers' | 'firstVisiblePageNumber' | 'lastVisiblePageNumber'> | null | undefined): import("@datalking/begonia-layout-renderer").PageViewportAnchor | null;
33
33
  export declare function browserViewportStateHasExplicitModeConflict(viewport: Pick<BrowserViewportState, 'flowMode' | 'layoutMode'> | null | undefined, flowMode: BrowserEditorFlowMode, layoutMode: BrowserEditorLayoutMode): boolean;
34
34
  export declare function sameBrowserViewportState(left: BrowserViewportState | null | undefined, right: BrowserViewportState | null | undefined): boolean;
35
35
  export declare function sameBrowserViewportStateForControllerSync(left: BrowserViewportState | null | undefined, right: BrowserViewportState | null | undefined): boolean;
@@ -1,4 +1,18 @@
1
1
  import type { BrowserEditorFlowMode, BrowserEditorLayoutMode, BrowserPreviewNavigationRequest, BrowserResolvedViewportRequestKey, BrowserViewportRequestKey, BrowserViewportState } from './browser-editor-types.ts';
2
+ /**
3
+ * Display-only toggles for the paginated preview.
4
+ *
5
+ * These affect decoration, never layout: turning one on must not change where a
6
+ * line breaks, how a page paginates, or what an offset means. Keeping them in one
7
+ * object means a future toggle (bookmarks, for example) does not reshape the
8
+ * session state again.
9
+ */
10
+ export interface BrowserPreviewDisplayOptions {
11
+ /** Draw ¶, space and tab marks. Off by default. */
12
+ showFormattingMarks?: boolean;
13
+ /** Draw bookmark markers. Off by default. */
14
+ showBookmarks?: boolean;
15
+ }
2
16
  export interface BrowserViewportSessionState {
3
17
  flowMode: BrowserEditorFlowMode;
4
18
  layoutMode: BrowserEditorLayoutMode;
@@ -7,6 +21,7 @@ export interface BrowserViewportSessionState {
7
21
  viewportRequestKey: BrowserViewportRequestKey;
8
22
  previewNavigationRequest: BrowserPreviewNavigationRequest | null;
9
23
  nextPreviewNavigationRequestToken: number;
24
+ display: BrowserPreviewDisplayOptions;
10
25
  }
11
26
  export interface BrowserPreviewNavigationStateResult {
12
27
  nextState: BrowserViewportSessionState;
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Keyboard resolution for the history shortcuts.
3
+ *
4
+ * Pure and framework-free on purpose: the same rules must hold for the plain
5
+ * flow editor, the paginated surface and any host that paints its own preview.
6
+ * The React hook that binds these is a thin adapter over this function.
7
+ */
8
+ /** The history actions a keystroke can resolve to. */
9
+ export type BrowserHistoryShortcutAction = 'undo' | 'redo';
10
+ export interface BrowserHistoryShortcutInput {
11
+ key?: string | null;
12
+ /** Physical key, used when a layout or IME rewrites `key`. */
13
+ code?: string | null;
14
+ ctrlKey?: boolean | null;
15
+ metaKey?: boolean | null;
16
+ shiftKey?: boolean | null;
17
+ altKey?: boolean | null;
18
+ isComposing?: boolean | null;
19
+ defaultPrevented?: boolean | null;
20
+ repeat?: boolean | null;
21
+ /** Event target, so a focused text field keeps its own editing keys. */
22
+ target?: unknown;
23
+ }
24
+ /**
25
+ * Resolve a keydown to a history action, or `null` when the event belongs to
26
+ * the browser, the operating system or another editing element.
27
+ *
28
+ * Shift+Z is redo on every platform; whether redo is also `y` (Windows/Linux)
29
+ * or Cmd+Shift+Z (macOS) is decided by the presence of Shift, so both work.
30
+ */
31
+ export declare function resolveBrowserHistoryShortcut(event: BrowserHistoryShortcutInput | null | undefined): BrowserHistoryShortcutAction | null;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The commands that reshape a picture after it has been placed.
3
+ *
4
+ * Word treats a picture as an object with a size, a wrap mode, and a description,
5
+ * and it puts those controls on the picture itself rather than in the ribbon.
6
+ * begonia could insert a picture and paint it, but nothing could change one
7
+ * afterwards: `documentApi.media.update` existed and had a headless caller and an
8
+ * MCP caller, and no browser command reached it. A writer who inserted a
9
+ * full-width screenshot had no way to shrink it.
10
+ *
11
+ * These are the missing verbs. They all act on the picture at the selection,
12
+ * which is how the OOXML object commands next door already work, and they all
13
+ * route through `media.update` so the document owns validation.
14
+ */
15
+ export declare const browserImageCommandIds: readonly ['selected-image-resize', 'selected-image-set-wrap', 'selected-image-set-alt', 'set-image-size'];
16
+ export type BrowserImageCommandId = (typeof browserImageCommandIds)[number];
17
+ export declare function isBrowserImageCommandId(value: string): value is BrowserImageCommandId;
18
+ /**
19
+ * The wrap modes Word offers, as the image schema stores them.
20
+ *
21
+ * `null` means "no wrapping", which is Word's "In line with text" for an inline
22
+ * picture and "In front of/behind text" for a floating one. The schema keeps
23
+ * `displayMode` separate from `wrapMode` for exactly that reason, so a caller
24
+ * that wants a picture out of the text flow must move BOTH.
25
+ */
26
+ export declare const browserImageWrapModes: readonly ['inline', 'square', 'tight', 'through', 'topAndBottom', 'behind', 'inFront'];
27
+ export type BrowserImageWrapMode = (typeof browserImageWrapModes)[number];
28
+ export declare function isBrowserImageWrapMode(value: unknown): value is BrowserImageWrapMode;
@@ -0,0 +1,5 @@
1
+ export declare const browserInsertCommandIds: readonly ['insert-table', 'insert-image', 'table-insert-row-above', 'table-insert-row-below', 'table-insert-column-left', 'table-insert-column-right', 'table-delete-row', 'table-delete-column', 'table-delete', 'table-merge-cells', 'table-split-cell'];
2
+ export type BrowserInsertCommandId = (typeof browserInsertCommandIds)[number];
3
+ /** The commands that need a table cell under the caret to mean anything. */
4
+ export declare const browserTableCellCommandIds: readonly ["table-insert-row-above", "table-insert-row-below", "table-insert-column-left", "table-insert-column-right", "table-delete-row", "table-delete-column", "table-delete", "table-split-cell"];
5
+ export declare function isBrowserInsertCommandId(value: string): value is BrowserInsertCommandId;
@@ -0,0 +1,44 @@
1
+ import type { ProjectionPositionHit } from '@datalking/begonia-layout-contracts';
2
+ /**
3
+ * Which review thread a click on a printed page belongs to.
4
+ *
5
+ * The paginated preview paints its pages rather than exposing the text as editable
6
+ * DOM: every commented run is a `<span>` with `pointer-events: none` sitting on top of
7
+ * the page surface. That makes `document.elementsFromPoint` useless here - the browser
8
+ * reports the page overlay, never the decorated run - which is why resolving a click
9
+ * through the DOM never worked for this renderer.
10
+ *
11
+ * The layout already knows the answer. A hit carries the line box it landed in
12
+ * (`from`/`to` in document space) together with that line's `inlineSpans`, each of which
13
+ * lists the `commentIds` covering its text. Walking those spans against the hit offset
14
+ * gives the thread without touching the DOM at all, so the same code works for the
15
+ * virtualized preview, a print renderer and a headless test.
16
+ */
17
+ export interface BrowserPageReviewSpanTarget {
18
+ /** Comment threads covering the clicked character, outermost first. */
19
+ commentIds: readonly string[];
20
+ /** Tracked-change ids covering the clicked character, outermost first. */
21
+ trackChangeIds: readonly string[];
22
+ /** Text of the span that owns the clicked character. */
23
+ text: string;
24
+ }
25
+ /**
26
+ * Locate the inline span a document offset falls inside.
27
+ *
28
+ * Spans are laid out in reading order and carry no absolute offset of their own, so the
29
+ * walk accumulates `text.length` from `from`. A hit past the last span (a click in the
30
+ * trailing whitespace of a justified line) resolves to `null` instead of snapping to the
31
+ * final span, which would select a thread the reader did not point at.
32
+ */
33
+ export declare function resolveBrowserPageReviewSpanTarget(hit: Pick<ProjectionPositionHit, 'pos' | 'from' | 'to' | 'inlineSpans'> | null | undefined): BrowserPageReviewSpanTarget | null;
34
+ /**
35
+ * The comment thread to activate for a page click, or `null`.
36
+ *
37
+ * Overlapping threads arrive outermost-first, so the first id is the one the sidebar
38
+ * anchors on.
39
+ */
40
+ export declare function resolveBrowserPageCommentId(hit: Pick<ProjectionPositionHit, 'pos' | 'from' | 'to' | 'inlineSpans'> | null | undefined): string | null;
41
+ /**
42
+ * The tracked change to reveal for a page click, or `null`.
43
+ */
44
+ export declare function resolveBrowserPageTrackChangeId(hit: Pick<ProjectionPositionHit, 'pos' | 'from' | 'to' | 'inlineSpans'> | null | undefined): string | null;
@@ -11,6 +11,12 @@ export interface BrowserPaginatedPreviewController {
11
11
  observeViewport(viewport: BrowserViewportState, viewportResetVersion?: number | null): void;
12
12
  resolvePositionHitEvent(event: BrowserPaginatedPreviewPositionHitEvent): BrowserPaginatedPreviewPositionHitEvent;
13
13
  handlePositionHit(event: BrowserPaginatedPreviewPositionHitEvent): boolean;
14
+ /**
15
+ * True once `destroy()` ran. React wrappers use this to recreate the
16
+ * controller after StrictMode's simulated unmount instead of holding a
17
+ * permanently destroyed instance.
18
+ */
19
+ isDestroyed(): boolean;
14
20
  destroy(): void;
15
21
  }
16
22
  export declare function createBrowserPaginatedPreviewController(input: BrowserPaginatedPreviewControllerInput): BrowserPaginatedPreviewController;