@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,380 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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;
+        /**
+         * 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;
+        /**
+         * How many lines the box is before anything is typed.
+         */
+        this.rows = 3;
+        /**
+         * 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 = '';
+        /**
+         * How the browser wraps the text, and whether the breaks are submitted with
+         * it.
+         */
+        this.wrap = 'soft';
+        /**
+         * 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: 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);
+            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 }));
+        };
+    }
+    /** Focus is delegated to the control, so the host is never the target. */
+    static { this.shadowRootOptions = {
+        ...HelixFormElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    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, and this wrote that straight back as a fixed `block-size`. The
+         * field then had a real inline height of zero pixels and stayed there:
+         * every later call measured a control pinned to zero and measured zero
+         * again. A textarea inside a tab panel, an accordion, or anything else that
+         * renders shut and opens later came 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) {
+            return this.value;
+        }
+        const data = new FormData();
+        data.append(this.name, this.value);
+        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
+     * caret was the one thing a consumer could not reach: the control is inside
+     * this shadow root, so `querySelector` does not find it and there was no 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';
+    }
+    set selectionDirection(direction) {
+        const control = this.control;
+        if (control) {
+            control.selectionDirection = direction;
+        }
+    }
+    /** Where the selection ends, as an offset into the value. */
+    get selectionEnd() {
+        return this.control?.selectionEnd ?? 0;
+    }
+    set selectionEnd(at) {
+        const control = this.control;
+        if (control) {
+            control.selectionEnd = at;
+        }
+    }
+    /** Where the selection starts, as an offset into the value. */
+    get selectionStart() {
+        return this.control?.selectionStart ?? 0;
+    }
+    set selectionStart(at) {
+        const control = this.control;
+        if (control) {
+            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 a framework reordering
+     * a list left this permanently dead: the observer gone, nothing to rebuild
+     * it, and the component still rendering as though it were watching. Guarded
+     * on `hasUpdated`, because the first connection happens before the first
+     * render and there is nothing to watch yet. `check:observers` holds it. */
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.hasUpdated) {
+            this.watchControl();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.resize?.disconnect();
+        this.resize = undefined;
+    }
+    firstUpdated(changed) {
+        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) {
+            return;
+        }
+        this.resize?.disconnect();
+        this.resize = new ResizeObserver(() => this.grow());
+        this.resize.observe(control);
+    }
+    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;
+        }
+        const control = this.control;
+        if (changed.has('value') && control && this.shadowRoot?.activeElement === control) {
+            this.releaseCaret = holdCaret(control);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.releaseCaret?.();
+        this.releaseCaret = undefined;
+        this.sync();
+        this.grow();
+    }
+    render() {
+        return html `${this.renderLabel()}
+    <div part="field">
+      <textarea
+        part="control"
+        id="control"
+        .value=${this.value}
+        rows=${this.rows}
+        cols=${this.cols ?? nothing}
+        wrap=${this.wrap}
+        name=${this.name || nothing}
+        placeholder=${this.placeholder || nothing}
+        autocomplete=${this.autocomplete || nothing}
+        minlength=${this.minLength ?? nothing}
+        maxlength=${this.maxLength ?? nothing}
+        aria-describedby=${this.describedBy ?? nothing}
+        ?disabled=${this.isDisabled}
+        ?readonly=${this.readOnly}
+        ?required=${this.required}
+        @input=${this.handleInput}
+        @change=${this.handleChange}
+      ></textarea>
+    </div>
+    ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTextarea.prototype, "autocomplete", void 0);
+__decorate([
+    property({ attribute: 'auto-grow', reflect: true, type: Boolean })
+], HelixHeadlessTextarea.prototype, "autoGrow", void 0);
+__decorate([
+    property()
+], HelixHeadlessTextarea.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'readonly', reflect: true, type: Boolean })
+], HelixHeadlessTextarea.prototype, "readOnly", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessTextarea.prototype, "rows", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessTextarea.prototype, "cols", void 0);
+__decorate([
+    property({ attribute: 'dirname' })
+], HelixHeadlessTextarea.prototype, "dirName", void 0);
+__decorate([
+    property()
+], HelixHeadlessTextarea.prototype, "wrap", void 0);
+__decorate([
+    property({ attribute: 'minlength', type: Number })
+], HelixHeadlessTextarea.prototype, "minLength", void 0);
+__decorate([
+    property({ attribute: 'maxlength', type: Number })
+], HelixHeadlessTextarea.prototype, "maxLength", void 0);
+HelixHeadlessTextarea = __decorate([
+    customElement('helix-headless-textarea')
+], HelixHeadlessTextarea);
+export { HelixHeadlessTextarea };

package/dist/time-input/index.d.ts

@@ -0,0 +1 @@
+export * from './root/time-input-root.js';

package/dist/time-input/index.js

@@ -0,0 +1 @@
+export * from './root/time-input-root.js';