@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/checkbox/root/checkbox-root.js

@@ -7,122 +7,37 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { AriaForwardController, customElement, HelixFormElement, MixinControllerChecked, MixinField, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A box that is ticked, or not, or neither.
- *
- * @description
- * Renders a real `<input type="checkbox">`, so the space key, the focus ring,
- * and the indeterminate glyph come from the platform. `delegatesFocus` puts
- * focus on it, and it serializes into the server's markup, so the control is
- * reachable before any script loads.
- *
- * **The input inside a shadow root submits nothing**, because the form is on
- * the other side of the boundary. The host is form-associated instead and
- * reports its own value through `ElementInternals`, which is also what carries
- * validity and what answers a form reset.
- *
- * A checked box submits its `value`, and an unchecked one submits nothing at
- * all. That is what a native checkbox does, and a form built around one reads
- * the absence rather than a `false`.
- *
- * `indeterminate` is presentation and nothing else. It is neither checked nor
- * unchecked to a reader, it never submits, and the first click resolves it: a
- * third state that survives interaction is a control nobody can finish.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Tickbox, Toggle
- * @documentation https://helix.fusion.dev/components/checkbox
- *
- * @slot - The label.
- *
- * @event {Event} change - Relayed from the input once the state has changed.
- * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
- * @event {Event} input - Announced once the state has moved.
- *
- * @csspart box - The frame the input is painted as, and the mark sits over.
- * @csspart control - The input.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row the box and its label share, and the surface the card appearance draws.
- * @csspart hint - Help under the control, while nothing is wrong.
- * @csspart label - The label beside it.
- * @csspart mark - The tick, or the dash when the box is indeterminate.
- */
 let HelixHeadlessCheckbox = class HelixHeadlessCheckbox extends MixinControllerChecked(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
         });
-        /**
-         * Whether the box shows as neither checked nor unchecked.
-         *
-         * Presentation only. It never submits, and the first change resolves it.
-         */
         this.indeterminate = false;
-        /**
-         * Value submitted when the box is checked.
-         */
         this.value = 'on';
         this.handleChange = (event) => {
             const input = event.target;
-            // The input has already flipped itself. Where the change is refused it is
-            // put back to whatever the element resolves to, so the box never shows a
-            // state the element does not hold.
             const next = input.checked;
-            /* The dash goes only where the change is taken. Clearing it
-             * unconditionally leaves a refused change holding the checked state and
-             * losing the third one: a box neither ticked nor dashed, which is a state
-             * nobody asked for. Refusing leaves everything as it was, which is the
-             * argument the line below already makes for `checked`. */
             if (this.requestChecked(next)) {
                 this.indeterminate = false;
             }
             input.checked = this.checked;
             this.relayNativeEvent(event);
         };
-        /**
-         * Whether there is a label to leave room for, written to the host.
-         *
-         * The row is a flex line with a gap in it, so a label span rendered empty is
-         * still a box and still takes that gap: an unlabelled box came out with eight
-         * pixels of nothing after it. The input answers this by not rendering the
-         * element, which cannot work here, because a checkbox is named by its own
-         * content and the property is only that slot's fallback. Gating on the
-         * property would unlabel every `<helix-checkbox>Text</helix-checkbox>` ever
-         * written.
-         *
-         * So the slot is asked instead, the same way `Tooltip` asks its own: with
-         * `flatten`, because here the fallback counts, being where the property
-         * renders. Client only, so a server-rendered unlabelled checkbox carries the
-         * gap for one frame. That is a control with no accessible name, which has a
-         * worse problem than its spacing.
-         */
         this.handleLabelChange = () => {
             this.syncLabelPresence();
         };
     }
-    /** Focus is delegated to the input, so the host is never the focus target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    /** Reports the value and the validity the host stands behind. */
     sync() {
         this.internals.setFormValue(this.checked ? this.value : null);
         this.reportRequired(!this.checked, 'Tick this box to continue.', 'control');
     }
-    /** Returns the box to the state its markup declared. */
     formResetCallback() {
         this.indeterminate = false;
-        // `resetChecked` drops both halves, the consumer's and the element's, so
-        // there is nothing to clear before it.
         this.resetChecked();
     }
     willUpdate(changed) {
@@ -134,41 +49,13 @@ let HelixHeadlessCheckbox = class HelixHeadlessCheckbox extends MixinControllerC
         this.sync();
         this.syncLabelPresence();
     }
