@fusion.dev/helix 0.0.0-dev → 0.0.3

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

@@ -20,12 +20,24 @@ export interface PreviewConsole {
     text: string;
     type: 'helix-preview-console';
 }
+/**
+ * A press inside the frame, which is the one event the page cannot see for
+ * itself.
+ *
+ * Carries nothing. What the page needs to know is that a reader pressed
+ * something here, not where: every overlay outside is dismissed by the fact of
+ * the press, and coordinates in the frame's viewport would not mean anything in
+ * the page's anyway.
+ */
+export interface PreviewPress {
+    type: 'helix-preview-press';
+}
 /** How tall the frame says its content is, in CSS pixels. */
 export interface PreviewSize {
     size: number;
     type: 'helix-preview-size';
 }
-export type PreviewMessage = PreviewConsole | PreviewReady | PreviewRender | PreviewSize;
+export type PreviewMessage = PreviewConsole | PreviewPress | PreviewReady | PreviewRender | PreviewSize;
 /**
  * @summary Renders sandbox source in a frame of its own.
  *
@@ -47,32 +59,25 @@ export type PreviewMessage = PreviewConsole | PreviewReady | PreviewRender | Pre
  * consumer's document rather than something guessed at here.
  *
  * **The source is not trusted, and the frame is what makes that safe.**
- * `fullscreen` is granted for the same reason and found the same way: a video
- * in the preview offered a fullscreen button that did nothing at all, because
- * the policy default is `self`, this frame is not `self`, and a denied request
- * rejects a promise nobody was watching. Two capabilities now, both explicit,
- * both starred.
- *
- * `allow="clipboard-write *"` is granted explicitly, and the star matters: the
- * policy defaults to `self` and this frame has an opaque origin, so it is not
- * `self` and the default denies it. A component inside the preview that copies
- * to the clipboard is otherwise a control that silently does nothing, which is
- * how this was found. Nothing else is granted, and a copy still needs the
- * reader's own gesture.
- *
  * `sandbox="allow-scripts"` and no `allow-same-origin`, so the document runs on
  * an opaque origin: script in an example cannot reach this page, its storage,
  * its cookies, or the editor the source was typed into. Without it they could,
  * measured, through an `onerror` handler on an image that fails to load, which
- * `innerHTML` does not strip the way it refuses a `<script>` tag.
- *
- * That is what lets a sandbox hold markup a reader pasted from somewhere, or
- * one day arrived in a shared link, rather than only what its owner typed.
+ * `innerHTML` does not strip the way it refuses a `<script>` tag. That is what
+ * lets a sandbox hold markup a reader pasted from somewhere, or one day arrived
+ * in a shared link, rather than only what its owner typed.
  *
  * `allow-forms` is granted because examples have forms in them and a submit
  * that silently does nothing is a worse lie than one that navigates a frame
  * nobody is looking at. Top-level navigation, popups and modals are not.
  *
+ * **`allow="clipboard-write *; fullscreen *"`, and the stars matter.** Both
+ * policies default to `self`, and a frame on an opaque origin is not `self`, so
+ * the default denies both: a component that copies to the clipboard and a video
+ * offering a fullscreen button each become a control that silently does nothing,
+ * a denied request rejecting a promise nobody was watching. Nothing else is
+ * granted, and a copy still needs the reader's own gesture.
+ *
  * @since 0.1.0
  * @status experimental
  * @aliases Result, Output
@@ -97,47 +102,47 @@ export declare class HelixSandboxPreview extends HelixElement {
      * It matters more than a background: `light-dark()` is compiled to a shim
      * keyed on this attribute, and of the 56 tokens that differ by scheme the
      * theme engine emits 19. The other 37 would stay light in a dark preview,
-     * including every one of the 24 series colours a chart reads.
+     * including every one of the 24 series colors a chart reads.
      */
     colorMode?: 'dark' | 'light';
     /**
-     * Document the frame loads, which brings the styles and the elements.
+     * Writing direction inside the frame.
      */
