@sobree/core 0.1.14 → 0.1.15

package/dist/doc/builders/block.d.ts

@@ -0,0 +1,8 @@
+import { InlineRun, Paragraph, ParagraphProperties, SectionBreak } from '../types';
+/** A paragraph with the given runs and properties (both optional). */
+export declare function paragraph(runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
+/** Heading paragraph (`Heading{level}` style, level clamped to 1..6). */
+export declare function heading(level: number, runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
+/** A section break that switches to `toSectionIndex` in the document's
+ *  `sections` array for the content that follows. */
+export declare function sectionBreak(toSectionIndex: number): SectionBreak;

package/dist/doc/{builders.d.ts → builders/document.d.ts}

@@ -1,20 +1,9 @@
-import { Block, HeaderFooterRef, InlineRun, NamedStyle, PageMargins, PageSize, Paragraph, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument, Table, TextRun } from './types';
+import { Block, HeaderFooterRef, NamedStyle, PageMargins, PageSize, Paragraph, SectionProperties, SobreeDocument, Table } from '../types';
 /** A new, blank document with an A4 portrait section and the standard styles. */
 export declare function emptyDocument(): SobreeDocument;
 export declare function defaultSection(): SectionProperties;
 export declare function defaultPageSize(): PageSize;
 export declare function defaultMargins(): PageMargins;
-/** A paragraph with no runs and no properties beyond the defaults. */
-export declare function paragraph(runs?: InlineRun[], properties?: ParagraphProperties): Paragraph;
-/** Heading paragraph (`Heading{level}` style, level clamped to 1..6). */
-export declare function heading(level: number, runs?: InlineRun[], extra?: ParagraphProperties): Paragraph;
-/** Plain text run with optional formatting. */
-export declare function text(value: string, properties?: RunProperties): TextRun;
-/** Convenience: emphasised (bold + italic) text run. */
-export declare function emphasis(value: string, properties?: RunProperties): TextRun;
-export declare function strong(value: string, properties?: RunProperties): TextRun;
-export declare function softBreak(): InlineRun;
-export declare function pageBreak(): InlineRun;
 /** Default Word styles every doc declares so headings render correctly.
  *
  *  Carries WORD-HARDCODED-DEFAULT typography — i.e. what Word uses

package/dist/doc/builders/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Constructors for AST nodes. Two reasons these exist as helpers instead
+ * of object literals at every call site:
+ *   1. Defaults — A4 paper, an empty cell's placeholder paragraph, equal
+ *      column widths — without sprinkling magic numbers into caller code.
+ *   2. Future schema migration — when a new required field is added, all
+ *      construction goes through here and the migration is one diff.
+ *
+ * Conventions across the layer:
+ *   - The factory is named for the node it builds (`text`, `table`,
+ *     `tableCell`, `hyperlink`, `sectionBreak`).
+ *   - Required content is positional; optional formatting is a trailing
+ *     `properties` argument (a leaf's `RunProperties`, a container's
+ *     `*Properties`). Many-field nodes (`image`, `table`, `namedStyle`)
+ *     take a single trailing options object instead.
+ *   - Measurements keep their native OOXML unit, suffixed (`widthEmu`,
+ *     `…Twips`), matching the AST.
+ *
+ * Organised by node category: document / block / inline / table / style.
+ */
+export { appendBlock, defaultMargins, defaultPageSize, defaultSection, defaultStyles, emptyDocument, isParagraph, isTable, makeHeaderFooterRef, } from './document';
+export { heading, paragraph, sectionBreak } from './block';
+export { columnBreak, commentRef, emphasis, field, footnoteRef, hyperlink, image, type ImageOptions, pageBreak, softBreak, strong, tab, text, } from './inline';
+export { type CellProperties, type TableOptions, table, tableCell, tableRow } from './table';
+export { type NamedStyleOptions, namedStyle } from './style';

package/dist/doc/builders/inline.d.ts

@@ -0,0 +1,38 @@
+import { BreakRun, CommentRefRun, DrawingRun, FieldRun, FootnoteRefRun, HyperlinkRun, InlineRun, RunProperties, TabRun, TextRun } from '../types';
+/** Plain text run with optional formatting. */
+export declare function text(value: string, properties?: RunProperties): TextRun;
+/** Convenience: italic text run. */
+export declare function emphasis(value: string, properties?: RunProperties): TextRun;
+/** Convenience: bold text run. */
+export declare function strong(value: string, properties?: RunProperties): TextRun;
+/** Soft line break inside a paragraph (Shift-Enter). */
+export declare function softBreak(): BreakRun;
+/** Explicit page break. */
+export declare function pageBreak(): BreakRun;
+/** Column break (advances to the next column in a multi-column section). */
+export declare function columnBreak(): BreakRun;
+/** A tab character — advances to the next tab stop. */
+export declare function tab(properties?: RunProperties): TabRun;
+/** A hyperlink wrapping inline children. `href` is an external URL or an
+ *  internal anchor id (`#bookmark`). */
+export declare function hyperlink(href: string, children: InlineRun[], properties?: RunProperties): HyperlinkRun;
+/** A field run (`PAGE`, `NUMPAGES`, `DATE`, …). `cached` is the preview
+ *  text shown until a viewer recalculates the field. */
+export declare function field(instruction: string, cached?: string, properties?: RunProperties): FieldRun;
+/** Options for {@link image}. `partPath` references a binary in the
+ *  document's `rawParts`; the caller is responsible for registering the
+ *  bytes there (or use the editor's `insertImage`, which does both). */
+export interface ImageOptions {
+    widthEmu: number;
+    heightEmu: number;
+    altText?: string;
+    /** Layout mode — defaults to `"inline"` (flows like a tall character). */
+    placement?: DrawingRun["placement"];
+    verticalAlign?: DrawingRun["verticalAlign"];
+}
+/** An image / drawing run referencing a part in `rawParts`. */
+export declare function image(partPath: string, opts: ImageOptions): DrawingRun;
+/** A footnote reference — `id` keys into `SobreeDocument.footnotes`. */
+export declare function footnoteRef(id: number, properties?: RunProperties): FootnoteRefRun;
+/** A comment reference — `id` keys into `SobreeDocument.comments`. */
+export declare function commentRef(id: number, properties?: RunProperties): CommentRefRun;

package/dist/doc/builders/style.d.ts

@@ -0,0 +1,7 @@
+import { NamedStyle } from '../types';
+/** Everything on {@link NamedStyle} except `id` (the positional argument);
+ *  `type` defaults to `"paragraph"` and `displayName` to the id. */
+export type NamedStyleOptions = Partial<Omit<NamedStyle, "id">>;
+/** A named style. `id` is required; `type` defaults to `"paragraph"` and
+ *  `displayName` to `id` when not given. */
+export declare function namedStyle(id: string, options?: NamedStyleOptions): NamedStyle;

package/dist/doc/builders/table.d.ts

@@ -0,0 +1,20 @@
+import { Block, Table, TableCell, TableProperties, TableRow } from '../types';
+/** A cell's properties — everything on {@link TableCell} except `content`
+ *  (which is the positional argument). */
+export type CellProperties = Partial<Omit<TableCell, "content">>;
+/** A table cell. `content` defaults to a single empty paragraph (Word
+ *  requires every cell to hold at least one paragraph). */
+export declare function tableCell(content?: Block[], properties?: CellProperties): TableCell;
+/** A table row. */
+export declare function tableRow(cells: TableCell[], opts?: {
+    isHeader?: boolean;
+}): TableRow;
+export interface TableOptions {
+    /** Column widths in twips (length = column count). Derived as equal
+     *  columns from {@link DEFAULT_TABLE_WIDTH_TWIPS} when omitted. */
+    grid?: number[];
+    properties?: TableProperties;
+}
+/** A table. The column `grid` is taken from `opts.grid`, else derived as
+ *  equal-width columns from the widest row's column count. */
+export declare function table(rows: TableRow[], opts?: TableOptions): Table;

package/dist/doc/formatting.types.d.ts

@@ -1,12 +1,11 @@
 /**
- * Formatting value-types: borders, shading, and table-style conditional
- * formatting.
+ * Visual formatting primitives: borders, shading, and cell spacing.
  *
- * Split out from `types.ts` (the core AST module) as a dependency-free
- * LEAF — none of these reference the recursive `Block` document graph, so
- * they import nothing from `types.ts`. Keeping them here avoids a circular
- * dependency: `types.ts` imports + re-exports them, so consumers still get
- * every AST type from `./types`.
+ * Low-level value-types shared across the AST — paragraphs, runs, and
+ * tables all paint with these. A dependency-free LEAF: none reference the
+ * recursive `Block` document graph, so keeping them here (out of
+ * `types.ts`) avoids a circular dependency. `types.ts` imports +
+ * re-exports them, so consumers still get every AST type from `./types`.
  */
 export interface BorderSpec {
     style: "single" | "double" | "dashed" | "dotted" | "thick" | "none";
@@ -25,6 +24,8 @@ export interface Shading {
     /** Pattern foreground `#rrggbb` or `auto`. */
     color?: string;
 }
+/** A table's outer edges plus the inside-horizontal / inside-vertical
+ *  separators (`<w:tblBorders>`). */
 export interface TableBorders {
     top?: BorderSpec;
     right?: BorderSpec;
@@ -33,6 +34,7 @@ export interface TableBorders {
     insideH?: BorderSpec;
     insideV?: BorderSpec;
 }
+/** A single cell's four edges (`<w:tcBorders>`). */
 export interface TableCellBorders {
     top?: BorderSpec;
     right?: BorderSpec;
@@ -47,45 +49,3 @@ export interface TableCellMargins {
     bottomTwips?: number;
     leftTwips?: number;
 }
-/** `<w:tblLook>` flags. A flag absent ⇒ that conditional format is OFF. */
-export interface TableLook {
-    firstRow?: boolean;
-    lastRow?: boolean;
-    firstColumn?: boolean;
-    lastColumn?: boolean;
-    /** Row (horizontal) banding active. */
-    hBand?: boolean;
-    /** Column (vertical) banding active. */
-    vBand?: boolean;
-}
-/**
- * A table style's conditional-format regions (`<w:tblStylePr w:type>`).
- * Each names a slice of the table whose cells get extra formatting when
- * the table's `<w:tblLook>` enables it. Resolution precedence (low→high,
- * ECMA-376 §17.7.6): wholeTable → vBands → hBands → first/last column →
- * first/last row → corner cells, then direct cell formatting wins.
- */
-export type TableConditionalType = "firstRow" | "lastRow" | "firstCol" | "lastCol" | "band1Horz" | "band2Horz" | "band1Vert" | "band2Vert" | "nwCell" | "neCell" | "swCell" | "seCell";
-/** The formatting one region (or the whole-table base) contributes. */
-export interface TableStyleCellFormat {
-    shading?: Shading;
-    borders?: TableCellBorders;
-}
-/**
- * A `<w:style w:type="table">` definition: whole-table base formatting +
- * per-region conditional formatting + band sizes. Resolved per cell at
- * render time against the table's `look`.
- */
-export interface TableStyleDefinition {
-    /** Whole-table borders (`<w:tblBorders>` — incl. `insideH`/`insideV`). */
-    borders?: TableBorders;
-    /** Whole-table base cell shading. */
-    shading?: Shading;
-    /** Rows per horizontal band (`<w:tblStyleRowBandSize>`, default 1). */
-    rowBandSize?: number;
-    /** Columns per vertical band (`<w:tblStyleColBandSize>`, default 1). */
-    colBandSize?: number;
-    /** Whole-table default cell padding (`<w:tblCellMar>` in the style). */
-    cellMargins?: TableCellMargins;
-    conditional?: Partial<Record<TableConditionalType, TableStyleCellFormat>>;
-}

package/dist/doc/tableStyle.types.d.ts

@@ -0,0 +1,43 @@
+import { Shading, TableBorders, TableCellBorders, TableCellMargins } from './formatting.types';
+/** `<w:tblLook>` flags. A flag absent ⇒ that conditional format is OFF. */
+export interface TableLook {
+    firstRow?: boolean;
+    lastRow?: boolean;
+    firstColumn?: boolean;
+    lastColumn?: boolean;
+    /** Row (horizontal) banding active. */
+    hBand?: boolean;
+    /** Column (vertical) banding active. */
+    vBand?: boolean;
+}
+/**
+ * A table style's conditional-format regions (`<w:tblStylePr w:type>`).
+ * Each names a slice of the table whose cells get extra formatting when
+ * the table's `<w:tblLook>` enables it. Resolution precedence (low→high,
+ * ECMA-376 §17.7.6): wholeTable → vBands → hBands → first/last column →
+ * first/last row → corner cells, then direct cell formatting wins.
+ */
+export type TableConditionalType = "firstRow" | "lastRow" | "firstCol" | "lastCol" | "band1Horz" | "band2Horz" | "band1Vert" | "band2Vert" | "nwCell" | "neCell" | "swCell" | "seCell";
+/** The formatting one region (or the whole-table base) contributes. */
+export interface TableStyleCellFormat {
+    shading?: Shading;
+    borders?: TableCellBorders;
+}
+/**
+ * A `<w:style w:type="table">` definition: whole-table base formatting +
+ * per-region conditional formatting + band sizes. Resolved per cell at
+ * render time against the table's `look`.
+ */
+export interface TableStyleDefinition {
+    /** Whole-table borders (`<w:tblBorders>` — incl. `insideH`/`insideV`). */
+    borders?: TableBorders;
+    /** Whole-table base cell shading. */
+    shading?: Shading;
+    /** Rows per horizontal band (`<w:tblStyleRowBandSize>`, default 1). */
+    rowBandSize?: number;
+    /** Columns per vertical band (`<w:tblStyleColBandSize>`, default 1). */
+    colBandSize?: number;
+    /** Whole-table default cell padding (`<w:tblCellMar>` in the style). */
+    cellMargins?: TableCellMargins;
+    conditional?: Partial<Record<TableConditionalType, TableStyleCellFormat>>;
+}

package/dist/doc/types.d.ts

@@ -1,6 +1,8 @@
-import { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, TableLook, TableStyleDefinition } from './formatting.types';
+import { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins } from './formatting.types';
+import { TableLook, TableStyleDefinition } from './tableStyle.types';
 import { FontDeclaration as _FontDeclaration } from '../fonts/types';
-export type { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, TableConditionalType, TableLook, TableStyleCellFormat, TableStyleDefinition, } from './formatting.types';
+export type { BorderSpec, Shading, TableBorders, TableCellBorders, TableCellMargins, } from './formatting.types';
+export type { TableConditionalType, TableLook, TableStyleCellFormat, TableStyleDefinition, } from './tableStyle.types';
 export interface SobreeDocument {
     /** Top-level body content, in document order. */
     body: Block[];