@vectojs/markdown 0.18.1 → 0.18.2

package/dist/Markdown.d.ts

@@ -94,14 +94,40 @@ export declare class Markdown extends UIComponent {
     saveFile: (filename: string, content: string, mimeType: string) => void;
     private activeBlockMetrics;
     /**
-     * Called after a streamed append has re-laid-out the document.
-     *
-     * Not required for a `VirtualList` to track a streaming row's height: the list
-     * re-reads `height` on every mounted row each frame, so it sees this entity grow
-     * without being told. Prefer that over wiring this up — it fires from the append
-     * path only, **not** from `setContent()`, so it is not a complete size signal.
+     * Called after this entity's own `width`/`height` changed because the document
+     * was re-laid-out. **This is the hook to wire up when a host has to move or
+     * resize anything positioned below the document.**
+     *
+     * Fires from three paths, all of which republish `width`/`height` from
+     * `content`:
+     *
+     * - a streamed append (`updateTokens`),
+     * - a width change ({@link setMaxWidth}),
+     * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+     *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+     *   on essentially every document containing an image, and a host that misses
+     *   it leaves every block below the image overlapping it.
+     *
+     * It does **not** fire from `setContent()`, which replaces the whole document
+     * and is a call the host already made, so this is a re-layout signal rather
+     * than a complete size signal.
+     *
+     * A `VirtualList` needs none of this to track a streaming row: it re-reads
+     * `height` on every mounted row each frame, so it sees this entity grow without
+     * being told. Prefer that where it applies. Reach for this callback when the
+     * host owns absolute positions of its own — a page that stacks navigation, a
+     * footer and a scroll height under the document has to recompute them here.
+     *
+     * There is no `onHeightChanged`. That name has been assigned by real callers
+     * through an `as unknown as` cast, which compiles, silences the type error and
+     * then never fires; if a layout callback appears dead, check the name first.
      */
     onLayoutUpdated?: () => void;
+    /**
+     * Latch for the miswired-hook warning, so a streaming document warns once
+     * rather than on every chunk.
+     */
+    private hasWarnedLayoutHookName;
     /**
      * The document's BODY text — everything after any front matter block.
      *
@@ -596,6 +622,23 @@ export declare class Markdown extends UIComponent {
      * level sees a freshly-sized child before it positions anything.
      */
     private reflowAfterImageResize;
+    /**
+     * Publish a completed re-layout to the host.
+     *
+     * Every path that republishes `width`/`height` from `content` ends here rather
+     * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+     * reached however the re-layout was triggered.
+     *
+     * The check exists because the failure it catches is silent and was found in
+     * production, not in review. A host wired its reflow to `onHeightChanged` — a
+     * name this class has never had — through an `as unknown as` cast. The cast
+     * satisfied the compiler, the callback never fired, and every post containing
+     * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+     * document scroll height. Nothing in the type system, the tests or the console
+     * said anything. A property that is *only ever assigned* has no read site to
+     * fail, so the one place that can notice is the moment we would have called it.
+     */
+    private notifyLayoutUpdated;
     /**
      * Re-derive one `MarkdownContainer`'s cached box from its children.
      *

package/dist/index.js

@@ -2787,6 +2787,12 @@ import_marked.marked.use({
     }
   ]
 });
+var MISWIRED_LAYOUT_HOOK_NAMES = [
+  "onHeightChanged",
+  "onHeightChange",
+  "onLayoutUpdate",
+  "onResize"
+];
 var markdownWorker = null;
 var workerIdCounter = 0;
 var workerInstanceCounter = 0;
@@ -2854,14 +2860,40 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
   saveFile;
   activeBlockMetrics = null;
   /**
-   * Called after a streamed append has re-laid-out the document.
+   * Called after this entity's own `width`/`height` changed because the document
+   * was re-laid-out. **This is the hook to wire up when a host has to move or
+   * resize anything positioned below the document.**
+   *
+   * Fires from three paths, all of which republish `width`/`height` from
+   * `content`:
+   *
+   * - a streamed append (`updateTokens`),
+   * - a width change ({@link setMaxWidth}),
+   * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+   *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+   *   on essentially every document containing an image, and a host that misses
+   *   it leaves every block below the image overlapping it.
    *
-   * Not required for a `VirtualList` to track a streaming row's height: the list
-   * re-reads `height` on every mounted row each frame, so it sees this entity grow
-   * without being told. Prefer that over wiring this up — it fires from the append
-   * path only, **not** from `setContent()`, so it is not a complete size signal.
+   * It does **not** fire from `setContent()`, which replaces the whole document
+   * and is a call the host already made, so this is a re-layout signal rather
+   * than a complete size signal.
+   *
+   * A `VirtualList` needs none of this to track a streaming row: it re-reads
+   * `height` on every mounted row each frame, so it sees this entity grow without
+   * being told. Prefer that where it applies. Reach for this callback when the
+   * host owns absolute positions of its own — a page that stacks navigation, a
+   * footer and a scroll height under the document has to recompute them here.
+   *
+   * There is no `onHeightChanged`. That name has been assigned by real callers
+   * through an `as unknown as` cast, which compiles, silences the type error and
+   * then never fires; if a layout callback appears dead, check the name first.
    */
   onLayoutUpdated;
+  /**
+   * Latch for the miswired-hook warning, so a streaming document warns once
+   * rather than on every chunk.
+   */
+  hasWarnedLayoutHookName = false;
   /**
    * The document's BODY text — everything after any front matter block.
    *
@@ -3312,7 +3344,7 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.content.layout();
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
     this.scene?.markDirty();
     return this;
   }
@@ -4182,7 +4214,40 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     }
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
+  }
+  /**
+   * Publish a completed re-layout to the host.
+   *
+   * Every path that republishes `width`/`height` from `content` ends here rather
+   * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+   * reached however the re-layout was triggered.
+   *
+   * The check exists because the failure it catches is silent and was found in
+   * production, not in review. A host wired its reflow to `onHeightChanged` — a
+   * name this class has never had — through an `as unknown as` cast. The cast
+   * satisfied the compiler, the callback never fired, and every post containing
+   * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+   * document scroll height. Nothing in the type system, the tests or the console
+   * said anything. A property that is *only ever assigned* has no read site to
+   * fail, so the one place that can notice is the moment we would have called it.
+   */
+  notifyLayoutUpdated() {
+    if (this.onLayoutUpdated) {
+      this.onLayoutUpdated();
+      return;
+    }
+    if (!this.hasWarnedLayoutHookName) {
+      const wrongName = MISWIRED_LAYOUT_HOOK_NAMES.find(
+        (name) => typeof this[name] === "function"
+      );
+      if (wrongName) {
+        this.hasWarnedLayoutHookName = true;
+        console.warn(
+          `[VectoJS] Markdown.${wrongName} is not a VectoJS callback and will never fire. The document just re-laid-out and nothing was notified. Assign \`onLayoutUpdated\` instead \u2014 anything positioned below the document needs it, and a paragraph image corrects its guessed aspect ratio on decode, so a missed signal leaves following blocks overlapping the image.`
+        );
+      }
+    }
   }
   /**
    * Re-derive one `MarkdownContainer`'s cached box from its children.
@@ -4993,9 +5058,7 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.width = this.content.width;
     this.height = this.content.height;
     this.scene?.markDirty();
-    if (this.onLayoutUpdated) {
-      this.onLayoutUpdated();
-    }
+    this.notifyLayoutUpdated();
   }
   /**
    * Render one nested block with a temporary width/margin context while

package/dist/index.mjs

@@ -2735,6 +2735,12 @@ marked.use({
     }
   ]
 });
+var MISWIRED_LAYOUT_HOOK_NAMES = [
+  "onHeightChanged",
+  "onHeightChange",
+  "onLayoutUpdate",
+  "onResize"
+];
 var markdownWorker = null;
 var workerIdCounter = 0;
 var workerInstanceCounter = 0;
@@ -2802,14 +2808,40 @@ var Markdown = class _Markdown extends UIComponent3 {
   saveFile;
   activeBlockMetrics = null;
   /**
-   * Called after a streamed append has re-laid-out the document.
+   * Called after this entity's own `width`/`height` changed because the document
+   * was re-laid-out. **This is the hook to wire up when a host has to move or
+   * resize anything positioned below the document.**
+   *
+   * Fires from three paths, all of which republish `width`/`height` from
+   * `content`:
+   *
+   * - a streamed append (`updateTokens`),
+   * - a width change ({@link setMaxWidth}),
+   * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+   *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+   *   on essentially every document containing an image, and a host that misses
+   *   it leaves every block below the image overlapping it.
    *
-   * Not required for a `VirtualList` to track a streaming row's height: the list
-   * re-reads `height` on every mounted row each frame, so it sees this entity grow
-   * without being told. Prefer that over wiring this up — it fires from the append
-   * path only, **not** from `setContent()`, so it is not a complete size signal.
+   * It does **not** fire from `setContent()`, which replaces the whole document
+   * and is a call the host already made, so this is a re-layout signal rather
+   * than a complete size signal.
+   *
+   * A `VirtualList` needs none of this to track a streaming row: it re-reads
+   * `height` on every mounted row each frame, so it sees this entity grow without
+   * being told. Prefer that where it applies. Reach for this callback when the
+   * host owns absolute positions of its own — a page that stacks navigation, a
+   * footer and a scroll height under the document has to recompute them here.
+   *
+   * There is no `onHeightChanged`. That name has been assigned by real callers
+   * through an `as unknown as` cast, which compiles, silences the type error and
+   * then never fires; if a layout callback appears dead, check the name first.
    */
   onLayoutUpdated;
+  /**
+   * Latch for the miswired-hook warning, so a streaming document warns once
+   * rather than on every chunk.
+   */
+  hasWarnedLayoutHookName = false;
   /**
    * The document's BODY text — everything after any front matter block.
    *
@@ -3260,7 +3292,7 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.content.layout();
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
     this.scene?.markDirty();
     return this;
   }
@@ -4130,7 +4162,40 @@ var Markdown = class _Markdown extends UIComponent3 {
     }
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
+  }
+  /**
+   * Publish a completed re-layout to the host.
+   *
+   * Every path that republishes `width`/`height` from `content` ends here rather
+   * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+   * reached however the re-layout was triggered.
+   *
+   * The check exists because the failure it catches is silent and was found in
+   * production, not in review. A host wired its reflow to `onHeightChanged` — a
+   * name this class has never had — through an `as unknown as` cast. The cast
+   * satisfied the compiler, the callback never fired, and every post containing
+   * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+   * document scroll height. Nothing in the type system, the tests or the console
+   * said anything. A property that is *only ever assigned* has no read site to
+   * fail, so the one place that can notice is the moment we would have called it.
+   */
+  notifyLayoutUpdated() {
+    if (this.onLayoutUpdated) {
+      this.onLayoutUpdated();
+      return;
+    }
+    if (!this.hasWarnedLayoutHookName) {
+      const wrongName = MISWIRED_LAYOUT_HOOK_NAMES.find(
+        (name) => typeof this[name] === "function"
+      );
+      if (wrongName) {
+        this.hasWarnedLayoutHookName = true;
+        console.warn(
+          `[VectoJS] Markdown.${wrongName} is not a VectoJS callback and will never fire. The document just re-laid-out and nothing was notified. Assign \`onLayoutUpdated\` instead \u2014 anything positioned below the document needs it, and a paragraph image corrects its guessed aspect ratio on decode, so a missed signal leaves following blocks overlapping the image.`
+        );
+      }
+    }
   }
   /**
    * Re-derive one `MarkdownContainer`'s cached box from its children.
@@ -4941,9 +5006,7 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.width = this.content.width;
     this.height = this.content.height;
     this.scene?.markDirty();
-    if (this.onLayoutUpdated) {
-      this.onLayoutUpdated();
-    }
+    this.notifyLayoutUpdated();
   }
   /**
    * Render one nested block with a temporary width/margin context while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "publishConfig": {
     "access": "public"
   },