@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/breadcrumbs/root/breadcrumbs-root.js

@@ -6,64 +6,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
-/**
- * @summary Shows the path to the current page.
- *
- * @description
- * The host is the landmark, so `aria-label` on it names the trail directly and
- * there is no property mirroring one. A page may hold more than one navigation,
- * and landmarks are how a screen-reader user chooses between them.
- *
- * `role="list"` is set explicitly on the `<ol>` even though it is already a
- * list: removing the markers with `list-style: none` strips list semantics in
- * Safari, and a breadcrumb trail always removes its markers.
- *
- * Items are slotted rather than wrapped, so they are `<ol>` children in the flat
- * tree and each carries `role="listitem"` itself.
- *
- * **The trail does not measure itself, and the overflow is markup.** Measuring
- * how many crumbs fit can never reach the server: there is no width without a
- * DOM, so the server ships every crumb and the client removes some after
- * hydrating, and a trail that collapses paints wrong on every single load. Nor
- * does anybody specify a breadcrumb in units of fit. Designs say "keep the root
- * and the current page, fold the middle", which is a fact about depth, or "fold
- * below this width", which is a fact CSS knows.
- *
- * So the trail lays out crumbs and separators, and the consumer writes what
- * folds: a `helix-menu` of `helix-menu-item`s in a crumb, where the gap
- * belongs. Server rendered, no observer, no stylesheet, and correct before the
- * first script runs. A trail that should fold only at some widths is a
- * container query in the consumer's own sheet, which is theirs to write and
- * theirs to leave out.
- *
- * **And the crumbs carry no marker for any of it.** CSS can already see it: the
- * crumb with the menu in it is `:has(helix-menu)`, and the middle is
- * `:not(:first-child, [current])`. A marker would be the design rule written
- * twice, once in the HTML and once in the sheet, with nothing keeping the two
- * honest.
- *
- * @since 0.1.0
- * @status stable
- * @category navigation
- * @aliases Breadcrumb, Crumbs
- * @documentation https://helix.fusion.dev/components/breadcrumbs
- *
- * @slot - The trail's items, in order from root to current page, with the
- * crumb holding the fold wherever the gap should appear.
- *
- * @csspart list - The ordered list.
- */
 let HelixHeadlessBreadcrumbs = class HelixHeadlessBreadcrumbs extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
-        // On the host through internals, so the landmark is the element itself and
-        // an author's `aria-label` names it without anything being copied inward.
         hostAria(this.internals, { role: 'navigation' });
     }
     render() {
-        /* One slot. The crumb holding the fold is one the consumer placed in
-           source order, so there is nothing here to position it: the list renders
-           what it was given, in the order it was given. */
         return html `<ol part="list" role="list">
       <slot></slot>
     </ol>`;

package/dist/button/root/button-root.js

@@ -7,161 +7,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { AriaForwardController, customElement, HelixFallbackCommandEvent, HelixFormElement, supportsInvokers, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Triggers an action, submits a form, or navigates.
- *
- * @description
- * Renders a real `<button>`, so activation, focus, and the browser's own
- * affordances come from the platform rather than from key handlers.
- *
- * **It never renders an anchor.** A router has to render its own `<a>` to
- * intercept a click and cannot render one inside this shadow root, so a button
- * that could also be a link forced every such navigation to be a full page
- * load. A link that looks like a button is styling rather than behavior, so it
- * is a recipe in the base layer: `<Link data-button="solid">` is the same
- * control, and the consumer keeps their anchor.
- *
- * `delegatesFocus` puts focus on the inner control, and it serializes into the
- * server's markup, so the button is keyboard reachable before any JavaScript
- * loads.
- *
- * Form submission is explicit. A `<button type="submit">` inside a shadow root
- * submits nothing, because the form is on the other side of the boundary, so
- * the inner control is always `type="button"` and this element calls
- * `requestSubmit()` on its form instead. That routes through validation, unlike
- * `submit()`.
- *
- * @since 0.1.0
- * @status stable
- * @category actions
- * @documentation https://helix.fusion.dev/components/button
- *
- * @slot - The button's label.
- * @slot end - Content after the label.
- * @slot start - Content before the label, usually an icon.
- *
- * @csspart button - The inner control.
- */
 let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their tree and this control is
-           in a shadow root, so the reference has to be carried down as an element
-           rather than copied as an id. See the controller: measured, the host held
-           the description and the accessibility tree exposed the inner control
-           without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="button"]') ?? null,
         });