-    src: string;
+    direction?: 'rtl';
     /**
-     * Markup to render.
+     * Accessible name for the frame.
      */
-    source: string;
+    label: string;
     /**
-     * Stylesheet applied inside the frame, alongside the markup.
+     * How the example is placed in the frame.
      */
-    styles: string;
+    layout?: 'padded' | 'centered' | 'fullscreen' | 'hug';
     /**
-     * Accessible name for the frame.
+     * Markup to render.
      */
-    label: string;
+    source: string;
     /**
-     * Writing direction inside the frame.
+     * Document the frame loads, which brings the styles and the elements.
      */
-    direction?: 'rtl';
+    src: string;
     /**
-     * How the example is placed in the frame.
+     * Stylesheet applied inside the frame, alongside the markup.
      */
-    layout?: 'padded' | 'centered' | 'fullscreen' | 'hug';
+    styles: string;
     /** Whether the frame has said it is listening. */
     private ready;
     private get frame();
     /**
      * The frame's document has finished loading, so its listener exists.
      *
-     * **The announcement is one shot and the parent can miss it.** The frame
-     * posts `helix-preview-ready` at the end of its own module evaluation and
-     * never repeats it, and `handleMessage` drops anything whose `source` is not
+     * **The announcement is one shot and the parent can miss it.** The frame posts
+     * `helix-preview-ready` at the end of its own module evaluation and never
+     * repeats it, and `handleMessage` drops anything whose `source` is not
      * `this.frame?.contentWindow`. That getter reads the render root, so it is
-     * null until this element has rendered once. A frame that loads before that
-     * render commits therefore announces into a guard that refuses it, `ready`
-     * stays false, and `send` returns early forever: the source is set, the
-     * markup is correct, and the preview is blank with nothing logged.
+     * null until this element has rendered once: a frame that loads before that
+     * render commits announces into a guard that refuses it, `ready` stays false,
+     * and `send` returns early forever, leaving the source set, the markup
+     * correct, and the preview blank with nothing logged.
      *
      * **It is a race, so it hides in the one place nobody looks.** The frame is
      * only fast enough to win when its document and its bundle are already in the
@@ -186,12 +191,11 @@ export declare class HelixSandboxPreview extends HelixElement {
     /**
      * Sends once the typing stops, replacing anything already waiting.
      *
-     * A frame was tried first and is the wrong unit. Keystrokes arrive fifty to a
-     * hundred and fifty milliseconds apart, so each one lands in a frame of its
-     * own and coalescing by frame coalesces nothing: the example was still being
-     * rebuilt per character. The delay has to be longer than the gap between
-     * keystrokes to catch a burst, and short enough to read as immediate when the
-     * typing stops.
+     * A frame is the wrong unit. Keystrokes arrive fifty to a hundred and fifty
+     * milliseconds apart, so each one lands in a frame of its own and coalescing
+     * by frame coalesces nothing, leaving the example rebuilt per character. The
+     * delay has to be longer than the gap between keystrokes to catch a burst, and
+     * short enough to read as immediate when the typing stops.
      */
     private scheduleSend;
     /** Sends the current source to the frame, once it is listening. */

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

@@ -38,32 +38,25 @@ import { styles as sheet } from './sandbox-preview.css.js';
  * consumer's document rather than something guessed at here.
  *
  * **The source is not trusted, and the frame is what makes that safe.**
