@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,322 @@
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../icon/index.js';
+import '../../tag/index.js';
+import '../../time-picker/index.js';
+declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A time, typed or picked from a list.
+ *
+ * @description
+ * **The list is `helix-time-picker`, not a second one written here.** It is worth
+ * having on its own, flat in a settings pane with nothing to open, and this
+ * element is the field, the overlay and the form. Exactly the arrangement Input
+ * Date has with `helix-date-picker` and Color Input with `helix-color-picker`.
+ *
+ * **Typed as well as picked, and that is the division the list depends on.** A
+ * list at a step offers the times a product actually has, and the field is how a
+ * reader says `09:07`. Neither is a worse version of the other: without the
+ * field a step is a cage, and without the list every common time is typed out.
+ *
+ * **The value is `HH:mm` on a twenty-four hour clock, always**, because that is
+ * what a form submits, what `min` and `max` compare against, and what sorts as a
+ * string. What the field *shows* is the reader's own convention while it is
+ * idle, and the value itself once the caret is in it: the same separation Input
+ * Date draws, and for the same reason, which is that `2:30 PM` cannot be typed
+ * back and `Intl` has no parser to make it so.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases TimeField, InputTime
+ * @documentation https://helix.fusion.dev/components/time-input
+ *
+ * @slot feedback - What is wrong with it.
+ * @slot hint - Help under the field.
+ * @slot trigger - The mark on the field saying a list opens.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} input - Announced once the value has moved.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart control - The text input.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The box holding the text and the trigger.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart label - The question, over the field.
+ * @csspart picker - The list inside it.
+ * @csspart picker-column - One of them.
+ * @csspart picker-column-empty - Shown when a filter has hidden everything.
+ * @csspart picker-column-feedback - What is wrong with it.
+ * @csspart picker-column-filter-icon - The mark beside that field.
+ * @csspart picker-column-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart picker-column-hint - Help under the list.
+ * @csspart picker-column-items - The list itself.
+ * @csspart picker-column-label - The question, over the list.
+ * @csspart picker-column-loading - Shown while the options are still on their way.
+ * @csspart picker-column-search - The region holding the field that narrows the list.
+ * @csspart picker-column-search-field - The field itself.
+ * @csspart picker-columns - The row of columns, in `wheels`.
+ * @csspart picker-list - The listbox holding the times, in `list`.
+ * @csspart picker-list-empty - Shown when a filter has hidden everything.
+ * @csspart picker-list-feedback - What is wrong with it.
+ * @csspart picker-list-filter-icon - The mark beside that field.
+ * @csspart picker-list-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart picker-list-hint - Help under the list.
+ * @csspart picker-list-items - The list itself.
+ * @csspart picker-list-label - The question, over the list.
+ * @csspart picker-list-loading - Shown while the options are still on their way.
+ * @csspart picker-list-search - The region holding the field that narrows the list.
+ * @csspart picker-list-search-field - The field itself.
+ * @csspart picker-option - One time in it. Carries `data-between` inside a range.
+ * @csspart picker-option-description - The caption under the words, when there is one.
+ * @csspart picker-option-item - The row.
+ * @csspart picker-option-label - The words.
+ * @csspart picker-option-text - The words and the caption, as one column.
+ * @csspart rest - How many times are held beyond the ones shown.
+ * @csspart surface - The floating panel.
+ * @csspart time - One held time, as a tag, in `multiple`.
+ * @csspart time-dismiss - The remove button, when `dismissible`.
+ * @csspart time-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart time-prefix - The category before the label.
+ * @csspart trigger - The control that opens the list.
+ * @csspart trigger-icon - The mark on the button that opens the clock.
+ */
+export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * 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 and is what
+     * lets autofill work at all. This used to be hardcoded `off`, so a reader
+     * could never have a birthday or a postal code filled in for them and a
+     * consumer had no way to ask for it. See 295.
+     */
+    autocomplete: string;
+    /**
+     * Whether the panel is one list of times or a column each.
+     *
+     * `list` offers whole times, which is what a product with slots or opening
+     * hours has. `wheels` splits them into an hour, a minute and a meridiem where
+     * the locale uses one, which is the only way to reach `23:45` without
+     * scrolling most of a day. `helix-time-picker` carries the longer note on the trade.
+     *
+     * **Optional rather than defaulted, which is not a style preference.** A
+     * reflecting property with a default writes its attribute onto every host the
+     * moment the element upgrades, including the ones a consumer rendered and did
+     * not touch, and React reads that as a hydration mismatch. The absent
+     * attribute *is* the list, which the stylesheet reads as the base rule, so
+     * only the departure has to be named.
+     */
+    variant?: 'list' | 'wheels';
+    /**
+     * How many times can be held at once.
+     *
+     * Absent is one. `range` holds a start and an end, `multiple` holds any
+     * number, and both are carried as one comma-separated value, which is what a
+     * form submits. `helix-time-picker` carries the longer note on the interaction and on
+     * why a wheel cannot do either.
+     */
+    mode?: 'multiple' | 'range';
+    /**
+     * How many times are shown as tags before the rest are counted, in `multiple`.
+     *
+     * `0` is all of them, and is the default, for the reason Date Input gives: how
+     * many fit depends on the width of the field and the length of what is in it,
+     * and this element knows neither.
+     */
+    maxTags: number;
+    /**
+     * How far apart the offered times are, in minutes.
+     */
+    step: number;
+    /**
+     * Earliest time that can be chosen, as `HH:mm`.
+     */
+    min: string;
+    /**
+     * Latest time that can be chosen, as `HH:mm`.
+     */
+    max: string;
+    /**
+     * Whether the field writes the time out, or holds the value as it is.
+     *
+     * `local` is the reader's own convention from `Intl`, which is what a time is
+     * for reading; `iso` is `HH:mm`, which is what it is for typing. The field
+     * swaps to the value while the caret is in it either way, so the rendering is
+     * never something this element would refuse to read back.
+     */
+    timeStyle: 'iso' | 'local';
+    /**
+     * Language tag the times are written in.
+     *
+     * Absent uses the runtime's own.
+     */
+    locale: string;
+    /**
+     * What the field says before a time is in it.
+     */
+    placeholder: string;
+    /**
+     * Accessible name for the control that opens the list.
+     */
+    triggerLabel: string;
+    /**
+     * Whether the caret is in the field, which is when it holds the value.
+     */
+    private editing;
+    /** The overlay, placed against the field for the reason Date Input gives. */
+    protected readonly panel: PopoverController;
+    private get control();
+    /** Every time in the value, which may hold more than one. */
+    private get held();
+    /** One time, written the way `time-style` asks for. */
+    private written;
+    /** What the field shows: the value while it is being edited, a reading when not. */
+    private get display();
+    /**
+     * What is being typed but not yet held, for `multiple` only.
+     *
+     * The other modes type into the value directly, because one time and a range
+     * are both a whole answer the moment they are complete. A multiple is a set
+     * being added to, so the field needs somewhere to hold a time before it joins.
+     */
+    private draft;
+    /** The times that get a tag, which is all of them until `maxTags` says not. */
+    private get shownTimes();
+    /** How many are held beyond the ones shown. */
+    private get restCount();
+    /** Adds what was typed to the set, or takes the last one back out. */
+    private readonly handleDraftKey;
+    /** Takes one time back out of the set. */
+    private readonly removeTime;
+    /**
+     * What the list should show, which is only ever a whole time.
+     *
+     * Half-typed input reaches here on every keystroke and `09:` is not a time.
+     * Handing it on would clear the list's selection mid-word, which is the same
+     * reason Date Input withholds a half-typed date from its calendar.
+     */
+    private get picked();
+    private readonly handleInput;
+    private readonly handlePicked;
+    /**
+     * Puts the caret back in the field without the field reopening the list.
+     *
+     * Focus opens the list, so handing focus back after a pick would reopen the
+     * thing that was just answered, and a reader could not get out of it. Input
+     * Date guards the same case by asking where focus came from, which is enough
+     * there and is not enough here: the option that had focus is gone by the time
+     * this runs, so `relatedTarget` is whatever the document fell back to, which
+     * is outside this element and reads as a genuine arrival.
+     *
+     * A flag rather than a better guess, because this element is the one moving
+     * the focus and it is the only thing that can know so. Cleared synchronously,
+     * since `focus()` dispatches before it returns.
+     *
+     * Reasoned rather than measured, and Date Input carries the long version of
+     * why: `focus()` dispatches no event in an unfocused document, which is what
+     * both the test runtime and the browser pane here are, so the path cannot be
+     * exercised from either.
+     */
+    private returning;
+    private returnFocus;
+    private readonly handleBlur;
+    /**
+     * Focusing the field opens the list, and only from outside the element.
+     *
+     * The guard is the one Date Input needed: picking a time shuts the panel and
+     * puts the caret back in the field, and without it the list came straight
+     * back and a reader could not get out of it.
+     */
+    private readonly handleFocus;
+    /** Puts the field back where the answer differs from what was typed. */
+    private restore;
+    /** Reports the value and the validity the host stands behind. */
+    private sync;
+    /** Escape shuts the list without moving the time. */
+    private readonly handleKeydown;
+    /**
+     * Whether the control refuses changes while still submitting its value.
+     *
+     * **Enforced by refusing every request in one place**, which is the seam this
+     * component already has: `requestValue` is what every path here comes through,
+     * and gating it once is what stops the next call site from being written
+     * without the check.
+     *
+     * Not `disabled`, which is the confusion worth naming: a disabled control
+     * submits nothing and leaves the tab order, and a read-only one submits its
+     * value and stays reachable, which is what a form showing a value somebody
+     * else set needs.
+     */
+    readOnly: boolean;
+    /** Refuses every change while read-only. See `readOnly`. */
+    requestValue(next: string): boolean;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    /**
+     * The clock the field opens, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderPicker(): TemplateResult;
+    /**
+     * One chosen time, as a tag, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderTag(at: string): TemplateResult;
+    /**
+     * The mark on the button that opens the clock, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding.
+     *
+     * **A named import rather than `<helix-icon>`, and that is a reversal.** The
+     * element looked like the tidier of the two and loses on three counts.
+     * `helix-icon` indexes the whole icon map at runtime, `icons[this.name]`, and
+     * no bundler can shake a runtime lookup, so every consumer of any component
+     * that renders one ships all 50kB of path data; a named import ships one
+     * path. The import is checked when the package compiles, where a `name`
+     * string is checked only when `check:icons` runs. And `helix-icon` is not
+     * registered on the headless tier at all, which registers `helix-headless-icon`,
+     * so a headless consumer got an inert unknown element and no mark whatsoever.
+     */
+    protected renderTrigger(): TemplateResult;
+    protected render(): TemplateResult;
+    /**
+     * The value as a `Date` on 1 January 1970 UTC, or `null` while there is no time.
+     *
+     * The platform's own pair on `<input type="time">`, epoch day included: a time
+     * is an offset into a day rather than an instant, and putting it on the epoch
+     * is what makes `valueAsNumber` come out as milliseconds since midnight rather
+     * than as a moment nobody meant. Assigning any date reads the clock off it, so
+     * a consumer handing over `new Date()` gets the time of day they expected.
+     */
+    get valueAsDate(): Date | null;
+    set valueAsDate(date: Date | null);
+    /** The value as milliseconds since midnight, or `NaN` while there is no time. */
+    get valueAsNumber(): number;
+    set valueAsNumber(ms: number);
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-time-input': HelixHeadlessTimeInput;
+    }
+}
+export {};