-        /**
-         * What to send when the button is activated, and what to send it to.
-         *
-         * The platform's invoker attributes, forwarded onto the inner `<button>`
-         * rather than left on the host: only a real button is recognized as an
-         * invoker, so `commandfor` written on a custom element resolves nothing and
-         * the trigger silently does nothing at all. A wrapper has to hand them down,
-         * the same way `label` becomes `aria-label` in there.
-         *
-         * ```html
-         * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
-         * ```
-         *
-         * `commandFor` spells its attribute out, because Lit lowercases a property
-         * name to derive one rather than dash-casing it, and what a consumer writes
-         * is the platform's `commandfor`.
-         *
-         * @reference https://html.spec.whatwg.org/multipage/form-elements.html#attr-button-command Invoker Commands
-         */
         this.command = '';
-        /**
-         * The id of the element the command is sent to.
-         *
-         * @reference https://html.spec.whatwg.org/multipage/form-elements.html#attr-button-commandfor Invoker Commands
-         */
         this.commandFor = '';
-        /**
-         * Whether the button holds its group's tab stop.
-         *
-         * A toolbar keeps one tab stop across its children, and the obvious way to do
-         * that is to write `tabindex` onto each of them. That is a change to markup
-         * the consumer rendered, so a React consumer's hydration reports it and does
-         * not patch it up. A parent sets this property instead, which writes nothing,
-         * and the stop lands on the inner control inside the shadow root.
-         *
-         * No attribute, because it is coordination between elements rather than
-         * anything a consumer sets.
-         */
         this.focusable = true;
-        /**
-         * Where this button's submission goes, overriding the form's own.
-         *
-         * **The five `form*` overrides work by writing the form and putting it back**,
-         * which is the only mechanism available and is closer to the platform than it
-         * sounds. `requestSubmit(submitter)` is how a native submitter carries these,
-         * and it refuses ours twice over: the inner `<button>` is `type="button"` so
-         * it is not a submit button, and it sits in this shadow root so its form owner
-         * is not the consumer's form. Both throw. So the submission is started with no
-         * submitter and the overrides are applied to the form for the duration of it.
-         *
-         * The whole submit algorithm runs synchronously inside `requestSubmit()`, so
-         * the window is one call and a `finally` closes it whether or not a listener
-         * refused. What a `submit` handler observes during that window is the form a
-         * native submitter would have given it, which is the point.
-         */
         this.formAction = '';
-        /**
-         * How the submission is encoded, overriding the form's own.
-         */
         this.formEnctype = '';
-        /**
-         * Which HTTP method the submission uses, overriding the form's own.
-         */
         this.formMethod = '';
-        /**
-         * Whether this submission skips the form's validation.
-         */
         this.formNoValidate = false;
-        /**
-         * Which browsing context the response lands in, overriding the form's own.
-         */
         this.formTarget = '';
