@design.estate/dees-document 5.6.0 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-document",
-  "version": "5.6.0",
+  "version": "6.1.0",
   "private": false,
   "description": "A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.",
   "main": "dist_ts_web/index.js",
@@ -15,31 +15,31 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "dependencies": {
-    "@design.estate/dees-domtools": "^3.0.0",
-    "@design.estate/dees-element": "^3.2.0",
+    "@design.estate/dees-domtools": "^5.0.0",
+    "@design.estate/dees-element": "^4.0.1",
     "@fin.cx/calculation": "^1.4.0",
     "@push.rocks/smartfile": "^13.1.3",
     "@push.rocks/smartfs": "^1.7.0",
     "@push.rocks/smartjson": "^6.0.2",
     "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartpdf": "^6.0.1",
+    "@push.rocks/smartpdf": "^6.5.0",
     "@push.rocks/smarttime": "^4.2.3",
     "@tsclass/tsclass": "^10.2.0",
     "@types/qrcode": "^1.5.6",
     "qrcode": "^1.5.4"
   },
   "peerDependencies": {
-    "@design.estate/dees-catalog": "^9.7.0 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+    "@design.estate/dees-catalog": "^21.0.0"
   },
   "devDependencies": {
-    "@design.estate/dees-catalog": "^19.4.0",
-    "@design.estate/dees-wcctools": "^3.9.4",
-    "@git.zone/tsbuild": "^5.1.2",
-    "@git.zone/tsbundle": "^3.1.3",
-    "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^7.0.0",
-    "@git.zone/tswatch": "^6.0.0",
-    "@types/node": "^26.6.3"
+    "@design.estate/dees-catalog": "^21.0.0",
+    "@design.estate/dees-wcctools": "^5.0.0",
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsbundle": "^3.2.1",
+    "@git.zone/tsrun": "^3.0.3",
+    "@git.zone/tstest": "^7.2.0",
+    "@git.zone/tswatch": "^7.1.1",
+    "@types/node": "^26.6.4"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -12,7 +12,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm install @design.estate/dees-document @design.estate/dees-catalog
 ```
 
-`@design.estate/dees-catalog` is a peer dependency (9.7 to 19.x): the web components (`@design.estate/dees-document/web`) render the catalog's `dees-icon` and use the catalog copy your application installs. Custom elements are registered globally, so an application must hold one catalog copy, and a component library that brought its own would register each catalog element a second time. pnpm and npm 7+ install a missing peer automatically; Yarn reports it as missing, so list it yourself. The server side (`@design.estate/dees-document`, `/node`) and `/shared` do not load the catalog at runtime: `PdfService` renders with the bundle built into the package.
+`@design.estate/dees-catalog` is a peer dependency (21.x, the catalog on `@design.estate/dees-element` 4): the web components (`@design.estate/dees-document/web`) render the catalog's `dees-icon` and use the catalog copy your application installs. Custom elements are registered globally, so an application must hold one catalog copy, and a component library that brought its own would register each catalog element a second time. pnpm and npm 7+ install a missing peer automatically; Yarn reports it as missing, so list it yourself. The web components run on `@design.estate/dees-element` 4 and `@design.estate/dees-domtools` 5; an application that depends on either itself needs those majors too, or its bundle carries a second copy. The server side (`@design.estate/dees-document`, `/node`) and `/shared` do not load the catalog at runtime: `PdfService` renders with the bundle built into the package.
 
 ## Features
 
@@ -142,7 +142,7 @@ await fs.file('./invoice.pdf').write(Buffer.from(pdfResult.buffer));
 await pdfService.stop();
 ```
 
-`createPdfFromLetterObject()` returns the `IPdf` of `@push.rocks/smartpdf` 6: the PDF in `buffer`, and in `metadata.textExtraction` its text as PDF.js reads it, a line break where a printed line ends and a blank line (`PDF_TEXT_PAGE_SEPARATOR` of smartpdf) between pages. PDF generation needs Node.js 22.13 or newer.
+`createPdfFromLetterObject()` returns the `IPdf` of `@push.rocks/smartpdf` 6: the PDF in `buffer`, and in `metadata.textExtraction` its text as PDF.js reads it, a line break where a printed line ends and a blank line (`PDF_TEXT_PAGE_SEPARATOR` of smartpdf) between pages. The page is printed once the document is laid out (it has the attribute `rendered`, see [Web Component Usage](#web-component-usage)); a document that is not within 30 seconds rejects with an error naming the selector it waited for and the errors the page threw. PDF generation needs Node.js 22.13 or newer.
 
 ### Document Settings
 
@@ -214,6 +214,8 @@ html`
 `;
 ```
 
+`<dedocument-dedocument>` lays the letter out on pages after it updates. Once the pages show the current letter and settings, with their images loaded (or failed) and the fonts ready, the element has the attribute `rendered`; a change to the letter or the settings takes it away until the pages show the change. Whatever prints or captures the element waits for `dedocument-dedocument[rendered]`, as `PdfService` does.
+
 ### Translation System
 
 The package includes a translation system for multi-language document generation:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-document',
-  version: '5.6.0',
+  version: '6.1.0',
   description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
 }

package/ts/classes.pdfservice.ts

@@ -66,9 +66,10 @@ export class PdfService {
     )}"></dedocument-dedocument>
     `;
     // console.log(html);
-    const pdfResult = await this.smartpdfInstance.getA4PdfResultForHtmlString(
-      html
-    );
+    // the page is printed once the document's pages are done, with their images and fonts
+    const pdfResult = await this.smartpdfInstance.getA4PdfResultForHtmlString(html, {
+      readySelector: "dedocument-dedocument[rendered]",
+    });
     return pdfResult;
   }
 }

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-document',
-  version: '5.6.0',
+  version: '6.1.0',
   description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
 }

