@fusion.dev/helix 0.205.0 → 0.205.1

package/custom-elements.json

@@ -178501,7 +178501,7 @@
               }
             }
           ],
-          "description": "Serves the frame side of a sandbox preview, in the document its `src` loads.\n\nCall it once from that document, after the elements your examples use are\ndefined. It does what the preview's protocol asks of a frame:\n\n- Posts `helix-preview-ready` once it listens.\n- Writes each `helix-preview-render` into the root: the markup, the\n  stylesheet, the direction, the layout and the color mode. Scripts in the\n  markup run.\n- Posts every console call, uncaught error, and unhandled promise rejection\n  as `helix-preview-console`, an uncaught one marked `uncaught`, which marks\n  the preview `failed`.\n- Posts `helix-preview-size` whenever what was drawn changes height.\n- Posts `helix-preview-press` on every press, so menus outside close.\n\nOnly a message from the parent window is rendered. Answers go to `*`, which\nis the only target a sandboxed frame can name, and carry only what the\nexample itself wrote."
+          "description": "Serves the frame side of a sandbox preview, in the document its `src` loads.\n\nCall it once from that document, after the elements your examples use are\ndefined. It does what the preview's protocol asks of a frame:\n\n- Posts `helix-preview-ready` once it listens.\n- Writes each `helix-preview-render` into the root: the markup, the\n  stylesheet, the direction, the layout and the color mode. Scripts in the\n  markup run.\n- Posts every console call, uncaught error, and unhandled promise rejection\n  as `helix-preview-console`, an uncaught one marked `uncaught`, which marks\n  the preview `failed`.\n- Posts `helix-preview-rendered` after each render, which shows a frame\n  the preview held transparent until it drew.\n- Posts `helix-preview-size` whenever what was drawn changes height.\n- Posts `helix-preview-press` on every press, so menus outside close.\n\nOnly a message from the parent window is rendered. Answers go to `*`, which\nis the only target a sandboxed frame can name, and carry only what the\nexample itself wrote."
         },
         {
           "kind": "function",
@@ -179240,6 +179240,54 @@
               "default": "new DelayController(this, { renders: false })",
               "description": "Holds a coalesced send, so only one is ever queued, and drops it on\ndisconnect.\n\n**It renders nothing**, so it asks for no update when its wait starts or\nends. One that did sent the source at once from that update, ahead of the\nwait, and the send at the end of the wait then cleared `failed` after the\nerror it should have reported."
             },
+            {
+              "kind": "field",
+              "name": "patience",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DelayController(this, { renders: false })",
+              "description": "Shows a frame that was sent an example and never said it drew it."
+            },
+            {
+              "kind": "field",
+              "name": "blank",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the frame has drawn nothing since its document started loading."
+            },
+            {
+              "kind": "method",
+              "name": "setBlank",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "on",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Marks the frame `blank`, or shown."
+            },
+            {
+              "kind": "method",
+              "name": "drawn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "The frame has drawn an example, so it is shown."
+            },
             {
               "kind": "method",
               "name": "scheduleSend",
@@ -179844,6 +179892,10 @@
             }
           ],
           "cssStates": [
+            {
+              "description": "From the moment the frame's document starts loading until it has drawn an example. The styled tier keeps the frame transparent meanwhile, so a document that has not yet drawn in the page's color mode does not show as a white flash.",
+              "name": "blank"
+            },
             {
               "description": "Since the example threw an error it did not catch, until the next source is sent.",
               "name": "failed"
@@ -272893,6 +272945,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix",
-    "version": "0.205.0"
+    "version": "0.205.1"
   }
 }

package/dist/sandbox/frame.d.ts

@@ -54,6 +54,8 @@ export declare const loggedText: (value: unknown) => string;
  * - Posts every console call, uncaught error, and unhandled promise rejection
  *   as `helix-preview-console`, an uncaught one marked `uncaught`, which marks
  *   the preview `failed`.
