@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/textarea/root/textarea-root.js

@@ -7,122 +7,33 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { AriaForwardController, customElement, HelixFormElement, holdCaret, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Several lines of text a reader types into.
- *
- * @description
- * A real `<textarea>`, so the caret, the selection, spellcheck, the resize
- * handle and the keyboard a phone chooses are all the platform's, and it
- * serializes into the server's markup so the field is usable before any script
- * loads.
- *
- * **Not an Input with a taller box.** The difference is the Enter key: in a
- * single-line field it submits the form, and here it inserts a line. That is a
- * behavioral difference the platform owns and cannot be styled into existence,
- * which is why this is its own element rather than `Input` with a property.
- *
- * `rows` sets the height it starts at, and `auto-grow` lets it follow its own
- * content. They are not alternatives: `rows` is where an empty field begins and
- * `auto-grow` is what happens after, so a field that grows still has to start
- * somewhere.
- *
- * @since 0.1.0
- * @status stable
- * @category forms
- * @aliases Multiline, TextArea
- * @documentation https://helix.fusion.dev/components/textarea
- *
- * @event {Event} change - Relayed from the textarea 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 control - The textarea itself.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding the control.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- */
 let HelixHeadlessTextarea = class HelixHeadlessTextarea 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 box follows its own content rather than scrolling.
-         */
         this.autoGrow = false;
-        /**
-         * The name a second entry carries, holding which way the text runs.
-         *
-         * **Submitted through `setFormValue`, because the inner control's own
-         * `dirname` cannot reach the form.** This host is form-associated and reports
-         * its value itself, so the `<textarea>` inside the shadow root participates in
-         * no form at all and forwarding the attribute would have looked right and
-         * submitted nothing. `ElementInternals` takes a `FormData`, which is how one
-         * element sends two entries, and that is what this does.
-         */
         this.dirName = '';
-        /**
-         * 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.
-         */
         this.readOnly = false;
-        /**
-         * Every keystroke, cancelable, and put back where it is refused.
-         *
-         * The control has already taken the character by the time this runs, so
-         * refusing has to restore it, or what is on screen and what the form would
-         * submit disagree.
-         */
         this.handleInput = (event) => {
-            // Stopped for the reason `Input.handleInput` gives: the inner control's own
-            // `input` is composed and would reach a consumer beside this element's.
             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. */
             this.requestValue(next);
             restoreValue(control, this.value);
             this.grow();
         };
-        /** 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 }));
         };
-        /**
-         * How many lines the box is before anything is typed.
-         */
         this.rows = 3;
-        /**
-         * How the browser wraps the text, and whether the breaks are submitted with
-         * it.
-         */
         this.wrap = 'soft';
     }
-    /** Focus is delegated to the control, so the host is never the target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
@@ -130,49 +41,18 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
     get control() {
         return this.renderRoot.querySelector('[part="control"]');
     }
-    /**
-     * Follows the content, by measuring rather than by counting.
-     *
-     * `scrollHeight` is what the text actually needs, which no arithmetic over
-     * line count and line height gets right: a wrapped line, a pasted paragraph
-     * and a font that has not loaded yet all break the arithmetic and none of
-     * them break the measurement.
-     *
-     * Reset to `auto` first, because `scrollHeight` of an element already sized to
-     * its content is that size, so without the reset the box can only ever grow.
-     */
     grow() {
         const control = this.control;
         if (!this.autoGrow || !control) {
             return;
         }
         control.style.blockSize = 'auto';
-        /* Zero is not a height, it is the absence of a layout box.
-         *
-         * An element with `display: none` anywhere above it reports `scrollHeight`
-         * as zero. Written back as a fixed `block-size` it pins the field there,
-         * since every later call then measures a control at zero and measures zero
-         * again: a textarea inside a tab panel, an accordion, or anything else that
-         * renders shut and opens later comes out as a hairline with the text hidden
-         * behind it. `tabs-root` refuses zero for the same reason.
-         *
-         * The reset to `auto` above has already been written by this point, which
-         * is the right state to leave it in: an ungrown auto-grow field is the
-         * browser's own height, not a stale number from the last time it had one. */
         const next = control.scrollHeight;
         if (next === 0) {
             return;
         }
         control.style.blockSize = `${next}px`;
     }
-    /**
-     * What the form receives, which is two entries where `dirName` asks for it.
-     *
-     * A plain string otherwise, because that is the common case and a `FormData`
-     * of one entry says the same thing at more cost. The direction is read off
-     * the control rather than assumed, so a field a consumer set `dir="rtl"` on,
-     * or one inside an RTL document, submits what the reader actually saw.
-     */
     formValue() {
         const control = this.control;
         if (!this.dirName || !this.name || !control) {
@@ -183,19 +63,6 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
         data.append(this.dirName, getComputedStyle(control).direction === 'rtl' ? 'rtl' : 'ltr');
         return data;
     }
-    /**
-     * The caret and the selection, under the platform's own names.
-     *
-     * **The whole reason this renders a real `<textarea>` is the caret**, and the
-     * control is inside this shadow root, so `querySelector` does not find it and
-     * a consumer has no other way to ask where the selection is, let alone move
-     * it. A field that cannot be scripted at the caret cannot do an
-     * insert-at-cursor toolbar, which is the first thing anybody builds on a
-     * textarea.
-     *
-     * Written through to the control, and answering zero before there is one,
-     * which is where an empty field's caret would be anyway.
-     */
     get selectionDirection() {
         return this.control?.selectionDirection ?? 'none';
     }
@@ -205,7 +72,6 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
             control.selectionDirection = direction;
         }
     }
-    /** Where the selection ends, as an offset into the value. */
     get selectionEnd() {
         return this.control?.selectionEnd ?? 0;
     }
@@ -215,7 +81,6 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
             control.selectionEnd = at;
         }
     }
-    /** Where the selection starts, as an offset into the value. */
     get selectionStart() {
         return this.control?.selectionStart ?? 0;
     }
@@ -225,49 +90,27 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
             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);
     }
-    /** How many characters the value holds. */
     get textLength() {
         return this.value.length;
     }
-    /** What kind of control this is, which for a textarea is always the one word. */
     get type() {
         return 'textarea';
     }
-    /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options) {
         this.control?.focus(options);
     }
-    /** Reports the value and the validity the host stands behind. */
     sync() {
         this.internals.setFormValue(this.formValue());
         const control = this.control;
         if (!control) {
             return;
         }
-        // The platform's verdict, copied rather than recomputed, with the control as
-        // the anchor so a validity bubble points at the text and not at the host.
         this.internals.setValidity(control.validity, control.validationMessage, control);
         this.refreshFeedback();
     }
-    /* Rebuilt on reconnection, because nothing else does it.
-     *
-     * `firstUpdated` runs once for the life of the element and
-     * `disconnectedCallback` runs every time it moves, so without this a
-     * framework reordering a list leaves the observer gone with nothing to
-     * rebuild it. Guarded on `hasUpdated`, because the first connection happens
-     * before the first render and there is nothing to watch yet. */
     connectedCallback() {
         super.connectedCallback();
         if (this.hasUpdated) {
@@ -283,7 +126,6 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
         super.firstUpdated(changed);
         this.watchControl();
     }
-    /** Watches the control so the box grows with what is typed into it. */
     watchControl() {
         const control = this.control;
         if (!control) {
@@ -295,10 +137,6 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
     }
     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;
         }