- * `fullscreen` is granted for the same reason and found the same way: a video
- * in the preview offered a fullscreen button that did nothing at all, because
- * the policy default is `self`, this frame is not `self`, and a denied request
- * rejects a promise nobody was watching. Two capabilities now, both explicit,
- * both starred.
- *
- * `allow="clipboard-write *"` is granted explicitly, and the star matters: the
- * policy defaults to `self` and this frame has an opaque origin, so it is not
- * `self` and the default denies it. A component inside the preview that copies
- * to the clipboard is otherwise a control that silently does nothing, which is
- * how this was found. Nothing else is granted, and a copy still needs the
- * reader's own gesture.
- *
  * `sandbox="allow-scripts"` and no `allow-same-origin`, so the document runs on
  * an opaque origin: script in an example cannot reach this page, its storage,
  * its cookies, or the editor the source was typed into. Without it they could,
  * measured, through an `onerror` handler on an image that fails to load, which
- * `innerHTML` does not strip the way it refuses a `<script>` tag.
- *
- * That is what lets a sandbox hold markup a reader pasted from somewhere, or
- * one day arrived in a shared link, rather than only what its owner typed.
+ * `innerHTML` does not strip the way it refuses a `<script>` tag. That is what
+ * lets a sandbox hold markup a reader pasted from somewhere, or one day arrived
+ * in a shared link, rather than only what its owner typed.
  *
  * `allow-forms` is granted because examples have forms in them and a submit
  * that silently does nothing is a worse lie than one that navigates a frame
  * nobody is looking at. Top-level navigation, popups and modals are not.
  *
+ * **`allow="clipboard-write *; fullscreen *"`, and the stars matter.** Both
+ * policies default to `self`, and a frame on an opaque origin is not `self`, so
+ * the default denies both: a component that copies to the clipboard and a video
+ * offering a fullscreen button each become a control that silently does nothing,
+ * a denied request rejecting a promise nobody was watching. Nothing else is
+ * granted, and a copy still needs the reader's own gesture.
+ *
  * @since 0.1.0
  * @status experimental
  * @aliases Result, Output
