@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.
- package/dist/browser-command-table-state.d.ts +5 -0
- package/dist/browser-command-types.d.ts +3 -1
- package/dist/browser-comment-range-point.d.ts +56 -0
- package/dist/browser-editor-comments-controller.d.ts +2 -1
- package/dist/browser-editor-context-menu-open-at.d.ts +15 -0
- package/dist/browser-editor-contracts.d.ts +6 -0
- package/dist/browser-editor-domain-types.d.ts +48 -1
- package/dist/browser-editor-host.d.ts +0 -2
- package/dist/browser-editor-selection-geometry.d.ts +135 -1
- package/dist/browser-editor-types-controller.d.ts +46 -1
- package/dist/browser-editor-types-shared.d.ts +17 -0
- package/dist/browser-editor-viewport/browser-editor-viewport-bounds.d.ts +1 -1
- package/dist/browser-editor-viewport-session-state-types.d.ts +15 -0
- package/dist/browser-history-shortcut.d.ts +31 -0
- package/dist/browser-image-command-types.d.ts +28 -0
- package/dist/browser-insert-command-types.d.ts +5 -0
- package/dist/browser-page-review-target.d.ts +44 -0
- package/dist/browser-paginated-preview-editor-binding.d.ts +76 -1
- package/dist/browser-paginated-preview-key-selection.d.ts +48 -0
- package/dist/browser-paginated-preview-position-hit.d.ts +28 -0
- package/dist/browser-table-target-resolution.d.ts +59 -0
- package/dist/command.js +5 -5
- package/dist/editor.d.ts +8 -0
- package/dist/editor.js +5 -4
- package/dist/header-footer/header-footer-band-geometry.d.ts +70 -0
- package/dist/header-footer/header-footer-band-press.d.ts +51 -0
- package/dist/header-footer/header-footer-edit-state.d.ts +44 -0
- package/dist/header-footer/header-footer-edit-target.d.ts +54 -0
- package/dist/header-footer/header-footer-editing-controller.d.ts +133 -0
- package/dist/header-footer/header-footer-exit-press.d.ts +54 -0
- package/dist/header-footer/header-footer-slot.d.ts +38 -0
- package/dist/header-footer/header-footer-story-blocks.d.ts +71 -0
- package/dist/header-footer/section-header-footer-links.d.ts +60 -0
- package/dist/header-footer/section-header-footer-variants.d.ts +55 -0
- package/dist/index.d.ts +31 -0
- package/dist/index.js +60 -5
- package/dist/ooxml.js +4 -4
- package/dist/paginated-editing/index.d.ts +7 -0
- package/dist/paginated-editing/paginated-caret-reveal.d.ts +51 -0
- package/dist/paginated-editing/paginated-column-keyboard.d.ts +50 -0
- package/dist/paginated-editing/paginated-editing-session.d.ts +8 -0
- package/dist/paginated-editing/paginated-editing-types.d.ts +169 -0
- package/dist/paginated-editing/paginated-ime-caret-measure.d.ts +26 -0
- package/dist/paginated-editing/paginated-input-anchor.d.ts +116 -0
- package/dist/paginated-editing/paginated-input-bridge.d.ts +169 -0
- package/dist/paginated-editing/paginated-table-boundary-keyboard.d.ts +24 -0
- package/dist/paginated-editing/paginated-table-boundary-keys.d.ts +33 -0
- package/dist/paginated-preview-selection-table/preview-selection-table-exit.d.ts +61 -0
- package/dist/paginated-preview-selection-table/preview-selection-table-resolve.d.ts +7 -2
- package/dist/preview.js +1 -1
- package/dist/theme/theme-tokens.d.ts +35 -1
- package/dist/theme.js +1 -1
- package/dist/v1.d.ts +6 -0
- package/dist/v1.js +9 -9
- 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
|
+
};
|