+ * - Posts `helix-preview-rendered` after each render, which shows a frame
+ *   the preview held transparent until it drew.
  * - Posts `helix-preview-size` whenever what was drawn changes height.
  * - Posts `helix-preview-press` on every press, so menus outside close.
  *

package/dist/sandbox/frame.js

@@ -124,6 +124,7 @@ const serveWith = (tools, options = {}) => {
         sheet.textContent = styles;
         options.onRender?.(root, fresh);
         measure();
+        post({ type: 'helix-preview-rendered' });
     };
     const watcher = new ResizeObserver(measure);
     const watch = () => {

package/dist/sandbox/preview/sandbox-preview.css.js

@@ -1,2 +1,2 @@
 import { createSheet } from '@fusion.dev/helix-core';
-export const styles = createSheet(`:host {display: block;min-block-size: 0;position: relative}[part="frame"] {background-color: var(--helix-color-background);block-size: 100%;border: none;display: block;inline-size: 100%}[part="error"] {background-color: var(--helix-color-background);box-sizing: border-box;color: var(--helix-color-danger);font-family: var(--helix-font-mono);font-size: var(--helix-text-xs);inset: 0;line-height: var(--helix-leading-normal);margin: var(--helix-space-none);overflow: auto;padding: var(--helix-space-md);position: absolute;white-space: pre-wrap;word-break: break-word}[part="controls"] {display: flex;font-family: var(--helix-font-sans);font-size: var(--helix-text-xs);gap: var(--helix-space-2xs);inset-block-end: var(--helix-space-xs);inset-inline-end: var(--helix-space-xs);position: absolute}[part="reload"], [part="open"] {background-color: var(--helix-color-surface);border: var(--helix-border-thin) solid var(--helix-color-border);border-radius: var(--helix-radii-sm);color: var(--helix-color-foreground);cursor: pointer;font: inherit;padding: var(--helix-space-2xs) var(--helix-space-xs)}[part="reload"]:hover, [part="open"]:hover {background-color: var(--helix-color-surface-sunken)}[part="reload"]:focus-visible, [part="open"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset)}`);
+export const styles = createSheet(`:host {display: block;min-block-size: 0;position: relative}[part="frame"] {background-color: var(--helix-color-background);block-size: 100%;border: none;display: block;inline-size: 100%}[part="error"] {background-color: var(--helix-color-background);box-sizing: border-box;color: var(--helix-color-danger);font-family: var(--helix-font-mono);font-size: var(--helix-text-xs);inset: 0;line-height: var(--helix-leading-normal);margin: var(--helix-space-none);overflow: auto;padding: var(--helix-space-md);position: absolute;white-space: pre-wrap;word-break: break-word}[part="controls"] {display: flex;font-family: var(--helix-font-sans);font-size: var(--helix-text-xs);gap: var(--helix-space-2xs);inset-block-end: var(--helix-space-xs);inset-inline-end: var(--helix-space-xs);position: absolute}[part="reload"], [part="open"] {background-color: var(--helix-color-surface);border: var(--helix-border-thin) solid var(--helix-color-border);border-radius: var(--helix-radii-sm);color: var(--helix-color-foreground);cursor: pointer;font: inherit;padding: var(--helix-space-2xs) var(--helix-space-xs)}[part="reload"]:hover, [part="open"]:hover {background-color: var(--helix-color-surface-sunken)}[part="reload"]:focus-visible, [part="open"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: var(--helix-size-focus-offset)}:host(:state(blank)) [part="frame"] {opacity: 0}`);

package/dist/sandbox/preview/sandbox-preview.d.ts

@@ -35,12 +35,16 @@ export interface PreviewConsole {
 export interface PreviewPress {
     type: 'helix-preview-press';
 }
+/** The frame saying it has drawn the example it was sent. */
+export interface PreviewRendered {
+    type: 'helix-preview-rendered';
+}
 /** How tall the frame says its content is, in CSS pixels. */
 export interface PreviewSize {
     size: number;
     type: 'helix-preview-size';
 }
-export type PreviewMessage = PreviewConsole | PreviewFetch | PreviewPress | PreviewReady | PreviewRender | PreviewSize;
+export type PreviewMessage = PreviewConsole | PreviewFetch | PreviewPress | PreviewReady | PreviewRender | PreviewRendered | PreviewSize;
 /**
  * @summary A frame that renders sandbox source in a separate document.
  *
@@ -140,6 +144,7 @@ export type PreviewMessage = PreviewConsole | PreviewFetch | PreviewPress | Prev
  * @csspart open - The button that opens the example in a new tab, under `controls`.
  * @csspart reload - The button that reloads the frame's document, under `controls`.
  *
+ * @cssstate blank - From the moment the frame's document starts loading until it has drawn an example. The styled tier keeps the frame transparent meanwhile, so a document that has not yet drawn in the page's color mode does not show as a white flash.
  * @cssstate failed - Since the example threw an error it did not catch, until the next source is sent.
  * @cssstate loading - While the frame's document loads, until it can take the example.
  */
@@ -368,6 +373,14 @@ export declare class HelixSandboxPreview extends HelixElement {
      * error it should have reported.
      */
     private readonly settle;
+    /** Shows a frame that was sent an example and never said it drew it. */
+    private readonly patience;
+    /** Whether the frame has drawn nothing since its document started loading. */
+    private blank;
+    /** Marks the frame `blank`, or shown. */
+    private setBlank;
+    /** The frame has drawn an example, so it is shown. */
+    private drawn;
     /**
      * Sends once the typing stops, replacing anything already waiting.
      *

package/dist/sandbox/preview/sandbox-preview.js

@@ -2,6 +2,7 @@ var HelixSandboxPreview_1;
 import { __decorate } from "tslib";
 import { customElement, DelayController, HelixConsoleEvent, HelixElement, HelixResizeEvent, words, } from '@fusion.dev/helix-core';
 const SETTLE = 120;
+const PAINT_PATIENCE = 1000;
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { COMPILED, compile } from '../compile.js';
@@ -47,6 +48,9 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
                 this.handleFrameLoad();
                 return;
             }
+            if (data?.type === 'helix-preview-rendered' || data?.type === 'helix-preview-size') {
+                this.drawn();
+            }
             if (data?.type === 'helix-preview-console') {
                 this.dispatchEvent(new HelixConsoleEvent({ level: data.level, text: data.text }));
                 if (data.uncaught) {
@@ -62,6 +66,8 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
             }
         };
         this.settle = new DelayController(this, { renders: false });
+        this.patience = new DelayController(this, { renders: false });
+        this.blank = false;
         this.loadedMap = '';
     }
     static { HelixSandboxPreview_1 = this; }
@@ -139,6 +145,14 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
         });
     }
     static { this.target = '*'; }
+    setBlank(on) {
+        this.blank = on;
+        this.toggleState('blank', on);
+    }
+    drawn() {
+        this.patience.cancel();
+        this.setBlank(false);
+    }
     scheduleSend() {
         this.settle.start(SETTLE, () => {
             if (this.sending !== this.failedSource) {
@@ -163,6 +177,9 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
         }
         this.frame?.contentWindow?.postMessage(this.message, HelixSandboxPreview_1.target);
         this.sentSource = this.sending;
+        if (this.blank) {
+            this.patience.start(PAINT_PATIENCE, () => this.drawn());
+        }
     }
     open() {
         const tab = window.open('', '_blank');
@@ -223,7 +240,9 @@ frame.onload = () => frame.contentWindow.postMessage(${JSON.stringify(this.messa
         this.sentSource = undefined;
         this.failedSource = undefined;
         this.fail();
+        this.patience.cancel();
         this.toggleState('loading', true);
+        this.setBlank(true);
     }
     willUpdate(changed) {
         super.willUpdate(changed);