@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/image/root/image-root.js

@@ -7,126 +7,18 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary A picture that says whether it arrived.
- *
- * @description
- * **An element rather than a recipe, because of the part CSS cannot do.**
- * Reserving the box is `aspect-ratio` and needs nothing from anybody; `Link` and
- * the megamenu row are recipes in `preview.css` for exactly that reason. What
- * cannot be written as a rule is *when the picture arrived*: a stylesheet has no
- * way to know, and no way to hear that it never will. So this owns three states
- * and the two events that move between them, and leaves the box to the
- * stylesheet.
- *
- * **The placeholder is a slot with nothing in it by default.** A default of
- * `Skeleton` would be right and is not written here: this tier renders no other
- * component, and reaching for one would make the headless package depend on the
- * styled one. The styled tier draws the resting placeholder instead, and a
- * consumer who wants a `Skeleton`, a blurred thumbnail or a solid color slots
- * it.
- *
- * **No source is a loading state, not a fourth one.** A picture whose `src` has
- * not arrived yet is the common case for anything drawn from data, and the
- * useful answer there is the same as for one still on the wire: stand something
- * in its place and keep the ground reserved. So an element with no `src` shows
- * its placeholder and waits, rather than resolving to an empty box that has to
- * be laid out twice.
- *
- * **`alt` is a property and not an afterthought.** An empty string is a real
- * answer, meaning the picture is decoration and a screen reader should skip it,
- * which is why the attribute is always written even when it is empty: omitting
- * it entirely makes a reader announce the file name instead.
- *
- * @since 0.1.0
- * @status experimental
- * @category media
- * @aliases Picture, Img, Figure
- * @documentation https://helix.fusion.dev/components/image
- *
- * @slot fallback - Shown instead of it, if it never does.
- * @slot placeholder - Shown until the picture arrives.
- *
- * @event {Event} error - Relayed for the same reason.
- * @event {Event} load - Relayed, because the platform's own does not escape.
- *
- * @csspart fallback - What stands in when it fails.
- * @csspart image - The picture itself.
- * @csspart placeholder - What stands in until it arrives.
- */
 let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * What it shows, for a reader who cannot see it.
-         *
-         * Empty is a real answer and means decoration. Omitting the attribute is not
-         * the same thing: a reader with nothing to read announces the file name.
-         */
         this.alt = '';
-        /**
-         * How the picture is fetched across origins, which decides whether a canvas
-         * can read it.
-         */
         this.crossOrigin = null;
-        /**
-         * Whether the browser may decode off the main thread.
-         *
-         * `async` is the resting value and right for a picture in a page. `sync` is
-         * what a consumer reaches for when the picture is about to be composited with
-         * something else and a tear would show.
-         */
         this.decoding = 'async';
-        /**
-         * How urgently to fetch it, for the one picture that is the page.
-         *
-         * The hero of a page is usually its largest contentful paint, and the fix is
-         * two attributes rather than one: `loading="eager"` stops it waiting for the
-         * viewport, and this stops it queueing behind everything else the parser
-         * found first. Left alone the browser decides, which is right for the other
-         * ninety-nine pictures.
-         */
         this.fetchPriority = 'auto';
-        /**
-         * How much of the referring URL to send with the request.
-         */
         this.referrerPolicy = '';
-        /**
-         * How much of the line it will take, passed through to the picture.
-         */
         this.sizes = '';
-        /**
-         * Where the picture is.
-         */
         this.src = '';
-        /**
-         * The candidate widths, passed through to the picture.
-         */
         this.srcset = '';
-        /**
-         * Whether the picture is on its way, here, or never coming.
-         *
-         * Read-only to a consumer: it is a report rather than a setting.
-         *
-         * **Mirrored to `data-status`, and not reflected as `status`.** It is element
-         * state, so reflecting it puts the element's own bookkeeping into the markup
-         * a consumer rendered: React reads the attribute appearing at upgrade as a
-         * hydration mismatch, and a serialized `<helix-image status="loaded">` pasted
-         * back declares that a picture has arrived which this element has never
-         * fetched. The `data-` name is the library's answer to both, being a name a
-         * re-parse cannot mistake for a declaration, and it is what `data-closed` on
-         * `Toast.Item` already does. A picture arrives after somebody fetched it,
-         * which puts this on the safe side of hydration: a fact that can be true on
-         * the *first* update mirrors to a custom state instead, which is what
-         * `:state(open)` and `:state(checked)` are.
-         *
-         * `loading` writes nothing, because it is where every image starts and the
-         * resting state of a mirror is the attribute's absence.
-         */
         this.status = 'loading';
