@onodocs/canvas 0.2.1 → 0.4.0

package/templates.md

@@ -0,0 +1,71 @@
+# Word templates and document generation
+
+Use `createTemplateEditor` from `@onodocs/sdk/editor` to design reusable DOCX templates. Run `npm run example:templates` in the source workspace for the invoice example at localhost port 5193. The designer uses the ordinary Word editor for layout, formatting and generated-document adjustments.
+
+For a complete business-data-to-export journey, run `npm run example:proposal`. The [proposal studio guide](proposal.md) covers setup, repeating fee rows, wording edits and Word/PDF downloads.
+
+```ts
+import { createTemplateEditor } from "@onodocs/sdk/editor";
+
+const designer = createTemplateEditor({
+  container: document.querySelector("#templates"),
+  sampleData: { customer: "Willow Design", items: [{ name: "Review", price: 125 }] },
+});
+await designer.open(templateBytes);
+```
+
+Select a placeholder and choose Text field, a data field and Apply binding. Selected text keeps the rest of the sentence intact. Use Selected paragraphs for whole paragraphs, Table row for repeating line items, or Whole table for a conditional table. Define an outer repeat or condition before adding fields inside it. Array-item choices in the data selector resolve against the current repeated item. Number, currency and date fields have format controls; image fields use point dimensions and supplied PNG/JPEG data. Existing bindings can be selected, updated or removed. Removing a binding preserves its placeholder content.
+
+Reusable sections have a name and content. Define a section once, then choose Insert reusable section at each insertion point. Each insertion can select a different subrecord. Definitions do not appear in generated output. Sections are reused within their defining Word story part; cross-part insertion is not supported because package relationships belong to their source part. Section content can contain its own fields, repeats and conditions.
+
+Preview document opens generated content in the editor. Adjust it with the ordinary editing controls and download Word or PDF. Back to template restores the design without incorporating those preview adjustments. Download template always saves the design. A JSON array in Sample data enables Generate batch, which downloads one DOCX for each record; browsers may ask to allow multiple downloads. The SDK batch iterator gives applications control over filenames and storage.
+
+For generation in Node or a browser, use the default SDK entry. The browser entry exports the same template API.
+
+```ts
+import { openTemplate } from "@onodocs/sdk";
+
+const template = await openTemplate(templateBytes, { licenseKey });
+try {
+  const documentBytes = await template.generate(data, { locale: "en-US", signal });
+  for await (const bytes of template.batch(records, { locale: "en-US", signal })) {
+    await storeDocument(bytes);
+  }
+} finally {
+  template.dispose();
+}
+```
+
+Generation starts from the original source each time. It neither edits the source template nor calls external services. Open the result through the existing Node/browser SDK or server renderer to query, render, edit or export it. Failed and cancelled generations leave the template available for another attempt. Consume batch results incrementally to avoid retaining a whole batch in memory.
+
+Bindings are stored in ordinary Word content-control tags. Use `templateTag(binding)` with the editor's `template` command for programmatic authoring:
+
+```ts
+import { templateTag } from "@onodocs/sdk";
+
+await doc.edit({
+  kind: "template",
+  scope: "selection",
+  selection,
+  title: "Customer name",
+  tag: templateTag({ kind: "value", path: ["customer", "name"] }),
+});
+```
+
+The command supports `selection`, `paragraph`, `row` and `table` scopes. Inline selection stays within one paragraph and uses ordinary adjacent text runs; it cannot cross existing controls or marks. A collapsed selection inserts a placeholder using the title. `action: "update"` changes the selected control's tag and title; `action: "remove"` unwraps it. Supply `controlId` when choosing a specific control from `doc.query.contentControls()`. Use `editor.execute` for changes that must participate in the component's undo history.
+
+| Binding | Required values | Result |
+| --- | --- | --- |
+| `value` | `path` | String, finite number, boolean or null; null becomes empty text |
+| `value` with `format` | `path`, `{ kind: "number", options }` or `{ kind: "date", options }` | `Intl.NumberFormat` or `Intl.DateTimeFormat` output |
+| `image` | `path`, `width`, `height` | PNG/JPEG from `{ bytes: Uint8Array, mediaType }`; optional `description` |
+| `repeat` | `path` | One copy for each array item; descendants use that item as their context |
+| `if` | `path` | Included for truthy values or nonempty arrays |
+| `section` | `name` | Reusable content definition, omitted from output |
+| `include` | `name`, optional `path` | Section inserted with the current context or selected subrecord |
+
+Paths are arrays of own-property names, not executable expressions. An empty path selects the current record. Missing data, wrong value types and recursive sections report an error. Currency options are ordinary `Intl.NumberFormatOptions`, for example `{ style: "currency", currency: "USD" }`. Date values can be a `Date`, timestamp or ISO date string; use an explicit offset for timestamps. The default locale is `en-US` and the default date time zone is UTC.
+
+Formatting comes from the first run of a text placeholder. Unrelated Word content and package resources are preserved. Generation refreshes supported sequence and bookmark-reference fields. The browser template API also lays out the generated document to refresh page numbers, page references and supported tables of contents. Node callers can supply a `finalize` callback that opens the generated bytes with the server renderer and returns `document.save(options)`.
+
+Unsupported fields retain their cached content. Use `onFieldStatus` to receive diagnostics, or `fields: "require-current"` to reject output containing unresolved fields. The default reports retained caches and completes generation. Locked fields retain their authored values. `fields: "preserve"` explicitly keeps all cached results. Existing signed-package, document-protection and editing restrictions still apply. Native DOTX/DOTM generation is not supported; save the template as DOCX. The reusable source is still a Word document and can be saved and opened by Word.