package/ts_web/elements/document.ts

@@ -38,6 +38,42 @@ declare global {
   }
 }
 
+/** the elements under a node, those in shadow roots included */
+const elementsUnder = (rootArg: ParentNode): Element[] => {
+  const found: Element[] = [];
+  for (const element of Array.from(rootArg.querySelectorAll("*"))) {
+    found.push(element);
+    if (element.shadowRoot) {
+      found.push(...elementsUnder(element.shadowRoot));
+    }
+  }
+  return found;
+};
+
+/**
+ * Resolves once the pages under a node show what they are given: no element
+ * under it has an update pending, its images have loaded or failed, and the
+ * fonts are ready.
+ */
+const settleRendering = async (rootArg: ParentNode): Promise<void> => {
+  for (;;) {
+    const pending = elementsUnder(rootArg).filter(
+      (element): element is DeesElement =>
+        element instanceof DeesElement && element.isUpdatePending
+    );
+    if (pending.length === 0) {
+      break;
+    }
+    await Promise.all(pending.map((element) => element.updateComplete));
+  }
+  const images = elementsUnder(rootArg).filter(
+    (element): element is HTMLImageElement => element instanceof HTMLImageElement
+  );
+  // an image that fails is shown as the browser shows it: it settles all the same
+  await Promise.all(images.map((image) => image.decode().catch(() => {})));
+  await document.fonts.ready;
+};
+
 @customElement("dedocument-dedocument")
 export class DeDocument extends DeesElement {
   public static demo = demoFunc;
@@ -121,15 +157,23 @@ export class DeDocument extends DeesElement {
     return html` <div class="documentContainer"></div> `;
   }
 
-  public async firstUpdated(
-    _changedProperties: Map<string | number | symbol, unknown>
-  ) {
-    domtools.plugins.smartdelay.delayFor(0).then(async () => {
+  public willUpdate(
+    changedProperties: Map<string | number | symbol, unknown>
+  ): void {
+    super.willUpdate(changedProperties);
+    // the settings the document is first given are completed with the
+    // defaults before its first update, so it renders once, with them
+    if (!this.hasUpdated) {
       this.documentSettings = {
         ...defaultDocumentSettings,
         ...this.documentSettings,
       };
-    });
+    }
+  }
+
+  public async firstUpdated(
+    _changedProperties: Map<string | number | symbol, unknown>
+  ) {
     const resizeObserver = new ResizeObserver((entries) => {
       for (const entry of entries) {
         const width = entry.contentRect.width;
@@ -149,8 +193,19 @@ export class DeDocument extends DeesElement {
   public latestRenderedLetterData: plugins.tsclass.business.TLetter | null = null;
   public cleanupStore: HTMLElement[] = [];
   public paginationInfo: IPagePaginationInfo[] = [];
+  /** the renders begun; a render a later one superseded leaves the document to it */
+  private renderGeneration = 0;
 
+  /**
+   * Lays the letter out on pages. Once the pages show the current letter and
+   * settings, with their images loaded and the fonts ready, the element has
+   * the attribute `rendered` (what a print of it can wait for); a render begun
+   * since takes it away until that render is done.
+   */
   public async renderDocument() {
+    const generation = ++this.renderGeneration;
+    const isCurrent = () => generation === this.renderGeneration;
+    this.removeAttribute("rendered");
     // a document whose advance payments do not add up to its paid amount, or
     // whose accent colour is no hex colour, is refused: no page of it, and none
     // of the letter before it, stays on screen. The accent is checked here,
@@ -168,7 +223,7 @@ export class DeDocument extends DeesElement {
     }
     this.latestDocumentSettings = this.documentSettings;
     this.latestRenderedLetterData = this.letterData;
-    this.paginationInfo = [];
+    const paginationInfo: IPagePaginationInfo[] = [];
 
     const cleanUpStoreCurrentRender: HTMLElement[] = [];
     const cleanUpStoreNextRender: HTMLElement[] = [];
@@ -189,7 +244,7 @@ export class DeDocument extends DeesElement {
     content.documentSettings = this.documentSettings;
     document.body.appendChild(content);
 
-    await domtools.convenience.smartdelay.delayFor(0);
+    await domtools.convenience.smartpromise.delayFor(0);
     let overallContentOffset: number = 0;
     let currentContentOffset: number;
     let trimmed: number;
@@ -224,7 +279,7 @@ export class DeDocument extends DeesElement {
       overallContentOffset = overallContentOffset + currentContentOffset;
 
       // Track pagination info for this page
-      this.paginationInfo.push({
+      paginationInfo.push({
         pageNumber: pageCounter,
         startOffset: pageStartOffset,
         contentLength: currentContentOffset,
@@ -235,6 +290,15 @@ export class DeDocument extends DeesElement {
       }
     }
 
+    if (!isCurrent()) {
+      // a later render shows the document: this one's pages are dropped
+      for (const cleanUp of [...cleanUpStoreCurrentRender, ...cleanUpStoreNextRender]) {
+        cleanUp.remove();
+      }
+      return;
+    }
+    this.paginationInfo = paginationInfo;
+
     for (const cleanUp of this.cleanupStore) {
       cleanUp.remove();
     }
@@ -275,6 +339,11 @@ export class DeDocument extends DeesElement {
       bubbles: true,
       composed: true,
     }));
+
+    await settleRendering(documentContainer);
+    if (isCurrent()) {
+      this.toggleAttribute("rendered", true);
+    }
   }
 
   async updated(