@@ -78,34 +71,34 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
     constructor() {
         super(...arguments);
         /**
-         * Document the frame loads, which brings the styles and the elements.
+         * Accessible name for the frame.
          */
-        this.src = '';
+        this.label = 'Preview';
         /**
          * Markup to render.
          */
         this.source = '';
         /**
-         * Stylesheet applied inside the frame, alongside the markup.
+         * Document the frame loads, which brings the styles and the elements.
          */
-        this.styles = '';
+        this.src = '';
         /**
-         * Accessible name for the frame.
+         * Stylesheet applied inside the frame, alongside the markup.
          */
-        this.label = 'Preview';
+        this.styles = '';
         /** Whether the frame has said it is listening. */
         this.ready = false;
         /**
          * The frame's document has finished loading, so its listener exists.
          *
-         * **The announcement is one shot and the parent can miss it.** The frame
-         * posts `helix-preview-ready` at the end of its own module evaluation and
-         * never repeats it, and `handleMessage` drops anything whose `source` is not
+         * **The announcement is one shot and the parent can miss it.** The frame posts
+         * `helix-preview-ready` at the end of its own module evaluation and never
+         * repeats it, and `handleMessage` drops anything whose `source` is not
          * `this.frame?.contentWindow`. That getter reads the render root, so it is
-         * null until this element has rendered once. A frame that loads before that
-         * render commits therefore announces into a guard that refuses it, `ready`
-         * stays false, and `send` returns early forever: the source is set, the
-         * markup is correct, and the preview is blank with nothing logged.
+         * null until this element has rendered once: a frame that loads before that
+         * render commits announces into a guard that refuses it, `ready` stays false,
+         * and `send` returns early forever, leaving the source set, the markup
+         * correct, and the preview blank with nothing logged.
          *
          * **It is a race, so it hides in the one place nobody looks.** The frame is
          * only fast enough to win when its document and its bundle are already in the
@@ -152,6 +145,29 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
             if (event.data?.type === 'helix-preview-console') {
                 this.dispatchEvent(new HelixConsoleEvent({ level: event.data.level, text: event.data.text }));
             }
+            /* **A press in the frame, put back into the page as a press.**
+             *
+             * The frame is on an opaque origin, which is the point of it, and a
+             * consequence is that a press inside is invisible outside: the event does
+             * not cross the boundary, the document cannot listen to a document it may
+             * not touch, and in WebKit the press moves no focus and blurs no window
+             * either, so there is nothing at all to infer it from. Measured: with the
+             * sandbox's settings menu open, pressing the component it configures left
+             * the menu standing over it, and the only way out was Escape or the trigger.
+             *
+             * So the frame reports it and this element re-states it where the page can
+             * hear it. A real `pointerdown` rather than a name of our own, because
+             * every light-dismiss in the library — and every one a consumer wrote —
+             * already listens for exactly that, and what happened *was* a press. It
+             * carries no coordinates for the reason the message does not: this element
+             * is where it happened, as far as the page is concerned.
+             *
+             * `composed` so it leaves whatever shadow root this element sits in, which
+             * is how those listeners find it in the path.
+             */
+            if (event.data?.type === 'helix-preview-press') {
+                this.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, composed: true }));
+            }
             /* Relayed rather than acted on. What the frame measured is a fact about the
                example; how much room to give it is a decision, and it belongs to
                whatever laid this element out. A preview that resized itself would be
@@ -180,12 +196,11 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
     /**
      * Sends once the typing stops, replacing anything already waiting.
      *
-     * A frame was tried first and is the wrong unit. Keystrokes arrive fifty to a
-     * hundred and fifty milliseconds apart, so each one lands in a frame of its
-     * own and coalescing by frame coalesces nothing: the example was still being
-     * rebuilt per character. The delay has to be longer than the gap between
-     * keystrokes to catch a burst, and short enough to read as immediate when the
-     * typing stops.
+     * A frame is the wrong unit. Keystrokes arrive fifty to a hundred and fifty
+     * milliseconds apart, so each one lands in a frame of its own and coalescing
+     * by frame coalesces nothing, leaving the example rebuilt per character. The
+     * delay has to be longer than the gap between keystrokes to catch a burst, and
+     * short enough to read as immediate when the typing stops.
      */
     scheduleSend() {
         clearTimeout(this.pending);
@@ -252,12 +267,10 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
          *
          * The frame renders by assigning `innerHTML`, which throws away the example
          * and builds it again, and every custom element in it disconnects and
-         * upgrades a second time. Sent on each update, that happened once per
-         * keystroke: an example of any size was being torn down and rebuilt for
-         * every character, and the work grows with the example while the typing
-         * does not.
+         * upgrades a second time. Sent on each update that is once per keystroke,
+         * and the work grows with the example while the typing does not.
          *
-         * A frame is short enough to feel immediate and long enough that a burst of
+         * `SETTLE` is short enough to feel immediate and long enough that a burst of
          * keystrokes is one render. Layout, direction and the color mode go
          * straight out: they arrive one at a time from a menu, there is nothing to
          * coalesce, and a delay there is a delay a reader can see. */
@@ -282,24 +295,24 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
 __decorate([
     property({ attribute: 'color-mode' })
 ], HelixSandboxPreview.prototype, "colorMode", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixSandboxPreview.prototype, "direction", void 0);
 __decorate([
     property()
-], HelixSandboxPreview.prototype, "src", void 0);
+], HelixSandboxPreview.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixSandboxPreview.prototype, "layout", void 0);
 __decorate([
     property()
 ], HelixSandboxPreview.prototype, "source", void 0);
 __decorate([
     property()
-], HelixSandboxPreview.prototype, "styles", void 0);
+], HelixSandboxPreview.prototype, "src", void 0);
 __decorate([
     property()
-], HelixSandboxPreview.prototype, "label", void 0);
-__decorate([
-    property({ reflect: true })
-], HelixSandboxPreview.prototype, "direction", void 0);
-__decorate([
-    property({ reflect: true })
-], HelixSandboxPreview.prototype, "layout", void 0);
+], HelixSandboxPreview.prototype, "styles", void 0);
 HelixSandboxPreview = HelixSandboxPreview_1 = __decorate([
     customElement('helix-sandbox-preview')
 ], HelixSandboxPreview);

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