-    /**
-     * Asks the slot, and records the answer as a state.
-     *
-     * Called on `slotchange` and after every update, and the second is not
-     * belt-and-braces: **`slotchange` does not fire when nothing is assigned.**
-     * Without it a checkbox labeled only by its property, which is most of them,
-     * never hears about its own label and renders without one.
-     *
-     * **`:state(has-label)` and not `data-has-label`.** The answer comes from
-     * `assignedNodes` and a server has no tree to ask, so an attribute would
-     * appear on every labeled checkbox the instant it upgraded and on none that
-     * any server sent. See `HelixElement.toggleState`.
-     */
     syncLabelPresence() {
         const slot = this.renderRoot.querySelector('[part="label"] slot');
         const filled = (slot?.assignedNodes({ flatten: true }) ?? []).some((node) => node.textContent?.trim() !== '' || node.nodeType === Node.ELEMENT_NODE);
         this.toggleState('has-label', filled);
-        /* And `hidden` on the region itself, because the state is on the host and
-           this tier has no sheet to turn one into the other, so a checkbox with no
-           label would keep an empty label box beside it. The styled rule stays,
-           since it hides through a descendant selector this cannot replace. */
         this.renderRoot.querySelector('[part="label"]')?.toggleAttribute('hidden', !filled);
     }
     render() {
-        /* A real `<label>` around both, which is the whole of what makes the text a
-           target. A `<span>` beside the input leaves pressing the words doing
-           nothing.
-    
-           Labeling is behavior, which is what earns an element here rather than a
-           bare slot: the wrapper is not decoration and there is no other way to get
-           it. The browser handles the forwarding, so there is no click handler to
-           write and none to get wrong.
-    
-           The one line of description goes under that row, which is where a field
-           puts it too. */
         return html `<label part="field">
       <span part="box">
         <input

package/dist/checkbox-group/root/checkbox-group-root.js

@@ -8,99 +8,21 @@ import { customElement, DisabledCascadeController, HelixBeforeChangeEvent, Helix
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessCheckbox } from '../../checkbox/root/checkbox-root.js';
-/**
- * @summary Groups related checkboxes, and reports them as one set.
- *
- * @description
- * The host is the group, so `role="group"` sits on it through internals and
- * `label` names it. A run of checkboxes with no name is announced as separate
- * controls, which is what the grouping exists to say it is not.
- *
- * **Each checkbox still submits itself.** They are form-associated already and
- * a native group is several inputs sharing a name, so this adds no form value
- * of its own: it would submit the same answers twice. What it adds is the
- * grouping, a shared `name` so it is written once, and one place to read and
- * write the whole set.
- *
- * `value` is the checked values, comma separated, in the order the boxes are
- * written. Setting it ticks exactly those and unticks the rest.
- *
- * **Its message is always given, never derived.** The group is form-associated
- * for validity alone and never calls `setFormValue`, so `feedback` is what shows
- * here: the browser has nothing to say about a set it does not submit.
- *
- * @since 0.1.0
- * @status stable
- * @category forms
- * @aliases Checkbox list, Multi-select
- * @documentation https://helix.fusion.dev/components/checkbox-group
- *
- * @slot - The checkboxes.
- * @slot hint - Richer than a string.
- * @slot label - Richer than a string, where the label is more than one.
- *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before any box changes, with the whole set. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- *
- * @csspart feedback - What is wrong with it.
- * @csspart hint - Help under the set.
- * @csspart items - The list itself, which is what `orientation` lays out.
- * @csspart label - The group's name, over the set.
- */
 let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinField(HelixFormElement) {
     constructor() {
-        /* `name` is inherited from `HelixFormElement`, reflected and with the
-           converter that makes an empty one absent rather than `name=""`. What it
-           means differs slightly and the property does not: the group submits nothing
-           under it, and hands it to every box that has none. */
         super(...arguments);
-        /**
-         * The checked values, comma separated.
-         */
         this.value = '';
-        /* Stated once, and the group never thinks about it again. The controller is
-           what stops the cascade being hand-called from whichever methods a component
-           happens to have. */
         this.cascade = new DisabledCascadeController(this, {
             items: () => this.boxes,
         });
-        /**
-         * Reads a box's requested change into `value`, and says so once.
-         *
-         * The box is found from the event's target, which does two things. It tells
-         * the group which box asked, where the detail carries only the shared name.
-         * And it ignores the group's own dispatch, which lands on this same listener
-         * because the group is what it is dispatched from: without the guard the
-         * group answers itself until the stack gives out.
-         *
-         * The requested state comes from the event rather than from the box. Driving
-         * the boxes from `value` makes them controlled, so a controlled box applies
-         * nothing on its own and reports what it was asked for. Reading `checked`
-         * here would read the state it still holds and nothing would ever change.
-         */
         this.handleToggle = (event) => {
             const target = event.target;
             const changed = this.boxes.find((box) => box === target);
             if (!changed) {
                 return;
             }
-            /* A box's `helix-before-toggle` bubbles, and the group is the single voice
-               for the set: a consumer listening here wants the whole answer, not one
-               box's half of it. */
             event.stopImmediatePropagation();
             const wanted = event.detail.checked;
-            /* Announced before it is written, never after: dispatching once the group's
-               value has moved leaves `preventDefault()` refusing a set that has already
-               changed.
-        
-               Hand-rolled rather than through `MixinControllerValue`, and that is a
-               decision rather than an omission. The group's `value` is a derived read of
-               the boxes rather than state it owns, so there is nothing for the mixin to
-               control.
-        
-               The boxes have already moved either way. Each answered the reader before
-               this ran, so refusing here stops only the group's value from following. */
             const next = this.boxes
                 .filter((box) => (box === changed ? wanted : box.checked))
                 .map((box) => box.value)
@@ -109,50 +31,18 @@ let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinF
                 return;
             }
             this.value = next;
-            /* Under the platform's own name, after the value has moved, so a consumer
-               binding `onChange` reads the group's new value off the target.
-        
-               `input` beside it, because this is a discrete control and that is the
-               pair a native `<select>` sends and the pair every other discrete control
-               here sends through `MixinControllerValue`. */
             this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
             this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
         };
-        /**
-         * Stops a box's own announcement, for the reason the request above is stopped.
-         *
-         * A box announces `input` and `change` from its own host, which is what makes
-         * `onChange` work on a checkbox, and both bubble up through this group:
-         * measured, one click produced `change` from the group and `input` and
-         * `change` from the box, all three at a consumer listening here, two of them
-         * describing one box rather than the set.
-         *
-         * `stopImmediatePropagation` and not `stopPropagation`: the box's event and
-         * this group's own carry one name from what a consumer sees as one element,
-         * so stopping propagation alone still leaves every other listener on this
-         * host receiving both.
-         *
-         * A listener on the box itself is unaffected, which is where per-box handling
-         * belongs. Each box is form-associated and submits itself; what this stops is
-         * one box answering a question asked of the set.
-         */
         this.handleMemberNative = (event) => {
             if (event.target !== this) {
                 event.stopImmediatePropagation();
             }
         };
     }
-    /** The boxes, in light-DOM order. Client only: the server has no tree. */
     get boxes() {
         return [...this.children].filter((child) => child instanceof HelixHeadlessCheckbox);
     }
-    /**
-     * Pushes the group's name and value onto the boxes.
-     *
-     * As properties rather than attributes. A `name` written onto a box is a
-     * change to markup the consumer rendered, which a React consumer's hydration
-     * reports and does not patch up. A box that names itself keeps its own.
-     */
     sync() {
         const wanted = new Set(this.value
             .split(',')
@@ -165,21 +55,6 @@ let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinF
             box.checked = wanted.has(box.value);
         }
     }
-    /**
-     * Reads the boxes' own state into `value`, once, before anything is pushed.
-     *
-     * Seeding, and never a guard in `sync` refusing to write while `value` is
-     * empty. The guard would answer the same case, a group written with no `value`
-     * whose boxes declare their own `checked` being cleared on the first update,
-     * and it also makes `group.value = ''` do nothing at all: the obvious way to
-     * clear a group would silently not, and the last box could not be unticked
-     * through the group either.
-     *
-     * The markup decides the starting set, and from then on `value` is what the
-     * boxes follow, including when it is empty. The group's `value` is a derived
-     * read of the boxes rather than state it owns, so reading it out of them at
-     * the start is what it already means.
-     */
     seed() {
         const checked = this.boxes.filter((box) => box.checked).map((box) => box.value);
         if (checked.length > 0) {
@@ -200,39 +75,15 @@ let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinF
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* The string half, which is what a server can write. `linkHost` adds the
-           element references on the client, and those win where a consumer slotted
-           a label richer than a string. */
         hostAria(this.internals, { label: this.label, role: 'group' });
         this.internals.ariaRequired = this.required ? 'true' : null;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        /* Before the first `sync`, and only ever once: after this the group's value
-           is what the boxes follow. Client only, the server having no boxes to
-           read. */
         if (this.value === '') {
             this.seed();
         }
     }
-    /**
-     * Refuses an empty set where one was required.
-     *
-     * **The group is form-associated, and submits nothing.** Nothing here calls
-     * `setFormValue`, so the set that reaches the server is exactly the boxes,
-     * each of which submits itself. What form association buys is the other half
-     * of participation, validity, and there is no other mechanism for it:
-     * `setValidity` throws `NotSupportedError` on an element the platform does not
-     * know is a control. happy-dom's shim does not throw, so a spec passes against
-     * code that fails on every update in Chromium.
-     *
-     * It is also what makes the rest work: the form refuses to submit, which fires
-     * `invalid`, which is what marks the field touched and puts the message on
-     * screen.
-     *
-     * Anchored on the list, because the browser needs somewhere to point the
-     * bubble.
-     */
     validate() {
         this.reportRequired(this.value === '', 'Choose at least one to continue.', 'items');
     }
@@ -243,16 +94,9 @@ let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinF
         this.linkHost();
     }
     render() {
-        /* The list is an element of its own, because the label and the hint are the
-           host's children too and `orientation` lays out whatever is in the flex
-           container. On the host, a horizontal group would have put its own label
-           in the row beside the first box. */
         return html `${this.renderGroupLabel()}
       <div part="items">
-        ${
-        /* A box arriving after first render has neither the shared name nor
-           the value's checked state until something pushes them onto it. */
-        ''}
+        ${''}
         <slot @slotchange=${() => this.requestUpdate()}></slot>
       </div>
       ${this.renderHint()}${this.renderFeedback()}`;

package/dist/code/root/code-root.js

@@ -6,32 +6,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
-/**
- * @summary A fragment of code inside a line of prose.
- *
- * @description
- * **A real `<code>`, because the element is the meaning.** A styled span reads
- * as code and is not: a screen reader announces nothing about it, a translation
- * tool will happily translate it, and a search that understands documents
- * cannot tell it from emphasis. The tag is the whole point, which is also why
- * this component is so small.
- *
- * **Inline, and only inline.** A block of code is `CodeBlock`, a separate
- * family rather than a variant here. The two differ in more than presentation:
- * one flows with a sentence and must never scroll, the other is a figure with
- * its own box, its own overflow and something to copy. Namespacing them
- * together would say `CodeBlock` is part of `Code`, and it is not.
- *
- * @since 0.1.0
- * @status stable
- * @category typography
- * @aliases Inline code, Kbd
- * @documentation https://helix.fusion.dev/components/code
- *
- * @slot - The code.
- *
- * @csspart code - The `<code>` element.
- */
 let HelixHeadlessCode = class HelixHeadlessCode extends HelixElement {
     render() {
         return html `<code part="code"><slot></slot></code>`;

package/dist/code-block/root/code-block-root.js

@@ -9,126 +9,26 @@ import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../copy-button/index.js';
-/**
- * @summary A block of code, with somewhere to put its name and a way to take it.
- *
- * @description
- * **`<pre><code>` and nothing cleverer.** The pair is what the platform means
- * by a block of code: `pre` keeps the whitespace, `code` says what the
- * whitespace is for, and losing either one loses something no styling puts
- * back. Indentation in a `div` is a paragraph with odd spacing.
- *
- * **It scrolls rather than wraps.** A wrapped line of code is a lie about where
- * the line ends, and in a language where a line break can be significant it is
- * a lie that costs someone an afternoon. The box takes its own scrollbar.
- *
- * **The copy button is here because the alternative is selecting it by hand.**
- * Every consumer would otherwise put one there, slightly differently, and the
- * one that forgot would be the one with the longest snippet. It is on unless
- * `no-copy` says otherwise, and takes its text from the slot rather than from a
- * property, so there is no second copy of the code to keep in step.
- *
- * A `Code` for a fragment inside a sentence. Separate families, because one
- * flows with prose and the other is a figure.
- *
- * @since 0.1.0
- * @status stable
- * @category typography
- * @aliases Code block, Snippet, Pre
- * @documentation https://helix.fusion.dev/components/code-block
- *
- * @slot - The code.
- *
- * @csspart block - The scrolling `<pre>`.
- * @csspart code - The `<code>` inside it.
- * @csspart copy - The copy button.
- * @csspart copy-button - The inner button.
- * @csspart copy-mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart copy-tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart copy-tooltip-arrow - The point, resting against the trigger.
- * @csspart frame - The code and the copy button beside it.
- * @csspart header - The bar carrying the name, where there is one.
- * @csspart label - The file name or language, where one is given.
- */
 let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * What to call this block, usually a file name or a language.
-         */
         this.label = '';
-        /**
-         * Whether to leave the copy button off.
-         *
-         * Negative, which is not a style choice. A boolean attribute is true whenever
-         * it is *present*, so a `copyable` defaulting to true could never be turned
-         * off from markup: `copyable="false"` is the string "false", which is
-         * present, which is true. Measured, and it is why this is named the other way
-         * round. The platform already writes booleans like this for the same reason,
-         * `novalidate` and `nomodule` and `noreferrer` among them.
-         *
-         * **Reflected, because the gutter is a stylesheet rule.** `code-block.css`
-         * reserves the copy button's width with `:host(:not([no-copy]))`, so the
-         * attribute is what decides whether the block pays for a control. Unreflected,
-         * setting it from script takes the button away (`render` reads the property)
-         * and leaves the 40px it stood in reserved.
-         *
-         * A false boolean reflects as the attribute's absence, so this costs no
-         * `no-copy=""` on hosts that never asked for one, and the rule about a
-         * reflected property taking no default is satisfied by the default being
-         * `false`.
-         */
         this.noCopy = false;
     }
-    /**
-     * The code as text, read from the slot rather than stored.
-     *
-     * Client only, and it has to be: the server has no children to read. The
-     * copy button is a client-side affordance anyway, so nothing is lost, and
-     * taking the text from a property instead would be a second copy of the code
-     * that goes stale the moment the slot changes.
-     */
     get text() {
         const slot = this.renderRoot?.querySelector('slot');
         return (slot?.assignedNodes() ?? []).map((node) => node.textContent ?? '').join('');
     }
-    /**
-     * One more render, once there is a slot to read.
-     *
-     * The first render has no shadow children yet, so `text` is empty and the
-     * copy button is bound to nothing. `slotchange` normally schedules the render
-     * that fixes it, and leaning on that alone was measured to leave the button
-     * empty through four update cycles: the event is not guaranteed to have
-     * arrived, and in one environment never arrives at all. A component should not
-     * need an event to show its own content, so it asks for the second render
-     * itself and `slotchange` is left to handle the case it is actually for, which
-     * is content changing later.
-     */
     firstUpdated() {
         this.requestUpdate();
     }
     render() {
-        /* The copy button sits beside the code, not in a bar above it. In the
-           header, a block with nothing to call itself still draws a full-width bar
-           to hold one button, so a `Usage` section of one-line imports is a run of
-           empty strips. Beside the code, the header exists only when there is a
-           name to put in it. */
         return html `${this.label ? html `<div part="header"><span part="label">${this.label}</span></div>` : nothing}
       <div part="frame">
         <pre part="block"><code part="code"><slot @slotchange=${() => this.requestUpdate()}></slot></code></pre>
         ${this.noCopy ? nothing : this.renderCopyButton()}
       </div>`;
     }
-    /**
-     * The button that takes the code, behind a seam the styled tier can move.
-     *
-     * A method rather than a fragment inline, so a tier above can render its own
-     * copy control, wrap this one, or pass it something the base does not know
-     * about, without reimplementing the whole template to do it. The tag is
-     * interpolated rather than written, so `tier` resolves it: this renders the
-     * base button, and a styled subclass that sets `tier` renders the styled one
-     * from the same template.
-     */
     renderCopyButton() {
         return html `<${this.tag('copy-button')}
       part="copy"