@datalking/begonia-react 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 (41) hide show
  1. package/dist/binding/BegoniaPdfViewer.d.ts +4 -1
  2. package/dist/binding/BrowserPaginatedEditorSurface.d.ts +44 -0
  3. package/dist/binding/HeaderFooterScratchMount.d.ts +25 -0
  4. package/dist/binding/PaginatedLayoutView.d.ts +21 -2
  5. package/dist/binding/PaginatedPageOverlayView.d.ts +44 -0
  6. package/dist/binding/VirtualPagedPreview.d.ts +38 -1
  7. package/dist/binding/begonia-theme-style.d.ts +12 -0
  8. package/dist/binding/browser-header-footer-bands.d.ts +98 -0
  9. package/dist/binding/browser-header-footer-format-bar.d.ts +21 -0
  10. package/dist/binding/browser-paginated-preview-drag-state.d.ts +2 -0
  11. package/dist/binding/headless.d.ts +1 -1
  12. package/dist/binding/index.d.ts +4 -0
  13. package/dist/binding/paginated-preview-doc-style.d.ts +40 -0
  14. package/dist/binding/paginated-preview-font-family.d.ts +19 -0
  15. package/dist/binding/paginated-scroll-axis-host.d.ts +32 -0
  16. package/dist/binding/preview-link-activation.d.ts +71 -0
  17. package/dist/binding/resolve-snapshot-comment-state.d.ts +32 -0
  18. package/dist/binding/use-browser-header-footer-editing.d.ts +114 -0
  19. package/dist/binding/use-header-footer-scratch-surface.d.ts +48 -0
  20. package/dist/binding/use-owned-destroyable.d.ts +9 -0
  21. package/dist/binding/use-undo-redo-hotkeys.d.ts +45 -0
  22. package/dist/binding/useVirtualPagedPreviewState.d.ts +13 -3
  23. package/dist/binding/v1.d.ts +16 -0
  24. package/dist/binding/virtual-paged-preview-comment-highlight.d.ts +33 -0
  25. package/dist/binding/virtual-paged-preview-drag-session.d.ts +1 -1
  26. package/dist/binding/virtual-paged-preview-interaction.d.ts +2 -2
  27. package/dist/binding/virtual-paged-preview-list-marker.d.ts +42 -0
  28. package/dist/binding/virtual-paged-preview-renderers/virtual-paged-preview-block-text.d.ts +21 -6
  29. package/dist/binding/virtual-paged-preview-renderers/virtual-paged-preview-block-views.d.ts +18 -2
  30. package/dist/binding/virtual-paged-preview-review-attributes.d.ts +78 -0
  31. package/dist/binding/virtual-paged-preview-text-lines.d.ts +4 -0
  32. package/dist/chunk-LIAB6VEG.js +1 -0
  33. package/dist/editor-surface.css +457 -0
  34. package/dist/index.d.ts +6 -0
  35. package/dist/index.js +1 -1
  36. package/dist/v1.d.ts +4 -2
  37. package/dist/v1.js +1 -1
  38. package/package.json +19 -16
  39. package/dist/binding/paginated-preview-defaults.d.ts +0 -2
  40. package/dist/binding/virtual-paged-preview-table-metrics.d.ts +0 -1
  41. package/dist/chunk-IEHE33P5.js +0 -1
