@fusion.dev/helix 0.1.0 → 0.3.0

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

@@ -1,4 +1,3 @@
-// Generated from src/quote/root/quote-root.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 display: inline;

package/dist/quote/root/quote-root.js

@@ -7,21 +7,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement } from '@fusion.dev/helix-core';
 import { HelixHeadlessQuote } from '@fusion.dev/helix-headless/quote';
 import { styles } from './quote-root.css.js';
-/**
- * @summary A short quotation, set inline with the text around it.
- *
- * @description
- * Takes the surrounding type rather than a size of its own, because a quotation
- * inside a paragraph is that paragraph's text with marks around it.
- *
- * @since 0.1.0
- * @status stable
- * @category typography
- * @aliases Q, InlineQuote
- * @documentation https://helix.fusion.dev/components/quote
- *
- * @cssproperty --quote-color - Color of the quoted text.
- */
 let HelixQuote = class HelixQuote extends HelixHeadlessQuote {
     static { this.styles = styles; }
 };

package/dist/radio/group/radio-group.css.js

@@ -1,4 +1,3 @@
-// Generated from src/radio/group/radio-group.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 display: flex;

package/dist/radio/group/radio-group.js

@@ -9,22 +9,6 @@ import { HelixHeadlessRadioGroup } from '@fusion.dev/helix-headless/radio';
 import { styles as fieldStyles } from '../../shared/field/field.css.js';
 import { styles as fieldStackedStyles } from '../../shared/field/field-stacked.css.js';
 import { styles } from './radio-group.css.js';
-/**
- * @summary A set of choices where exactly one is the answer.
- *
- * @description
- * The field's three parts, laid out the way every other field lays them out: a
- * question over the set, and one line under it that is help until something is
- * wrong. `orientation` lays out the choices and not the field, so a horizontal
- * group keeps its question above the row rather than beside the first choice.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases RadioButtons, Choice group
- * @documentation https://helix.fusion.dev/components/radio-group
- *
- * @cssproperty --radio-group-gap - Space between the choices.
- */
 let HelixRadioGroup = class HelixRadioGroup extends HelixHeadlessRadioGroup {
     static { this.styles = [fieldStyles, fieldStackedStyles, styles]; }
 };

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

@@ -1,4 +1,3 @@
-// Generated from src/radio/root/radio-root.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 display: block;

package/dist/radio/root/radio-root.js

@@ -8,55 +8,9 @@ import { customElement } from '@fusion.dev/helix-core';
 import { HelixHeadlessRadio } from '@fusion.dev/helix-headless/radio';
 import { property } from 'lit/decorators.js';
 import { styles } from './radio-root.css.js';
