@fusion.dev/helix-headless 0.0.0-dev

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import './element-events.generated.js';
+/**
+ * Everything core exports, forwarded whole.
+ *
+ * Named individually before, and the list drifted every time a component used
+ * something new: a value-change event, a placement type, a close event. Each
+ * one compiled here and broke in the generated React package, which imports
+ * the type a public property is declared with. 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';
+export * from './app-header/index.js';
+export * from './avatar/index.js';
+export * from './badge/index.js';
+export * from './bar-chart/index.js';
+export * from './blockquote/index.js';
+export * from './breadcrumbs/index.js';
+export * from './button/index.js';
+export * from './button-group/index.js';
+export * from './callout/index.js';
+export * from './card/index.js';
+export * from './carousel/index.js';
+export * from './chat/index.js';
+export * from './checkbox/index.js';
+export * from './checkbox-group/index.js';
+export * from './code/index.js';
+export * from './code-block/index.js';
+export * from './color-input/index.js';
+export * from './color-picker/index.js';
+export * from './combobox/index.js';
+export * from './command/index.js';
+export * from './copy-button/index.js';
+export * from './data-table/index.js';
+export * from './date-input/index.js';
+export * from './date-picker/index.js';
+export * from './dialog/index.js';
+export * from './divider/index.js';
+export * from './donut-chart/index.js';
+export * from './drawer/index.js';
+export * from './drilldown/index.js';
+export * from './empty/index.js';
+export * from './file-input/index.js';
+export * from './format-date/index.js';
+export * from './heatmap/index.js';
+export * from './icon/index.js';
+export * from './icon-button/index.js';
+export * from './image/index.js';
+export * from './input/index.js';
+export * from './kbd/index.js';
+export * from './legend/index.js';
+export * from './line-chart/index.js';
+export * from './list/index.js';
+export * from './listbox/index.js';
+export * from './loader/index.js';
+export * from './megamenu/index.js';
+export * from './menu/index.js';
+export * from './meter/index.js';
+export * from './navigation/index.js';
+export * from './notifications/index.js';
+export * from './number-input/index.js';
+export * from './option/index.js';
+export * from './outline/index.js';
+export * from './pagination/index.js';
+export * from './pin-input/index.js';
+export * from './popover/index.js';
+export * from './progress/index.js';
+export * from './qr-code/index.js';
+export * from './quote/index.js';
+export * from './radio/index.js';
+export * from './rating/index.js';
+export * from './scroll-area/index.js';
+export * from './select/index.js';
+export * from './skeleton/index.js';
+export * from './slider/index.js';
+export * from './sparkline/index.js';
+export * from './speed-dial/index.js';
+export * from './splitter/index.js';
+export * from './stat/index.js';
+export * from './steps/index.js';
+export * from './switch/index.js';
+export * from './table/index.js';
+export * from './tabs/index.js';
+export * from './tag/index.js';
+export * from './textarea/index.js';
+export * from './time-input/index.js';
+export * from './time-picker/index.js';
+export * from './timeline/index.js';
+export * from './toast/index.js';
+export * from './toggle/index.js';
+export * from './toolbar/index.js';
+export * from './tooltip/index.js';
+export * from './tour/index.js';
+export * from './tree/index.js';
+export * from './trend/index.js';
+export * from './video/index.js';
+export * from './video-playlist/index.js';
+export * from './virtual-list/index.js';

package/dist/index.js

@@ -0,0 +1,99 @@
+import './element-events.generated.js';
+/**
+ * Everything core exports, forwarded whole.
+ *
+ * Named individually before, and the list drifted every time a component used
+ * something new: a value-change event, a placement type, a close event. Each
+ * one compiled here and broke in the generated React package, which imports
+ * the type a public property is declared with. 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';
+export * from './app-header/index.js';
+export * from './avatar/index.js';
+export * from './badge/index.js';
+export * from './bar-chart/index.js';
+export * from './blockquote/index.js';
+export * from './breadcrumbs/index.js';
+export * from './button/index.js';
+export * from './button-group/index.js';
+export * from './callout/index.js';
+export * from './card/index.js';
+export * from './carousel/index.js';
+export * from './chat/index.js';
+export * from './checkbox/index.js';
+export * from './checkbox-group/index.js';
+export * from './code/index.js';
+export * from './code-block/index.js';
+export * from './color-input/index.js';
+export * from './color-picker/index.js';
+export * from './combobox/index.js';
+export * from './command/index.js';
+export * from './copy-button/index.js';
+export * from './data-table/index.js';
+export * from './date-input/index.js';
+export * from './date-picker/index.js';
+export * from './dialog/index.js';
+export * from './divider/index.js';
+export * from './donut-chart/index.js';
+export * from './drawer/index.js';
+export * from './drilldown/index.js';
+export * from './empty/index.js';
+export * from './file-input/index.js';
+export * from './format-date/index.js';
+export * from './heatmap/index.js';
+export * from './icon/index.js';
+export * from './icon-button/index.js';
+export * from './image/index.js';
+export * from './input/index.js';
+export * from './kbd/index.js';
+export * from './legend/index.js';
+export * from './line-chart/index.js';
+export * from './list/index.js';
+export * from './listbox/index.js';
+export * from './loader/index.js';
+export * from './megamenu/index.js';
+export * from './menu/index.js';
+export * from './meter/index.js';
+export * from './navigation/index.js';
+export * from './notifications/index.js';
+export * from './number-input/index.js';
+export * from './option/index.js';
+export * from './outline/index.js';
+export * from './pagination/index.js';
+export * from './pin-input/index.js';
+export * from './popover/index.js';
+export * from './progress/index.js';
+export * from './qr-code/index.js';
+export * from './quote/index.js';
+export * from './radio/index.js';
+export * from './rating/index.js';
+export * from './scroll-area/index.js';
+export * from './select/index.js';
+export * from './skeleton/index.js';
+export * from './slider/index.js';
+export * from './sparkline/index.js';
+export * from './speed-dial/index.js';
+export * from './splitter/index.js';
+export * from './stat/index.js';
+export * from './steps/index.js';
+export * from './switch/index.js';
+export * from './table/index.js';
+export * from './tabs/index.js';
+export * from './tag/index.js';
+export * from './textarea/index.js';
+export * from './time-input/index.js';
+export * from './time-picker/index.js';
+export * from './timeline/index.js';
+export * from './toast/index.js';
+export * from './toggle/index.js';
+export * from './toolbar/index.js';
+export * from './tooltip/index.js';
+export * from './tour/index.js';
+export * from './tree/index.js';
+export * from './trend/index.js';
+export * from './video/index.js';
+export * from './video-playlist/index.js';
+export * from './virtual-list/index.js';

package/dist/input/index.d.ts

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

package/dist/input/index.js

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

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

@@ -0,0 +1,281 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/** What the control accepts, which is text of one kind or another. */
+export type InputType = 'email' | 'number' | 'password' | 'search' | 'tel' | 'text' | 'url';
+declare const HelixHeadlessInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @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. They were
+ * promised by this paragraph and did not exist, so a consumer following the
+ * sentence wrote an attribute on the host that reached no input and constrained
+ * nothing: the field looked as though it were checked and was not.
+ *
+ * **`clearable` and `reveal` are the field's, not the consumer's.** The `end`
+ * slot used to be the answer to both, which meant every consumer of
+ * `type="search"` built the same button and every consumer of
+ * `type="password"` either built the same toggle or shipped a field a reader
+ * cannot check what they typed into. 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 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 icon - A glyph this component draws.
+ * @csspart label - The question, over the field.
+ * @csspart reveal - The button that shows and hides a password.
+ */
+export declare class HelixHeadlessInput extends HelixHeadlessInput_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;
+    /**
+     * 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`, which is the platform's spelling, and it was `read-only`
+     * until 28 Aug 2026.** A camelCase property needs an explicit `attribute`
+     * and the library had been answering that question two ways: thirteen
+     * attributes kept the name HTML uses (`crossorigin`, `maxlength`,
+     * `formnovalidate`, `dirname` and the rest) and five dash-cased a word the
+     * platform writes as one. `readonly` was the only one on both lists, this
+     * spelling on `Rating` and `read-only` on the eight other fields, so one
+     * library shipped both and each was inert on the other's families.
+     *
+     * The cost of the dash-cased form is the one this repository keeps writing
+     * down about attributes: nothing warns. `<helix-input readonly>` is what
+     * anybody who has written HTML types, it parsed to no property at all, and
+     * the field stayed editable with no error anywhere. Measured before the
+     * rename: `readOnly` came back `false`.
+     *
+     * Taken now for the reason [#213](../../../../../docs/19-queue.md) gives
+     * about the part it 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.
+     * `check:attribute-names` holds it from here.
+     */
+    readOnly: boolean;
+    /**
+     * What the field accepts, which decides the keyboard and the validation.
+     *
+     * **Not reflected**, and it was. Reflection exists so a selector can reach a
+     * value, and no stylesheet in this repository selects on `type`: what it did
+     * instead was write `type="text"` onto every `<helix-input>` ever rendered,
+     * an attribute no consumer's markup had. That is precisely the fault `Button`
+     * had with `href`, `target` and `rel`, written up in the area rules as the
+     * reason the rule exists, and this was the last property in the library still
+     * doing it. Audited: ten reflected attributes have no selector anywhere, and
+     * this is the only one of them with a value that puts itself on the host.
+     *
+     * 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.
+     */
+    type: InputType;
+    /**
+     * 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.
+     */
+    clearable: boolean;
+    /**
+     * What the clear button is called, since an icon has no name of its own.
+     */
+    clearLabel: string;
+    /**
+     * 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.
+     */
+    reveal: boolean;
+    /**
+     * What the reveal toggle is called.
+     *
+     * The state is `aria-pressed`, not this.
+     */
+    revealLabel: string;
+    /**
+     * 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.
+     */
+    private revealed;
+    /**
+     * 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.
+     */
+    private get effectiveType();
+    /** Whether there is a clear button on screen right now. */
+    private get showsClear();
+    /** Focus is delegated to the input, so the host is never the focus target. */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * 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. See 295.
+     *
+     * Zero before there is a control, 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;
+    private get control();
+    /**
+     * 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.
+     */
+    private readonly handleInput;
+    /**
+     * 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.
+     */
+    private readonly handleClear;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /** Reports the value and the validity the host stands behind. */
+    private sync;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    /** Selects everything in the field. */
+    select(): void;
+    /**
+     * 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;
+    /**
+     * A regular expression the value has to match, as the platform reads it.
+     *
+     * The class documentation promised `pattern` and `minlength` "and the rest"
+     * were set on the real input, and no such properties existed: a consumer
+     * following that sentence wrote an attribute on the host, it reached no input,
+     * and the field constrained nothing while looking as though it did.
+     *
+     * 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.
+     */
+    pattern: string;
+    /**
+     * Fewest characters the value may have.
+     */
+    minLength?: number;
+    /**
+     * Most characters the value may have.
+     */
+    maxLength?: number;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-input': HelixHeadlessInput;
+    }
+}
+export {};