-        /**
-         * Which `src` the current status belongs to, so a new one starts over.
-         */
         this.answered = '';
         this.handleLoad = (event) => {
             this.announce('loaded', event);
@@ -135,28 +27,6 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
             this.announce('error', event);
         };
     }
-    /**
-     * Says so under the platform's own name, because the platform's cannot escape.
-     *
-     * `load` and `error` on an `<img>` neither bubble nor compose, so the ones
-     * fired inside this shadow root reach nobody outside it. Re-emitting from the
-     * host is what `relayNativeEvent` is for, and it is what `Avatar` already does
-     * for the same pair on the same element.
-     *
-     * **Unprefixed, unlike every other event here.** The prefix exists to stop a
-     * collision with a native name, and there is none to collide with: the native
-     * events cannot reach a consumer at all.
-     *
-     * **Not bubbling, and that is not a small point.** A bubbling relay of `load`
-     * would be the tempting one, letting a gallery count its pictures with one
-     * listener, and it reaches nothing in React: `load` is in react-dom's
-     * `nonDelegatedEvents`, so there is no root
-     * listener to catch it, and React attaches a direct one for `<img>` and never
-     * for a custom element. `bindReactHandler` binds exactly the non-bubbling
-     * ones, so matching the native propagation is what makes `onLoad` work at
-     * all. A gallery does here what it already does for `<img>`, which is listen
-     * in the capture phase or listen per picture.
-     */
     announce(status, event) {
         this.status = status;
         const name = status === 'loaded' ? 'load' : 'error';
@@ -164,29 +34,8 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
             this.relayNativeEvent(event);
             return;
         }
-        /* No original to relay: `settle` catches a picture that was already
-           complete when the listener attached, which is the cached case, and the
-           platform fired its `load` before anyone was listening. The synthesized
-           one carries the native propagation rather than defaults, so a consumer
-           cannot tell the two paths apart. */
         this.dispatchEvent(new Event(name, { bubbles: false, cancelable: false, composed: false }));
     }