@@ -0,0 +1,114 @@
1
+ import type { PageProjection } from '@datalking/begonia-layout-contracts';
2
+ import { type HeaderFooterEditState, type HeaderFooterInlineFormatKey, type HeaderFooterInlineFormatState, type HeaderFooterKind, type HeaderFooterParagraphAlignment, type HeaderFooterSlot, type HeaderFooterTargetResolution } from '@datalking/begonia-browser-sdk';
3
+ import type { BrowserCommandId, BrowserEditorController } from '@datalking/begonia-browser/v1';
4
+ import type { EditorUiHost } from '@datalking/begonia-editor-ui';
5
+ /**
6
+ * Header and footer editing as one hook.
7
+ *
8
+ * The split is deliberate: the controller in `browser-sdk` owns the state
9
+ * machine and talks to the document API, this hook owns the DOM. Everything a
10
+ * test would want to assert about "what happens when a band is opened" lives in
11
+ * the controller and runs without a browser; everything React-shaped lives
12
+ * here and stays a thin adaptation.
13
+ */
14
+ /**
15
+ * The band's surface as a toolbar can see it.
16
+ *
17
+ * Typed from the engine adapter rather than from the toolbar so this package
18
+ * keeps depending on the same layers it already did; the toolbar's own props
19
+ * accept exactly this shape.
20
+ */
21
+ export type HeaderFooterToolbarHost = EditorUiHost<BrowserCommandId>;
22
+ export interface BrowserHeaderFooterEditing {
23
+ state: HeaderFooterEditState;
24
+ /** True while the band is open, for hosts that dim the body. */
25
+ active: boolean;
26
+ openAtPage(page: PageProjection, kind: HeaderFooterKind): void;
27
+ /**
28
+ * Opens a slot picked in the toolbar.
29
+ *
30
+ * `page` is the page that hosts the editor and names the section. A toolbar
31
+ * has no page of its own, so without it the editor would open on section zero
32
+ * and on every page that draws that section's story at once.
33
+ */
34
+ openSlot(kind: HeaderFooterKind, slot: HeaderFooterSlot, page?: PageProjection | null): void;
35
+ /** Writes the open story back without closing the band. */
36
+ commit(): void;
37
+ /**
38
+ * Closes the band and writes the story back.
39
+ *
40
+ * `restoreFocus` defaults to true: closing from the keyboard has to hand the
41
+ * caret back to the page, or the next keystroke goes nowhere. A caller that is
42
+ * closing *because the reader pressed somewhere* must pass false - the press is
43
+ * about to place its own caret, and stealing focus from it puts the caret back
44
+ * where the reader left it instead of where they just clicked.
45
+ */
46
+ close(options?: {
47
+ restoreFocus?: boolean;
48
+ }): void;
49
+ /**
50
+ * Rendered inside the open band: the element the scratch view mounts into.
51
+ * Null until a band is open, so the band keeps its plain hover treatment when
52
+ * nothing is being edited.
53
+ */
54
+ editorMount: HTMLElement | null;
55
+ /**
56
+ * The inline marks the open story's selection carries.
57
+ *
58
+ * Meaningful only while a band is open; otherwise every mark is off, because
59
+ * there is no story to ask.
60
+ */
61
+ inlineFormat: HeaderFooterInlineFormatState;
62
+ /** Toggles one mark on the open story. Returns whether anything changed. */
63
+ toggleInlineFormat(key: HeaderFooterInlineFormatKey): boolean;
64
+ /**
65
+ * The text colour the open story's selection carries, or null.
66
+ *
67
+ * A separate value rather than a fifth boolean in `inlineFormat`: colour has a
68
+ * value, and a bar that rendered "colour on" without saying which colour would
69
+ * be lying about the text it is pointing at.
70
+ */
71
+ textColor: string | null;
72
+ /** Sets the open story's text colour. Returns whether anything changed. */
73
+ applyTextColor(color: string | null): boolean;
74
+ /**
75
+ * The caret paragraph's alignment in the open story, or null when no band is
76
+ * open or the selection spans more than one alignment.
77
+ */
78
+ paragraphAlignment: HeaderFooterParagraphAlignment | null;
79
+ /**
80
+ * Aligns the paragraphs the open story's selection touches. Returns whether
81
+ * anything changed; a bar that pressed without the story changing would keep
82
+ * showing a state the page does not have.
83
+ */
84
+ setParagraphAlignment(align: HeaderFooterParagraphAlignment): boolean;
85
+ /**
86
+ * The open story published as a toolbar host, or null when no band is open.
87
+ *
88
+ * A header is a story of its own, so the body toolbar cannot style it: that
89
+ * toolbar asks the body surface about the body's selection, which is empty
90
+ * while the writer is in the band. The story *is* an engine surface, though,
91
+ * and the engine already knows how to publish one to a toolbar. Handing that
92
+ * host to the toolbar is what makes bold, alignment, indent, lists and undo
93
+ * act on the header the writer is looking at instead of only on the four
94
+ * buttons the band carries itself.
95
+ */
96
+ toolbarHost: HeaderFooterToolbarHost | null;
97
+ /** Why the last attempt did nothing, for a toast or an inline note. */
98
+ reason: string | null;
99
+ }
100
+ export interface UseBrowserHeaderFooterEditingOptions {
101
+ controller: BrowserEditorController | null;
102
+ /** Called after a commit so the host can re-render the pages. */
103
+ onCommitted?: () => void;
104
+ /**
105
+ * The section the toolbar's slot buttons act on.
106
+ *
107
+ * Needed because the toolbar has no page of its own: a click on "Header
108
+ * (first page)" means "the section the reader is in", and only the host knows
109
+ * which page that is. A host that renders one section can leave this out.
110
+ */
111
+ readSectionIndex?: () => number;
112
+ }
113
+ export declare function useBrowserHeaderFooterEditing({ controller, onCommitted, readSectionIndex, }: UseBrowserHeaderFooterEditingOptions): BrowserHeaderFooterEditing;
114
+ export type { HeaderFooterTargetResolution };
@@ -0,0 +1,48 @@
1
+ import type { Node as ProseMirrorNode } from 'prosemirror-model';
2
+ import { type DocumentSurface } from '@datalking/begonia-engine';
3
+ import type { HeaderFooterScratchSurface } from '@datalking/begonia-browser-sdk';
4
+ /**
5
+ * Builds the throw-away surface a header or footer is typed into.
6
+ *
7
+ * Why a separate surface at all: the paginated editor's own surface addresses
8
+ * the body story, and a header is a different story (historically a different
9
+ * OOXML part). A position inside a header is not a position in the body
10
+ * document, and the surface's own policy makes a detached side story read-only,
11
+ * so typing into the band through the live surface is rejected on the first
12
+ * keystroke rather than merely misplaced.
13
+ *
14
+ * So the band gets its own small document: a real, editable ProseMirror view
15
+ * holding a copy of the header's blocks. The controller commits that copy back
16
+ * through the document API when the writer leaves the band, and the view dies
17
+ * with the band so the copy and the truth cannot drift apart between sessions.
18
+ */
19
+ export interface HeaderFooterScratchSurfaceHandle {
20
+ surface: HeaderFooterScratchSurface;
21
+ /**
22
+ * The element the scratch view paints into.
23
+ *
24
+ * It starts parked off-screen and is adopted into the open band by
25
+ * `HeaderFooterScratchMount`. Adoption moves the node rather than copying it,
26
+ * so the caret survives the move.
27
+ */
28
+ element: HTMLElement;
29
+ /** The live engine surface, for callers that need its schema or view. */
30
+ runtime: DocumentSurface;
31
+ destroy(): void;
32
+ }
33
+ export interface HeaderFooterParticipant {
34
+ id: string;
35
+ name: string;
36
+ /** Optional, because the surface's own profile type allows it to be. */
37
+ color?: string;
38
+ }
39
+ export declare function createHeaderFooterScratchSurface(participant: HeaderFooterParticipant, blocks: readonly ProseMirrorNode[]): HeaderFooterScratchSurfaceHandle;
40
+ /**
41
+ * One live scratch surface per open band.
42
+ *
43
+ * The element is created imperatively and handed back through the returned
44
+ * handle rather than rendered as JSX: ProseMirror needs a real DOM node at
45
+ * construction time, and attaching one in an effect would leave the first frame
46
+ * without a view.
47
+ */
48
+ export declare function useHeaderFooterScratchSurface(build: (() => HeaderFooterScratchSurfaceHandle | null) | null): import("react").RefObject<HeaderFooterScratchSurfaceHandle | null>;
@@ -2,4 +2,13 @@ import { type DependencyList } from 'react';
2
2
  export interface OwnedDestroyable {
3
3
  destroy(): void;
4
4
  }
