@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,50 @@
1
+ type EditorView = any;
2
+ import type { LayoutProjection, LayoutProjectionOptions, LayoutTextMeasure } from '@datalking/begonia-layout-contracts';
3
+
4
+ export interface InstallPaginatedColumnKeyboardInput {
5
+ /**
6
+ * The live paginated editor view.
7
+ *
8
+ * A getter rather than a view so a surface that remounts its hidden editor
9
+ * keeps the same listener; the handler always reads the current view.
10
+ */
11
+ getView: () => EditorView | null | undefined;
12
+ /**
13
+ * The projection the surface is currently painting.
14
+ *
15
+ * A getter for the same reason: relayout replaces the projection object and a
16
+ * captured one would answer the next keystroke with yesterday's lines.
17
+ */
18
+ getProjection: () => LayoutProjection | null | undefined;
19
+ /**
20
+ * The measured geometry of that projection, when the caller has it.
21
+ *
22
+ * Passing it keeps the arrow landing on the same boundary a click or the
23
+ * painted caret used; without it the resolver falls back to the line geometry
24
+ * stored in the projection.
25
+ */
26
+ getMeasurement?: () => {
27
+ measureText?: LayoutTextMeasure;
28
+ measurementEpoch?: LayoutProjectionOptions['measurementEpoch'];
29
+ } | null | undefined;
30
+ /** The document the surface paints into, when the caller already has it. */
31
+ ownerDocument?: Document | null;
32
+ }
33
+ /**
34
+ * Route up and down through painted lines on multi-column pages.
35
+ *
36
+ * The editable surface drives a hidden single-column contenteditable. Its native
37
+ * up and down walk that single column, so on a two-column page an up arrow can
38
+ * jump from the right column to a line halfway down the left one. This listener
39
+ * runs in the capture phase, before the browser's default caret move, and claims
40
+ * up/down only when the caret is on a page that paints more than one column.
41
+ *
42
+ * Everything else is deliberately left alone:
43
+ * - left/right, Home and End keep their existing handling;
44
+ * - single-column pages keep the host's native motion, which is the same
45
+ * wrapping the page paints;
46
+ * - a document edge keeps its default, so an unhandled arrow still scrolls;
47
+ * - Alt/Ctrl/Meta and IME composition are never claimed, because those keys
48
+ * mean an edit or a word jump rather than line motion.
49
+ */
50
+ export declare function installPaginatedColumnKeyboard(input: InstallPaginatedColumnKeyboardInput): () => void;
@@ -0,0 +1,8 @@
1
+ import type { CreatePaginatedEditingSessionInput, PaginatedEditingSession } from './paginated-editing-types.ts';
2
+ /**
3
+ * Owns the state and DOM wiring behind in-place editing on a paginated surface.
4
+ *
5
+ * Framework-agnostic on purpose: it publishes a plain snapshot and never renders.
6
+ * React (or anything else) only mirrors the snapshot and draws the boxes.
7
+ */
8
+ export declare function createPaginatedEditingSession(input: CreatePaginatedEditingSessionInput): PaginatedEditingSession;
@@ -0,0 +1,169 @@
1
+ import type { PaginatedCaretRectLike, PaginatedOverlayModel, PaginatedOverlayRectLike } from '@datalking/begonia-layout-renderer';
2
+ /**
3
+ * The slice of the browser editor UI a paginated editing session reads.
4
+ *
5
+ * Deliberately structural so the session stays usable from a fake in tests and
6
+ * from any consumer that can produce selection geometry, not just React.
7
+ */
8
+ /**
9
+ * One focus transition, as the bridge observed it.
10
+ *
11
+ * `phase` is which DOM event fired. During `out`, `activeElement` has not
12
+ * moved yet in some browsers and is already `body` in others, so the transition
13
+ * is only fully described by pairing it with the following `in` - which is what
14
+ * `relatedTarget` carries early.
15
+ */
16
+ export interface PaginatedFocusChange {
17
+ phase: 'in' | 'out';
18
+ /** The element that lost or gained focus, if the browser named one. */
19
+ target: Element | null;
20
+ /** Where focus is heading, from `FocusEvent.relatedTarget`. */
21
+ relatedTarget: Element | null;
22
+ }
23
+ export interface PaginatedEditingSelectionSource {
24
+ getRects(): readonly PaginatedOverlayRectLike[];
25
+ getCaretRect(options?: {
26
+ bias?: 'start' | 'end';
27
+ }): PaginatedCaretRectLike | null;
28
+ subscribe(listener: (snapshot: unknown) => void): () => void;
29
+ /**
30
+ * Boxes covering selected table cells, when the selection is a cell range.
31
+ *
32
+ * Optional because most selections are text: a backend that cannot express a
33
+ * cell range simply omits it, and the overlay paints text selection only.
34
+ */
35
+ getCellSelectionRects?(): readonly PaginatedOverlayRectLike[] | null | undefined;
36
+ }
37
+ export interface PaginatedEditingPreviewSource {
38
+ subscribeResolvedProjection?(listener: (projection: unknown) => void): () => void | undefined;
39
+ /**
40
+ * Forgets the pointer press behind the current caret.
41
+ *
42
+ * Keyboard navigation has no pointer, so it must not inherit the painted side
43
+ * a press chose for the same collapsed offset.
44
+ */
45
+ setPointerCaretOrigin?(origin: null): void;
46
+ }
47
+ export interface PaginatedEditingSessionEditor {
48
+ selection: PaginatedEditingSelectionSource;
49
+ preview: PaginatedEditingPreviewSource;
50
+ }
51
+ /**
52
+ * The slice of a scrollable element caret reveal and page scrolling needs.
53
+ *
54
+ * Structural rather than `HTMLElement` because the paginated preview can
55
+ * virtualize against the window, which is not an element.
56
+ *
57
+ * Both axes are described because the preview has three layout modes: vertical
58
+ * pages scroll on `scrollTop`, horizontal and book spreads scroll on
59
+ * `scrollLeft`. A vertical-only host type is what made horizontal layout unable
60
+ * to reveal the caret at all.
61
+ */
62
+ export interface PaginatedEditingScrollHost {
63
+ scrollTop: number;
64
+ scrollHeight: number;
65
+ /** Horizontal offset. Optional for hosts that only ever scroll vertically. */
66
+ scrollLeft?: number;
67
+ /** Horizontal extent. Required to clamp a horizontal reveal. */
68
+ scrollWidth?: number;
69
+ /**
70
+ * The axis pages advance along: `'vertical'` (default) reveals by scrolling
71
+ * top, `'horizontal'` reveals by scrolling left. Book spreads are horizontal.
72
+ *
73
+ * Deliberately not named `scrollDirection`: the observed scroll host already
74
+ * uses that name for text direction (ltr/rtl).
75
+ */
76
+ scrollAxis?: 'vertical' | 'horizontal';
77
+ /**
78
+ * How the host's `scrollLeft` encodes physical position, for RTL scrollers.
79
+ *
80
+ * Mirrors the shared scroll-axis model so a resolved preview scroll host is
81
+ * assignable here unchanged; reveal reads it when it needs to convert a
82
+ * physical offset into the host's own coordinates.
83
+ */
84
+ rtlScrollCoordinateModel?: 'default' | 'negative' | 'reverse';
85
+ getBoundingClientRect(): {
86
+ top: number;
87
+ height: number;
88
+ left?: number;
89
+ width?: number;
90
+ };
91
+ }
92
+ export interface PaginatedEditingSnapshot {
93
+ /** Projection-space overlay content; scale is applied per page frame later. */
94
+ overlay: PaginatedOverlayModel;
95
+ composing: boolean;
96
+ /**
97
+ * The text the IME is composing, or the text it just committed.
98
+ *
99
+ * Non-empty from `compositionstart` until the pages have caught up with the
100
+ * committed document, so the surface can paint the preedit at the caret while
101
+ * the paginated layout is held back. `composing` alone cannot carry this: it
102
+ * drops to false on `compositionend`, exactly when the committed text still
103
+ * needs a stand-in for the layout pass that has not run yet.
104
+ */
105
+ compositionText: string;
106
+ /**
107
+ * Whether paginated layout must wait for the composition to settle.
108
+ *
109
+ * True while a composition is active and, after the commit, until the single
110
+ * pass that applies the committed text has been requested. A surface that
111
+ * repaginates per keystroke pays a full projection rebuild and a page render
112
+ * for every character the IME is still editing.
113
+ */
114
+ compositionHeld: boolean;
115
+ /**
116
+ * Whether the painted caret should be on screen right now.
117
+ *
118
+ * True while the editor holds focus, and while focus is in the editor's own
119
+ * chrome - a toolbar, a font dropdown - so that formatting a word does not
120
+ * make the caret disappear and reappear. False once focus leaves for anywhere
121
+ * else, including another editor on the same page.
122
+ */
123
+ focused: boolean;
124
+ /** Bumped whenever the overlay, composing flag or focus actually changes. */
125
+ revision: number;
126
+ }
127
+ export interface CreatePaginatedEditingSessionInput {
128
+ editor: PaginatedEditingSessionEditor;
129
+ /** Focuses the real (off-screen) editor host. */
130
+ focus?: () => void;
131
+ /** Resolves the mounted editor host element, used for IME tracking. */
132
+ getEditorHost?: () => HTMLElement | null;
133
+ /**
134
+ * Identifies this editor to the UI-surface registry.
135
+ *
136
+ * Supplied by the surface host and matched against the owner a registered
137
+ * toolbar declares. When absent, every registered surface counts as this
138
+ * editor's chrome, which is only correct for a page with a single editor.
139
+ */
140
+ editorId?: string;
141
+ /** Opens a context menu for the selection at a viewport point. */
142
+ onContextMenu?: (point: {
143
+ clientX: number;
144
+ clientY: number;
145
+ }) => boolean;
146
+ marginPx?: number;
147
+ reportErrors?: (error: unknown) => void;
148
+ }
149
+ export interface PaginatedEditingSession {
150
+ getSnapshot(): PaginatedEditingSnapshot;
151
+ subscribe(listener: (snapshot: PaginatedEditingSnapshot) => void): () => void;
152
+ /** Binds preview-host input routing; pass `null` to detach. */
153
+ attachPreviewHost(host: HTMLElement | null): void;
154
+ /** Binds the element whose scroll position caret reveal adjusts. */
155
+ attachScrollHost(host: PaginatedEditingScrollHost | null): void;
156
+ focus(): boolean;
157
+ reveal(): boolean;
158
+ /**
159
+ * Retires the preedit stand-in once the deferred pass has run.
160
+ *
161
+ * The release decision, not the arrival of a changed projection, is what
162
+ * removes the ghost: a commit can produce a projection identical to the
163
+ * previous one, and an identical projection is not re-published. Calling this
164
+ * while a composition is active is a no-op, because that composition owns the
165
+ * ghost.
166
+ */
167
+ releaseComposition(): void;
168
+ destroy(): void;
169
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * DOM reads behind the IME caret anchor.
3
+ *
4
+ * The anchor module is pure geometry over already-measured rects; this module is
5
+ * the boundary that produces them. The split keeps the fallback rule testable
6
+ * without a browser while the measurement itself stays in one place - both the
7
+ * session's anchor pass and its empty-block case read through here.
8
+ */
9
+ import { type PaginatedImeCaretRect } from './paginated-input-anchor.ts';
10
+ /** The focused editable, as far as measurement is concerned. */
11
+ export interface PaginatedImeCaretHost {
12
+ ownerDocument: Document;
13
+ contains(node: Node | null): boolean;
14
+ }
15
+ /**
16
+ * Where the editable's caret is, in viewport pixels.
17
+ *
18
+ * The IME asks the *focused editable* for this rectangle. A collapsed range is
19
+ * the browser's own answer for "where does the caret sit", so it moves with
20
+ * zoom, the host's internal scroll, and the editable's own layout - no mirrored
21
+ * arithmetic here.
22
+ *
23
+ * Returns null when the selection is not inside this host, so a click that has
24
+ * already moved focus elsewhere cannot park the host on a stale caret.
25
+ */
26
+ export declare function readPaginatedImeCaretRect(host: PaginatedImeCaretHost): PaginatedImeCaretRect | null;
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Geometry for parking the real editable on the caret the paginated surface paints.
3
+ *
4
+ * A paginated surface keeps the real ProseMirror host mounted but invisible (see
5
+ * `resolvePaginatedEditingHostStyle`): its pages are painted from a layout
6
+ * projection, and the editable itself is parked outside the viewport. Chrome -
7
+ * like any other IME client - asks the focused editable for its caret rectangle
8
+ * and hangs the candidate window there, so a host parked at `left:-10000px`
9
+ * makes the window open at the top-left corner of the screen. Flow editing does
10
+ * not have the problem because the editable sits where the text is.
11
+ *
12
+ * The fix is to move the host so that the editable's own caret covers the caret
13
+ * the surface paints. The host stays transparent, one pixel tall, and
14
+ * `pointer-events:none`, so nothing about the page changes; only the rectangle
15
+ * the IME reads moves. Everything here is a pure function of measured rects -
16
+ * the DOM reads live in the session - so zoom, scrolling, and a caret on a later
17
+ * page can be tested without a browser.
18
+ */
19
+ /** A measured rectangle, in viewport pixels. */
20
+ export interface PaginatedImeRectLike {
21
+ left: number;
22
+ top: number;
23
+ }
24
+ /** The caret box a page overlay paints, in the frame's own layout pixels. */
25
+ export interface PaginatedImeCaretBoxLike extends PaginatedImeRectLike {
26
+ height: number;
27
+ }
28
+ /** The content box a caret box is positioned against, in viewport pixels. */
29
+ export type PaginatedImeFrameLike = PaginatedImeRectLike;
30
+ export interface ResolvePaginatedImeAnchorRectInput {
31
+ /**
32
+ * The painted caret, in the frame's layout pixels.
33
+ *
34
+ * Layout pixels, not viewport pixels: the same numbers the overlay multiplies
35
+ * by `scale`, which is what keeps this function honest under zoom.
36
+ */
37
+ caret: PaginatedImeCaretBoxLike | null | undefined;
38
+ /** The frame content box the caret is positioned against, in viewport pixels. */
39
+ frame: PaginatedImeFrameLike | null | undefined;
40
+ /** Preview zoom, 1 meaning 100%. */
41
+ scale?: number | null;
42
+ }
43
+ export interface PaginatedImeAnchorRect {
44
+ left: number;
45
+ top: number;
46
+ height: number;
47
+ }
48
+ /** A measured caret or line box, in viewport pixels. */
49
+ export type PaginatedImeCaretRect = PaginatedImeAnchorRect;
50
+ export interface ResolvePaginatedImeCaretRectInput {
51
+ /**
52
+ * The caret rectangle the browser reported for the editable's selection.
53
+ *
54
+ * A collapsed range is Chrome's own answer, but an empty block has no caret
55
+ * box to measure: the range collapses to 0x0 at the document origin.
56
+ */
57
+ caret?: PaginatedImeCaretRect | null;
58
+ /**
59
+ * The content box of the block the caret is in, measured only when the caret
60
+ * itself is not usable.
61
+ */
62
+ line?: PaginatedImeCaretRect | null;
63
+ }
64
+ export interface ResolvePaginatedImeHostOffsetInput {
65
+ /** Where the surface paints the caret. */
66
+ anchor: PaginatedImeRectLike | null | undefined;
67
+ /**
68
+ * Where the editable's own caret currently is, in viewport pixels.
69
+ *
70
+ * Measured with the host where it currently sits, so the two rects already
71
+ * carry every zoom, scroll, and transform between them. The difference is a
72
+ * pure translation, which is why this stays correct at any zoom without
73
+ * redoing the frame math.
74
+ */
75
+ hostCaret: PaginatedImeRectLike | null | undefined;
76
+ /** The host's fixed position, used when it cannot be aligned. */
77
+ offset: PaginatedImeRectLike;
78
+ }
79
+ export interface PaginatedImeHostOffset {
80
+ left: number;
81
+ top: number;
82
+ /** Whether the offset differs from the one passed in. */
83
+ moved: boolean;
84
+ }
85
+ /**
86
+ * Where the IME would look if the host's caret was the painted caret.
87
+ *
88
+ * A caret on a later page is the case that breaks naive implementations: the
89
+ * frame's own `top` has to be added before scaling the caret, or every page
90
+ * after the first lands at the same place.
91
+ */
92
+ export declare function resolvePaginatedImeAnchorRect(input: ResolvePaginatedImeAnchorRectInput): PaginatedImeAnchorRect | null;
93
+ /**
94
+ * The editable's caret rectangle, falling back to its line's box.
95
+ *
96
+ * Chrome reports an empty paragraph's collapsed selection as 0x0 at the document
97
+ * origin. That is not a caret at the corner of the page - the block has simply
98
+ * not produced a caret box yet - but it is what the IME would be anchored to, so
99
+ * the candidate window opened at the window's bottom-right corner after Enter
100
+ * created an empty block. The block's own content box starts where the first
101
+ * character will be typed and has the line's height, which is the same rectangle
102
+ * the caret paints a frame later.
103
+ *
104
+ * Height is the test, not width: a collapsed caret is legitimately zero wide, but
105
+ * it is never zero tall on a line that is laid out.
106
+ */
107
+ export declare function resolvePaginatedImeCaretRect(input: ResolvePaginatedImeCaretRectInput): PaginatedImeCaretRect | null;
108
+ /**
109
+ * The host position that puts the editable's caret on the anchor.
110
+ *
111
+ * Translating the host translates its caret, so the new position is the old one
112
+ * plus the gap between the two rects. Repeating the call is a no-op once the gap
113
+ * is closed, which is what makes it safe to run on every scroll, selection, and
114
+ * projection change.
115
+ */
116
+ export declare function resolvePaginatedImeHostOffset(input: ResolvePaginatedImeHostOffsetInput): PaginatedImeHostOffset;
@@ -0,0 +1,169 @@
1
+ import type { PaginatedFocusChange } from './paginated-editing-types.ts';
2
+ export interface PaginatedInputBridgeKeyEventLike {
3
+ type?: string;
4
+ key?: string | null;
5
+ defaultPrevented?: boolean;
6
+ altKey?: boolean;
7
+ ctrlKey?: boolean;
8
+ metaKey?: boolean;
9
+ isComposing?: boolean;
10
+ /** Event target, used to keep focus out of other form fields. */
11
+ target?: unknown;
12
+ }
13
+ /**
14
+ * Whether an element owns typing focus for itself.
15
+ *
16
+ * A keydown that starts inside a text field, a select or a contenteditable
17
+ * belongs to that element. Stealing focus back for it would make every comment
18
+ * composer, search box and settings input on the page untypable while the
19
+ * paginated surface is mounted.
20
+ */
21
+ export declare function isTypingFocusOwnedByTarget(target: unknown): boolean;
22
+ /**
23
+ * Whether a keydown on the painted surface should pull focus back into the
24
+ * real (off-screen) editor so the keystroke lands in the document.
25
+ *
26
+ * Modifier-only presses, browser shortcuts and keys aimed at another typing
27
+ * element are skipped: refocusing for them would swallow commands like Cmd+F,
28
+ * or make an unrelated input on the page untypable.
29
+ */
30
+ export declare function shouldFocusPaginatedHostForKey(event: PaginatedInputBridgeKeyEventLike | null | undefined): boolean;
31
+ /**
32
+ * Where a pointer press happened, as far as focus ownership is concerned.
33
+ *
34
+ * - `body`: the painted document, which the off-screen editor owns.
35
+ * - `band`: page furniture the surface itself draws - the header and footer
36
+ * bands. It is not a form field, so the typing-target test above cannot
37
+ * recognise it, and yet focus must stay where the press put it: the press
38
+ * either starts the double press that opens the band, or lands in the story
39
+ * already open in it.
40
+ * - `typing`: a form field or a contenteditable that owns typing for itself.
41
+ */
42
+ export type PaginatedPointerFocusOwner = 'body' | 'band' | 'typing';
43
+ /**
44
+ * Resolves which of those a press belongs to.
45
+ *
46
+ * The band attribute is spelled out here rather than imported: this module is
47
+ * the *policy*, and the renderer that writes the attribute is a package this one
48
+ * must not depend on. A rename on the renderer side is caught by the test that
49
+ * asserts the policy against the rendered markup.
50
+ *
51
+ * A node without `closest` is treated as the body on purpose. Every press the
52
+ * bridges see comes through a DOM event, so a target that cannot answer
53
+ * `closest` is a test double or a detached node - neither of which is a band,
54
+ * and treating it as one would silently disable focusing in that host.
55
+ */
56
+ export declare function resolvePaginatedPointerFocusOwner(target: unknown): PaginatedPointerFocusOwner;
57
+ /**
58
+ * Whether a pointer press should move focus back into the real editor host.
59
+ *
60
+ * Only the primary button is handled: a right-click opens the context menu and
61
+ * must not steal the selection the menu is about to be built from.
62
+ *
63
+ * A press inside a band is skipped for a different reason. The band editor is a
64
+ * separate ProseMirror view, and this listener sits on the preview host in the
65
+ * capture phase, so it runs *before* the press reaches that view. Pulling focus
66
+ * into the body's off-screen host there did two visible things: it moved the
67
+ * caret out of the header the writer was editing, and the body host's selection
68
+ * painting then competed with the band's, so a single keystroke could be applied
69
+ * twice - which is what "typing in the footer is slow and duplicates
70
+ * characters" was.
71
+ */
72
+ export declare function shouldFocusPaginatedHostForPointer(event: {
73
+ button?: number;
74
+ defaultPrevented?: boolean;
75
+ target?: unknown;
76
+ } | null | undefined): boolean;
77
+ export type PaginatedCompositionEventType = 'compositionstart' | 'compositionupdate' | 'compositionend';
78
+ /**
79
+ * Whether a document change is outside the composition's live preedit.
80
+ *
81
+ * Deliberately keyed on the *named* input type rather than on
82
+ * `InputEvent.isComposing`. Around a commit the flag is ambiguous: some
83
+ * engines report `insertFromComposition` with `isComposing: true`, and an IME
84
+ * that never sends `compositionend` would then keep the latch on forever.
85
+ * `insertFromComposition` is the commit itself, so it must count as a release
86
+ * even though its name contains "Composition". An absent or unknown input type
87
+ * is ignored: guessing would end the latch on every ordinary preedit keystroke
88
+ * on hosts that do not fill the field.
89
+ */
90
+ export declare function shouldReleasePaginatedCompositionForInput(inputType: string | null | undefined): boolean;
91
+ /**
92
+ * Composition is a latch with two overrides.
93
+ *
94
+ * `compositionstart` sets it and `compositionend` clears it, so a platform
95
+ * that stays silent about the end keeps the preedit (and the held layout)
96
+ * alive. Two signals prove the composition is no longer producing a preedit:
97
+ *
98
+ * - leaving the editor, because the browser does not promise
99
+ * `compositionend` when focus is torn away mid-session (switching
100
+ * applications, a native dialog, some platforms' IME cancellation). Without
101
+ * it the latch stays stuck on with the caret suppressed, which reads as a
102
+ * frozen editor: nothing ever clears the flag, so even the next click leaves
103
+ * the caret hidden;
104
+ * - a document change that is not a preedit edit (see
105
+ * {@link shouldReleasePaginatedCompositionForInput}). An IME commit that
106
+ * never announces itself, a paste during composition, and automation all
107
+ * change the document while the latch is on; the release must not wait for
108
+ * an event the browser may never send.
109
+ *
110
+ * `compositionupdate` re-arms the latch. After an escape the IME may still be
111
+ * composing (a paste does not necessarily cancel it), and the next preedit
112
+ * update is the truthful signal that layout has to be held again.
113
+ */
114
+ export declare function resolvePaginatedCompositionTransition(current: boolean, type: string): boolean;
115
+ export interface CreatePaginatedInputBridgeInput {
116
+ getPreviewHost: () => HTMLElement | null;
117
+ getEditorHost?: () => HTMLElement | null;
118
+ focus?: () => void;
119
+ /**
120
+ * Reports the composition latch and, alongside it, the text being composed.
121
+ *
122
+ * The text is what lets a surface paint the preedit without repaginating the
123
+ * document on every keystroke: the composition is already in the editor's DOM,
124
+ * but the paginated pages only ever see a layout projection. An empty string
125
+ * means "no preedit", which is also what a `compositionstart` and a cancelled
126
+ * composition report.
127
+ */
128
+ onCompositionChange?: (composing: boolean, text: string) => void;
129
+ /**
130
+ * Called before the editor handles any keydown.
131
+ *
132
+ * Keyboard navigation has no pointer, so the press that placed the caret must
133
+ * stop speaking for it before a key moves the selection.
134
+ */
135
+ onKeyDown?: () => void;
136
+ /** Returns `true` when a menu was opened, which suppresses the native one. */
137
+ onContextMenu?: (point: {
138
+ clientX: number;
139
+ clientY: number;
140
+ }) => boolean;
141
+ /**
142
+ * Reports that focus moved anywhere in the document.
143
+ *
144
+ * Deliberately fires for every focus change, not just the ones that land in
145
+ * the editor: the caller decides, because only it knows whether the new
146
+ * owner is editor chrome or somewhere unrelated. Reporting "focus arrived"
147
+ * and "focus left" separately would push that judgement into this module and
148
+ * make it wrong for the second editor on a page.
149
+ */
150
+ /**
151
+ * Called when focus enters or leaves an editor-related element.
152
+ *
153
+ * `relatedTarget` is the element focus is moving to, which a `focusout`
154
+ * on the document reports even though `document.activeElement` is still the
155
+ * old node at that instant. A \`focusout\`/\`focusin\` pair therefore looks like
156
+ * "focus went nowhere, then somewhere"; the target lets a listener that cannot
157
+ * re-read the DOM (a test harness, a never-focused document) still see where it
158
+ * went.
159
+ */
160
+ onFocusChange?: (change: PaginatedFocusChange) => void;
161
+ }
162
+ export interface PaginatedInputBridge {
163
+ isComposing(): boolean;
164
+ focus(): boolean;
165
+ setPreviewHost(host: HTMLElement | null): void;
166
+ setEditorHost(host: HTMLElement | null): void;
167
+ destroy(): void;
168
+ }
169
+ export declare function createPaginatedInputBridge(input?: CreatePaginatedInputBridgeInput): PaginatedInputBridge;
@@ -0,0 +1,24 @@
1
+ type EditorView = any;
2
+
3
+ export interface InstallPaginatedTableBoundaryKeyboardInput {
4
+ /**
5
+ * The live paginated editor view.
6
+ *
7
+ * A getter rather than a view so a surface that remounts its hidden editor
8
+ * keeps the same listener; the handler always reads the current view.
9
+ */
10
+ getView: () => EditorView | null;
11
+ /** The document the surface paints into, when the caller already has it. */
12
+ ownerDocument?: Document | null;
13
+ }
14
+ /**
15
+ * Route arrow keys at a table boundary through the document model.
16
+ *
17
+ * The editable paginated surface drives a normal off-screen contenteditable, so
18
+ * the browser owns arrow motion: at the end of a table followed by a page
19
+ * break it selects the break node, and no caret is painted. This listener runs
20
+ * in the capture phase on the owner document, before the browser's default
21
+ * caret move, and only claims the exact positions the boundary rules
22
+ * recognize. Every other arrow keeps its native behavior.
23
+ */
24
+ export declare function installPaginatedTableBoundaryKeyboard(input: InstallPaginatedTableBoundaryKeyboardInput): () => void;
@@ -0,0 +1,33 @@
1
+ type ProseMirrorNode = any;
2
+
3
+ /**
4
+ * What an arrow key at a table boundary means to the editable paginated
5
+ * surface.
6
+ *
7
+ * `null` means the key is not ours and the browser must keep its default
8
+ * behavior. Anything else is a decision the surface has to apply:
9
+ * - `preventDefault` keeps the browser from performing its own caret move
10
+ * (which, at the end of a table followed by a page break, selects the break
11
+ * node and leaves no painted caret at all).
12
+ * - `pos` is where the caret should go; `null` means stay exactly where it is.
13
+ *
14
+ * Only collapsed selections with no modifier are considered. Shift+Arrow is
15
+ * selection extension, Alt+Arrow moves blocks in Word, and Ctrl/Cmd+Arrow is
16
+ * word-wise motion; none of them is a table exit.
17
+ */
18
+ export interface PaginatedTableBoundaryArrowInput {
19
+ doc: ProseMirrorNode;
20
+ from: number;
21
+ to: number;
22
+ key: string;
23
+ shiftKey?: boolean | null | undefined;
24
+ altKey?: boolean | null | undefined;
25
+ ctrlKey?: boolean | null | undefined;
26
+ metaKey?: boolean | null | undefined;
27
+ }
28
+ export interface PaginatedTableBoundaryArrowResolution {
29
+ /** Caret position to apply; `null` means leave the selection unchanged. */
30
+ pos: number | null;
31
+ preventDefault: boolean;
32
+ }
33
+ export declare function resolvePaginatedTableBoundaryArrow(input: PaginatedTableBoundaryArrowInput): PaginatedTableBoundaryArrowResolution | null;
@@ -0,0 +1,61 @@
1
+ type ProseMirrorNode = any;
2
+ import { type PageBlockPlacement } from '@datalking/begonia-layout-contracts';
3
+
4
+ /**
5
+ * Where a press in the empty paper to the right of a table's last row should
6
+ * put the caret.
7
+ *
8
+ * Two facts have to come together, and neither alone is enough:
9
+ * - `caretPos` is the first position after the table: the start of the
10
+ * following paragraph when one exists, or the slot an empty paragraph would
11
+ * occupy when one has to be inserted.
12
+ * - `insertAt` is set only when the document has nowhere to put that caret.
13
+ * The surface must insert an empty paragraph there before moving the
14
+ * selection; the position is the table's end, and `caretPos` is that
15
+ * paragraph's single caret slot.
16
+ */
17
+ export interface PreviewTableExitIntent {
18
+ /** Caret position after the table (inside the following paragraph). */
19
+ caretPos: number;
20
+ /** When non-null, insert an empty paragraph here (the table's end) first. */
21
+ insertAt: number | null;
22
+ }
23
+ export interface ResolvePreviewTableExitCaretInput {
24
+ doc: ProseMirrorNode;
25
+ block: PageBlockPlacement;
26
+ /** Pointer position in the same projection space as `block.left/top`. */
27
+ x: number;
28
+ y: number;
29
+ }
30
+ /**
31
+ * The caret a press in the paper right of a table's last row asks for.
32
+ *
33
+ * Deliberately narrow: only a press that is
34
+ * - on the table's *last source row* (the last fragment row may be a repeated
35
+ * header, so the source index is what decides), and
36
+ * - horizontally beyond the table's painted right edge
37
+ * counts. A press on the table's own border, in an earlier row, or in a cell
38
+ * keeps the existing cell-aware hit resolution. Nested tables are excluded
39
+ * because their next sibling is inside a cell, not the body this rule is
40
+ * about.
41
+ */
42
+ export declare function resolvePreviewTableExitCaret(input: ResolvePreviewTableExitCaretInput): PreviewTableExitIntent | null;
43
+ /**
44
+ * Resolve where a caret goes after a top-level table.
45
+ *
46
+ * A textblock immediately after the table is where the writer means to land;
47
+ * anything else (nothing at all, a page break, a section break, another table)
48
+ * leaves the document with no text position below the table, so the caller has
49
+ * to insert an empty paragraph at the table's end. The insertion position is
50
+ * the table's end and the caret is one step inside the new paragraph.
51
+ */
52
+ export declare function resolvePreviewCaretAfterTable(doc: ProseMirrorNode, tablePos: number): PreviewTableExitIntent | null;
53
+ /**
54
+ * End-of-text position of the table's last cell's last textblock.
55
+ *
56
+ * Walks the last child at every level so a cell that ends in a nested table or
57
+ * a final empty paragraph lands on the last caret slot that actually exists,
58
+ * not on a boundary token. Returns null when the cell has no textblock at all.
59
+ */
60
+ export declare function resolvePreviewTableLastTextEnd(tablePos: number, table: ProseMirrorNode): number | null;
61
+ export declare function resolveLastTextblockEnd(nodePos: number, node: ProseMirrorNode): number | null;