@forevka/wordcanvas 0.1.0 → 0.2.0

package/dist-lib/{wordcanvas-DPJsuqnm.js → wordcanvas-CgZ_uuf9.js}

@@ -320,7 +320,7 @@ class c {
           this.handle = t, o(t);
         },
         onEvent: (t) => this.emit(t)
-      }), import("./editorApp-Bl8rfr3S.js");
+      }), import("./editorApp-Dl_Glngl.js");
     });
   }
   /** Subscribe to a collaboration event. Returns an unsubscribe function. */
@@ -344,6 +344,14 @@ class c {
   async openDocx(e) {
     return (await this.ready).openDocx(e);
   }
+  /** Replace the open document with a programmatically-built one (e.g. a
+   *  DocumentBuilder result). The input is cloned. Like openDocx, this starts
+   *  a NEW document: undo history and any live collab session are dropped
+   *  (the next share() forks). Zoom and scroll position are preserved, so
+   *  calling this on every data change gives a stable live preview. */
+  async setDocument(e) {
+    (await this.ready).setDocument(e);
+  }
   /** Publish the current document and resolve its shareable link (online only). */
   async share() {
     return (await this.ready).share();

package/dist-lib/wordcanvas.js

@@ -1,4 +1,4 @@
-import { W as r } from "./wordcanvas-DPJsuqnm.js";
+import { W as r } from "./wordcanvas-CgZ_uuf9.js";
 export {
   r as WordCanvas
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forevka/wordcanvas",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Embeddable canvas-rendered, Word-compatible document editor with live collaboration and DOCX/PDF import & export. Self-contained, zero runtime dependencies.",
   "license": "MIT",
@@ -32,6 +32,7 @@
       "types": "./types/wordcanvas.d.ts",
       "import": "./dist-lib/wordcanvas.js"
     },
+    "./builder": "./src/builder/index.ts",
     "./import": "./src/import/docx/pipeline.ts",
     "./export": "./src/export/pipeline.ts",
     "./export/measure": "./src/export/shared/measureHost.ts"
@@ -42,6 +43,10 @@
       ".": {
         "types": "./types/wordcanvas.d.ts",
         "import": "./dist-lib/wordcanvas.js"
+      },
+      "./builder": {
+        "types": "./types/builder.d.ts",
+        "import": "./dist-lib/builder.js"
       }
     }
   },

package/types/builder.d.ts

