@sobree/core 0.1.1 → 0.1.2

package/dist/doc/types.d.ts

@@ -30,6 +30,15 @@ export interface SobreeDocument {
      * emits each body to its own OOXML part at export time.
      */
     headerFooterBodies: Record<string, Block[]>;
+    /**
+     * Floating objects that live inside a header/footer part, keyed by the
+     * SAME `HeaderFooterRef.partId` as `headerFooterBodies`. A header part
+     * is a self-contained sub-document: its flow blocks live in
+     * `headerFooterBodies[partId]`, its anchored frames here. The renderer
+     * paints these into a per-zone overlay exactly like body `anchoredFrames`.
+     * Empty/absent for the common header-without-floats case.
+     */
+    headerFooterFrames?: Record<string, AnchoredFrame[]>;
     /** Named styles (Heading1, Quote, Body Text, …) defined at the doc level. */
     styles: NamedStyle[];
     /** List/numbering definitions referenced by `Paragraph.properties.numbering`. */
@@ -271,6 +280,31 @@ export interface SectionBreak {
  * **Status**: type declared (Phase 1.0). Importer does not yet emit
  * this; renderer treats it as a no-op. Wiring lands in Phase 1.1-1.2.
  */
+/** One textbox shape inside an inline-frame group: its intra-group
+ *  position + size and recursive body, plus optional chrome (fill /
+ *  border / text insets) and vertical text anchor. */
+export interface InlineFrameTextbox {
+    offsetEmu: {
+        xEmu: number;
+        yEmu: number;
+    };
+    sizeEmu: {
+        wEmu: number;
+        hEmu: number;
+    };
+    body: Block[];
+    fill?: string;
+    border?: FrameBorder;
+    /** `<wps:bodyPr>` text insets (lIns/tIns/rIns/bIns) → CSS padding. */
+    padding?: {
+        topEmu: number;
+        rightEmu: number;
+        bottomEmu: number;
+        leftEmu: number;
+    };
+    /** Vertical text anchor from `<wps:bodyPr anchor>`; defaults to "top". */
+    vAlign?: "top" | "center" | "bottom";
+}
 export interface InlineFrame {
     kind: "inline_frame";
     /** From the containing `<w:p>`'s `<w:pPr>`. The paginator emits a
@@ -304,36 +338,12 @@ export interface InlineFrame {
         wEmu: number;
         hEmu: number;
     };
-    /** The textbox SHAPE's intra-group position + size + body. The
-     *  renderer places `body` at the EXACT coordinates the author
-     *  intended. Optional because some drawings have only pictures /
-     *  shapes (no textbox content). */
-    textbox?: {
-        offsetEmu: {
-            xEmu: number;
-            yEmu: number;
-        };
-        sizeEmu: {
-            wEmu: number;
-            hEmu: number;
-        };
-        body: Block[];
-        fill?: string;
-        border?: FrameBorder;
-        /** `<wps:bodyPr>` text insets (lIns/tIns/rIns/bIns). The renderer
-         *  paints these as the region's CSS padding. */
-        padding?: {
-            topEmu: number;
-            rightEmu: number;
-            bottomEmu: number;
-            leftEmu: number;
-        };
-        /** Vertical text anchor from `<wps:bodyPr anchor>`. Word centers a
-         *  single heading line by sizing a short textbox and centering its
-         *  text; this carries that intent into the renderer's flex column.
-         *  Defaults to "top" when the attribute is absent. */
-        vAlign?: "top" | "center" | "bottom";
-    };
+    /** The group's textbox SHAPES, in document (child) order. Most groups
+     *  have one (a section "pill" heading: a centred line over a background
+     *  picture), but a "Project: X" entry has two — a title textbox and a
+     *  details textbox — and the renderer must show BOTH. Empty when the
+     *  group carries only pictures / shapes (no textbox content). */
+    textboxes: InlineFrameTextbox[];
     /** Decorative pictures inside the group. Each carries its own
      *  intra-group position. The renderer paints them as
      *  absolute-positioned `<img>` children of the frame wrapper,

package/dist/docx/shared/units.d.ts

@@ -28,8 +28,9 @@ export declare const twipsToPt: (t: number) => number;
 /** pt → twips. */
 export declare const ptToTwips: (pt: number) => number;
 /**
- * `w:line` for line spacing in "auto" mode: 240 twips = single-spacing.
- * So `line-height: 1.5` → `240 * 1.5 = 360`.
+ * `w:line` value (in "auto" line-rule mode) for single line spacing.
+ * Word treats 240 as 1.0×, so `line-height: 1.5` → `240 * 1.5 = 360`.
  */
+export declare const SINGLE_SPACING_LINE = 240;
 export declare const lineHeightToOoxml: (lineHeight: number) => number;
 export declare const ooxmlLineHeightToCss: (line: number) => number;

package/dist/docx/shared/xml.d.ts

@@ -17,6 +17,18 @@ export declare function wChildren(parent: Element, localName: string): Element[]
  * serialised documents differ.
  */
 export declare function wVal(el: Element | null): string | null;
+/**
+ * Read an OOXML on/off toggle property (`CT_OnOff`: `<w:pageBreakBefore>`,
+ * `<w:b>`, `<w:keepNext>`, …). Absent → false. Present with no `w:val` →
+ * true (a bare element means "on"). Present with `w:val` →
+ * "false"/"0"/"off" mean OFF; anything else ON.
+ *
+ * Reading these by mere presence is a classic OOXML bug: Word writes the
+ * explicit-off form (`<w:pageBreakBefore w:val="0"/>`) in DocDefaults and
+ * styles, so presence-only flips the property ON for every consumer — e.g.
+ * a page break before every paragraph.
+ */
+export declare function wOnOff(root: Document | Element, localName: string): boolean;
 /** Build an XML declaration header + root element. Used by the exporter. */
 export declare function xmlDocument(rootXml: string): string;
 /**

package/dist/editor/commands.d.ts

@@ -0,0 +1,14 @@
+import { CommandBus, CommandDefinition, CommandSnapshot } from './types';
+/**
+ * Default {@link CommandBus} implementation. Plain in-memory map; no
+ * editor coupling beyond the closure plugins use when registering.
+ * Replacing it would mean swapping a field on Editor — the rest of
+ * the surface stays the same.
+ */
+export declare class EditorCommands implements CommandBus {
+    private readonly commands;
+    register<Args = void>(def: CommandDefinition<Args>): () => void;
+    execute<Args = void>(name: string, args?: Args): void;
+    list(): CommandSnapshot[];
+    has(name: string): boolean;
+}

package/dist/editor/context.d.ts

@@ -0,0 +1,71 @@
+import { BlobCache, BlobStore } from '../blob';
+import { Range as ApiRange, BlockRef, EditResult } from '../doc/api';
+import { SobreeDocument } from '../doc/types';
+import { FontFaceRegistry } from '../fonts';
+import { History } from '../history';
+import { BlockRegistry } from './internal/blockRegistry';
+import { Mutation } from './internal/mutations';
+import { EditorSelection } from './selection';
+import { TrackChangesState } from './types';
+import type * as Y from "yjs";
+/**
+ * The kernel seam between the `Editor` (which owns mutable state, the
+ * `commit()` transaction pipeline, DOM-listener wiring, and Y.Doc
+ * mirroring) and the behaviour modules (`ops/*`, `query`) that implement
+ * each editing concern as free functions over this context.
+ *
+ * The `Editor` builds one `EditorContext` once in its constructor,
+ * closing over its own privates — so `commit` / `checkRefs` / `ensureCurrent`
+ * stay private to the class while the behaviour modules get exactly the
+ * surface they need and nothing more. This is the state/behaviour split
+ * that lets the central editor decompose without Host-seam slicing
+ * (which would have to expose nearly everything).
+ *
+ * Members are named to match the `Editor`'s own field/method names so a
+ * behaviour body reads identically whether it lives on the class or in a
+ * module: `this.commit(...)` becomes `ctx.commit(...)`.
+ */
+export interface EditorContext {
+    readonly host: HTMLElement;
+    readonly selection: EditorSelection;
+    readonly registry: BlockRegistry;
+    readonly history: History;
+    readonly ydoc: Y.Doc;
+    readonly blobStore: BlobStore | null;
+    readonly blobCache: BlobCache | null;
+    readonly fontFaces: FontFaceRegistry;
+    /** Live view of the editor's current document (re-read on every access). */
+    readonly doc: SobreeDocument;
+    /** Replace the cached document wholesale (rare — most paths use `commit`). */
+    setDoc(doc: SobreeDocument): void;
+    /** Full document replace: reset registry, re-render, mirror, emit change. */
+    setDocument(doc: SobreeDocument): void;
+    /** Re-render the current `doc` into the hosts (no selection restore, no emit). */
+    renderCurrent(): void;
+    /**
+     * Soft-revert the in-memory doc to `snapshot` and re-render (resets the
+     * serialised-block cache + dom-dirty flag; no registry reset, mirror, or
+     * emit). Used to roll back the browser's native IME mutations before a
+     * tracked re-insert.
+     */
+    restoreSnapshot(snapshot: SobreeDocument): void;
+    /** The content host(s) the renderer paints into (may differ from `host`). */
+    getContentHosts(): HTMLElement[];
+    /** The host(s) a DOM selection may live in. */
+    _hosts(): HTMLElement[];
+    readonly trackChanges: TrackChangesState;
+    /** Set tracked-changes state WITHOUT firing the change event (internal). */
+    setTrackChangesRaw(state: TrackChangesState): void;
+    readonly lastPartRefs: Record<string, string>;
+    setLastPartRefs(refs: Record<string, string>): void;
+    readonly pendingPartRefMigrations: Set<string>;
+    commit<T = void>(update: Partial<SobreeDocument>, mutations: readonly Mutation[], value?: T, reason?: string): EditResult<T>;
+    ensureCurrent(): SobreeDocument;
+    syncFromDom(): SobreeDocument;
+    checkRefs(refs: readonly BlockRef[]): EditResult<never> | null;
+    checkRange(range: ApiRange, expect: Record<string, number> | undefined): EditResult<never> | null;
+    emitChangeNow(): void;
+    mirrorToYDoc(): void;
+    scheduleChange(): void;
+    setDomDirty(value: boolean): void;
+}

package/dist/editor/dom.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DOM utilities for the editor — selection geometry, block-element
+ * lookup, drag/drop image detection, image sizing. Browser-only
+ * (no model state); kept apart from `editor/index.ts` so the editor
+ * module stays about editing, not DOM plumbing.
+ */
+/** Nearest ancestor (or self) that is a direct block child of a host. */
+export declare function closestBlockElement(node: Node, hosts: HTMLElement[]): HTMLElement | null;
+/** The live DOM selection range, but only if both ends are inside a host. */
+export declare function currentDomRangeInsideHosts(hosts: HTMLElement[]): Range | null;
+/** True when a drag/paste DataTransfer carries at least one image file. */
+export declare function hasImageInDataTransfer(dt: DataTransfer | null): boolean;
+/** Cross-browser caret range at viewport (x, y) — drop-point resolution. */
+export declare function caretRangeFromPoint(x: number, y: number): Range | null;
+/** Decode an image file's natural dimensions (falls back to 200×150). */
+export declare function readImageDimensions(file: File): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Replace an element with its children (lift contents up one level). */
+export declare function unwrap(el: HTMLElement): void;

package/dist/editor/events.d.ts

@@ -0,0 +1,29 @@
+import { Selection } from '../doc/api';
+import { ChangePayload, EditorEvent, EditorEventPayload, TrackChangesState, Unsubscribe } from './types';
+/**
+ * The editor's observable event surface — `change`, `selection`,
+ * `keydown`, `track-changes-change`. Owns the four listener sets and the
+ * dispatch loops; the Editor keeps the *triggers* (the DOM listeners and
+ * the commit pipeline) and forwards built payloads here. Each dispatch
+ * isolates listener exceptions so one bad subscriber can't break the
+ * others or the edit that fired the event.
+ */
+export declare class EditorEvents {
+    private readonly listeners;
+    on<E extends EditorEvent>(event: E, cb: (p: EditorEventPayload[E]) => void): Unsubscribe;
+    /** Whether any `change` subscriber exists — lets the caller skip
+     *  building the (cloned) payload when nobody's listening. */
+    hasChangeListeners(): boolean;
+    emitChange(payload: ChangePayload): void;
+    /** Compose a {@link SelectionPayload} from `sel` and dispatch. */
+    emitSelection(sel: Selection): void;
+    /**
+     * Normalise a DOM `KeyboardEvent` into a {@link KeyDownPayload} and
+     * dispatch in registration order. Subscribers can `preventDefault()`
+     * (browser default) and/or `stopPropagation()` (further subscribers).
+     */
+    emitKeyDown(e: KeyboardEvent): void;
+    emitTrackChanges(state: TrackChangesState): void;
+    /** Drop all subscribers on editor destroy. */
+    clear(): void;
+}