-        /**
-         * Accessible name, for a button whose content is not text.
-         *
-         * Lives here rather than only on `IconButton` so the two share one render.
-         * An icon-only button without it is a control a screen reader announces as
-         * "button" and nothing else.
-         */
         this.label = '';
         this.handleClick = () => {
-            /* **Re-linked here, and this is the line that makes a trigger reliable.**
-             *
-             * From `updated` alone the target resolves once, whenever the button last
-             * rendered, and never again. A button whose properties do not change does
-             * not update again, so one whose target had not been inserted yet stays
-             * wired to nothing for good. Measured: `commandForElement` read null with
-             * the target absent, null again after the target was inserted, and resolved
-             * the instant an unrelated property forced an update. Whether a trigger
-             * works then comes down to insertion order, which is why it survives a full
-             * reload and not a client navigation, where the same markup arrives in
-             * pieces.
-             *
-             * `sendCommand` resolves through `commandTarget` at activation, so a browser
-             * *without* invokers was never affected and one with them was.
-             *
-             * A click listener is early enough, and that is measured rather than read
-             * off the specification: activation behavior runs after the click has
-             * finished dispatching, so a handler that assigns `commandForElement` sets
-             * it before the browser looks. Probed on a bare `<button command>` whose
-             * target was assigned from its own click listener, the dialog opened, and
-             * the control that assigned nothing did not.
-             *
-             * `updated` keeps its call, because the common case is a target that was
-             * there all along and `commandForElement` should be readable before anybody
-             * clicks anything. This is the guarantee, not the mechanism. */
             this.linkCommand();
-            // Before the type check, which returns for `button`, the default and the
-            // type every invoker in this library uses.
             this.sendCommand();
             if (this.type === 'button') {
                 return;
@@ -177,47 +39,13 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
                 form.reset();
             }
         };
-        /**
-         * What activating the button does to its form.
-         */
         this.type = 'button';
-        /**
-         * What this button submits under its own `name`, the way a native submitter does.
-         *
-         * **Reported for exactly the submission this button starts and not otherwise.**
-         * A native submit button contributes `name=value` only when it is the one
-         * that submitted, and every other button on the form contributes nothing. A
-         * form-associated element reporting a value continuously would contribute on
-         * every submission whoever started it, which is a different feature wearing
-         * the same name, so `submit` below sets it, submits, and clears it inside one
-         * synchronous call.
-         *
-         * `CopyButton` has a `value` of its own meaning the text to put on the
-         * clipboard, which is not this and is why it is declared there rather than
-         * inherited.
-         */
         this.value = '';
     }
-    /** Moves focus to the inner control, so the host is never the focus target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    /**
-     * Submits the form as this button, for the length of one call.
-     *
-     * Everything a native submitter carries is written onto the form, the
-     * submission is started, and everything is put back. See `formAction` for why
-     * `requestSubmit(submitter)` is not available to a control inside a shadow
-     * root.
-     *
-     * `novalidate` is in the same list rather than reached by `form.submit()`,
-     * which looks like the shortcut and is not: `submit()` skips the `submit`
-     * event as well as the validation, so a consumer's handler would stop running
-     * the moment somebody wrote `formnovalidate`. Turning the flag on and calling
-     * `requestSubmit()` skips the validation alone, which is what the attribute
-     * means.
-     */
     submit(form) {
         const undo = [];
         const override = (attribute, value) => {
@@ -256,15 +84,6 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
             }
         }
     }
-    /**
-     * The element this button's command is sent to, resolved.
-     *
-     * The platform's own accessor, because the resolution is otherwise kept
-     * inside: `linkCommand` writes the target onto the inner `<button>`, where a
-     * consumer cannot reach it, and `commandFor` answers with an id rather than
-     * an element. Writing assigns the inner control directly, which is what an
-     * invoker without an id in the same tree needs.
-     */
     get commandForElement() {
         const button = this.renderRoot?.querySelector('button');
         return button?.commandForElement ?? this.commandTarget();
@@ -275,20 +94,6 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
             button.commandForElement = target;
         }
     }