@@ -0,0 +1,231 @@
+// Public type surface for @forevka/wordcanvas/builder — the fluent
+// programmatic document composer. Hand-written, self-contained (model types
+// come from ./model, shared with wordcanvas.d.ts).
+//
+//   import { DocumentBuilder } from "@forevka/wordcanvas/builder";
+//   const b = await DocumentBuilder.fromTemplate(templateBytes);
+//   const doc = b.paragraph(data.title).withStyle("Heading1").build();
+//
+// Works in the browser (live preview via WordCanvas.setDocument) and in Node
+// (server-side DOCX/PDF generation via the export subpath).
+
+import type { CellBorders, CellMargin, CharStyle, Document, NamedStyle, ParaStyle, Stylesheet } from "./model";
+
+export type { Block, CharStyle, Document, NamedStyle, ParaStyle, Stylesheet } from "./model";
+
+// ---------------------------------------------------------------------------
+// Units
+
+/** Inches → px @96dpi. */
+export declare function inches(n: number): number;
+/** Centimeters → px @96dpi. */
+export declare function cm(n: number): number;
+/** Points (1/72in) → px @96dpi. */
+export declare function pt(n: number): number;
+/** Twips (1/20pt) → px @96dpi. */
+export declare function twips(n: number): number;
+
+export interface PageSize {
+  pageWidthPx: number;
+  pageHeightPx: number;
+}
+
+/** Common page sizes in px @96dpi. */
+export declare const PAGE_SIZES: Record<"Letter" | "Legal" | "A4" | "A3" | "Tabloid", PageSize>;
+export type PageSizeName = keyof typeof PAGE_SIZES;
+
+/** Base64-encode image bytes as a portable data: URL. */
+export declare function bytesToDataUrl(bytes: Uint8Array | ArrayBuffer, mime: string): string;
+
+// ---------------------------------------------------------------------------
+// Options
+
+export interface BuilderWarning {
+  code: string;
+  message: string;
+}
+
+export interface CreateOptions {
+  pageSize?: PageSizeName | PageSize;
+  margins?: Partial<{ top: number; right: number; bottom: number; left: number }>;
+  /** Start from a custom stylesheet (default: the editor's default gallery). */
+  stylesheet?: Stylesheet;
+  /** Deterministic id namespace (tests); default is a random per-builder seed. */
+  idSeed?: string;
+}
+
+export interface TemplateOptions {
+  /** Keep the template's body content and append after it (default: discard —
+   *  the template contributes styles, lists, page setup, and bands). */
+  keepBody?: boolean;
+  idSeed?: string;
+}
+
+export interface PageSetup {
+  pageSize?: PageSizeName | PageSize;
+  orientation?: "portrait" | "landscape";
+  margins?: Partial<{ top: number; right: number; bottom: number; left: number }>;
+  columns?: { count: number; gapPx?: number };
+  headerDistancePx?: number;
+  footerDistancePx?: number;
+  pageNumberStart?: number;
+}
+
+export interface BandOptions {
+  /** Which page band variant: default (all pages), first page, or even pages. */
+  variant?: "default" | "first" | "even";
+}
+
+export interface ImageOptions {
+  /** Required — the builder runs in Node too, where images can't be measured. */
+  widthPx: number;
+  heightPx: number;
+  align?: "left" | "center" | "right";
+  wrap?: "block" | "square";
+}
+
+export interface ListItem {
+  text: string;
+  /** Nesting level 0..8 (default 0, or ListOptions.level). */
+  level?: number;
+  style?: Partial<CharStyle>;
+}
+
+export interface ListOptions {
+  kind?: "bullet" | "number";
+  /** Reference an existing list definition (e.g. one carried by the template). */
+  listId?: string;
+  level?: number;
+}
+
+export interface CellSpec {
+  text?: string;
+  colSpan?: number;
+  rowSpan?: number;
+  /** Background fill (CSS color). */
+  shading?: string;
+  borders?: CellBorders;
+  margin?: CellMargin;
+  /** Char formatting for the cell's text. */
+  style?: Partial<CharStyle>;
+  align?: ParaStyle["align"];
+}
+
+export type CellContent = string | CellSpec;
+export type CellOptions = Omit<CellSpec, "text">;
+
+export interface TableOptions {
+  /** Column widths as fractions of the content width (normalized to sum 1). */
+  colFractions?: number[];
+  /** Bold every run in the first row. */
+  headerRow?: boolean;
+}
+
+export interface SpacingOptions {
+  before?: number;
+  after?: number;
+  lineHeight?: number;
+}
+
+export interface IndentOptions {
+  left?: number;
+  right?: number;
+  firstLine?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Scopes
+
+/** Block-scope surface shared by the document body, header/footer bands, and
+ *  table cells. Methods append eagerly and return the scope (or a paragraph
+ *  scope that delegates back), so chains never need a seal step. */
+export declare class StoryBuilder {
+  paragraph(text?: string, style?: Partial<CharStyle>): ParagraphBuilder<this>;
+  table(rows: CellContent[][], opts?: TableOptions): this;
+  table(build: (t: TableBuilder) => void, opts?: TableOptions): this;
+  image(src: string | { data: Uint8Array | ArrayBuffer; mime: string }, opts: ImageOptions): this;
+  list(items: (string | ListItem)[], opts?: ListOptions): this;
+  bulletList(items: (string | ListItem)[]): this;
+  numberedList(items: (string | ListItem)[]): this;
+  /** The NEXT block starts a new page. */
+  pageBreak(): this;
+}
+
+/** Paragraph scope. Char formatting (bold/color/font/…) patches every run
+ *  already in the paragraph and becomes the default for later text() runs;
+ *  mixed formatting uses text(t, { …patch }). Any block-starting call pops
+ *  back to the parent scope. */
+export declare class ParagraphBuilder<P extends StoryBuilder> {
+  /** Apply a named style: sets the reference and patches exactly the fields
+   *  the style defines. Direct formatting applied AFTER this call wins. */
+  withStyle(id: string): this;
+  /** Append a run. Inherits the scope's accrued formatting; `style` wins. */
+  text(text: string, style?: Partial<CharStyle>): this;
+  bold(on?: boolean): this;
+  italic(on?: boolean): this;
+  underline(on?: boolean): this;
+  strikethrough(on?: boolean): this;
+  color(cssColor: string): this;
+  highlight(cssColor: string): this;
+  fontSize(px: number): this;
+  font(family: string): this;
+  link(url: string): this;
+  align(align: ParaStyle["align"]): this;
+  spacing(opts: SpacingOptions): this;
+  indent(opts: IndentOptions): this;
+  keepWithNext(on?: boolean): this;
+  /** Escape the paragraph scope explicitly (block-starting calls do it implicitly). */
+  end(): P;
+
+  // Delegated block-starting surface (pops this scope):
+  paragraph(text?: string, style?: Partial<CharStyle>): ParagraphBuilder<P>;
+  table(rows: CellContent[][], opts?: TableOptions): P;
+  table(build: (t: TableBuilder) => void, opts?: TableOptions): P;
+  image(src: string | { data: Uint8Array | ArrayBuffer; mime: string }, opts: ImageOptions): P;
+  list(items: (string | ListItem)[], opts?: ListOptions): P;
+  bulletList(items: (string | ListItem)[]): P;
+  numberedList(items: (string | ListItem)[]): P;
+  pageBreak(): P;
+
+  // Document-level delegators (only when the parent is the root builder):
+  header(this: ParagraphBuilder<DocumentBuilder>, build: (s: StoryBuilder) => void, opts?: BandOptions): DocumentBuilder;
+  footer(this: ParagraphBuilder<DocumentBuilder>, build: (s: StoryBuilder) => void, opts?: BandOptions): DocumentBuilder;
+  pageSetup(this: ParagraphBuilder<DocumentBuilder>, setup: PageSetup): DocumentBuilder;
+  style(this: ParagraphBuilder<DocumentBuilder>, def: NamedStyle): DocumentBuilder;
+  build(this: ParagraphBuilder<DocumentBuilder>): Document;
+}
+
+export declare class TableBuilder {
+  row(cells: CellContent[]): this;
+  row(build: (r: RowBuilder) => void): this;
+  rows(data: CellContent[][]): this;
+  colFractions(fractions: number[]): this;
+}
+
+export declare class RowBuilder {
+  cell(content: CellContent, opts?: CellOptions): this;
+  cell(build: (s: StoryBuilder) => void, opts?: CellOptions): this;
+}
+
+/** Root of the fluent builder. Produces the same plain-data Document the
+ *  editor renders (WordCanvas.setDocument) and the exporters write. build()
+ *  returns a deep clone; the builder stays usable afterwards. */
+export declare class DocumentBuilder extends StoryBuilder {
+  /** Start from a blank document (default stylesheet, US Letter, 1in margins). */
+  static create(opts?: CreateOptions): DocumentBuilder;
+  /** Start from a .docx template: its stylesheet, list definitions, page setup,
+   *  and header/footer bands carry over (body discarded unless keepBody). */
+  static fromTemplate(docx: ArrayBuffer | Uint8Array, opts?: TemplateOptions): Promise<DocumentBuilder>;
+
+  /** Lossy decisions (unknown style ids, template import warnings, …). */
+  readonly warnings: readonly BuilderWarning[];
+  /** Compose a header band (replaces the variant's existing story). */
+  header(build: (s: StoryBuilder) => void, opts?: BandOptions): this;
+  footer(build: (s: StoryBuilder) => void, opts?: BandOptions): this;
+  /** Merge page geometry onto the section (template values are the base). */
+  pageSetup(setup: PageSetup): this;
+  /** Register (or override) a named style — BEFORE applying it via withStyle(). */
+  style(def: NamedStyle): this;
+  /** Snapshot the document: deep clone, guaranteed at least one paragraph. */
+  build(): Document;
+}

package/types/model.d.ts

@@ -0,0 +1,225 @@
+// Public document-model types for @forevka/wordcanvas. Hand-written (like
+// wordcanvas.d.ts) so the published surface stays self-contained and stable;
+// mirrors shared/src/model — the editor, builder, and exporters all consume
+// this same plain-data shape.
+
+export interface CharStyle {
+  fontFamily: string;
+  fontSizePx: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  /** CSS color, e.g. "#202124". */
+  color: string;
+  /** Hidden text (OOXML w:vanish) — preserved but never laid out or painted. */
+  hidden?: boolean;
+  letterSpacingPx?: number;
+  /** Background highlight (Word's text highlight). */
+  highlightColor?: string | undefined;
+  /** Sub/superscript. */
+  verticalAlign?: "sub" | "super" | undefined;
+  /** Hyperlink target; linked runs paint blue+underlined. */
+  link?: string | undefined;
+  /** Footnote reference id — this run is the marker. */
+  footnoteRef?: string | undefined;
+  /** Content-control membership (properties live in Document.sdts). */
+  sdtId?: string | undefined;
+}
+
+export interface TabStop {
+  /** Position from the left content edge, px. */
+  posPx: number;
+  align?: "left" | "center" | "right" | "decimal";
+  leader?: "none" | "dot" | "dash" | "underscore";
+}
+
+export interface ParaStyle {
+  align: "left" | "center" | "right" | "justify";
+  /** Line height multiplier. */
+  lineHeight: number;
+  spaceBeforePx: number;
+  spaceAfterPx: number;
+  indentFirstLinePx: number;
+  indentLeftPx: number;
+  indentRightPx?: number;
+  keepWithNext?: boolean;
+  keepLinesTogether?: boolean;
+  /** This paragraph starts a new page. */
+  pageBreakBefore?: boolean;
+  /** List membership: definition id + level 0..8. */
+  list?: { listId: string; level: number } | undefined;
+  /** Named style reference into Document.stylesheet (e.g. "Heading1"). */
+  namedStyle?: string;
+  columnBreakBefore?: boolean;
+  tabStops?: TabStop[];
+}
+
+/** Style-homogeneous span of text. */
+export interface Run {
+  text: string;
+  style: CharStyle;
+}
+
+export interface Paragraph {
+  kind: "paragraph";
+  /** Stable unique id. */
+  id: string;
+  revision: number;
+  runs: Run[];
+  style: ParaStyle;
+}
+
+export interface ImageBlock {
+  kind: "image";
+  id: string;
+  revision: number;
+  /** Image URL — use data: URLs for portable documents. */
+  src: string;
+  /** Content address of the bytes (sha256 hex), when registered. */
+  mediaId?: string;
+  widthPx: number;
+  heightPx: number;
+  align: "left" | "center" | "right";
+  /** 'block' (default): own line. 'square': floats per align, text wraps. */
+  wrap?: "block" | "square";
+}
+
+export interface CellBorder {
+  color: string;
+  widthPx: number;
+  style?: "single" | "double" | "dashed" | "dotted";
+}
+
+export interface CellBorders {
+  top?: CellBorder;
+  right?: CellBorder;
+  bottom?: CellBorder;
+  left?: CellBorder;
+}
+
+export interface CellMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface TableCell {
+  id: string;
+  blocks: Block[];
+  colSpan?: number;
+  rowSpan?: number;
+  /** Background fill (CSS color). */
+  shading?: string;
+  borders?: CellBorders;
+  margin?: CellMargin;
+}
+
+export interface TableRow {
+  cells: TableCell[];
+}
+
+export interface TableBlock {
+  kind: "table";
+  id: string;
+  revision: number;
+  rows: TableRow[];
+  /** Column widths as fractions of content width (sum = 1). Absent = equal. */
+  colFractions?: number[];
+}
+
+export type Block = Paragraph | ImageBlock | TableBlock;
+
+export type BandContainer = "header" | "footer" | "headerFirst" | "headerEven" | "footerFirst" | "footerEven";
+
+export interface SectionProps {
+  pageWidthPx: number;
+  pageHeightPx: number;
+  marginPx: { top: number; right: number; bottom: number; left: number };
+  /** Newspaper columns. Absent = single column. */
+  columns?: { count: number; gapPx: number };
+  pageNumberStart?: number;
+  headerDistancePx?: number;
+  footerDistancePx?: number;
+  /** Header/footer block stories. {page}/{pages} tokens in run text are
+   *  substituted per page at layout time. */
+  header?: Block[];
+  footer?: Block[];
+  headerFirst?: Block[];
+  headerEven?: Block[];
+  footerFirst?: Block[];
+  footerEven?: Block[];
+}
+
+export interface NamedStyle {
+  /** Shares the docx styleId space ("Normal", "Heading1", …). */
+  id: string;
+  /** Display name. */
+  name: string;
+  basedOn?: string;
+  char: Partial<CharStyle>;
+  para: Partial<ParaStyle>;
+}
+
+export interface Stylesheet {
+  styles: NamedStyle[];
+  defaultStyleId: string;
+}
+
+export type ListNumberFormat = "bullet" | "decimal" | "lowerLetter" | "upperLetter" | "lowerRoman" | "upperRoman";
+
+export interface ListLevel {
+  format: ListNumberFormat;
+  /** Marker pattern; %N is level N-1's counter (e.g. "%1."). Ignored for bullets. */
+  text: string;
+  bulletChar?: string;
+  indentLeftPx: number;
+  hangingPx: number;
+  start: number;
+  markerStyle?: Partial<CharStyle>;
+}
+
+export interface ListDefinition {
+  id: string;
+  /** Up to 9 levels (0..8). */
+  levels: ListLevel[];
+}
+
+export interface DocPosition {
+  blockId: string;
+  offset: number;
+}
+
+export interface BookmarkRange {
+  start: DocPosition;
+  end: DocPosition;
+}
+
+export type SdtType = "richText" | "plainText" | "checkbox" | "dropDown" | "comboBox" | "date";
+
+export interface SdtProps {
+  type: SdtType;
+  alias?: string;
+  tag?: string;
+  placeholder?: boolean;
+  listItems?: { display: string; value: string }[];
+  dateFormat?: string;
+  checked?: boolean;
+  lockContent?: boolean;
+  lockControl?: boolean;
+}
+
+export interface Document {
+  section: SectionProps;
+  blocks: Block[];
+  stylesheet?: Stylesheet;
+  /** List definitions keyed by id. */
+  lists?: Record<string, ListDefinition>;
+  /** Footnote bodies keyed by ref id. */
+  footnotes?: Record<string, Paragraph[]>;
+  /** Content-control properties keyed by sdtId. */
+  sdts?: Record<string, SdtProps>;
+  /** Bookmark name → character range. */
+  bookmarks?: Record<string, BookmarkRange>;
+}

package/types/wordcanvas.d.ts

@@ -2,6 +2,10 @@
 // Hand-written so the published types stay small, self-contained, and stable
 // regardless of internal refactors — no dependency on internal workspace types.
 
+import type { Document } from "./model";
+
+export type { Document } from "./model";
+
 /** Caller-supplied identity, used for change attribution and presence. */
 export interface UserInfo {
   id: string;
@@ -43,6 +47,12 @@ export interface WordCanvasEventMap {
 
 /** Handle resolved once the editor is mounted (via `whenReady()`). */
 export interface EditorHandle {
+  /** Snapshot of the current document (plain data). */
+  getDocument(): Document;
+  /** Replace the open document with a programmatically-built one (e.g. a
+   *  DocumentBuilder result). Cloned; drops undo history and any live collab
+   *  session; preserves zoom + scroll. */
+  setDocument(doc: Document): void;
   /** Open a .docx (auto-publishes when online); resolves when loaded. */
   openDocx(file: File | ArrayBuffer): Promise<void>;
   /** Publish the current document and resolve its shareable link (online only). */
@@ -62,6 +72,12 @@ export declare class WordCanvas {
   whenReady(): Promise<EditorHandle>;
   /** Open a .docx. When online, auto-publishes it and surfaces a share link. */
   openDocx(file: File | ArrayBuffer): Promise<void>;
+  /** Replace the open document with a programmatically-built one (e.g. a
+   *  DocumentBuilder result). The input is cloned. Like openDocx, this starts a
+   *  NEW document: undo history and any live collab session are dropped (the
+   *  next share() forks). Zoom and scroll are preserved, so calling this on
+   *  every data change gives a stable live preview. */
+  setDocument(doc: Document): Promise<void>;
   /** Publish the current document and resolve its shareable link (online only). */
   share(): Promise<string>;
   getDocId(): string | null;