5
+ /**
6
+ * Creates a value that owns subscriptions and destroys it when React lets go.
7
+ *
8
+ * Destroying is deferred by one microtask so StrictMode's simulated unmount
9
+ * (which runs the cleanup and then immediately re-runs the same effect with the
10
+ * same memoized value) does not kill a value React still holds. A real unmount,
11
+ * or a dependency change, leaves the destroyed value unclaimed and it is torn
12
+ * down as usual.
13
+ */
5
14
  export declare function useOwnedDestroyable<TValue extends OwnedDestroyable | null>(factory: () => TValue, dependencies: DependencyList): TValue;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * The slice of the document surface that owns history.
3
+ *
4
+ * Narrow on purpose: the hook needs two booleans-returning calls, not the whole
5
+ * controller, so it can be tested with a plain object.
6
+ */
7
+ export interface BrowserHistoryShortcutTarget {
8
+ undo?: () => boolean;
9
+ redo?: () => boolean;
10
+ }
11
+ /**
12
+ * Bind `Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z` and `Cmd/Ctrl+Y` to undo/redo.
13
+ *
14
+ * This lives at the document level rather than only in a ProseMirror keymap
15
+ * because the paginated editor paints its pages and keeps the real editable
16
+ * host off-screen, so the element holding focus is not always the editing DOM.
17
+ * Pressing a painted page does forward focus into that host, and the view
18
+ * keymap answers that case on its own; the document listener is the backstop
19
+ * for the states where it cannot.
20
+ *
21
+ * The listener runs in the capture phase so it is not lost to a handler that
22
+ * stops propagation. It calls `preventDefault` only when the command actually
23
+ * ran, which is what keeps the editor's own keymap from applying the same undo
24
+ * a second time.
25
+ *
26
+ * `ownsFocus` is what makes the binding safe with more than one editor on a
27
+ * page. Every instance listens on the same document, so without it the first
28
+ * one mounted handles every keystroke no matter where the caret is - and since
29
+ * a successful undo calls `preventDefault`, the editor the reader is actually
30
+ * looking at never gets the event. Two editors then undo out of order: the
31
+ * background one reverts and the focused one appears stuck. A host with a single
32
+ * editor can omit the option, in which case every keystroke in the document is
33
+ * claimed - which is what a lone editor wants.
34
+ */
35
+ export declare function useUndoRedoHotkeys({ history, enabled, ownerDocument, ownsFocus, }: {
36
+ history: BrowserHistoryShortcutTarget | null | undefined;
37
+ enabled?: boolean;
38
+ /** Injected in tests; defaults to the global document. */
39
+ ownerDocument?: Document | null;
40
+ /**
41
+ * Whether the keydown should be handled by this instance. Defaults to
42
+ * "always" so a lone editor keeps working without extra wiring.
43
+ */
44
+ ownsFocus?: (event: KeyboardEvent) => boolean;
45
+ }): void;
@@ -7,7 +7,14 @@ interface UseVirtualPagedPreviewStateInput {
7
7
  width?: number | null;
8
8
  scale: number;
9
9
  pageGap: number;
10
- windowPages: number;
10
+ /**
11
+ * Optional cap on how many pages a window may mount.
12
+ *
13
+ * Leaving it unset mounts the visible range plus overscan, which is what a
14
+ * reader expects: the window follows the screen. Set it only when a caller
15
+ * wants a fixed budget independent of how much is visible.
16
+ */
17
+ windowPages?: number | undefined;
11
18
  overscan: number;
12
19
  virtualize: boolean;
13
20
  layoutMode: LayoutRenderMode;
@@ -18,11 +25,14 @@ interface UseVirtualPagedPreviewStateInput {
18
25
  pinnedPageNumbers: readonly number[] | undefined;
19
26
  scrollHost?: HTMLElement | null | undefined;
20
27
  onViewportChange?: ((state: PageViewportMetrics) => void) | undefined;
28
+ /** Whether a pointer drag currently owns preview scrolling. */
29
+ interactionNavigationActive?: boolean | undefined;
21
30
  }
22
- export declare function useVirtualPagedPreviewState({ projection, version, height, width, scale, pageGap, windowPages, overscan, virtualize, layoutMode, flowMode, anchorPageNumber, initialViewportAnchor, viewportRequestKey, pinnedPageNumbers, scrollHost, onViewportChange, }: UseVirtualPagedPreviewStateInput): {
31
+ export declare function useVirtualPagedPreviewState({ projection, version, height, width, scale, pageGap, windowPages, overscan, virtualize, layoutMode, flowMode, anchorPageNumber, initialViewportAnchor, viewportRequestKey, pinnedPageNumbers, scrollHost, onViewportChange, interactionNavigationActive, }: UseVirtualPagedPreviewStateInput): {
23
32
  hostRef: import("react").RefObject<HTMLDivElement | null>;
24
- resolveObservedScrollHost(): VirtualPagedPreviewObservedScrollHost | null;
33
+ resolveObservedScrollHost: () => VirtualPagedPreviewObservedScrollHost | null;
25
34
  deferredProjection: LayoutProjection | null;
26
35
  renderState: import("@datalking/begonia-layout-renderer").PageWindowRendererState;
36
+ setInteractionNavigationActive: (active: boolean) => void;
27
37
  };
28
38
  export {};
@@ -3,10 +3,26 @@ export { DocumentReactMount } from './DocumentReactMount.tsx';
3
3
  export type { DocumentReactMountProps } from './DocumentReactMount.tsx';
4
4
  export { BrowserPaginatedPreview } from './BrowserPaginatedPreview.tsx';
5
5
  export type { BrowserPaginatedPreviewProps } from './BrowserPaginatedPreview.tsx';
6
+ export { BrowserPaginatedEditorSurface } from './BrowserPaginatedEditorSurface.tsx';
7
+ export type { BrowserPaginatedEditorSurfaceProps } from './BrowserPaginatedEditorSurface.tsx';
6
8
  export { BrowserWhiteboardPdfPreview } from './BrowserWhiteboardPdfPreview.tsx';
7
9
  export type { BrowserWhiteboardPdfPreviewProps } from './BrowserWhiteboardPdfPreview.tsx';
8
10
  export { BrowserWhiteboardPreview } from './BrowserWhiteboardPreview.tsx';
9
11
  export type { BrowserWhiteboardPreviewProps } from './BrowserWhiteboardPreview.tsx';
12
+ export { BrowserHeaderFooterBands } from './browser-header-footer-bands.tsx';
13
+ export type { BrowserHeaderFooterBandsProps, HeaderFooterBandSlots, HeaderFooterBandTarget, } from './browser-header-footer-bands.tsx';
14
+ export { createHeaderFooterScratchSurface, useHeaderFooterScratchSurface, } from './use-header-footer-scratch-surface.ts';
15
+ export type { HeaderFooterParticipant, HeaderFooterScratchSurfaceHandle, } from './use-header-footer-scratch-surface.ts';
16
+ export { BrowserHeaderFooterFormatBar } from './browser-header-footer-format-bar.tsx';
17
+ export type { BrowserHeaderFooterFormatBarProps } from './browser-header-footer-format-bar.tsx';
18
+ export { BrowserHeaderFooterControls } from '../browser-header-footer-controls.tsx';
19
+ export type { BrowserHeaderFooterControlsProps } from '../browser-header-footer-controls.tsx';
20
+ export { HeaderFooterScratchMount } from './HeaderFooterScratchMount.tsx';
21
+ export type { HeaderFooterScratchMountProps } from './HeaderFooterScratchMount.tsx';
22
+ export { useBrowserHeaderFooterEditing } from './use-browser-header-footer-editing.ts';
23
+ export type { BrowserHeaderFooterEditing, UseBrowserHeaderFooterEditingOptions, } from './use-browser-header-footer-editing.ts';
10
24
  export { useBrowserEditorController } from './use-browser-editor-controller.ts';
11
25
  export type { UseBrowserEditorControllerOptions, UseBrowserEditorControllerResult, } from './use-browser-editor-controller.ts';
12
26
  export { useBrowserEditorDocument } from './use-browser-editor-document.ts';
27
+ export { useUndoRedoHotkeys } from './use-undo-redo-hotkeys.ts';
28
+ export type { BrowserHistoryShortcutTarget } from './use-undo-redo-hotkeys.ts';
@@ -0,0 +1,33 @@
1
+ import type { InlineRevisionSpan } from '@datalking/begonia-layout-contracts';
2
+ /**
3
+ * How a commented run is tinted on the page.
4
+ *
5
+ * Comments are an annotation layered *behind* the text rather than a property of
6
+ * it, so the tint is a box-shadow instead of a background colour: a run that is
7
+ * both author-highlighted and commented has to keep both meanings, and a
8
+ * background colour would let one silently overwrite the other.
9
+ *
10
+ * Three states, matching what a review surface needs to distinguish:
11
+ *
12
+ * - **open** - a light wash, so a document with many threads stays readable.
13
+ * - **active** - the thread the user is currently reading, in the page as well as
14
+ * in the sidebar. Without this, selecting a thread highlighted only the
15
+ * sidebar entry and the page gave no indication of where the thread sat.
16
+ * - **resolved** - faded right down. The thread still anchors text, so the run
17
+ * must stay findable, but it must not compete with open work.
18
+ *
19
+ * Scope: body-text runs and table-cell runs. A cell carries its spans on
20
+ * `block.tableCells[row][column].inlineSpans`, a different path from the block's
21
+ * own `inlineSpans`, so the renderer reads both.
22
+ */
23
+ export type PreviewCommentHighlightState = 'open' | 'active' | 'resolved';
24
+ /** Resolves the state for a thread, defaulting to open. */
25
+ export type PreviewCommentStateResolver = (commentId: string) => PreviewCommentHighlightState;
26
+ /**
27
+ * Inset shadow that paints the comment wash under the text.
28
+ *
29
+ * Returns `undefined` when the run is not commented, so the caller can leave the
30
+ * property off entirely rather than emitting `boxShadow: undefined` noise into
31
+ * every plain run.
32
+ */
33
+ export declare function resolvePreviewCommentHighlight(span: Pick<InlineRevisionSpan, 'commentIds'> | null | undefined, resolveState?: PreviewCommentStateResolver | null): string | undefined;
@@ -1,2 +1,2 @@
1
- export { createVirtualPagedPreviewDragSession, isVirtualPagedPreviewFrameTarget, VIRTUAL_PAGED_PREVIEW_FRAME_DATA_ATTRIBUTE, } from '@datalking/begonia-layout-renderer';
1
+ export { createVirtualPagedPreviewDragSession, isVirtualPagedPreviewChromeTarget, isVirtualPagedPreviewFrameTarget, VIRTUAL_PAGED_PREVIEW_FRAME_DATA_ATTRIBUTE, } from '@datalking/begonia-layout-renderer';
2
2
  export type { CreateVirtualPagedPreviewDragSessionInput, VirtualPagedPreviewDragSession, VirtualPagedPreviewDragSessionResult, VirtualPagedPreviewMouseLikeEvent, } from '@datalking/begonia-layout-renderer';
@@ -1,2 +1,2 @@
1
- export { resolveVirtualPagedPreviewPositionHit, resolveVirtualPagedPreviewPositionHitInMountedFrames, } from '@datalking/begonia-layout-renderer';
2
- export type { ResolveVirtualPagedPreviewMountedFrameHitInput, ResolveVirtualPagedPreviewPositionHitInput, VirtualPagedPreviewPaginatedHorizontalOrigin, VirtualPagedPreviewPositionHitEvent, VirtualPagedPreviewSelectionAnchor, } from '@datalking/begonia-layout-renderer';
1
+ export { resolveVirtualPagedPreviewPointerHit, resolveVirtualPagedPreviewPositionHit, resolveVirtualPagedPreviewPositionHitInMountedFrames, } from '@datalking/begonia-layout-renderer';
2
+ export type { ResolveVirtualPagedPreviewMountedFrameHitInput, ResolveVirtualPagedPreviewPositionHitInput, VirtualPagedPreviewPaginatedHorizontalOrigin, VirtualPagedPreviewPointerHitRequest, VirtualPagedPreviewPointerHitSource, VirtualPagedPreviewPositionHitEvent, VirtualPagedPreviewSelectionAnchor, } from '@datalking/begonia-layout-renderer';
@@ -0,0 +1,42 @@
1
+ import { type ListMarkerSource } from '@datalking/begonia-layout-contracts';
2
+ import type { PageBlockPlacement } from '@datalking/begonia-page-layout';
3
+ import type { ReactNode } from 'react';
4
+ /**
5
+ * Paints the marker of a list item inside the indent its block reserved.
6
+ *
7
+ * A marker is document data - an ordinal, a nesting level and a `w:numFmt` -
8
+ * so it is drawn from the placement rather than left to a CSS counter. A
9
+ * counter would only know the DOM order of the painted pages, which is not the
10
+ * document order: page two begins mid-list and must not restart at 1, and a
11
+ * fragment continuing from the previous page must repeat no marker at all.
12
+ *
13
+ * The indent is reserved by the layout, not by this component: the estimator
14
+ * adds `listMarkerGutterWidth` to the block's `indentLeft`, so the measured
15
+ * wrap width, the caret geometry and the hit boxes all already account for it.
16
+ * This only places a glyph in space that exists, which is why it cannot change
17
+ * pagination.
18
+ */
19
+ interface ListMarkerGlyphProps {
20
+ block: ListMarkerSource & {
21
+ continuedFromPrevious?: boolean;
22
+ };
23
+ /** Width of the indent reserved for the marker, already scaled. */
24
+ gutterWidth: number;
25
+ fontSize: number;
26
+ color: string;
27
+ }
28
+ export declare function renderListMarkerGlyph({ block, gutterWidth, fontSize, color, }: ListMarkerGlyphProps): ReactNode;
29
+ /**
30
+ * Places the marker of a block, or nothing when the block is not a list item.
31
+ *
32
+ * Only a list block that actually starts on this page prints a marker; a
33
+ * fragment continuing an earlier page prints none, which the glyph component
34
+ * enforces so the two call sites cannot disagree about it.
35
+ */
36
+ interface RenderListMarkerForBlockInput {
37
+ block: PageBlockPlacement;
38
+ /** Surface scale, so a marker sized here matches the painted text. */
39
+ scale: number;
40
+ }
41
+ export declare function renderListMarkerForBlock({ block, scale, }: RenderListMarkerForBlockInput): ReactNode;
42
+ export {};
@@ -1,14 +1,29 @@
1
1
  import { type CSSProperties } from 'react';
2
2
  import { type LayoutProjectionOptions, type RenderableTableCellPlacement, type PageBlockPlacement } from '@datalking/begonia-layout-contracts';
3
+ import { resolvePreviewLeftPx, resolvePreviewTopPx } from '@datalking/begonia-layout-renderer';
4
+ import { type PreviewCommentStateResolver } from '../virtual-paged-preview-comment-highlight.ts';
3
5
  declare function blockFontSize(block: PageBlockPlacement): number;
4
6
  declare function blockTextAlign(block: Pick<PageBlockPlacement, 'align'>): CSSProperties['textAlign'];
5
7
  declare function blockDirection(block: Pick<PageBlockPlacement, 'direction'>): CSSProperties['direction'];
6
- declare function renderBlockText(block: PageBlockPlacement, scale: number, measureText?: LayoutProjectionOptions['measureText'], measurementEpoch?: LayoutProjectionOptions['measurementEpoch']): string | number | bigint | true | import("react").JSX.Element[] | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | Iterable<import("react").ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
7
- declare function renderTableCellContent(block: PageBlockPlacement, cell: RenderableTableCellPlacement, keyPrefix: string, scale: number): string | import("react").JSX.Element[];
8
+ declare function renderBlockText(block: PageBlockPlacement, scale: number, measureText?: LayoutProjectionOptions['measureText'], measurementEpoch?: LayoutProjectionOptions['measurementEpoch'], resolveCommentState?: PreviewCommentStateResolver | null, showFormattingMarks?: boolean, showBookmarks?: boolean): string | number | bigint | true | import("react").JSX.Element[] | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | Iterable<import("react").ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
9
+ declare function renderTableCellContent(block: PageBlockPlacement, cell: RenderableTableCellPlacement, keyPrefix: string, scale: number, resolveCommentState?: PreviewCommentStateResolver | null): string | import("react").JSX.Element[];
10
+ /**
11
+ * Width a table paints at, in CSS pixels.
12
+ *
13
+ * The paginator wrapped this table's cells and reserved its row heights from
14
+ * `tableWidth`, so the painter has to use the same number. Letting the table
15
+ * fill its column instead stretched every column past what the layout
16
+ * measured, and the caret and selection boxes - which are derived from that
17
+ * measurement - then sat left of the glyphs they belonged to.
18
+ *
19
+ * Falls back to `undefined` (the browser's own sizing) when the placement does
20
+ * not declare a width, so tables that never carried one keep painting as
21
+ * before.
22
+ */
23
+ export declare function paintedTableWidth(block: PageBlockPlacement, scale: number): number | undefined;
8
24
  declare function tableColumnStyles(block: PageBlockPlacement): import("react").JSX.Element[] | null;
9
- declare function resolvePreviewTopPx(top: number, contentTop: number, scale: number): number;
10
- declare function resolvePreviewLeftPx(left: number, contentLeft: number, scale: number): number;
11
25
  declare function baseBlockStyle(block: PageBlockPlacement, scale: number, contentTop?: number, contentLeft?: number): {
26
+ boxSizing: 'border-box';
12
27
  position: 'absolute';
13
28
  top: number;
14
29
  left: number;
@@ -17,10 +32,10 @@ declare function baseBlockStyle(block: PageBlockPlacement, scale: number, conten
17
32
  paddingBottom: number;
18
33
  fontSize: number;
19
34
  lineHeight: string;
20
- fontFamily: "\"Times New Roman\", serif";
35
+ fontFamily: "var(--ald-font-doc, \"Aptos\", Calibri, \"Segoe UI\", sans-serif)";
21
36
  whiteSpace: 'pre-wrap';
22
37
  wordBreak: 'break-word';
23
- color: "#1f2937" | "#2f2417";
38
+ color: "var(--ald-doc-heading, #000000)" | "var(--ald-doc-text, #000000)";
24
39
  fontWeight: number;
25
40
  textAlign: import("csstype").Property.TextAlign | undefined;
26
41
  direction: import("csstype").Property.Direction | undefined;
@@ -1,17 +1,33 @@
1
1
  import { type ReactNode } from 'react';
2
- import { type LayoutProjectionOptions } from '@datalking/begonia-layout-contracts';
2
+ import { type LayoutProjection, type LayoutProjectionOptions } from '@datalking/begonia-layout-contracts';
3
3
  import { type LayoutFlowMode, type VirtualPageFrame } from '@datalking/begonia-layout-renderer';
4
+ import type { PreviewCommentStateResolver } from '../virtual-paged-preview-comment-highlight.ts';
4
5
  import type { VirtualPagedPreviewPositionHitEvent } from '../virtual-paged-preview-interaction.ts';
5
6
  interface VirtualPageFrameViewProps {
6
7
  frame: VirtualPageFrame;
8
+ /**
9
+ * The projection this frame was painted from.
10
+ *
11
+ * A table that crosses a page boundary paints several fragments sharing one
12
+ * `block.from`, so a fragment cannot know where its own text begins without
13
+ * the layout's sealed ranges. Passing the projection lets each row carry the
14
+ * offset the layout assigned it instead of an offset re-derived from the
15
+ * fragment's own rows.
16
+ */
17
+ projection?: LayoutProjection | null;
7
18
  scale: number;
8
19
  measureText?: LayoutProjectionOptions['measureText'];
9
20
  measurementEpoch?: LayoutProjectionOptions['measurementEpoch'];
21
+ resolveCommentState?: PreviewCommentStateResolver | null;
10
22
  offsetTop?: number;
11
23
  offsetLeft?: number;
12
24
  flowMode?: LayoutFlowMode;
13
25
  renderPageOverlay?: (frame: VirtualPageFrame, scale: number) => ReactNode;
14
26
  onProjectionPositionHit?: (event: VirtualPagedPreviewPositionHitEvent) => boolean | void;
27
+ /** Draw non-printing marks. Decoration only; never affects layout. */
28
+ showFormattingMarks?: boolean;
29
+ /** Draw bookmark markers. Decoration only; never affects layout. */
30
+ showBookmarks?: boolean;
15
31
  }
16
- export declare function VirtualPageFrameView({ frame, scale, measureText, measurementEpoch, offsetTop, offsetLeft, flowMode, renderPageOverlay, onProjectionPositionHit, }: VirtualPageFrameViewProps): import("react").JSX.Element;
32
+ export declare function VirtualPageFrameView({ frame, projection, scale, measureText, measurementEpoch, resolveCommentState, offsetTop, offsetLeft, flowMode, renderPageOverlay, onProjectionPositionHit, showFormattingMarks, showBookmarks, }: VirtualPageFrameViewProps): import("react").JSX.Element;
17
33
  export {};
@@ -0,0 +1,78 @@
1
+ import type { InlineRevisionSpan } from '@datalking/begonia-layout-contracts';
2
+ /**
3
+ * Data attributes the review hit-testers read on painted inline pieces.
4
+ *
5
+ * The names are a cross-package contract: `browser-sdk`'s point review target
6
+ * resolves a right-click or a hover into a comment thread / tracked change by
7
+ * reading these off the clicked element and walking up to the surface. Nothing
8
+ * emitted them, so an overlapping tracked change or an anchored comment could
9
+ * never be hit by pointer - only by asking the document model.
10
+ */
11
+ export declare const PREVIEW_COMMENT_IDS_ATTRIBUTE = "data-comment-ids";
12
+ export declare const PREVIEW_TRACK_CHANGE_IDS_ATTRIBUTE = "data-track-change-ids";
13
+ /**
14
+ * The one change id a pointer click on this piece should resolve to.
15
+ *
16
+ * A painted character inside an overlapping tracked change belongs to two
17
+ * revisions at once: the insertion that put the text there and the deletion
18
+ * that took it back out. `data-track-change-ids` lists both, and the hit-tester
19
+ * tries them in order, so without this the click lands on whichever revision
20
+ * happens to be painted first. The reviewer is pointing at the inner edit - the
21
+ * deletion - because that is the one they can still act on, so the child wins.
22
+ *
23
+ * The reader side of this contract lives in
24
+ * `browser-editor-point-review-target.ts`, which reorders the list so the
25
+ * preferred id leads.
26
+ */
27
+ export declare const PREVIEW_TRACK_CHANGE_PREFERRED_ATTRIBUTE = "data-track-change-preferred-target-id";
28
+ type SpanLike = Pick<InlineRevisionSpan, 'changeId' | 'revisionKind' | 'revisionLayers'> | null | undefined;
29
+ type CommentSpanLike = Pick<InlineRevisionSpan, 'commentIds'> | null | undefined;
30
+ /**
31
+ * Every change id this span carries, outermost first.
32
+ *
33
+ * Overlapping revisions stack: one painted character can belong to a parent
34
+ * insertion and a child format change at once. The hit-tester wants the whole
35
+ * set, not just the layer that wins the paint, so all layers are collected.
36
+ */
37
+ export declare function resolvePreviewTrackChangeIds(span: SpanLike): string[];
38
+ /**
39
+ * The change a click on this span should resolve to, when the span is an
40
+ * overlapping pair.
41
+ *
42
+ * A deletion that sits inside an insertion carries that insertion as its
43
+ * overlap parent. The deletion is the later edit and the only one the reviewer
44
+ * can still decide on - accepting the insertion alone would leave the deleted
45
+ * text standing. So the child is preferred, and it must be a revision the span
46
+ * actually carries, otherwise the hit-tester reorders to an id it can never
47
+ * resolve and the click falls through to nothing.
48
+ *
49
+ * Returns null for a span with no overlap, which is the common case: the
50
+ * attribute is then omitted and the reader keeps its normal ordering.
51
+ */
52
+ export declare function resolvePreviewTrackChangePreferredTargetId(span: SpanLike): string | null;
53
+ /**
54
+ * Comment thread ids carried by a span, outermost first.
55
+ *
56
+ * Empty means the run is not commented, which is the common case: the renderer
57
+ * uses this to decide whether to paint a highlight at all.
58
+ */
59
+ export declare function resolvePreviewCommentIds(span: CommentSpanLike): string[];
60
+ /**
61
+ * Comment ids that survive the attribute encoding.
62
+ *
63
+ * The highlight and the attribute have to agree on this set. When every id of
64
+ * a run is unencodable the attribute is omitted, and a run that was still
65
+ * tinted would paint a wash the hit-tester can never resolve - visible review
66
+ * work the reader cannot click. Callers pass these ids to both.
67
+ */
68
+ export declare function resolveEncodableCommentIds(span: CommentSpanLike): string[];
69
+ /**
70
+ * Attributes to spread onto a painted inline piece.
71
+ *
72
+ * Returns an empty object when the piece carries no review data, so callers can
73
+ * spread unconditionally and React omits the attributes instead of rendering
74
+ * `data-track-change-ids=""` (which reads as an empty id list at hit-test
75
+ * time rather than as "no ids").
76
+ */
77
+ export declare function resolvePreviewReviewAttributes(span: SpanLike & CommentSpanLike): Record<string, string>;
78
+ export {};
@@ -5,6 +5,10 @@ interface RenderMeasuredTextLinesInput {
5
5
  scale: number;
6
6
  measureText?: LayoutProjectionOptions['measureText'];
7
7
  measurementEpoch?: LayoutProjectionOptions['measurementEpoch'];
8
+ /** Draw non-printing marks. Decoration only; never affects layout. */
9
+ showFormattingMarks?: boolean;
10
+ /** Draw bookmark markers. Decoration only; never affects layout. */
11
+ showBookmarks?: boolean;
8
12
  inlineSpanStyle: (block: PageBlockPlacement, span: NonNullable<PageBlockPlacement['inlineSpans']>[number], scale: number) => CSSProperties;
9
13
  interactiveInlineNodeSpanProps: (span: NonNullable<PageBlockPlacement['inlineSpans']>[number], fromOffset: number, toOffset: number, cell?: {
10
14
  originRow: number | null | undefined;