-    /**
-     * Points the inner button at the command's target, by reference.
-     *
-     * **The attribute cannot do this and it fails silently.** `commandfor` is an
-     * IDREF, and an IDREF resolves inside the tree it is written in: forwarded
-     * onto a button in this shadow root it looks for the id *here*, finds
-     * nothing, and the trigger does nothing at all. Measured before this existed:
-     * the button clicked, no `command` event was dispatched, and there was
-     * nothing anywhere to say why.
-     *
-     * `commandForElement` takes an element instead, and an element reference
-     * resolves outward: a node in a shadow root may point at one in the document.
-     * The same asymmetry the listbox relies on for `aria-activedescendant`.
-     */
     linkCommand() {
         const button = this.renderRoot?.querySelector('button');
         if (!button || !supportsInvokers()) {
@@ -298,30 +103,10 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
         button.commandForElement =
             this.commandTarget();
     }
-    /**
-     * The element this button commands, or nothing.
-     *
-     * Looked up in the button's own root rather than in the document, so a button
-     * inside somebody else's shadow root finds a target in that same root and not
-     * a coincidence in the page.
-     */
     commandTarget() {
         const root = this.getRootNode();
         return this.commandFor ? (root.getElementById?.(this.commandFor) ?? null) : null;
     }
-    /**
-     * Sends the `command` event where the browser will not.
-     *
-     * Invoker commands are recent, and where they are missing `linkCommand` sets a
-     * property that does not exist and returns, so the button does nothing at all
-     * when clicked. Silently: the markup is right, the component is right, and
-     * every `command` in the library is inert at once with no error to find.
-     *
-     * Only where the platform is absent, so a browser that has invokers sends
-     * exactly one event and this sends none. Doing both would open a dialog and
-     * immediately toggle it shut again, which is a worse bug than the one this
-     * fixes and would only appear on the browsers that work.
-     */
     sendCommand() {
         if (!this.command || supportsInvokers()) {
             return;

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

@@ -7,39 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Groups related buttons into one control.
- *
- * @description
- * The host is the group, so `role="group"` sits on it through internals and
- * `label` names it. A group of buttons with no name is announced as a run of
- * separate controls, which is what the grouping exists to say it is not.
- *
- * It manages no focus. A group is not a toolbar: the APG toolbar pattern asks
- * for one tab stop with arrow keys inside it, and that is what Toolbar is for.
- * Here every button keeps its own tab stop, which is what a reader expects from
- * buttons sitting side by side.
- *
- * Buttons are slotted rather than wrapped, so they stay the consumer's own
- * elements and keep whatever appearance and size they were given.
- *
- * @since 0.1.0
- * @status stable
- * @category actions
- * @aliases Segmented buttons, Split button
- * @documentation https://helix.fusion.dev/components/button-group
- *
- * @slot - The buttons in the group.
- */
 let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the group.
-         *
-         * On the host through internals, so an author's `aria-label` still overrides
-         * it and nothing lands on the host that a consumer's markup did not have.
-         */
         this.label = '';
     }
     willUpdate(changed) {

package/dist/callout/root/callout-root.js

@@ -8,59 +8,11 @@ import { customElement, HelixElement, hostAria, TONE_MARKS, toneMark } from '@fu
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary Sets a passage apart as information, a warning, or an error.
- *
- * @description
- * `tone` lives on the headless tier rather than being a treatment on the styled
- * one, because it is meaning and not decoration. It picks the icon and that
- * icon's accessible name, so a reader who cannot see that the box is red still
- * hears "Error". A callout whose meaning existed only as a color would say
- * nothing to them at all.
- *
- * The icon is the fallback content of a slot, so a consumer replaces it by
- * slotting their own and the default disappears with no emptiness check. That
- * is what slot fallback is for.
- *
- * Not an `Announcement`, which is the other thing this could be mistaken for.
- * A callout interrupts a document to set a passage apart and is read where it
- * sits; an announcement is page-level chrome above the masthead, announces
- * itself as a live region, and can be dismissed. Neither is a variant of the
- * other.
- *
- * @since 0.1.0
- * @status stable
- * @category markers
- * @aliases Admonition, Notice, Note, Alert
- * @documentation https://helix.fusion.dev/components/callout
- *
- * @slot - The callout's content.
- * @slot icon - Replaces the icon chosen by `tone`.
- * @slot title - A heading above the content.
- *
- * @csspart content - The content region.
- * @csspart icon - The icon region.
- * @csspart icon-mark - The tone glyph, where none is slotted.
- */
 let HelixHeadlessCallout = class HelixHeadlessCallout extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
-        // On the host, since the host is the box.
         hostAria(this.internals, { role: 'note' });
     }
-    /**
-     * The mark for the callout's tone, behind a seam.
-     *
-     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
-     * tier above replaces it by overriding. Those answer different people: the
-     * slot is for the page and the method is for whoever is building the styled
-     * layer, and a fallback with only the first is one a tier can restyle and
-     * cannot change.
-     *
-     * The mark and its label are passed in rather than looked up again, since
-     * `render` has already resolved the tone and a second lookup is a second
-     * place for the fallback to disagree with the tone around it.
-     */
     renderIcon(icon, label) {
         return html `<slot name="icon">
       <svg part="icon-mark" fill="currentColor" viewBox=${icon.viewBox} role="img" aria-label=${label}>
@@ -69,10 +21,6 @@ let HelixHeadlessCallout = class HelixHeadlessCallout extends HelixElement {
     </slot>`;
     }
     render() {
-        /* Falls back to `info`, because a callout exists to set a passage apart and
-           is therefore always *about* something. `Toast.Item` takes the same lookup
-           and draws nothing instead, since a message is just the next thing that
-           happened. Same vocabulary, two honest answers to an absent tone. */
         const { icon, label } = toneMark(this.tone) ?? TONE_MARKS.info;
         return html `<span part="icon">${this.renderIcon(icon, label)}</span>
       <div part="content">

package/dist/card/root/card-root.js

@@ -7,53 +7,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Groups related content and actions into a single surface.
- *
- * @description
- * Regions are slots rather than separate elements, because a header, body, and
- * footer carry no state, no behavior, and no API of their own. Slotting them
- * costs one custom element instead of five and lets the consumer bring their
- * own markup, so a title can be a real `<h2>` rather than an emulated one.
- *
- * The host is the surface. A wrapper `<div part="container">` would be a second
- * box doing nothing the host cannot: the element itself takes the border, the
- * radius, and the grid, and a consumer styles `helix-card` rather than reaching
- * through `::part`. One node instead of two, on every card on the page.
- *
- * Name the card with `aria-label` or `aria-labelledby`. That is the only
- * naming that survives server rendering: reading a title out of the light DOM
- * needs a DOM, and the server has none.
- *
- * @since 0.1.0
- * @status stable
- * @category layout
- * @aliases Panel, Surface
- * @documentation https://helix.fusion.dev/components/card
- *
- * @slot - The card's main content.
- * @slot footer - Actions that conclude the card.
- * @slot header - Title and any actions for the whole card.
- * @slot media - Image, video, or chart that runs edge to edge, outside the inset.
- */
 let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
-        // On the host, since the host is the box. Set here rather than in
-        // `connectedCallback`, which the server never calls.
         hostAria(this.internals, { role: 'group' });
     }
     render() {
-        // Bare slots, with no wrapper element around any of them. A `<slot>` is
-        // `display: contents` in the UA stylesheet, so an unassigned one generates
-        // no box at all: no grid row, no gap, nothing. A wrapper generates one
-        // whether or not anything is slotted into it, so an omitted region would
-        // paint an empty inset band.
-        //
-        // It has to be layout rather than detection, because the detection does not
-        // exist. `:host(:has([slot='header']))` is invalid CSS, so the whole rule is
-        // dropped and the region stays hidden even when filled, and the component
-        // cannot inspect its children on the server to do it in JavaScript.
         return html `
       <slot name="media"></slot>
       <slot name="header"></slot>

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

@@ -341,8 +341,8 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * an assignment changes, and under `slotAssignment: 'manual'` the only thing
      * that changes an assignment is this component calling `assign`, so a slide
      * appended by a consumer would reach no slot, render nowhere and be counted by
-     * nothing. The default slot used to carry that duty and could, because it took
-     * whatever was there. `Chat` watches for the same reason.
+     * nothing. A default slot needs no watcher, taking whatever is there; a manual
+     * one does. `Chat` watches for the same reason.
      */
     private watcher;
     connectedCallback(): void;