@datalking/begonia-browser-sdk 0.2.0 → 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 (55) 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-editor-binding.d.ts +76 -1
  19. package/dist/browser-paginated-preview-key-selection.d.ts +48 -0
  20. package/dist/browser-paginated-preview-position-hit.d.ts +28 -0
  21. package/dist/browser-table-target-resolution.d.ts +59 -0
  22. package/dist/command.js +5 -5
  23. package/dist/editor.d.ts +8 -0
  24. package/dist/editor.js +5 -4
  25. package/dist/header-footer/header-footer-band-geometry.d.ts +70 -0
  26. package/dist/header-footer/header-footer-band-press.d.ts +51 -0
  27. package/dist/header-footer/header-footer-edit-state.d.ts +44 -0
  28. package/dist/header-footer/header-footer-edit-target.d.ts +54 -0
  29. package/dist/header-footer/header-footer-editing-controller.d.ts +133 -0
  30. package/dist/header-footer/header-footer-exit-press.d.ts +54 -0
  31. package/dist/header-footer/header-footer-slot.d.ts +38 -0
  32. package/dist/header-footer/header-footer-story-blocks.d.ts +71 -0
  33. package/dist/header-footer/section-header-footer-links.d.ts +60 -0
  34. package/dist/header-footer/section-header-footer-variants.d.ts +55 -0
  35. package/dist/index.d.ts +31 -0
  36. package/dist/index.js +60 -5
  37. package/dist/ooxml.js +4 -4
  38. package/dist/paginated-editing/index.d.ts +7 -0
  39. package/dist/paginated-editing/paginated-caret-reveal.d.ts +51 -0
  40. package/dist/paginated-editing/paginated-column-keyboard.d.ts +50 -0
  41. package/dist/paginated-editing/paginated-editing-session.d.ts +8 -0
  42. package/dist/paginated-editing/paginated-editing-types.d.ts +169 -0
  43. package/dist/paginated-editing/paginated-ime-caret-measure.d.ts +26 -0
  44. package/dist/paginated-editing/paginated-input-anchor.d.ts +116 -0
  45. package/dist/paginated-editing/paginated-input-bridge.d.ts +169 -0
  46. package/dist/paginated-editing/paginated-table-boundary-keyboard.d.ts +24 -0
  47. package/dist/paginated-editing/paginated-table-boundary-keys.d.ts +33 -0
  48. package/dist/paginated-preview-selection-table/preview-selection-table-exit.d.ts +61 -0
  49. package/dist/paginated-preview-selection-table/preview-selection-table-resolve.d.ts +7 -2
  50. package/dist/preview.js +1 -1
  51. package/dist/theme/theme-tokens.d.ts +35 -1
  52. package/dist/theme.js +1 -1
  53. package/dist/v1.d.ts +6 -0
  54. package/dist/v1.js +9 -9
  55. package/package.json +14 -14