@@ -1,4 +1,4 @@
-// Generated from src/sandbox/root/sandbox-root.css by `bun run styles`. Do not edit.
+// Generated from src/sandbox/root/sandbox-root.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 background-color: var(--helix-color-background);
@@ -14,7 +14,6 @@ grid-row: 1;
 
 [part="body"] {
 grid-row: 2;
-min-block-size: 0;
 }
 
 ::slotted([slot="status"]) {

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

@@ -18,12 +18,9 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * a React component into the preview.
  *
  * **The dividers are two nested `helix-splitter`s, not a grid this element
- * drags itself.** It had its own: a five row grid, a stylesheet written to on
- * every pointer move, three pointer handlers, a keyboard handler reading which
- * axes each divider was allowed to move, and a corner placed by hand into the
- * cell where two tracks met. All of it is the splitter's now, including the
- * corner, which arrives on its own wherever a nested splitter crosses the one it
- * is in.
+ * drags itself.** The pointer handling, the keyboard handling and the corner are
+ * all the splitter's, and the corner arrives on its own wherever a nested
+ * splitter crosses the one it is in.
  *
  * The panes are the inner splitter and the panel is the outer one, which is the
  * order that makes the panel span the full width: the outer divider runs edge to
@@ -72,9 +69,29 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  */
 export declare class HelixSandbox extends HelixElement {
     /**
-     * Whether the panes sit side by side or stacked.
+     * Accessible name for the divider that moves both at once.
      */
-    orientation?: 'horizontal' | 'vertical';
+    cornerLabel: string;
+    /**
+     * What a reset makes the panel, in pixels.
+     *
+     * The pair to `panel-size`.
+     */
+    defaultPanelSize: number;
+    /**
+     * Where a reset puts the divider, where nothing declared it.
+     *
+     * Separate from `split` for the reason `Splitter` keeps `default-position`
+     * separate from `position`. Resetting to whatever `split` held on the first
+     * render is the declared arrangement only where nobody owns the property: the
+     * workbench does, and restores it from the address bar and from storage, so the
+     * first value it holds is the reader's last session and a reset puts the
+     * sandbox back to the size it already was.
+     *
+     * Declared rather than captured, so it is a number a consumer states and can
+     * change, and it needs no first frame to be read on.
+     */
+    defaultSplit: number;
     /**
      * Which pane comes first, before the divider.
      *
@@ -94,35 +111,9 @@ export declare class HelixSandbox extends HelixElement {
      */
     lead: 'source' | 'preview';
     /**
-     * Percentage of the sandbox given to the source pane.
-     */
-    split: number;
-    /**
-     * Where a reset puts the divider, where nothing declared it.
-     *
-     * Separate from `split` for the reason `Splitter` keeps `default-position`
-     * separate from `position`, and the bug is worth recording because this
-     * element had it after that one was fixed. A double click reset to whatever
-     * `split` held on the first render, which is the declared arrangement only
-     * when nobody owns the property. The workbench owns it, restores it from the
-     * address bar and from storage, so the first value it ever held was the
-     * reader's last session: double clicking reset the sandbox to the size it
-     * already was, which is to say it did nothing at all.
-     *
-     * Declared rather than captured, so it is a number a consumer states and can
-     * change, and it needs no first frame to be read on.
-     */
-    defaultSplit: number;
-    /**
-     * Height of the panel, in pixels.
-     */
-    panelSize: number;
-    /**
-     * What a reset makes the panel, in pixels.
-     *
-     * The pair to `panel-size`.
+     * Whether the panes sit side by side or stacked.
      */
-    defaultPanelSize: number;
+    orientation?: 'horizontal' | 'vertical';
     /**
      * What the panel's height becomes when it is closed.
      *
@@ -136,13 +127,17 @@ export declare class HelixSandbox extends HelixElement {
      */
     panelLabel: string;
     /**
-     * Accessible name for the divider that moves both at once.
+     * Height of the panel, in pixels.
      */
-    cornerLabel: string;
+    panelSize: number;
     /**
      * Accessible name for the divider.
      */
     separatorLabel: string;
+    /**
+     * Percentage of the sandbox given to the source pane.
+     */
+    split: number;
     /**
      * Whether anything is in the panel region.
      *
@@ -160,16 +155,14 @@ export declare class HelixSandbox extends HelixElement {
      * panel asked for at 192px quietly keeps whatever share of the old height that
      * was.
      *
-     * **Measured at render rather than cached from the observer**, which is the
-     * second design here. The first held the number the observer last reported and
-     * was correct only while the observer was firing, and a `ResizeObserver`
-     * callback is delivered from the rendering lifecycle: a background tab runs
-     * none, so the value went stale with nothing to say so. Reading the box at
-     * render leaves one source of truth, and the observer's only job is to say
-     * that a render is due.
+     * **Measured at render rather than cached from the observer.** A
+     * `ResizeObserver` callback is delivered from the rendering lifecycle and a
+     * background tab runs none, so a cached number goes stale with nothing to say
+     * so. Reading the box at render leaves one source of truth, and the observer's
+     * only job is to say that a render is due.
      *
-     * Cheap, because renders are rare. A drag no longer goes through this element
-     * at all: the splitter follows the pointer itself and announces once, when it
+     * Cheap, because renders are rare: a drag does not go through this element at
+     * all, the splitter following the pointer itself and announcing once, when it
      * settles.
      */
     private bodyHeight;
@@ -198,12 +191,11 @@ export declare class HelixSandbox extends HelixElement {
     /**
      * Whether a change came from inside this sandbox's source region.
      *
-     * Structural rather than a type check. It was `instanceof
-     * HelixSandboxSource`, which was right until there was a second kind of
-     * pane: the editor is `@fusion.dev/helix-sandbox/editor`, on its own path because it
-     * carries CodeMirror, and naming its class here would pull that back into
-     * this module for every consumer. Where the event came from is a question
-     * about the tree, and the tree can answer it.
+     * Structural rather than a type check. There is more than one kind of pane and
+     * the editor is `@fusion.dev/helix-sandbox/editor`, on its own path because it
+     * carries CodeMirror, so naming its class here would pull that back into this
+     * module for every consumer. Where the event came from is a question about the
+     * tree, and the tree can answer it.
      */
     private fromSource;
     /**
@@ -266,11 +258,9 @@ export declare class HelixSandbox extends HelixElement {
      * wrote to storage on its own would be deciding for all of them under a key
      * it chose.
      *
-     * **A verb each, where this was one `helix-before-resize` carrying which of the
-     * two had moved.** Both dividers are this element's, so `composedPath()[0]` is
-     * the same host for either and the name is the only thing that can separate
-     * them. It was the last caller of a field every request in the library carried
-     * for it. See 306.
+     * **A verb each, rather than one `helix-before-resize` naming which of the two
+     * moved.** Both dividers are this element's, so `composedPath()[0]` is the same
+     * host for either and the event name is the only thing that can separate them.
      */
     private splitSettled;
     /** As `splitSettled`, for the panel, whose value is pixels rather than a share. */
@@ -286,7 +276,8 @@ export declare class HelixSandbox extends HelixElement {
      * `target` against `currentTarget`, because a source pane's own change bubbles
      * up through these same elements on its way to the host. Only a splitter
      * speaking for itself is one of ours, and only those are stopped: the sandbox
-     * announces `arrangement` and a consumer never sees the two inside it.
+     * announces `helix-before-split` and `helix-before-panel-resize` in their
+     * place, and a consumer never sees the two splitters inside it.
      */
     private readonly handlePanesChange;
     private readonly handlePanelChange;