-    /**
-     * Catches the picture that was already there.
-     *
-     * A cached image can finish loading before this element has a listener on it,
-     * and then `load` never fires and the placeholder stays up over a picture that
-     * is sitting right behind it. `complete` is the platform's own answer to that
-     * question, and `naturalWidth` separates a decoded picture from one that
-     * carries no pixels, which `complete` reports as finished either way.
-     *
-     * **It can only ever conclude success.** A picture that has not been attempted
-     * looks exactly like one that failed: `complete` is true and `naturalWidth` is
-     * zero for both, and a DOM that never fetches anything reports that for every
-     * image it has, so deciding `error` here calls every picture broken the moment
-     * it renders. Failure has an event of its own and that event is reliable, so
-     * this is only here to catch the success that happened too early to hear.
-     */
     settle() {
         const image = this.renderRoot?.querySelector('img');
         if (this.src === '' || !image?.complete || image.naturalWidth === 0) {
@@ -196,9 +45,6 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* A new picture is a new question, so the old answer goes. Without this a
-           second `src` inherits the first one's `loaded` and never shows its own
-           placeholder. */
         if (changed.has('src') && this.answered !== this.src) {
             this.answered = this.src;
             this.status = 'loading';
@@ -209,9 +55,6 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
         if (changed.has('src')) {
             this.settle();
         }
-        /* The mirror, written here rather than reflected. `loading` is the resting
-           state and writes nothing, so a picture on its way carries no attribute
-           and one that has arrived or failed says which. */
         if (changed.has('status')) {
             if (this.status === 'loading') {
                 this.removeAttribute('data-status');
@@ -225,35 +68,18 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
         super.firstUpdated?.(changed);
         this.settle();
     }
-    /**
-     * The picture's own state, under the platform's own names.
-     *
-     * The `<img>` is inside this shadow root and `querySelector` does not cross a
-     * shadow boundary, so a consumer asking how big the picture turned out to be,
-     * or whether it is already there, has nowhere else to ask. `status` answers a
-     * narrower question in this library's words and is no substitute for the
-     * numbers.
-     *
-     * `naturalWidth` and `naturalHeight` are the case worth having: they are how
-     * a consumer sizes a lightbox or works out an aspect ratio, and they exist
-     * nowhere else on the page.
-     */
     get image() {
         return this.renderRoot?.querySelector('img') ?? null;
     }
-    /** Whether the picture has finished arriving, however it went. */
     get complete() {
         return this.image?.complete ?? false;
     }
-    /** Which candidate the browser actually chose out of `srcset`. */
     get currentSrc() {
         return this.image?.currentSrc ?? '';
     }
-    /** The picture's own height in pixels, and zero until it has arrived. */
     get naturalHeight() {
         return this.image?.naturalHeight ?? 0;
     }
-    /** The picture's own width in pixels, and zero until it has arrived. */
     get naturalWidth() {
         return this.image?.naturalWidth ?? 0;
     }

package/dist/index.js

@@ -1,13 +1,4 @@
 import './element-events.generated.js';
-/**
- * Everything core exports, forwarded whole.
- *
- * Not a named list. The generated React package imports the type each public
- * property is declared with, so anything a component newly reaches for (a
- * value-change event, a placement type, a close event) compiles here and breaks
- * there the moment the list misses it. Forwarding the module has nothing to
- * keep in step.
- */
 export * from '@fusion.dev/helix-core';
 export * from './accordion/index.js';
 export * from './announcement/index.js';

package/dist/input/root/input-root.js

@@ -8,177 +8,27 @@ import { AriaForwardController, customElement, drawIcon, HelixFormElement, holdC
 import { eye, eyeSlash, x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary A single line of text a reader types into.
- *
- * @description
- * Renders a real `<input>`, so the caret, selection, autofill, spellcheck, the
- * password manager, and the on-screen keyboard a phone chooses all come from the
- * platform. `delegatesFocus` puts focus on it, and it serializes into the
- * server's markup, so the field is usable 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.
- *
- * `value` and `defaultValue` are separate for the reason `checked` and
- * `defaultChecked` are: `value` is what is in the field now and
- * `defaultValue` is what the markup asked for, which is where a reset returns
- * to and is gone the moment anyone types.
- *
- * **Validity is the platform's.** The `type` and `required` are set on the real
- * input and its `validity` is copied onto the host, so an email field rejects
- * what the browser says is not an email rather than what a regular expression
- * here guesses. What this adds is the anchor, so `reportValidity` points the
- * bubble at the input rather than at the host.
- *
- * `pattern`, `minlength` and `maxlength` are forwarded with them.
- *
- * **`clearable` and `reveal` are the field's, not the consumer's.** Neither is
- * a slot's worth of variation: one empties the value, the other flips the type,
- * and both want the same position, the same size and the same disabled
- * behavior. The `end` slot stays for what actually varies, a unit or a prefix.
- *
- * Both opt in rather than following from `type`, and are booleans that default
- * to false. A Lit boolean property that defaults to *true* cannot be turned off
- * from HTML at all, only from script, which is the wrong way round for
- * revealing a password: a consumer should have to ask for it. Drawer's `modal`
- * defaults true for the opposite reason, that losing a focus trap by forgetting
- * a word is worse than having to say so.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases TextField, Field, TextInput
- * @documentation https://helix.fusion.dev/components/input
- *
- * @slot end - After the text, for an icon or a unit.
- * @slot start - Before the text, for an icon or a prefix.
- *
- * @event {Event} change - Relayed from the input once the reader has finished.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
- *
- * @csspart clear - The button that empties the field.
- * @csspart control - The input itself.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding everything.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart reveal - The button that shows and hides a password.
- */
 let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(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,
         });
-        /** Typed or dragged, so every edit is announced. See `announcesInput`. */
         this.announcesInput = true;
-        /**
-         * What the browser may autofill here, as one of the platform's own tokens.
-         *
-         * Empty leaves the attribute off, which is the browser's default. Set it to
-         * a token like `email` or `bday` to ask for autofill, or to `off` to refuse.
-         */
         this.autocomplete = '';
-        /**
-         * Whether the field offers a button that empties it.
-         *
-         * Shown only while there is something to clear, because a control that does
-         * nothing is worse than no control: a reader who presses it and sees no
-         * change has to work out whether the field was already empty or the button
-         * is broken.
-         */
         this.clearable = false;
-        /**
-         * What the clear button is called, since an icon has no name of its own.
-         */
         this.clearLabel = 'Clear';
-        /**
-         * A regular expression the value has to match, as the platform reads it.
-         *
-         * Forwarded rather than checked here, which is the whole reason validity is
-         * the platform's: the browser knows what a `pattern` means, anchors it at both
-         * ends, and produces the message in the reader's own language.
-         */
         this.pattern = '';
-        /**
-         * Shown while the field is empty.
-         *
-         * Not a label: it goes when typing starts.
-         */
         this.placeholder = '';
-        /**
-         * Whether the field refuses input while still submitting its value.
-         *
-         * **The attribute is `readonly`, which is the platform's spelling.** A
-         * camelCase property needs an explicit `attribute`, and dash-casing a word
-         * HTML writes as one costs what an attribute always costs here: nothing
-         * warns. `<helix-input readonly>` is what anybody who has written HTML types;
-         * against `read-only` it parses to no property at all, and the field stays
-         * editable with no error anywhere. Measured on the dash-cased form, `readOnly`
-         * came back `false`.
-         *
-         * A part was renamed for
-         * the same kind of reason: there is no `helix-v` tag, so no consumer is
-         * holding the old spelling, and this is free today and a deprecation after
-         * the first release.
-         */
         this.readOnly = false;
-        /**
-         * Whether the password is currently showing.
-         *
-         * State rather than a property: it is a reader's momentary choice about what
-         * is on their own screen, it must not survive anything, and a consumer that
-         * could set it could reveal a password without the reader asking.
-         */
         this.revealed = false;
-        /**
-         * Every keystroke, cancelable, and put back where it is refused.
-         *
-         * The input has already taken the character by the time this runs, so a
-         * consumer that refuses the change has to see the field returned to what the
-         * element still holds. Otherwise the text on screen and the value the form
-         * would submit disagree, which is the one thing a controlled field must never
-         * do.
-         */
         this.handleInput = (event) => {
-            /* **Stopped, because the control inside this one is not a control a consumer
-               has.** `input` is composed by specification, so the native event from the
-               `<input>` in this shadow root crosses the boundary and reaches the host
-               beside the one the mixin announces: measured in Chrome 148, one keystroke
-               produced `helix-before-change`, this element's own `input`, and the inner
-               control's, so `onInput` ran twice and one of the two carried the value
-               from before the change. `handleChange` two methods down does the same. */
             event.stopPropagation();
             const control = event.target;
             const next = control.value;
-            /* Through the mixin, which announces and then applies only if the value is
-               the element's to move. The native control has already changed either way,
-               so wherever the answer does not follow it has to be put back: that is a
-               refusal, and it is equally a consumer who owns the value and has not
-               given a new one yet. Both are "what is on screen is not the answer". */
             this.requestValue(next);
             restoreValue(control, this.value);
         };
-        /**
-         * Empties the field and gives the caret back.
-         *
-         * Focus returns to the input rather than staying on the button, which is
-         * about to disappear: a reader who cleared a field is going to type in it,
-         * and focus resting on a control that is being removed lands on the body.
-         *
-         * Through `requestValue` like every other change, so a consumer who owns the
-         * value hears about it and decides, and a canceled clear leaves the text
-         * where it was.
-         */
         this.handleClear = () => {
             this.requestValue('');
             const control = this.control;
@@ -187,74 +37,24 @@ let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(M
                 control.focus();
             }
         };
-        /** Relayed, because `change` does not cross a shadow boundary on its own. */
         this.handleChange = (event) => {
             event.stopPropagation();
             this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
         };
-        /**
-         * Whether a password field offers a toggle that shows what was typed.
-         *
-         * Ignored on every other type. A reveal on an email field would be a button
-         * that does nothing visible, and guarding it here rather than asking the
-         * consumer not to means the property can be set once on a component that
-         * changes type.
-         */
         this.reveal = false;
-        /**
-         * What the reveal toggle is called.
-         *
-         * The state is `aria-pressed`, not this.
-         */
         this.revealLabel = 'Show password';
-        /**
-         * What the field accepts, which decides the keyboard and the validation.
-         *
-         * **Not reflected.** Reflection exists so a selector can reach a value, and
-         * no stylesheet in this repository selects on `type`. Reflecting it writes
-         * `type="text"` onto every `<helix-input>` ever rendered, an attribute no
-         * consumer's markup has, which is the fault the area rules write up under
-         * `Button`'s `href`, `target` and `rel`.
-         *
-         * Nothing reads it from the attribute either. The real `<input>` inside takes
-         * it as a property binding, which is what makes the keyboard and the
-         * validation follow.
-         */
         this.type = 'text';
     }
-    /**
-     * The type the real input is given, which is not always the type asked for.
-     *
-     * A revealed password is a text field for exactly as long as the reader is
-     * looking at it. Reading through a getter rather than mutating `type` keeps
-     * the property the consumer's: what they set is what they get back, whatever
-     * the button is doing.
-     */
     get effectiveType() {
         return this.revealed && this.type === 'password' ? 'text' : this.type;
     }
-    /** Whether there is a clear button on screen right now. */
     get showsClear() {
         return this.clearable && this.value !== '' && !this.isDisabled && !this.readOnly;
     }
-    /** Focus is delegated to the input, so the host is never the focus target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    /**
-     * The caret and the selection, under the platform's own names.
-     *
-     * The `<input>` is inside this shadow root, so a consumer had no way to ask
-     * where the selection is, let alone move it: `querySelector` does not cross
-     * the boundary. An insert-at-cursor toolbar, a format button, a mask that
-     * repositions the caret after rewriting the value, all of them need this and
-     * none of them could be written. Textarea gained the same surface for the same
-     * reason.
-     *
-     * Zero before there is a control, which is where an empty field's caret would
-     * be anyway.
-     */
     get selectionDirection() {
         return this.control?.selectionDirection ?? 'none';
     }
@@ -264,7 +64,6 @@ let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(M
             control.selectionDirection = direction;
         }
     }
-    /** Where the selection ends, as an offset into the value. */
     get selectionEnd() {
         return this.control?.selectionEnd ?? 0;
     }
@@ -274,7 +73,6 @@ let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(M
             control.selectionEnd = at;
         }
     }
-    /** Where the selection starts, as an offset into the value. */
     get selectionStart() {
         return this.control?.selectionStart ?? 0;
     }
@@ -284,51 +82,29 @@ let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(M
             control.selectionStart = at;
         }
     }
-    /**
-     * Selects a range, which is the one operation the three accessors above
-     * cannot express between them.
-     *
-     * Setting `selectionStart` past the current `selectionEnd` drags the end
-     * along, so the two writes a consumer would make in sequence do not compose
-     * into the range they asked for. The platform has this method for that reason
-     * and so does this.
-     */
     setSelectionRange(start, end, direction) {
         this.control?.setSelectionRange(start, end, direction);
     }
     get control() {
         return this.renderRoot.querySelector('[part="control"]');
     }
-    /** Reports the value and the validity the host stands behind. */
     sync() {
         this.internals.setFormValue(this.value);
         const control = this.control;
         if (!control) {
             return;
         }
-        /* The input's own verdict, copied over rather than recomputed. It knows
-           what an email is and what `pattern` means, and it knows it the same way
-           the browser will when the form is submitted. The anchor is what this adds:
-           without it the validity bubble points at the host, which is a box with no
-           text in it. */
         this.internals.setValidity(control.validity, control.validationMessage, control);
-        // Straight after, because validity moved without any property moving.
         this.refreshFeedback();
     }
-    /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options) {
         this.control?.focus(options);
     }
-    /** Selects everything in the field. */
     select() {
         this.control?.select();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* Never before the first update, which is the one the server does: there is
-           no render root to query there, and `querySelector` is not merely empty on
-           Lit's element shim, it is undefined. There is also no caret to keep before
-           anything has rendered. */
         if (!this.hasUpdated) {
             return;
         }
@@ -344,10 +120,6 @@ let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(M
         this.sync();
     }
     render() {
-        /* Label, field, and one line under it.
-           The hint and the feedback share that line rather than stacking, so a
-           field is the same height either way and nothing below it moves when the
-           message changes. */
         return html `${this.renderLabel()}
     <div part="field">
       <slot name="start"></slot>