-/**
- * @summary One choice in a radio group.
- *
- * @description
- * A circle with a dot in it, drawn here rather than by the browser for the
- * reason the checkbox's box is: this is a `<button role="radio">`, so there was
- * never a native control to restyle, and the weight and the motion of the mark
- * are ours either way.
- *
- * The dot scales from nothing, like the checkbox's tick, so choosing shows
- * something happening. It has no color, because color is reserved for state
- * and being chosen is an answer rather than a state.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Option, Choice
- * @documentation https://helix.fusion.dev/components/radio
- *
- * @cssproperty --radio-background-color - Fill of an unselected circle.
- * @cssproperty --radio-border-color - Edge of the circle, in every state.
- * @cssproperty --radio-card-background-color - Fill behind a card-shaped choice.
- * @cssproperty --radio-card-border-color - Edge around one.
- * @cssproperty --radio-card-padding - Inset of the card appearance.
- * @cssproperty --radio-chip-size - Diameter of the chip appearance.
- * @cssproperty --radio-mark-color - Color of the dot.
- * @cssproperty --radio-size - Diameter of the circle.
- */
 let HelixRadio = class HelixRadio extends HelixHeadlessRadio {
     constructor() {
         super(...arguments);
-        /**
-         * Takes the circle away, leaving the card as the whole control.
-         *
-         * Unnecessary under `chip`, which has no room for a circle beside its mark
-         * and hides it already.
-         *
-         * `card` only, and it is a graphic that goes rather than a radio: the control
-         * in the shadow root is untouched, so the row is still focusable, still
-         * reported to a screen reader, and still the thing a form submits.
-         *
-         * Safe because the card already carries the answer in its surface, a raised
-         * fill inside a primary edge and a three-pixel ring of it. Without that ring
-         * nothing would be left saying which card was chosen.
-         *
-         * Not on `Checkbox`, deliberately. A radio card with no circle is still
-         * unmistakably one-of-many because its siblings behave that way; a checkbox
-         * card with no box loses the only thing that says you may pick several.
-         */
         this.hideControl = false;
     }
     static { this.styles = styles; }

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

@@ -1,4 +1,3 @@
-// Generated from src/rating/root/rating-root.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 

package/dist/rating/root/rating-root.js

@@ -8,28 +8,6 @@ import { customElement } from '@fusion.dev/helix-core';
 import { HelixHeadlessRating } from '@fusion.dev/helix-headless/rating';
 import { property } from 'lit/decorators.js';
 import { styles } from './rating-root.css.js';
-/**
- * @summary A score out of a few marks, given or shown.
- *
- * @description
- * Presentation only: the marks, and the clip that fills them partway.
- * Everything about what the score is and how it is chosen is the base class.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Stars, Score, Review score
- * @documentation https://helix.fusion.dev/components/rating
- *
- * @slot mark - The shape of a mark, cloned into every position. Left empty, the
- * stylesheet draws its own and `--rating-mark` swaps it.
- *
- * @cssproperty --rating-color - The color of a filled mark.
- * @cssproperty --rating-empty-color - And of an unfilled one.
- * @cssproperty --rating-gap - Space between marks.
- * @cssproperty --rating-mark - The shape of one mark, as a mask image.
- * @cssproperty --rating-size - How big one mark is.
- */
 let HelixRating = class HelixRating extends HelixHeadlessRating {
     static { this.styles = styles; }
 };

package/dist/sandbox/index.js

@@ -1,17 +1,3 @@
-/**
- * The sandbox: a preview that runs what it is given, and the panes around it.
- *
- * The editor is deliberately absent and lives on in `@fusion.dev/helix-editor`, because
- * it carries CodeMirror. That is roughly 4 MB installed against a design system
- * of about the same size, and a `dependencies` entry is paid at install time by
- * every consumer whether or not they import it, which is the one cost a subpath
- * export cannot avoid. Its pane takes an editor by slot, so bringing one is a
- * choice rather than a condition of using this.
- *
- * What makes this a sandbox rather than a layout is here: `Sandbox.Preview`
- * hardcodes `sandbox="allow-scripts allow-forms"` on its frame and never
- * `allow-same-origin`, which is the pairing that would undo it.
- */
 export * from './preview/sandbox-preview.js';
 export * from './root/sandbox-root.js';
 export * from './source/sandbox-source.js';

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

@@ -1,4 +1,3 @@
-// Generated from src/sandbox/preview/sandbox-preview.css by `turbo run styles`. Do not edit.
 import { createSheet } from '@fusion.dev/helix-core';
 export const styles = createSheet(`:host {
 display: block;

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

@@ -6,133 +6,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var HelixSandboxPreview_1;
 import { customElement, HelixConsoleEvent, HelixElement, HelixResizeEvent, } from '@fusion.dev/helix-core';
-/**
- * How long the source has to stop changing before the frame is asked to render,
- * in milliseconds.
- *
- * Long enough that a run of keystrokes is one render, short enough that letting
- * go of the keyboard and looking up finds the preview already there.
- */
 const SETTLE = 120;
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { styles as sheet } from './sandbox-preview.css.js';
-/**
- * @summary Renders sandbox source in a frame of its own.
- *
- * @description
- * A sandboxed `<iframe>` pointed at `src`, which is a document the consumer
- * provides. That document imports whatever the examples need, listens for a
- * render message, and writes the markup into itself.
- *
- * **A frame rather than the page.** Rendering into the page meant an example
- * was styled by whatever surrounded it, which flatters the preview and lies
- * about it: an example that restyles `helix-card` restyled the sandbox too, a
- * script in an example ran against the real document, and a stray
- * `position: fixed` escaped the pane. It also left nothing to capture console
- * output from, and the terminal has to come from somewhere.
- *
- * The cost is that the frame starts empty. Styles and element definitions do
- * not cross into it, because a document has its own stylesheets and a window
- * has its own custom element registry, so `src` has to load them. That is the
- * consumer's document rather than something guessed at here.
- *
- * **The source is not trusted, and the frame is what makes that safe.**
- * `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.
- *
- * `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
- * @documentation https://helix.fusion.dev/sandbox/preview
- *
- * @event {HelixConsoleEvent} helix-console - Relayed from the frame, one per console call.
- * @event {HelixResizeEvent} helix-resize - How tall the frame's content is, whenever it changes.
- *
- * @csspart frame - The iframe.
- */
 let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the frame.
-         */
         this.label = 'Preview';
-        /**
-         * Markup to render.
-         */
         this.source = '';
-        /**
-         * Document the frame loads, which brings the styles and the elements.
-         */
         this.src = '';
-        /**
-         * Stylesheet applied inside the frame, alongside the markup.
-         */
         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
-         * `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 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
-         * HTTP cache, which is a client-side navigation and never a cold load.
-         * Measured on the theme builder reached by clicking a link: `ready` false, a
-         * 9,382 character `source` in place, and an empty preview, where the same
-         * page loaded directly rendered correctly.
-         *
-         * `load` closes it without a retry protocol and without weakening either
-         * check on the way in. The frame's script is `defer`, so it has run by the
-         * time this fires, which makes the event a guarantee that the listener is
-         * there rather than a guess that it might be. The message path stays, because
-         * it is the one that works when the frame is slower than the render, and
-         * either arriving is enough.
-         */
         this.handleFrameLoad = () => {
             this.ready = true;
             this.send();
         };
-        /**
-         * Takes messages from the frame.
-         *
-         * Two checks, and both earn their place.
-         *
-         * The window is the identity: `event.source` is a reference the sender cannot
-         * forge, and this frame's `contentWindow` is one only this element holds.
-         *
-         * The origin has to be opaque. The frame is sandboxed, so every message it
-         * sends arrives as `"null"`, measured. A real origin therefore means the
-         * frame is no longer showing the document it was given: `allow-scripts` lets
-         * an example navigate its own frame, and whatever it navigated to inherits
-         * `contentWindow` and could otherwise write lines into the terminal as though
-         * the example had logged them.
-         */
         this.handleMessage = (event) => {
             if (event.source !== this.frame?.contentWindow || event.origin !== 'null') {
                 return;
@@ -145,34 +34,9 @@ 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
-               deciding for the page it sits in, and the workbench and a reference page
-               want opposite things from the same number. */
             if (event.data?.type === 'helix-preview-size') {
                 this.dispatchEvent(new HelixResizeEvent({ size: event.data.size }));
             }
@@ -182,26 +46,7 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
     get frame() {
         return this.renderRoot.querySelector('iframe');
     }
-    /**
-     * Where messages to the frame are addressed.
-     *
-     * `'*'`, because there is nothing else to say: a sandboxed document has an
-     * opaque origin and `postMessage` has no target string that names one.
-     *
-     * It costs nothing. What is sent is the example's own source and stylesheet,
-     * to the document that is about to render them, and that document is the one
-     * thing on the page already entitled to both.
-     */
     static { this.target = '*'; }
-    /**
-     * Sends once the typing stops, replacing anything already waiting.
-     *
-     * 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);
         this.pending = setTimeout(() => {
@@ -209,7 +54,6 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
             this.send();
         }, SETTLE);
     }
-    /** Sends the current source to the frame, once it is listening. */
     send() {
         if (!this.ready) {
             return;
@@ -234,20 +78,6 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
         this.pending = undefined;
         window.removeEventListener('message', this.handleMessage);
     }
-    /**
-     * Loads the frame's document again, and re-sends the example to it.
-     *
-     * For a bundle that has changed underneath a page nobody reloaded. The frame
-     * carries its own build of the component library, as a classic script it ran
-     * once at load, so a rebuilt bundle reaches a tab that is already open
-     * exactly never: the sandbox around it hot-reloads and the preview inside it
-     * keeps running whatever it started with, which reads as a component fix that
-     * did not work.
-     *
-     * Nothing needs to be resent by the caller. Clearing `ready` and reassigning
-     * `src` puts this back in the state it was in before the first load, and the
-     * new document announces itself the same way the first one did.
-     */
     reload() {
         const frame = this.frame;
         if (!frame) {
@@ -258,22 +88,10 @@ let HelixSandboxPreview = class HelixSandboxPreview extends HelixElement {
     }
     updated(changed) {
         super.updated(changed);
-        // A new document has to say it is listening again before anything is sent.
         if (changed.has('src')) {
             this.ready = false;
             return;
         }
-        /* Typing is coalesced; a setting is not.
-         *
-         * 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 is once per keystroke,
-         * and the work grows with the example while the typing does not.
-         *
-         * `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. */
         if (changed.has('source') || changed.has('styles')) {
             this.scheduleSend();
             return;

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

@@ -1,4 +1,3 @@
-// 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);