@@ -0,0 +1,70 @@
1
+ import type { PageProjection } from '@datalking/begonia-layout-contracts';
2
+ /**
3
+ * Where a header or footer band sits on a page, in page-local CSS pixels.
4
+ *
5
+ * Word draws the band from two numbers that are not the margins: the page
6
+ * margin says where the *body* stops, and the header/footer *distance* says how
7
+ * far the story sits from the page edge. The band is the strip between them -
8
+ * the part of the margin the story owns. SuperDoc computes exactly this
9
+ * rectangle (`#computeDecorationBox`):
10
+ *
11
+ * header: top = headerDistance, height = marginTop - headerDistance
12
+ * footer: top = pageHeight - marginBottom, height = marginBottom - footerDistance
13
+ *
14
+ * Using the body boundary instead put the header band up against the page edge
15
+ * with the body's first line painted directly under it, and pushed the footer's
16
+ * text far above the page's bottom edge - both read as broken chrome rather than
17
+ * as Word's compact strip.
18
+ *
19
+ * A strip can collapse: a document may set its header distance equal to its top
20
+ * margin, or reserve no band at all. The band is then widened to a minimum
21
+ * height, anchored to the story's own baseline, so there is still something to
22
+ * double-click.
23
+ */
24
+ export type HeaderFooterKind = 'header' | 'footer';
25
+ export interface HeaderFooterBand {
26
+ kind: HeaderFooterKind;
27
+ /** Top of the hover and hit strip, in page-local pixels. */
28
+ top: number;
29
+ left: number;
30
+ width: number;
31
+ /** Height of the hit strip. */
32
+ height: number;
33
+ /** Where the story's own text begins, relative to `top`. */
34
+ contentTop: number;
35
+ /** How much room the story's text gets inside the strip. */
36
+ contentHeight: number;
37
+ /**
38
+ * Distance from the page's nearest edge to the story text. Word calls this
39
+ * the header (or footer) margin, and it is what a writer drags to move the
40
+ * story.
41
+ */
42
+ marginDistance: number;
43
+ }
44
+ /**
45
+ * The header strip: from the header distance down to the top margin.
46
+ *
47
+ * `regions.headerTop` is where the header story is painted, and it is already
48
+ * `min(margins.top, headerDistance)`, so the strip is simply the margin above
49
+ * the body that the header fills.
50
+ */
51
+ export declare function resolveHeaderBand(page: PageProjection): HeaderFooterBand | null;
52
+ /**
53
+ * The footer strip: from the bottom margin up to the footer distance.
54
+ *
55
+ * The footer story grows upwards and ends at `pageHeight - footerDistance`, so
56
+ * the strip's *bottom* edge is the story's baseline, not the page edge. Anchoring
57
+ * the text to the strip's top instead is what made a page number float a whole
58
+ * margin above the bottom of the page.
59
+ */
60
+ export declare function resolveFooterBand(page: PageProjection): HeaderFooterBand | null;
61
+ export declare function resolveHeaderFooterBand(page: PageProjection, kind: HeaderFooterKind): HeaderFooterBand | null;
62
+ /**
63
+ * Which band a page-local `y` falls into, or `null` for the body.
64
+ *
65
+ * The answer is the band's own rectangle, not the region boundary. Word's header
66
+ * strip stops at the top margin, and the body owns everything below it - a press
67
+ * just under the strip is a body press even though it is still above
68
+ * `regions.bodyTop`'s leading allowance.
69
+ */
70
+ export declare function resolveHeaderFooterBandAtY(page: PageProjection, y: number): HeaderFooterKind | null;
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Double-press detection for the header and footer bands.
3
+ *
4
+ * Word, and SuperDoc after it, only enter a header or footer on a double
5
+ * click. A single press in the band is a no-op: it must not move the caret into
6
+ * a story that the writer has not asked to edit, and it must not take the caret
7
+ * away from the story already open.
8
+ *
9
+ * The browser's own `dblclick` cannot carry this on its own. A press inside a
10
+ * page also starts the preview's drag session, which calls `preventDefault` on
11
+ * the press, and Chromium then cancels the click and dblclick events that would
12
+ * have followed. Counting presses here keeps the behaviour identical whether the
13
+ * press was default-prevented or not.
14
+ *
15
+ * The counting is pure: it takes the previous press and the current event and
16
+ * answers with a new tracker plus the verdict.
17
+ */
18
+ export interface BandPress {
19
+ /** Milliseconds, from the same clock for both presses. */
20
+ time: number;
21
+ x: number;
22
+ y: number;
23
+ }
24
+ export interface BandPressTracker {
25
+ /** The last press, or null when the next press starts a new sequence. */
26
+ last: BandPress | null;
27
+ }
28
+ export declare const initialBandPressTracker: BandPressTracker;
29
+ export interface BandPressInput {
30
+ /** True when the press is the primary button going down. */
31
+ primary: boolean;
32
+ /** Detail from the native event: 2 means the browser already counted two. */
33
+ detail?: number | null;
34
+ time: number;
35
+ x: number;
36
+ y: number;
37
+ /** Two presses this far apart in milliseconds are one gesture at most. */
38
+ intervalMs: number;
39
+ }
40
+ export interface BandPressResolution {
41
+ tracker: BandPressTracker;
42
+ /** True when this press completes a double press and the band should open. */
43
+ open: boolean;
44
+ }
45
+ /**
46
+ * Folds one press into the tracker.
47
+ *
48
+ * A press that is not the primary button clears the sequence: a right-click
49
+ * between two left presses must not complete a double press.
50
+ */
51
+ export declare function resolveBandPress(tracker: BandPressTracker, input: BandPressInput): BandPressResolution;
@@ -0,0 +1,44 @@
1
+ type ProseMirrorNode = any;
2
+
3
+ import type { HeaderFooterEditTarget } from './header-footer-edit-target.ts';
4
+ import type { HeaderFooterKind, HeaderFooterSlot } from './header-footer-slot.ts';
5
+ /**
6
+ * The header/footer editor's state, as one plain object.
7
+ *
8
+ * Deliberately a value, not a class: the band can be opened, switched to the
9
+ * other kind, and closed from three different places (a page click, a toolbar
10
+ * button, an Escape key), and a reducer over a plain value is what keeps those
11
+ * three agreeing instead of each holding a piece of the truth.
12
+ */
13
+ export type HeaderFooterEditPhase = 'idle' | 'loading' | 'editing' | 'saving' | 'error';
14
+ export interface HeaderFooterEditState {
15
+ phase: HeaderFooterEditPhase;
16
+ target: HeaderFooterEditTarget | null;
17
+ /**
18
+ * Which page's band displays the editor, or null when it was opened from the
19
+ * toolbar without a page.
20
+ *
21
+ * The *target* identifies the story (section + kind + slot); this only decides
22
+ * where the scratch view is hosted. A section's pages all draw the same story,
23
+ * so hosting the editor on every one of them would mount the same element into
24
+ * N hosts - the last wins and the rest sit empty.
25
+ */
26
+ pageNumber: number | null;
27
+ /** The blocks currently in the offline editing surface. */
28
+ blocks: readonly ProseMirrorNode[];
29
+ /** True while the slot has no part of its own yet. */
30
+ inherited: boolean;
31
+ error: string | null;
32
+ /**
33
+ * True once the scratch surface has reported an edit.
34
+ *
35
+ * A hint for the UI (a dot on the band, an "unsaved" note), never the thing
36
+ * that decides whether to commit: that is decided by comparing the edited
37
+ * story with the one the band opened with, so a missed notification cannot
38
+ * turn into a lost edit and a redundant one cannot turn into a stray write.
39
+ */
40
+ dirty: boolean;
41
+ }
42
+ export declare const initialHeaderFooterEditState: HeaderFooterEditState;
43
+ export declare function isHeaderFooterEditing(state: HeaderFooterEditState): boolean;
44
+ export declare function headerFooterEditIsFor(state: HeaderFooterEditState, kind: HeaderFooterKind, slot: HeaderFooterSlot, sectionIndex: number): boolean;
@@ -0,0 +1,54 @@
1
+ type DocumentApi = any;
2
+ import type { PageProjection } from '@datalking/begonia-layout-contracts';
3
+
4
+ import { type HeaderFooterKind, type HeaderFooterSlot } from './header-footer-slot.ts';
5
+ /**
6
+ * Everything needed to open one header or footer for editing.
7
+ *
8
+ * A target is addressed by *section + kind + slot*, not by page. Word behaves
9
+ * the same way: you edit "the section's primary header", and every page that
10
+ * draws that slot shows what you typed. Addressing by page would give two pages
11
+ * in the same section two independent editors over one underlying story, and
12
+ * whichever committed last would silently win.
13
+ */
14
+ export interface HeaderFooterEditTarget {
15
+ sectionIndex: number;
16
+ kind: HeaderFooterKind;
17
+ slot: HeaderFooterSlot;
18
+ /**
19
+ * The part this slot resolves to, or `null` for a slot that currently
20
+ * inherits from the previous section and has no part of its own yet.
21
+ */
22
+ refId: string | null;
23
+ /** What `resolve` reported, kept so the UI can say "same as previous". */
24
+ status: 'explicit' | 'inherited' | 'none';
25
+ /** Whether this slot is offered at all, given the section's own flags. */
26
+ available: boolean;
27
+ }
28
+ export interface HeaderFooterTargetResolution {
29
+ target: HeaderFooterEditTarget | null;
30
+ /** Why there is no target, when there is none. */
31
+ reason: string | null;
32
+ }
33
+ /** The section-level flags the slot choice depends on. */
34
+ export interface HeaderFooterSectionFlags {
35
+ titlePage: boolean;
36
+ oddEvenHeadersFooters: boolean;
37
+ }
38
+ export declare function readHeaderFooterSectionFlags(api: DocumentApi, sectionIndex: number): HeaderFooterSectionFlags;
39
+ /**
40
+ * Resolves the target for one page's band.
41
+ *
42
+ * Returns `reason` rather than throwing: a page can legitimately have no
43
+ * editable band (a section that switched off "different first page" while the
44
+ * reader is looking at page one), and the UI needs to explain that instead of
45
+ * dropping the click on the floor.
46
+ */
47
+ export declare function resolveHeaderFooterEditTarget(api: DocumentApi, page: PageProjection, kind: HeaderFooterKind): HeaderFooterTargetResolution;
48
+ /**
49
+ * The same target, for a slot the reader picked deliberately.
50
+ *
51
+ * The toolbar offers all three slots a section enables, which is how a writer
52
+ * types the even-page footer without scrolling to an even page first.
53
+ */
54
+ export declare function resolveHeaderFooterSlotTarget(api: DocumentApi, sectionIndex: number, kind: HeaderFooterKind, slot: HeaderFooterSlot): HeaderFooterEditTarget;
@@ -0,0 +1,133 @@
1
+ type DocumentApi = any;
2
+ type ProseMirrorNode = any;
3
+
4
+ import type { PageProjection } from '@datalking/begonia-layout-contracts';
5
+
6
+ import { type HeaderFooterEditState } from './header-footer-edit-state.ts';
7
+ import type { HeaderFooterKind, HeaderFooterSlot } from './header-footer-slot.ts';
8
+ /**
9
+ * The block-level surface the header/footer editor types into.
10
+ *
11
+ * Declared structurally rather than imported from the engine so this package
12
+ * keeps its DOM-free import graph: the React layer supplies a real editor, and
13
+ * a test supplies a stub with the same four methods.
14
+ */
15
+ /** The inline marks a header or footer story supports. */
16
+ export type HeaderFooterInlineFormatKey = 'bold' | 'italic' | 'underline' | 'strike';
17
+ /**
18
+ * Which of those marks the story's current selection carries.
19
+ *
20
+ * The band draws its own small format bar, and a toggle that cannot say whether
21
+ * it is on is not a toggle. The shape follows the body's formatting state so a
22
+ * host can drive both from one component.
23
+ */
24
+ export type HeaderFooterInlineFormatState = Readonly<Record<HeaderFooterInlineFormatKey, boolean>>;
25
+ export declare const EMPTY_HEADER_FOOTER_INLINE_FORMAT: HeaderFooterInlineFormatState;
26
+ /**
27
+ * The paragraph alignments a header or footer story is edited with.
28
+ *
29
+ * A running head is a paragraph like any other, and a centred document title
30
+ * above a left-aligned running head is the common shape in real documents. The
31
+ * band carries the options so the writer does not have to reach for the document
32
+ * toolbar and then find their way back into the story.
33
+ */
34
+ export type HeaderFooterParagraphAlignment = 'left' | 'center' | 'right' | 'justify';
35
+ /**
36
+ * Reads an alignment off a surface snapshot.
37
+ *
38
+ * The snapshot's `align` is a free-form schema attribute, so it can be missing or
39
+ * carry a value this bar does not offer. Unknown reads as "no opinion": the bar
40
+ * then shows nothing pressed rather than lighting up a neighbouring option and
41
+ * implying the story is aligned that way.
42
+ */
43
+ export declare function toHeaderFooterParagraphAlignment(value: unknown): HeaderFooterParagraphAlignment | null;
44
+ export interface HeaderFooterScratchSurface {
45
+ readDocument(): ProseMirrorNode;
46
+ /** Replaces the scratch document; used when the band is opened. */
47
+ replaceDocument(document: ProseMirrorNode): void;
48
+ focus(): void;
49
+ destroy(): void;
50
+ subscribe?(listener: () => void): () => void;
51
+ /**
52
+ * Toggles one inline mark on the story's own selection.
53
+ *
54
+ * A header is a story of its own, so it carries its own marks: applying bold
55
+ * through the body surface would style the body's selection, which is not what
56
+ * the writer has in front of them. Returns whether anything changed.
57
+ */
58
+ toggleInlineFormat?(key: HeaderFooterInlineFormatKey): boolean;
59
+ /** The marks the story's selection currently carries. */
60
+ readInlineFormat?(): HeaderFooterInlineFormatState;
61
+ /**
62
+ * Sets the text colour on the story's own selection; `null` clears it.
63
+ *
64
+ * Colour is an attribute rather than a toggle, so it cannot ride
65
+ * `toggleInlineFormat`: pressing "red" twice must leave the text red, and
66
+ * clearing must remove the attribute without discarding the font size that
67
+ * shares the same `text_style` mark. Returns whether anything changed.
68
+ */
69
+ applyTextColor?(color: string | null): boolean;
70
+ /** The text colour the story's selection carries, or null when unset. */
71
+ readTextColor?(): string | null;
72
+ /**
73
+ * Aligns the paragraphs the story's selection touches.
74
+ *
75
+ * Paragraph-level, not a mark: a header often holds a centred title and a
76
+ * left-aligned running line at once, so the option has to reach the block the
77
+ * caret is in rather than the characters it selects. Returns whether anything
78
+ * changed.
79
+ */
80
+ setParagraphAlignment?(align: HeaderFooterParagraphAlignment): boolean;
81
+ /** The caret paragraph's alignment, or null when the selection is mixed. */
82
+ readParagraphAlignment?(): HeaderFooterParagraphAlignment | null;
83
+ }
84
+ export interface CreateHeaderFooterEditingControllerOptions {
85
+ readApi: () => DocumentApi;
86
+ /**
87
+ * Builds the offline editing surface for one story.
88
+ *
89
+ * Detached from the live editor on purpose. The surface's own policy makes a
90
+ * side story read-only, and a header is a side story: writing through it
91
+ * would be rejected on the first keystroke. A scratch surface the controller
92
+ * owns and commits explicitly sidesteps that policy instead of widening it
93
+ * for every side story in the product.
94
+ */
95
+ createScratchSurface: (blocks: readonly ProseMirrorNode[]) => HeaderFooterScratchSurface;
96
+ }
97
+ export interface HeaderFooterEditingController {
98
+ getState(): HeaderFooterEditState;
99
+ subscribe(listener: () => void): () => void;
100
+ /** Opens the band for a page-local header or footer. */
101
+ openAtPage(page: PageProjection, kind: HeaderFooterKind): boolean;
102
+ /**
103
+ * Opens a slot the reader picked from the toolbar.
104
+ *
105
+ * `pageNumber` says which page hosts the editor. Omitted means "the first
106
+ * page of the section", which is where a reader who never scrolled would
107
+ * expect a header to open.
108
+ */
109
+ openSlot(sectionIndex: number, kind: HeaderFooterKind, slot: HeaderFooterSlot, pageNumber?: number | null): boolean;
110
+ /** Why the last `open*` call did nothing, or null. */
111
+ readLastReason(): string | null;
112
+ /** Writes the scratch story back into the section. True when it changed. */
113
+ commit(): boolean;
114
+ /**
115
+ * Commits and closes.
116
+ *
117
+ * Returns true when the close wrote to the document: a host uses it to skip
118
+ * the repaint that a no-op dismissal does not need.
119
+ */
120
+ close(): boolean;
121
+ readScratchSurface(): HeaderFooterScratchSurface | null;
122
+ destroy(): void;
123
+ }
124
+ /**
125
+ * Owns the header/footer editing session: which slot is open, what the scratch
126
+ * surface currently holds, and when the story goes back into the document.
127
+ *
128
+ * Kept out of React and out of the controller because it is a small state
129
+ * machine with three entry points (a page click, a toolbar pick, an Escape) and
130
+ * one exit (a commit). Making it a value-returning object is what lets both
131
+ * surfaces share it and a test drive it without a DOM.
132
+ */
133
+ export declare function createHeaderFooterEditingController({ readApi, createScratchSurface, }: CreateHeaderFooterEditingControllerOptions): HeaderFooterEditingController;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Whether a press on the page leaves the open header or footer.
3
+ *
4
+ * Word and superdoc both treat a band as a mode, not a widget: the story stays
5
+ * open until the writer presses somewhere that is not it. Without this the band
6
+ * was only dismissable with Escape, so a reader who clicked into the body went
7
+ * on typing into a header they could no longer see - and, worse, the band kept
8
+ * claiming the top margin, so hovering it for the rest of the session showed
9
+ * nothing and a second double press did nothing either.
10
+ *
11
+ * The rule is deliberately narrow, and it is the one superdoc implements
12
+ * (`EditorInputManager#handleClickInHeaderFooterMode`): a press exits when it
13
+ * lands inside the band's own page but outside the story, or on any part of the
14
+ * page that is not a band at all. A press inside the open story is how the
15
+ * writer places the caret and selects a word, so it must not exit; a press in
16
+ * editor chrome - a toolbar, a dropdown, a style menu - is not a statement
17
+ * about the document and must not exit either, or pressing Bold would close the
18
+ * header being formatted.
19
+ */
20
+ export type HeaderFooterPressOutcome =
21
+ /** The press belongs to the open story: keep editing. */
22
+ 'inside'
23
+ /** The press is on page content that is not the open story: close it. */
24
+ | 'exit'
25
+ /** The press is on editor chrome rather than the page: keep editing. */
26
+ | 'ignore';
27
+ export interface ResolveHeaderFooterPressInput {
28
+ /** The event target, as it arrived. */
29
+ target: unknown;
30
+ /**
31
+ * Whether the press landed on the open story's own band.
32
+ *
33
+ * Computed by the caller from the band element it already owns, because only
34
+ * that element knows which story it is hosting. A press inside the *other*
35
+ * band of the same page therefore arrives as `false` and closes this one.
36
+ */
37
+ insideActiveBand: boolean;
38
+ /** Whether the press landed on any band at all, open or not. */
39
+ insideAnyBand: boolean;
40
+ /** Whether the press landed inside registered editor chrome. */
41
+ insideChrome: boolean;
42
+ }
43
+ /**
44
+ * Classifies one press against the open story.
45
+ *
46
+ * Pure and total: every input, including a null target, returns one of the three
47
+ * outcomes, so the caller never has to decide what an unrecognised press means.
48
+ * The order matters - chrome is checked before the band tests so a band rendered
49
+ * inside a toolbar (a preview thumbnail, say) is still chrome, and the story
50
+ * before "any band" so the open story is never mistaken for a sibling.
51
+ */
52
+ export declare function resolveHeaderFooterPress(input: ResolveHeaderFooterPressInput): HeaderFooterPressOutcome;
53
+ /** Whether an element sits inside one of this editor's bands. */
54
+ export declare function isInsideHeaderFooterBand(target: unknown): boolean;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Which header/footer slot a given page draws from.
3
+ *
4
+ * OOXML gives every section three slots - `default`, `first` and `even` - and
5
+ * picks between them per page. The layout already made that choice when it
6
+ * built the page (that is why `pageSlot` lives in layout-core), so editing must
7
+ * make the *same* choice: an editor that opened the `default` header while the
8
+ * page painted the `first` one would show the writer a story that is not on
9
+ * screen.
10
+ *
11
+ * Recomputed here rather than read off the projection because `PageProjection`
12
+ * carries 300-odd construction sites and no slot field; deriving it from
13
+ * `sectionPageNumber` and the section's own flags is one pure function instead
14
+ * of a field every caller would have to thread.
15
+ */
16
+ export type HeaderFooterSlot = 'default' | 'first' | 'even';
17
+ export type HeaderFooterKind = 'header' | 'footer';
18
+ export interface HeaderFooterSlotInput {
19
+ /** One-based page number inside its section, as the projection reports it. */
20
+ sectionPageNumber: number;
21
+ /** One-based page number in the whole document, used for odd/even parity. */
22
+ pageNumber: number;
23
+ /** `w:titlePg` on the page's section. */
24
+ titlePage: boolean;
25
+ /** `w:evenAndOddHeaders` on the page's section. */
26
+ oddEvenHeadersFooters: boolean;
27
+ }
28
+ export declare function resolveHeaderFooterSlot(input: HeaderFooterSlotInput): HeaderFooterSlot;
29
+ /**
30
+ * Whether a slot may hold content even though the page does not paint it.
31
+ *
32
+ * A writer who turns on "different first page" expects to be able to write the
33
+ * first-page header before scrolling to page one, so the editor offers the
34
+ * slot whenever the section *enables* it - not only on the page that displays
35
+ * it. The default slot is always offered.
36
+ */
37
+ export declare function isHeaderFooterSlotAvailable(slot: HeaderFooterSlot, input: Pick<HeaderFooterSlotInput, 'titlePage' | 'oddEvenHeadersFooters'>): boolean;
38
+ export declare function headerFooterSlotLabel(kind: HeaderFooterKind, slot: HeaderFooterSlot): string;
@@ -0,0 +1,71 @@
1
+ type DocumentApi = any;
2
+ type ProseMirrorNode = any;
3
+
4
+
5
+ import type { HeaderFooterEditTarget } from './header-footer-edit-target.ts';
6
+ import type { HeaderFooterKind } from './header-footer-slot.ts';
7
+ /**
8
+ * Reads and writes the blocks of one header or footer slot.
9
+ *
10
+ * Two rules make this safe to call from an editor:
11
+ *
12
+ * 1. Reading resolves through the same section the page drew from, so an
13
+ * inherited slot edits the *shared* story rather than a copy that only the
14
+ * current page would ever show.
15
+ * 2. Writing targets the section the reader is in. Materialising an inherited
16
+ * slot first (`setLinkedToPrevious({linked: false})`) is what keeps the edit
17
+ * local: writing straight into an inherited slot would silently change every
18
+ * earlier section that shares it.
19
+ */
20
+ export interface HeaderFooterStory {
21
+ /** The blocks currently in the slot, in document order. */
22
+ blocks: readonly ProseMirrorNode[];
23
+ /**
24
+ * True when this section has its own part. False means the content shown is
25
+ * inherited from a previous section - editing it has to materialise a part
26
+ * first, or the writer would edit a story they cannot see.
27
+ */
28
+ explicit: boolean;
29
+ /** The section the content came from; equals the target's when explicit. */
30
+ sourceSectionIndex: number;
31
+ }
32
+ export declare function readHeaderFooterStory(api: DocumentApi, target: HeaderFooterEditTarget): HeaderFooterStory;
33
+ /**
34
+ * Gives this section its own part for the slot.
35
+ *
36
+ * Nothing else about the document changes: the new part starts as a copy of
37
+ * the inherited content (that is what Word does when you unlink a header), so
38
+ * the first edit is a change to the text the reader was already looking at.
39
+ * Returns false when the slot was already explicit.
40
+ */
41
+ export declare function materializeHeaderFooterSlot(api: DocumentApi, target: HeaderFooterEditTarget): boolean;
42
+ export interface CommitHeaderFooterStoryInput {
43
+ api: DocumentApi;
44
+ target: HeaderFooterEditTarget;
45
+ blocks: readonly ProseMirrorNode[];
46
+ }
47
+ /**
48
+ * Commits an edited story back into the section.
49
+ *
50
+ * Materialises an inherited slot first, then writes: that order matters,
51
+ * because writing into a slot this section only inherits would edit the shared
52
+ * part and change every page before it.
53
+ */
54
+ export declare function commitHeaderFooterStory({ api, target, blocks, }: CommitHeaderFooterStoryInput): boolean;
55
+ /**
56
+ * True when the edited story still holds exactly what the band opened with.
57
+ *
58
+ * Comparing the documents instead of trusting a dirty flag is what makes "open
59
+ * a header, press Escape" free. A flag can be missed - a surface that emits no
60
+ * updates, an update swallowed by a re-render, a host that rebuilt the surface -
61
+ * while the two documents cannot disagree with themselves.
62
+ *
63
+ * An opened slot with no blocks reads as one empty paragraph once it is wrapped
64
+ * in a document, so an empty story on both sides also counts as unchanged.
65
+ * Without that, merely looking at an empty header would write an empty part.
66
+ */
67
+ export declare function headerFooterStoryUnchanged(opened: readonly ProseMirrorNode[], next: readonly ProseMirrorNode[]): boolean;
68
+ /** The one-block document an empty header starts from. */
69
+ export declare function emptyHeaderFooterBlocks(createParagraph: () => ProseMirrorNode): readonly ProseMirrorNode[];
70
+ export declare function headerFooterStoryIsEmpty(blocks: readonly ProseMirrorNode[]): boolean;
71
+ export type { HeaderFooterKind };
@@ -0,0 +1,60 @@
1
+ import type { BrowserEditorController } from '../browser-editor-types-controller.ts';
2
+ import type { HeaderFooterKind, HeaderFooterSlot } from './header-footer-slot.ts';
3
+ /**
4
+ * "Link to previous" - the control that decides whether a section OWNS a header
5
+ * or INHERITS one.
6
+ *
7
+ * This is the switch behind the user-visible promise that different pages can
8
+ * show different headers. A section that is linked draws the previous section's
9
+ * story; unlinking gives it a copy it can edit. Word exposes this as a single
10
+ * toggle in the header band, and without it a writer cannot create a second
11
+ * section with its own header at all - every section silently follows the first,
12
+ * which then reads as "different pages cannot have different headers".
13
+ *
14
+ * The document API already models it (`headerLinks`/`footerLinks` on section
15
+ * metadata, `headerFooters.refs.setLinkedToPrevious`). What was missing was a
16
+ * way to reach it from the browser surface. These helpers are that way, and they
17
+ * stay thin: the API owns validation, link bookkeeping, and the transaction.
18
+ *
19
+ * Unlinking is deliberately non-destructive. The API copies the inherited story
20
+ * into the new part, so the page looks identical until the writer types - which
21
+ * is what unlinking a header does in Word. A toggle that blanked the page would
22
+ * read as data loss.
23
+ */
24
+ /** Which slot of which section a link applies to. */
25
+ export interface SectionLinkTarget {
26
+ sectionIndex: number;
27
+ kind: HeaderFooterKind;
28
+ slot: HeaderFooterSlot;
29
+ }
30
+ /** The link state of one slot. */
31
+ export interface SectionLinkState {
32
+ /**
33
+ * True when the section draws the previous section's story (or has none of
34
+ * its own), false when it owns a part it can edit independently.
35
+ */
36
+ linked: boolean;
37
+ /** False when the section's flags do not offer this slot at all. */
38
+ available: boolean;
39
+ }
40
+ /**
41
+ * Reads one slot's link state.
42
+ *
43
+ * Asks the API what this slot RESOLVES to rather than reading the raw links
44
+ * record, because the two answer different questions: the record says what the
45
+ * file asked for, while resolve says what the page will actually draw. A slot
46
+ * whose part exists but sits in a linked section is still the previous section's
47
+ * story, and reporting it as "owned" would offer the writer an edit that changes
48
+ * every earlier page.
49
+ */
50
+ export declare function readSectionLinkState(controller: BrowserEditorController, target: SectionLinkTarget): SectionLinkState;
51
+ /** Links a section's slot back to the previous section, or unlinks it. */
52
+ export declare function setSectionLinkedToPrevious(controller: BrowserEditorController, linked: boolean, target: SectionLinkTarget): boolean;
53
+ /** One slot's link state plus the ways to change it. */
54
+ export declare function createSectionLinkActions(controller: BrowserEditorController, target: SectionLinkTarget): {
55
+ read: () => SectionLinkState;
56
+ setLinked: (linked: boolean) => boolean;
57
+ linkToPrevious: () => boolean;
58
+ unlinkFromPrevious: () => boolean;
59
+ toggle: () => boolean;
60
+ };
@@ -0,0 +1,55 @@
1
+ import type { BrowserEditorController } from '../browser-editor-types-controller.ts';
2
+ /**
3
+ * The section switches that decide WHICH header or footer a page draws.
4
+ *
5
+ * Word hides two toggles that have nothing to do with a story's text:
6
+ *
7
+ * - "Different first page" gives the section a separate `first` slot.
8
+ * - "Different odd and even pages" gives it a separate `even` slot.
9
+ *
10
+ * Both are section metadata and both are already writable through the document
11
+ * API, but nothing in the browser surface reached them. The toolbar could open
12
+ * the first-page header of a section that had "different first page" switched on
13
+ * by the FILE, and could not switch it on itself - so a writer could not create
14
+ * the very arrangement the page slots exist for.
15
+ *
16
+ * These helpers are the missing switch. They are deliberately thin: the document
17
+ * API owns validation and the transaction, so a bad input is rejected there
18
+ * rather than half-applied here.
19
+ */
20
+ /**
21
+ * Which section a switch applies to.
22
+ *
23
+ * Omitted means the section at the caret, which is the only section the writer
24
+ * can see while the toolbar is in front of them.
25
+ */
26
+ export interface SectionVariantTarget {
27
+ sectionIndex?: number;
28
+ }
29
+ /** Reads each section's variant flags, or the document-wide union. */
30
+ export declare function readSectionVariants(controller: BrowserEditorController, target?: SectionVariantTarget): {
31
+ titlePage: boolean;
32
+ oddEven: boolean;
33
+ };
34
+ /**
35
+ * Turns "different first page" on or off for a section.
36
+ *
37
+ * Returns whether the document changed. Disabling it is NOT destructive: the
38
+ * `first` slot keeps whatever it held, so switching back on restores the story
39
+ * instead of presenting an empty header - which is how Word behaves, and what a
40
+ * writer expects from a toggle they flipped by accident.
41
+ */
42
+ export declare function setSectionTitlePage(controller: BrowserEditorController, enabled: boolean, target?: SectionVariantTarget): boolean;
43
+ /** Turns "different odd and even pages" on or off for the document. */
44
+ export declare function setSectionOddEvenHeadersFooters(controller: BrowserEditorController, enabled: boolean): boolean;
45
+ /** Both switches, read and toggled together. */
46
+ export declare function createSectionVariantActions(controller: BrowserEditorController, target?: SectionVariantTarget): {
47
+ read: () => {
48
+ titlePage: boolean;
49
+ oddEven: boolean;
50
+ };
51
+ setTitlePage: (enabled: boolean) => boolean;
52
+ setOddEven: (enabled: boolean) => boolean;
53
+ toggleTitlePage: () => boolean;
54
+ toggleOddEven: () => boolean;
55
+ };