@docx-editor.dev/core 2.14.1 → 2.15.0

package/dist/semantic-interaction-DUAnxbgf.d.cts

@@ -1,160 +0,0 @@
-import { T as TextMeasurer, S as SemanticLayout, B as BlockFragmentRecord, C as ContentControlBoundaryRecord, a as StyleSpanRecord } from './semantic-records-BpozY7-j.cjs';
-
-/** A caret position in the model. */
-interface SemanticPosition {
-    readonly paragraphId: string;
-    readonly offset: number;
-}
-/** A caret position with the geometry that renders it. */
-interface CaretGeometry {
-    readonly position: SemanticPosition;
-    /** Page-relative, in the same coordinate space as the line boxes. */
-    readonly x: number;
-    readonly y: number;
-    readonly height: number;
-    readonly lineId: string;
-    readonly pageIndex: number;
-}
-/**
- * A selection as two semantic positions — never as DOM nodes.
- *
- * `anchor` is where the selection started and `head` is where it currently ends, so `head` before
- * `anchor` is an ordinary backwards selection rather than an error. Collapsed when the two are
- * equal, which is what a caret is.
- */
-interface SemanticSelection {
-    readonly anchor: SemanticPosition;
-    readonly head: SemanticPosition;
-}
-/** One painted selection rectangle, in page-relative layout points. */
-interface SelectionRect {
-    readonly pageIndex: number;
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-declare function caretStops(layout: SemanticLayout, measurer?: TextMeasurer): CaretGeometry[];
-/**
- * Caret stops for one story's block fragments (header/footer), in reading order.
- *
- * Coordinates stay story-relative — the same space `hitTestFragments` and furniture paint
- * use — so arrow motion follows tab-stop geometry and projected field atoms without mixing
- * body sheet offsets.
- */
-declare function caretStopsForBlocks(layout: SemanticLayout, pageIndex: number, fragments: readonly BlockFragmentRecord[], measurer?: TextMeasurer): CaretGeometry[];
-/**
- * How caret geometry is resolved.
- *
- * `preferPage` disambiguates a paragraph that paints on SEVERAL pages — a shared header appears
- * once per page, and without a preference the caret could be placed on any of its copies.
- */
-interface CaretAtOptions {
-    readonly measurer?: TextMeasurer;
-    /**
-     * Prefer geometry from this sheet when the same paragraph paints on multiple pages
-     * (shared header/footer copies).
-     */
-    readonly preferredPageIndex?: number;
-}
-/** Geometry for one model position, or null when it is not laid out. */
-declare function caretAt(layout: SemanticLayout, position: SemanticPosition, measurerOrOptions?: TextMeasurer | CaretAtOptions): CaretGeometry | null;
-/**
- * The caret position nearest a point, in PAGE-CONTENT coordinates.
- *
- * Never returns null for a point inside the document: a click in the margin, past the end of
- * a line, or below the last line still has an obvious intended caret, and refusing to answer
- * would make those clicks do nothing.
- *
- * The rules live in `semantic-hit-test.ts`, which answers with the cell address and the
- * on-glyphs flag a pointer controller needs too; this keeps the geometry-only shape for
- * callers that want nothing else.
- */
-declare function hitTestSemantic(layout: SemanticLayout, point: {
-    readonly x: number;
-    readonly y: number;
-    readonly pageIndex?: number;
-}): CaretGeometry | null;
-/**
- * Innermost content-control boundary at a page-content point, or null outside every control.
- *
- * Prefers the deepest nesting depth when nested boundaries share geometry.
- */
-declare function contentControlAtSemantic(layout: SemanticLayout, point: {
-    readonly x: number;
-    readonly y: number;
-    readonly pageIndex?: number;
-}): ContentControlBoundaryRecord | null;
-/** Layout-published content-control boundaries in document order. */
-declare function contentControlsInLayout(layout: SemanticLayout): readonly ContentControlBoundaryRecord[];
-/**
- * One caret movement, in Word's own vocabulary.
- *
- * Visual rather than logical where the two differ: `left` means left on screen, which in
- * right-to-left text is forward through the string.
- */
-type NavigationCommand = 'left' | 'right' | 'up' | 'down' | 'wordLeft' | 'wordRight' | 'lineStart' | 'lineEnd' | 'documentStart' | 'documentEnd' | 'pageUp' | 'pageDown';
-/**
- * The text of one paragraph, read back from the layout records.
- *
- * Word boundaries need characters, and the records carry them: every span holds the text it
- * was laid out from, keyed by the source range it covers. Reading them back keeps word
- * motion in the interaction lane instead of making it a second consumer of the model.
- */
-declare function paragraphTextFromLayout(layout: SemanticLayout, paragraphId: string): string;
-/**
- * Paragraph offsets a WORD may not run through: the edges of every struck half on screen.
- *
- * Deleted text is the one thing a view paints that does not exist in the document the reader
- * is heading towards — it is the OTHER version, spliced in beside the proposal so the two can
- * be compared. Its characters are therefore not adjacent to their neighbours in any single
- * version, however adjacent they look.
- *
- * A replacement is where that stops being pedantic. Word writes one as a deletion immediately
- * followed by an insertion, with no separator between them, so `ALL CAPS` struck and `fsdfsd`
- * added read as the single word `CAPSfsdfsd`: a double-click on the old text selected the new
- * text with it, across a decision the reader had not taken. Feeding these to `wordBoundary`
- * makes each half its own word.
- *
- * Only the halves this view actually renders contribute. `proposed` paints no deletion, so it
- * has no seams and this answers empty — which is also why the walk reads the LAYOUT rather
- * than the tree.
- */
-declare function deletedTextBoundaries(layout: SemanticLayout, paragraphId: string): ReadonlySet<number>;
-/** Story-scoped stops are required when navigating inside an open header or footer. */
-interface MoveCaretOptions {
-    /** Precomputed active-story stops; body navigation keeps the indexed default. */
-    readonly stops?: readonly CaretGeometry[];
-    readonly measurer?: TextMeasurer;
-}
-/** Move a caret; vertical movement carries a desired X through shorter lines. */
-declare function moveCaret(layout: SemanticLayout, position: SemanticPosition, command: NavigationCommand, desiredX?: number | null, options?: MoveCaretOptions): {
-    position: SemanticPosition;
-    desiredX: number | null;
-} | null;
-/**
- * The anchor an IME composition is attached to.
- *
- * Composition needs a position that survives the intermediate transactions it produces, so
- * it is expressed in model coordinates and re-resolved against each new layout rather than
- * cached as geometry.
- */
-declare function compositionAnchor(layout: SemanticLayout, position: SemanticPosition, 
-/** For an exact mid-span x (layout publishes no eager caret edges; see caretAt). */
-measurer?: TextMeasurer): CaretGeometry | null;
-/** The style spans a selection touches, for reporting active formatting. */
-declare function spansInSelection(layout: SemanticLayout, selection: SemanticSelection, 
-/**
- * Reading order of the ACTIVE story. See {@link orderPositions}.
- *
- * REQUIRED. A default here can only be one story's order, and whichever one it is will be
- * wrong for every caret in another — which is exactly how this read came to answer about the
- * body while the caret sat in a header. Requiring it is what makes the compiler find a call
- * site that forgot, and it already found one.
- *
- * A caller with no story in hand passes {@link everyStoryOrder}, which covers all of them: a
- * selection cannot span two stories, so only the order WITHIN one is ever compared.
- */
-order: readonly string[]): StyleSpanRecord[];
-
-export { type CaretGeometry as C, type MoveCaretOptions as M, type NavigationCommand as N, type SemanticPosition as S, type SemanticSelection as a, type SelectionRect as b, type CaretAtOptions as c, caretAt as d, caretStops as e, caretStopsForBlocks as f, compositionAnchor as g, contentControlAtSemantic as h, contentControlsInLayout as i, deletedTextBoundaries as j, hitTestSemantic as k, moveCaret as m, paragraphTextFromLayout as p, spansInSelection as s };

package/dist/semantic-paint-DufNL1Zr.d.cts

@@ -1,247 +0,0 @@
-import { C as ContentControlBoundaryRecord, S as SemanticLayout } from './semantic-records-BpozY7-j.cjs';
-import { V as ValidatedImageBytesHandle, t as RenderableImageMime } from './tree-op-types-BUulYD5y.cjs';
-
-/**
- * Everything a host can say about ONE author's presentation. Every field is optional and
- * every field is presentation-only — nothing here is ever serialised into the document.
- *
- * Deliberately about the PAINTED DOCUMENT (which only the painter can style) plus the
- * author's identity data. Review-card DESIGN is not configured here: the review chrome
- * follows `color` as its accent automatically, and everything further is composition —
- * a custom card reading this style through the review surface's `useReviewAuthor`, or
- * CSS on the cards' `data-review-author`/`data-review-author-slot` hooks.
- *
- * @public
- */
-interface RevisionAuthorStyle {
-    /**
-     * Ink and decoration colour of this author's changes in the document — and the accent
-     * the review chrome keys on (avatar disc, card variable, marker).
-     */
-    color?: string;
-    /** Background wash behind this author's changes in the document. */
-    background?: string;
-    /**
-     * Class names added to every painted span of this author's changes, for styling the
-     * typed fields do not cover. Keep the rules metric-safe (outlines, shadows, accents):
-     * the engine measures the text it paints, and a class that resizes glyphs drifts the
-     * page from its layout.
-     */
-    spanClassName?: string;
-    /** Avatar image for this author; the packaged card renders it in place of initials. */
-    avatarUrl?: string;
-}
-/**
- * Per-author style assignments.
- *
- * Keys match `w:author` exactly; a value is a CSS colour or a full
- * {@link RevisionAuthorStyle}. `others` says what authors WITHOUT an entry take: the
- * `--doc-review-author-N` ramp by default, or `'kind'` to leave them on the kind colours —
- * which is how "highlight these reviewers, leave everyone else green and red" is said.
- *
- * @public
- */
-interface RevisionAuthorAssignments {
-    /** Authors without an entry: the ramp (default), or the `'kind'` colours. */
-    readonly others?: 'kind' | 'author';
-    readonly authors: Readonly<Record<string, string | RevisionAuthorStyle>>;
-}
-/**
- * How painted tracked changes are coloured.
- *
- * - `'author'` (the DEFAULT) — every change takes its author's colour from the
- *   `--doc-review-author-N` ramp. An attached document seeds slots by order of first
- *   appearance, then keeps those assignments stable for that session. Word's own default,
- *   and the reason it is this engine's: a paragraph three people edited has to read as three
- *   people. Restyle a slot under `.docx-editor` to change the ramp.
- * - `'kind'` — insertions and deletions take the two kind colours
- *   (`--doc-revision-insertion` / `--doc-revision-deletion`), so "added" and "removed" are
- *   what a reader tells apart at a glance, whoever proposed them.
- * - {@link RevisionAuthorAssignments} — style the named authors; `others` decides whether
- *   the rest take the ramp (the default) or the kind colours.
- *
- * Presentation only: nothing here is ever serialised into the document.
- *
- * @public
- */
-type RevisionStyles = 'kind' | 'author' | RevisionAuthorAssignments;
-/**
- * One document author, resolved: who, which ramp slot, and what they draw in.
- *
- * @public
- */
-interface ReviewAuthorInfo {
-    /** The `w:author` string, exactly as the file carries it. */
-    readonly author: string;
-    /**
-     * Stable session rank, seeded by order of first appearance — an UNBOUNDED index.
-     *
-     * The ramp defines {@link REVIEW_AUTHOR_SLOTS} colours and every DOM hook wraps into it,
-     * so the ninth author ranks 8 here and carries `data-review-author-slot="0"`. Building a
-     * selector from this value needs the same wrap: `slot % 8`.
-     */
-    readonly slot: number;
-    /**
-     * The colour this author is DRAWN IN by the review chrome — their declared colour, or
-     * their ramp slot's token.
-     *
-     * Not necessarily what the document paints. `'kind'`, and `others: 'kind'` for an author
-     * with no declaration, colour the painted text by insertion/deletion instead, while the
-     * cards keep the per-author accent this reports.
-     */
-    readonly color: string;
-    /** The host-supplied style, normalised; absent when the author rides the ramp. */
-    readonly style?: RevisionAuthorStyle;
-}
-
-/** Host port for safe blob URLs — only called for {@link ImageResourceState.kind} `ready`. */
-interface PaintImageUrlPort {
-    create(handle: ValidatedImageBytesHandle, mime: RenderableImageMime): string;
-    revoke(url: string): void;
-}
-/** Localized refusal labels; adapters supply i18n-backed implementations. */
-interface DrawingPaintStrings {
-    readonly unsupportedFormat: (format: string) => string;
-    readonly nonPictureGraphic: (kind: string) => string;
-    readonly missingResource: string;
-    readonly externalResource: string;
-    readonly invalidResource: string;
-    readonly contentMismatch: string;
-    readonly decodeFailed: string;
-    readonly resourceLimit: string;
-    readonly pendingResource: string;
-}
-
-/**
- * When a field's result is drawn on its grey block, following Word's own View option.
- *
- * `when-selected` is Word's default and the reason the option exists at all: a document dense
- * with cross-references turns largely grey under `always`, and under `never` a reader cannot
- * tell computed text from typed text at all.
- */
-type FieldShadingMode = 'never' | 'when-selected' | 'always';
-/** Word's default: shaded only while the caret is inside the field. */
-declare const DEFAULT_FIELD_SHADING: FieldShadingMode;
-/**
- * How a layout is painted into DOM. Every field is optional.
- *
- * The painted pages ARE the editable surface, so everything here is presentation-only — nothing
- * set through these options is ever serialised back into the document.
- */
-interface PaintOptions {
-    /** Points to CSS pixels. 96/72 renders a point as a CSS point at 100% zoom. */
-    readonly scale?: number;
-    /** Generated paragraphs that paint as non-editable navigation surfaces. */
-    readonly readOnlyParagraphIds?: ReadonlySet<string>;
-    /**
-     * Empty-TOC begin paragraphs that paint subtle identifiable furniture. Paint-only — never
-     * serialised into the document.
-     */
-    readonly emptyTocPlaceholderIds?: ReadonlySet<string>;
-    /** Marks painted pages as presentational, so assistive tech reads the editable projection. */
-    readonly ariaHidden?: boolean;
-    /**
-     * Page indices to build in detail (task 9.4).
-     *
-     * Omitted means all of them. A page left out keeps its size and position but no content,
-     * so the document's height and page count are unchanged and scrolling to it reveals it
-     * instead of reflowing everything underneath.
-     */
-    readonly materialize?: ReadonlySet<number>;
-    /**
-     * Family-alias lookup for fonts the host registered on behalf of THIS document (see
-     * {@link PaintContext.fontAlias}). Painted runs emit the alias ahead of the declared
-     * family, so a file can never shadow a family name the host page uses.
-     */
-    readonly fontAlias?: (family: string) => string | undefined;
-    /** See {@link PaintContext.defaultFontFamily}. */
-    readonly defaultFontFamily?: string;
-    /** See {@link PaintContext.fieldShading}. */
-    readonly fieldShading?: FieldShadingMode;
-    /** See {@link PaintContext.shadeFormFields}. */
-    readonly shadeFormFields?: boolean;
-    /**
-     * How tracked changes are coloured: by AUTHOR through the `--doc-review-author-N`
-     * ramp (the default, as in Word), by kind, or by author with host-pinned colours.
-     * See {@link RevisionStyles}.
-     */
-    readonly revisionStyles?: RevisionStyles;
-    /**
-     * Relationship id of the header/footer story currently open for editing.
-     *
-     * When set, the matching `[data-docx-hf]` container is editable and every body
-     * `.docx-page-content` box is inert; all other furniture stays read-only.
-     *
-     * Deliberately OUTSIDE the paint-reuse key: entering a header must not rebuild
-     * body sheets. Chrome is applied to already-painted nodes in place, the way TOC
-     * hover is.
-     */
-    readonly activeHeaderFooterRId?: string;
-    /**
-     * Sheet that hosts the active visual occurrence of a shared furniture part.
-     *
-     * Required with {@link activeHeaderFooterRId} so only one painted copy receives
-     * `data-docx-hf-active` / the engine caret when the same rId appears on many pages.
-     * Also outside the paint-reuse key — moving the caret across shared copies retints
-     * markers in place rather than replacing every page.
-     */
-    readonly activeHeaderFooterPageIndex?: number;
-    /**
-     * On-demand content-control boundary chrome (show-all and/or caret-entry).
-     *
-     * Furniture only — never contributes layout records or changes page geometry. Omitted or
-     * empty means no control chrome is painted. Folded into the paint-reuse key so a toggle
-     * rebuilds furniture without a layout pass.
-     */
-    readonly contentControlChrome?: {
-        readonly showAll?: boolean;
-        /** Control ids whose boundaries are visible because the caret is inside them. */
-        readonly activeIds?: ReadonlySet<string>;
-        /**
-         * Control ids whose boundaries are visible because the pointer is over them.
-         * Used for TOC hover chrome without projecting a persistent caret-active state.
-         *
-         * Deliberately OUTSIDE the paint-reuse key: hover must never rebuild a page. The
-         * surface toggles `data-hover` / `data-boundary-visible` on the painted chrome it
-         * already has, and this set only tells a page that rebuilds for some OTHER reason
-         * which of its controls is currently under the pointer.
-         */
-        readonly hoverIds?: ReadonlySet<string>;
-        /**
-         * Control ids whose boundary furniture is painted by something else.
-         *
-         * An empty TOC paints its own placeholder box on the begin paragraph, so drawing the
-         * control boundary as well left two rounded rectangles (of different heights) plus a
-         * label chip stacked over one empty region.
-         */
-        readonly suppressedIds?: ReadonlySet<string>;
-        /** Checkbox control ids whose canonical `w14:checked` state is on. */
-        readonly checkedIds?: ReadonlySet<string>;
-        /** Non-SDT structured regions that intentionally reuse content-control chrome. */
-        readonly additionalBoundaries?: readonly ContentControlBoundaryRecord[];
-        /** Control ids that represent TOC regions (hover-only chrome; never caret-sticky). */
-        readonly tocControlIds?: ReadonlySet<string>;
-        /**
-         * No control may be written right now — viewing mode, or a protected document.
-         *
-         * The widget is a `<button>` the ENGINE paints, and a click on it commits a tree op, so
-         * an enabled-looking checkbox on a read-only document is not a cosmetic lie: it is the
-         * write itself. Disabling it here also stops the pointer lane, which already skips a
-         * widget carrying `data-disabled-reason`.
-         */
-        readonly readOnly?: boolean;
-    };
-    readonly drawingStrings?: DrawingPaintStrings;
-    readonly imageUrlPort?: PaintImageUrlPort;
-}
-
-/**
- * Paint a whole layout into a container, reusing the pages that did not change.
- *
- * The DOM is built with `createElement` and `textContent` only — no file-derived string is
- * ever parsed as markup — and stray children (nothing this module painted) are removed, so
- * the container's content is always exactly the painted pages.
- */
-declare function paintSemanticLayout(container: HTMLElement, layout: SemanticLayout, options?: PaintOptions): void;
-
-export { DEFAULT_FIELD_SHADING as D, type FieldShadingMode as F, type PaintOptions as P, type ReviewAuthorInfo as R, type RevisionAuthorAssignments as a, type RevisionAuthorStyle as b, type RevisionStyles as c, type DrawingPaintStrings as d, paintSemanticLayout as p };