@fusion.dev/helix-headless 0.0.0-dev

package/dist/tabs/tab/tab.js

@@ -0,0 +1,116 @@
+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 { customElement, HelixElement, HelixSelectEvent } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary One tab in a tab list.
+ *
+ * @description
+ * An element rather than a slot because it owns selection and its own tab stop.
+ *
+ * Its id and the id it controls are both derived from `value`, so the pairing
+ * between a tab and its panel survives server rendering. A generated id would
+ * differ between the server's render and the client's and break the link, and
+ * `aria-controls` pointing at nothing is worse than not being there.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Tab
+ * @documentation https://helix.fusion.dev/components/tabs
+ *
+ * @slot - The tab's label.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when the tab is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart tab - The tab itself.
+ */
+let HelixHeadlessTab = class HelixHeadlessTab extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Identifies the tab, and pairs it with the panel of the same value.
+         */
+        this.value = '';
+        /**
+         * Whether this tab is the current one.
+         */
+        this.selected = false;
+        /**
+         * Whether the tab can be chosen.
+         */
+        this.disabled = false;
+    }
+    /** Moves focus to this tab, for the list's arrow keys. */
+    focusItem() {
+        this.renderRoot.querySelector('[part="tab"]')?.focus();
+    }
+    /** Selects this tab and announces it. */
+    select() {
+        if (this.disabled) {
+            return;
+        }
+        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+    }
+    /**
+     * Mirrors the chosen state where a stylesheet can select on it.
+     *
+     * **A custom state and not the `selected` attribute it used to reflect.** The
+     * parent writes this: a listbox choosing a row, a tab strip moving the tab, a
+     * radio group answering for its set. Reflected, that put the element's own
+     * bookkeeping onto markup a consumer wrote and a consumer's server never sent,
+     * which React reconciles and reports as a mismatch, and which a serialized
+     * element pasted back declares as a choice nobody made. `ElementInternals`
+     * holds it instead, where it is not in the DOM at all.
+     *
+     * Reading `selected` is unaffected and so is writing it: the attribute still
+     * seeds the property, which is what `<helix-tab selected>` in a consumer's
+     * markup means. What stops is the write back. See 302 and 304.
+     */
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('selected', this.selected);
+    }
+    render() {
+        /* No `aria-controls`, and no id for one to point at.
+         *
+         * It named `panel-${value}`, an id rendered inside the panel's *own* shadow
+         * root, and an IDREF resolves only within the tree it is written in. So it
+         * pointed at nothing from the day it was written, on every tab, and this
+         * file's own comment said a dangling `aria-controls` is worse than none.
+         *
+         * There is no id form that could work and no element reference either: a
+         * reference is valid only into the same tree or a shadow-including ancestor
+         * of it, and the panel's shadow root is neither, it is a sibling. The
+         * relationship a reader actually needs is the panel's name, and the panel
+         * takes that as a string, which crosses anything. */
+        return html `<button
+      part="tab"
+      role="tab"
+      type="button"
+      aria-selected=${this.selected ? 'true' : 'false'}
+      ?disabled=${this.disabled}
+      tabindex=${this.selected ? '0' : '-1'}
+      @click=${() => this.select()}
+    >
+      <slot></slot>
+    </button>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTab.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessTab.prototype, "selected", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTab.prototype, "disabled", void 0);
+HelixHeadlessTab = __decorate([
+    customElement('helix-headless-tab')
+], HelixHeadlessTab);
+export { HelixHeadlessTab };

package/dist/tag/index.d.ts

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

package/dist/tag/index.js

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

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

@@ -0,0 +1,41 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+declare const HelixHeadlessTag_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
+/**
+ * @summary Labels content with a short piece of metadata.
+ *
+ * @description
+ * A tag is a label, and optionally a label the reader can take off.
+ * `dismissible` is what separates it from a badge: a badge reports a state the
+ * reader cannot change, a tag names something they can.
+ *
+ * Dismissing is a request. The tag does not remove itself, because the consumer
+ * owns the list it sits in and taking the node out from under them would put
+ * their state and the document out of step. Canceling `helix-dismiss` is a
+ * refusal.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category markers
+ * @aliases Chip, Pill, Label
+ * @documentation https://helix.fusion.dev/components/tag
+ *
+ * @slot - The tag's label.
+ * @slot prefix - A category the label belongs to, set before it and weightier.
+ *
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the tag. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart dismiss - The control that asks to remove the tag.
+ * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart prefix - The category before the label.
+ */
+export declare class HelixHeadlessTag extends HelixHeadlessTag_base {
+    dismissLabel: string;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-tag': HelixHeadlessTag;
+    }
+}
+export {};

package/dist/tag/root/tag-root.js

@@ -0,0 +1,67 @@
+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 { customElement, HelixElement, MixinDismissible } from '@fusion.dev/helix-core';
+import { x } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary Labels content with a short piece of metadata.
+ *
+ * @description
+ * A tag is a label, and optionally a label the reader can take off.
+ * `dismissible` is what separates it from a badge: a badge reports a state the
+ * reader cannot change, a tag names something they can.
+ *
+ * Dismissing is a request. The tag does not remove itself, because the consumer
+ * owns the list it sits in and taking the node out from under them would put
+ * their state and the document out of step. Canceling `helix-dismiss` is a
+ * refusal.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category markers
+ * @aliases Chip, Pill, Label
+ * @documentation https://helix.fusion.dev/components/tag
+ *
+ * @slot - The tag's label.
+ * @slot prefix - A category the label belongs to, set before it and weightier.
+ *
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the tag. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart dismiss - The control that asks to remove the tag.
+ * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart prefix - The category before the label.
+ */
+let HelixHeadlessTag = class HelixHeadlessTag extends MixinDismissible(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /* "Remove" rather than the mixin's "Dismiss". A tag is taken out of a set,
+           which is a different act from closing a message, and the control's name is
+           what a screen-reader user hears. */
+        this.dismissLabel = 'Remove';
+    }
+    render() {
+        return html `<slot name="prefix" part="prefix"></slot>
+      <slot></slot>
+      ${this.dismissible
+            ? html `<button
+            part="dismiss"
+            type="button"
+            aria-label=${this.dismissLabel}
+            @click=${() => this.dismiss()}
+          >
+            <svg part="dismiss-mark" fill="currentColor" viewBox=${x.viewBox} aria-hidden="true">
+              ${unsafeSVG(x.content)}
+            </svg>
+          </button>`
+            : nothing}`;
+    }
+};
+HelixHeadlessTag = __decorate([
+    customElement('helix-headless-tag')
+], HelixHeadlessTag);
+export { HelixHeadlessTag };

package/dist/textarea/index.d.ts

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

package/dist/textarea/index.js

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

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

@@ -0,0 +1,215 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessTextarea_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @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.
+ */
+export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
+    protected readonly aria: AriaForwardController;
+    /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+    protected readonly 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.
+     */
+    autocomplete: string;
+    /**
+     * Whether the box follows its own content rather than scrolling.
+     */
+    autoGrow: boolean;
+    /**
+     * Shown while the field is empty.
+     *
+     * Not a label: it goes when typing starts.
+     */
+    placeholder: string;
+    /**
+     * Whether the field refuses input while still submitting its value.
+     */
+    readOnly: boolean;
+    /**
+     * How many lines the box is before anything is typed.
+     */
+    rows: number;
+    /**
+     * How many characters wide the box is, where the layout is not deciding.
+     *
+     * Optional and absent by default, which is the reflected-property rule: a
+     * `<textarea>` left alone is 20 columns wide and a styled one is whatever its
+     * box says, so writing a number here is a departure rather than the resting
+     * state. `wrap="hard"` needs it, the two being the pair that decides where
+     * the browser inserts the line breaks it submits.
+     */
+    cols?: number;
+    /**
+     * 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.
+     */
+    dirName: string;
+    /**
+     * How the browser wraps the text, and whether the breaks are submitted with
+     * it.
+     */
+    wrap: 'hard' | 'off' | 'soft';
+    /** Focus is delegated to the control, so the host is never the target. */
+    static shadowRootOptions: ShadowRootInit;
+    private get control();
+    /**
+     * 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.
+     */
+    private readonly handleInput;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /**
+     * 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.
+     */
+    private grow;
+    /**
+     * Re-measures when the box changes rather than only when a property does.
+     *
+     * The height was computed on Lit updates alone, and nothing about a container
+     * narrowing, a font swapping, or the field finally gaining a layout box is a
+     * property change here. A field that wrapped to three lines at one width kept
+     * a three-line height at half the width and clipped the rest behind
+     * `overflow: hidden`, with no way for a reader to reach it.
+     *
+     * Observing the control also covers the zero case above from the other side:
+     * a `ResizeObserver` fires when an element gains a box, so a field that was
+     * hidden when it first tried to grow measures itself the moment it is shown.
+     */
+    private resize;
+    /**
+     * 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.
+     */
+    private formValue;
+    /**
+     * 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(): SelectionDirection;
+    set selectionDirection(direction: SelectionDirection);
+    /** Where the selection ends, as an offset into the value. */
+    get selectionEnd(): number;
+    set selectionEnd(at: number);
+    /** Where the selection starts, as an offset into the value. */
+    get selectionStart(): number;
+    set selectionStart(at: number);
+    /**
+     * 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: number, end: number, direction?: SelectionDirection): void;
+    /** How many characters the value holds. */
+    get textLength(): number;
+    /** What kind of control this is, which for a textarea is always the one word. */
+    get type(): string;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    /** Reports the value and the validity the host stands behind. */
+    private sync;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    /** Watches the control so the box grows with what is typed into it. */
+    private watchControl;
+    /**
+     * The caret, held across a value the consumer wrote rather than the reader.
+     *
+     * Set in `willUpdate` and spent in `updated`, because Lit's `.value` binding
+     * lands between the two and takes the selection with it. See `holdCaret`.
+     */
+    private releaseCaret;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Fewest characters the value may have.
+     *
+     * Forwarded to the real `<textarea>` rather than checked here, which is what
+     * makes the message the browser's and therefore the reader's own language.
+     * No `pattern`: the platform does not give a textarea one, and inventing it
+     * would be this library guessing where the point is to stop guessing.
+     */
+    minLength?: number;
+    /**
+     * Most characters the value may have.
+     */
+    maxLength?: number;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-textarea': HelixHeadlessTextarea;
+    }
+}
+export {};