@sobree/core 0.1.31 → 0.1.33

package/dist/docx/{import/anchoredFrames.d.ts → drawing/anchored.d.ts}

@@ -1,5 +1,5 @@
 import { AnchoredFrame, Block } from '../../doc/types';
-import { ThemePalette } from '../shared/drawingColor';
+import { ThemePalette } from './colors';
 export interface AnchoredFramesContext {
     /** RelationshipId → part path lookup, e.g. `"rId4" → "media/image1.png"`. */
     rels: Map<string, string>;
@@ -14,7 +14,7 @@ export interface AnchoredFramesContext {
     bodyParagraphIndexByElement?: Map<Element, number>;
     /**
      * Recursive body walker for `<w:txbxContent>`, injected by the caller
-     * to avoid an `anchoredFrames ↔ document` import cycle. When present,
+     * to avoid an `anchored ↔ document` import cycle. When present,
      * textbox bodies parse through the SAME pipeline as the document body
      * — real run formatting, paragraph spacing, lists, tables — so a
      * frame whose content flows into the body (see `flowFrames`) keeps

package/dist/docx/drawing/dom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Namespace-aware XML traversal helpers shared by every DrawingML reader.
+ * Pure plumbing — no DrawingML semantics live here, only the
+ * `namespaceURI`/`localName` matching the DOM's `getElementsByTagName`
+ * can't do directly. Numeric/EMU attribute reads live in `extents.ts`.
+ */
+/** First DIRECT child of `parent` in `ns` with `localName === local`. */
+export declare function firstChildNS(parent: Element, ns: string, local: string): Element | null;
+/** First DESCENDANT (any depth) of `root` in `ns` with `localName === local`. */
+export declare function firstNS(root: Element, ns: string, local: string): Element | null;
+/** All DIRECT children of `parent` in `ns` with `localName === local`. */
+export declare function directChildrenNS(parent: Element, ns: string, local: string): Element[];
+/** Nearest ANCESTOR of `start` in `ns` with `localName === local`. */
+export declare function findAncestor(start: Element, ns: string, local: string): Element | null;

package/dist/docx/drawing/extents.d.ts

@@ -0,0 +1,12 @@
+import { EmuExtent } from './model';
+/** Read a numeric XML attribute; `0` when absent, missing, or non-finite. */
+export declare function numAttr(el: Element | undefined | null, name: string): number;
+/** Read a numeric XML attribute, falling back to `fallback` when ABSENT —
+ *  used for `<wps:bodyPr>` insets whose OOXML defaults are non-zero. */
+export declare function numAttrOr(el: Element, name: string, fallback: number): number;
+/** Read an EMU attribute that the caller has already null-checked; `0`
+ *  for an explicitly-absent (`null`) value. Distinct from `numAttr` only
+ *  in taking the raw attribute string rather than the element. */
+export declare function emuAttr(v: string | null): number;
+/** Read an `<…:extent>` / `<…:ext>` element's `cx`/`cy` into EMU. */
+export declare function readExtent(el: Element | undefined | null): EmuExtent;

package/dist/docx/drawing/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DrawingML concept modules — the single home for OOXML `<w:drawing>`
+ * translation, split by concept (extents, position, wrap, margins,
+ * relationships, colours, shape properties). The import dispatch
+ * (`docx/import/{anchored,inline,float,flow}Frames`) and serialization
+ * (`docx/export/drawings`) call into these; they do not re-implement EMU
+ * math or `relativeFrom` coercion. See `OWNERSHIP.md`.
+ */
+export { directChildrenNS, findAncestor, firstChildNS, firstNS, } from './dom';
+export { emuAttr, numAttr, numAttrOr, readExtent } from './extents';
+export { coerceHRelativeFrom, coerceVRelativeFrom, readPosOffset } from './position';
+export { readWrapText, readWrapType } from './wrap';
+export type { WrapText, WrapType } from './wrap';
+export { readTextDistances } from './margins';
+export type { TextDistancesEmu } from './margins';
+export { normalizePartPath, readBlipEmbedPart } from './relationships';
+export { readBorder, readGeometry, readSolidFill } from './shapeProps';
+export { parseThemeXml, readDrawingColor } from './colors';
+export type { ThemePalette } from './colors';
+export type { EmuExtent, EmuOffset, RelativeFromH, RelativeFromV, XfrmBox, } from './model';

package/dist/docx/{import/inlineFrames.d.ts → drawing/inline.d.ts}

@@ -1,5 +1,5 @@
 import { Block, InlineFrame } from '../../doc/types';
-import { ThemePalette } from '../shared/drawingColor';
+import { ThemePalette } from './colors';
 export interface InlineFramesContext {
     /** RelationshipId → part path lookup. */
     rels: Map<string, string>;

package/dist/docx/drawing/margins.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Owns DrawingML text-distance insets: the `distT/B/L/R` attributes on
+ * `<wp:anchor>` — the clearance Word keeps between a wrapped frame and the
+ * text flowing around it. Maps to `AnchoredFrame.textDistancesEmu` /
+ * (after the float pass) `DrawingRun.floatMarginsEmu`.
+ */
+/** Text-distance insets in EMU, all four sides. */
+export interface TextDistancesEmu {
+    topEmu: number;
+    rightEmu: number;
+    bottomEmu: number;
+    leftEmu: number;
+}
+/**
+ * `distT/B/L/R` are attributes of `<wp:anchor>` itself (not the wrap
+ * child). Returns `undefined` when ALL four are absent — a frame with no
+ * declared clearance models none; a partially-declared one zero-fills the
+ * omitted sides (Word's default distance is 0 for the wrap modes).
+ */
+export declare function readTextDistances(anchor: Element): TextDistancesEmu | undefined;

package/dist/docx/drawing/model.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared structural vocabulary for the DrawingML concept readers. These
+ * are the small intermediate shapes the per-concept modules traffic in —
+ * deliberately separate from the final Sobree AST (`AnchoredFrame`,
+ * `InlineFrame`, `DrawingRun`) so importer and (future) exporter agree on
+ * one EMU-coordinate language without coupling to persisted editor types.
+ */
+/** A DrawingML `<…:ext cx cy>` / `<wp:extent>` size, in EMU. */
+export interface EmuExtent {
+    cx: number;
+    cy: number;
+}
+/** A DrawingML `<a:off x y>` position, in EMU. */
+export interface EmuOffset {
+    x: number;
+    y: number;
+}
+/** An `<a:xfrm>` offset+extent pair. Either may be absent in the source. */
+export interface XfrmBox {
+    off?: EmuOffset;
+    ext?: EmuExtent;
+}
+/** `<wp:positionH relativeFrom>` enum (horizontal frame origin). */
+export type RelativeFromH = "page" | "margin" | "column";
+/** `<wp:positionV relativeFrom>` enum (vertical frame origin). */
+export type RelativeFromV = "page" | "margin" | "paragraph";

package/dist/docx/drawing/position.d.ts

@@ -0,0 +1,8 @@
+import { RelativeFromH, RelativeFromV } from './model';
+/** Coerce `<wp:positionH relativeFrom>` to the AST enum; `page` default. */
+export declare function coerceHRelativeFrom(v: string | null): RelativeFromH;
+/** Coerce `<wp:positionV relativeFrom>` to the AST enum; `page` default. */
+export declare function coerceVRelativeFrom(v: string | null): RelativeFromV;
+/** Read the `<wp:posOffset>` EMU offset of a `<wp:positionH/V>` element;
+ *  `0` when the element or its offset child is absent. */
+export declare function readPosOffset(positionEl: Element | null): number;

package/dist/docx/drawing/relationships.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Owns relationship → media-part resolution for drawings: reading
+ * `r:embed` off an `<a:blip>`, looking it up in the document's rels map,
+ * and normalising the resulting part path. The one place that knows how a
+ * drawing points at its image bytes.
+ */
+/**
+ * Normalise a relationship target to a `word/…`-rooted part path.
+ *   - a package-absolute `/word/media/x.png` drops the leading slash,
+ *   - an already-`word/`-rooted path is left as-is,
+ *   - a document-relative `media/x.png` is rooted under `word/`.
+ */
+export declare function normalizePartPath(target: string): string;
+/**
+ * Resolve an `<a:blip r:embed>` to its normalised media part path, or
+ * `null` when the blip has no embed id or the id isn't in `rels`.
+ */
+export declare function readBlipEmbedPart(blip: Element, rels: Map<string, string>): string | null;

package/dist/docx/drawing/shapeProps.d.ts

@@ -0,0 +1,16 @@
+import { FrameBorder } from '../../doc/types';
+import { ThemePalette } from './colors';
+/** Map `<a:prstGeom prst>` to the AST's preset geometry enum; unknown
+ *  presets fall back to `rect`. (Custom geometry is handled separately by
+ *  the anchored reader via `customGeometry`.) */
+export declare function readGeometry(wsp: Element): "rect" | "ellipse" | "roundedRect" | "line";
+/**
+ * First `<a:solidFill>` directly inside the shape's `spPr` (wps or pic) —
+ * literal `srgbClr` or theme `schemeClr` (+ transforms), resolved by
+ * `readDrawingColor`. Direct-child traversal so a fill nested deeper
+ * inside a child shape isn't picked up by mistake.
+ */
+export declare function readSolidFill(shape: Element, theme?: ThemePalette): string | undefined;
+/** Read the shape outline `<a:ln>` (width + colour + dash) into a
+ *  `FrameBorder`; `undefined` when there's no outline or no stroke colour. */
+export declare function readBorder(shape: Element, theme?: ThemePalette): FrameBorder | undefined;

package/dist/docx/drawing/testUtil.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test-only helper: parse a single namespaced DrawingML fragment and
+ * return its root element, with all the OOXML prefixes the concept
+ * readers expect already declared. Keeps the per-concept `.test.ts`
+ * files free of namespace boilerplate.
+ */
+/** Parse `<prefix:tag …>…</…>` and return the root element. The namespace
+ *  declarations are injected onto the root so any prefix resolves. */
+export declare function el(fragment: string): Element;

package/dist/docx/drawing/wrap.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Owns DrawingML text-wrapping: the `<wp:wrap*>` child of `<wp:anchor>`
+ * that decides whether a frame DISPLACES body flow, and the `wrapText`
+ * side that decides which way a floated frame goes. Wrap is an
+ * anchored-drawing concept; inline drawings are in flow and carry none.
+ */
+/** The mapped wrap mode, or the AST's value for an `<wp:anchor>` with no
+ *  recognised wrap child. */
+export type WrapType = "square" | "topAndBottom" | "tight" | "through" | "none";
+/** Which sides of the frame body text flows on (`<wp:wrap* wrapText>`). */
+export type WrapText = "bothSides" | "left" | "right" | "largest";
+/**
+ * The wrap mode lives as a dedicated child of `<wp:anchor>`:
+ * `<wp:wrapSquare>`, `<wp:wrapTopAndBottom>`, `<wp:wrapTight>`,
+ * `<wp:wrapThrough>`, or `<wp:wrapNone>`. Returns the mapped enum or
+ * `undefined` when no wrap element is present.
+ */
+export declare function readWrapType(anchor: Element): WrapType | undefined;
+/**
+ * `wrapText` (`bothSides` / `left` / `right` / `largest`) lives on the
+ * displacing wrap child (`<wp:wrapSquare|Tight|Through>`) and says which
+ * sides of the frame text flows on. `topAndBottom` / `none` don't carry it.
+ */
+export declare function readWrapText(anchor: Element): WrapText | undefined;

package/dist/editor/internal/positionMap.d.ts

@@ -8,6 +8,17 @@ import { BlockRegistry } from './blockRegistry';
  * `offset = 0` — block-internal table addressing is a future extension.
  */
 export declare function positionFromDomPoint(hosts: readonly HTMLElement[], registry: BlockRegistry, node: Node, domOffset: number): InlinePosition | null;
+/**
+ * Registry-free `(node, offset)` → block descriptor (`blockId` + offset, plus a
+ * cell address inside a table). The id-based core of {@link positionFromDomPoint},
+ * also used to save/restore a selection across a DOM rebuild (repagination)
+ * where raw node references don't survive.
+ */
+interface BlockPoint {
+    blockId: string;
+    offset: number;
+    cell?: CellAddress;
+}
 /** Build an API `Range` from a live DOM `Range`. */
 export declare function rangeFromDomRange(hosts: readonly HTMLElement[], registry: BlockRegistry, range: Range): ApiRange | null;
 /** Read `window.getSelection()` as a model `Selection`. */
@@ -21,6 +32,15 @@ export declare function domPointFromPosition(hosts: readonly HTMLElement[], pos:
 } | null;
 /** Apply a model `Selection` to `window.getSelection()`. */
 export declare function applySelectionToDom(hosts: readonly HTMLElement[], selection: Selection): boolean;
+export interface SelectionDescriptor {
+    start: BlockPoint;
+    end: BlockPoint;
+    collapsed: boolean;
+}
+/** Capture the live selection as a {@link SelectionDescriptor}, or null. */
+export declare function captureSelectionDescriptor(hosts: readonly HTMLElement[]): SelectionDescriptor | null;
+/** Restore a {@link SelectionDescriptor} to the live DOM (after a rebuild). */
+export declare function applySelectionDescriptor(hosts: readonly HTMLElement[], desc: SelectionDescriptor | null): boolean;
 /** Total character-count length of a block, per the counting rules above. */
 export declare function blockLength(blockEl: Element): number;
 /** The DOM element for body block `index` via the positional `data-block-index`
@@ -31,3 +51,5 @@ export declare function blockElementAtIndex(hosts: readonly HTMLElement[], index
 /** Count distinct blocks in the rendered DOM. Dedups by id so a block split
  *  across a page boundary (two fragments, one id) counts once. */
 export declare function countBlocks(hosts: readonly HTMLElement[]): number;
+type CellAddress = NonNullable<InlinePosition["cell"]>;
+export {};