package/types/canvas/index.d.ts

@@ -1,3 +1,4 @@
+/** Spec: pipeline.sdk.pdf-export */
 /** Spec: pipeline.sdk.page-source */
 import { type PageInteraction } from "../foundation/index.js";
 import type { DocumentSource, PageSize } from "../render-api/index.js";
@@ -5,6 +6,7 @@ import type { DocumentView, ViewOptions } from "./presentation.js";
 export { materializePageDisplayListToCanvas } from "./canvas-materializer.js";
 export { encode, decode } from "./transport.js";
 export type * from "../render-api/index.js";
+export type { SelectionOverlay } from "./text-selection.js";
 export type { DocumentView, ViewOptions, ViewAnchor, DocumentAttachment, AttachmentOptions, AttachmentPlacement } from "./presentation.js";
 export interface DocumentPage {
     readonly index: number;
@@ -12,6 +14,7 @@ export interface DocumentPage {
     readonly interaction: PageInteraction;
     render(canvas: HTMLCanvasElement, options?: Readonly<{
         dpi?: number;
+        background?: "white" | "transparent";
         signal?: AbortSignal;
     }>): Promise<void>;
 }

package/types/canvas/presentation.d.ts

@@ -1,11 +1,14 @@
 /** Spec: pipeline.semantic.document-update */
 /** Spec: pipeline.sdk.presentation */
-import type { DocumentFragment, DocumentHit, DocumentPoint } from "../render-api/index.js";
+import type { DocumentFragment, DocumentHit, DocumentPoint, DocumentSelection } from "../render-api/index.js";
 import type { DocumentPage, PageSize } from "./index.js";
+import { type SelectionOverlay } from "./text-selection.js";
 export interface ViewOptions {
     readonly zoom?: number | "fit-width";
     readonly gap?: number;
     readonly title?: string;
+    readonly input?: HTMLTextAreaElement;
+    readonly onSelectionChange?: (selection: DocumentSelection | undefined) => void;
 }
 export interface DocumentAttachment {
     readonly element: HTMLElement;
@@ -42,6 +45,9 @@ export interface DocumentView {
         point: DocumentPoint;
     }> | undefined;
     hitTest(point: DocumentPoint): DocumentHit | undefined;
+    readonly selection: DocumentSelection | undefined;
+    setSelection(selection: DocumentSelection): void;
+    setSelectionOverlays(selections: readonly SelectionOverlay[]): void;
     scrollTo(anchor: ViewAnchor, options?: ScrollIntoViewOptions): boolean;
     attach(element: HTMLElement, options: AttachmentOptions): DocumentAttachment;
     dispose(): void;

package/types/canvas/text-selection.d.ts

@@ -1,7 +1,15 @@
-import type { PageTextLine } from "../render-api/index.js";
+import type { DocumentSelection, PageTextLine } from "../render-api/index.js";
 import type { DocumentPage } from "./index.js";
+export interface SelectionOverlay {
+    readonly selection: DocumentSelection;
+    readonly label: string;
+    readonly color: string;
+}
 /** Spec: pipeline.sdk.presentation */
-export declare function mountTextSelection(pageText: readonly PageTextLine[], viewport: HTMLElement, shells: readonly HTMLElement[], pageBounds: readonly DocumentPage["size"][], nearby: ReadonlySet<number>, signal: AbortSignal): {
+export declare function mountTextSelection(pageText: readonly PageTextLine[], viewport: HTMLElement, shells: readonly HTMLElement[], pageBounds: readonly DocumentPage["size"][], nearby: ReadonlySet<number>, signal: AbortSignal, input?: HTMLTextAreaElement, onSelectionChange?: (selection: DocumentSelection | undefined) => void): {
     paint: () => void;
+    setSelectionOverlays(values: readonly SelectionOverlay[]): void;
+    readonly selection: DocumentSelection | undefined;
+    setSelection(value: DocumentSelection): void;
 };
 //# sourceMappingURL=text-selection.d.ts.map

package/types/foundation/page-interaction.d.ts

@@ -3,6 +3,14 @@ export interface DocumentPoint {
     readonly x: number;
     readonly y: number;
 }
+export interface ParagraphPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+export interface DocumentSelection {
+    readonly start: ParagraphPosition;
+    readonly end: ParagraphPosition;
+}
 export interface PageRectangle extends DocumentPoint {
     readonly width: number;
     readonly height: number;
@@ -35,6 +43,7 @@ export interface DocumentHit {
     }>;
 }
 export interface PageTextLine {
+    readonly ink?: PageRectangle;
     readonly pageIndex: number;
     readonly order: number;
     readonly clip: PageRectangle | null;
@@ -44,6 +53,12 @@ export interface PageTextLine {
         transform?: PageTransform;
     }>[];
     readonly selection: Readonly<{
+        storyId?: string;
+        generated?: readonly Readonly<{
+            text: string;
+            x: number;
+            width: number;
+        }>[];
         transform?: PageTransform;
         paragraphId: string;
         sourceOrder?: bigint;
@@ -54,6 +69,7 @@ export interface PageTextLine {
         carets: readonly Readonly<{
             scalarOffset: number;
             x: number;
+            paragraphOffset?: number;
         }>[];
     }>;
 }
@@ -77,9 +93,19 @@ export interface PageHitLine {
     readonly emptyParagraph: boolean;
 }
 export interface PageInteraction {
+    readonly readingOrder: readonly Readonly<{
+        text: string;
+        headingLevel?: number;
+    }>[];
+    /** Spec: pipeline.sdk.pdf-export */
+    readonly figures?: readonly Readonly<{
+        elementId: string;
+        fragment: DocumentFragment;
+    }>[];
     readonly text: readonly PageTextLine[];
     readonly lines: readonly PageHitLine[];
     readonly areas: readonly Readonly<{
+        kind?: "image";
         elementId: string;
         fragment: DocumentFragment;
     }>[];

package/types/render-api/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./page-display-list.js";
 export * from "./page-source.js";
-export type { DocumentFragment, DocumentHit, DocumentPoint, PageTextLine, PageInteraction, FontFaceResource, ImageResourceData } from "../foundation/index.js";
+export type { DocumentFragment, DocumentHit, DocumentPoint, DocumentSelection, ParagraphPosition, PageTextLine, PageInteraction, FontFaceResource, ImageResourceData } from "../foundation/index.js";
 //# sourceMappingURL=index.d.ts.map