@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,380 @@
+import { HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../listbox/index.js';
+import '../../option/index.js';
+/** Whether a string is a time the rest of this component can reason about. */
+export declare const isTime: (value: string) => boolean;
+/** Minutes since midnight, or `null` where it is not a time. */
+export declare const toMinutes: (value: string) => number | null;
+/** Minutes since midnight back to `HH:mm`, which is the value shape throughout. */
+export declare const fromMinutes: (minutes: number) => string;
+/**
+ * A time written the way the reader's locale writes one.
+ *
+ * `Intl` decides between a twelve and a twenty-four hour clock, because that is
+ * a property of the locale rather than of this component: `en-US` gets
+ * `2:30 PM` and `en-GB` gets `14:30` without either being configured. There is
+ * no flag to force one, deliberately. A product that needs to override its
+ * reader's own convention has a locale problem rather than a component one, and
+ * the value is 24 hour regardless.
+ */
+export declare const writeTime: (value: string, locale?: string) => string;
+declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
+/**
+ * @summary Picks a time, from a list of them.
+ *
+ * @description
+ * **A list rather than three wheels**, and the reason is what a list already
+ * is. `helix-listbox` brings the keyboard, the typeahead, the scroll into view
+ * and the announcement of a set of options, and a time at a step is a set of
+ * options. Three little wheels for hours, minutes and a meridiem are three
+ * controls to build, three to test, and a tab stop each for something a reader
+ * answers once.
+ *
+ * **A step is what makes it a list at all.** Fifteen minutes is ninety-six rows,
+ * which a reader scrolls or types into; one minute is one thousand four hundred
+ * and forty, which is a listbox in name only. So the list is for the times a
+ * product actually offers, and arbitrary times are the field's job in Input
+ * Time, the same division Date Input draws between typing a date and using the
+ * calendar.
+ *
+ * **The value is `HH:mm` on a twenty-four hour clock, always.** That is what a
+ * form submits and what `min` and `max` compare against, and it sorts as a
+ * string, which is the whole reason the shape is that one. What each row *says*
+ * is the reader's own convention, from `Intl`.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Time, TimeList
+ * @documentation https://helix.fusion.dev/components/time-picker
+ *
+ * @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 {Event} input - Announced once the value has moved.
+ *
+ * @csspart column - One of them.
+ * @csspart column-empty - Shown when a filter has hidden everything.
+ * @csspart column-feedback - What is wrong with it.
+ * @csspart column-filter-icon - The mark beside that field.
+ * @csspart column-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart column-hint - Help under the list.
+ * @csspart column-items - The list itself.
+ * @csspart column-label - The question, over the list.
+ * @csspart column-loading - Shown while the options are still on their way.
+ * @csspart column-search - The region holding the field that narrows the list.
+ * @csspart column-search-field - The field itself.
+ * @csspart columns - The row of columns, in `wheels`.
+ * @csspart list - The listbox holding the times, in `list`.
+ * @csspart list-empty - Shown when a filter has hidden everything.
+ * @csspart list-feedback - What is wrong with it.
+ * @csspart list-filter-icon - The mark beside that field.
+ * @csspart list-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart list-hint - Help under the list.
+ * @csspart list-items - The list itself.
+ * @csspart list-label - The question, over the list.
+ * @csspart list-loading - Shown while the options are still on their way.
+ * @csspart list-search - The region holding the field that narrows the list.
+ * @csspart list-search-field - The field itself.
+ * @csspart option - One time in it. Carries `data-between` inside a range.
+ * @csspart option-description - The caption under the words, when there is one.
+ * @csspart option-item - The row.
+ * @csspart option-label - The words.
+ * @csspart option-text - The words and the caption, as one column.
+ */
+export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_base {
+    /**
+     * Whether the current selection fails validation.
+     *
+     * A flag rather than a message, which is the split Date Picker already drew and
+     * these two now follow. A flat picker has no room of its own for a sentence:
+     * the field that wraps one owns the label, the hint and the feedback, and a
+     * second message inside the panel would be the same error said twice. What is
+     * left for the picker is the one thing the field cannot draw from outside, the
+     * mark on the answer itself.
+     */
+    invalid: boolean;
+    /**
+     * How far apart the offered times are, in minutes.
+     *
+     * Fifteen, which is four rows an hour and ninety-six in a day: enough that a
+     * reader scrolls rather than hunts, and few enough that the list is a list.
+     * Anything under five is a thousand rows and wants a field instead.
+     */
+    step: number;
+    /**
+     * Earliest time offered, as `HH:mm`.
+     */
+    min: string;
+    /**
+     * Latest time offered, as `HH:mm`.
+     */
+    max: string;
+    /**
+     * Times that cannot be chosen, comma separated, as `HH:mm`.
+     *
+     * The counterpart to Date Picker's `disable-dates`, and it exists for the same
+     * shape of problem: `min` and `max` take away a span, and what a booking
+     * usually has to take away is a scatter. A morning with 09:30 and 11:00
+     * already gone is not two bounds.
+     *
+     * A time not on the step is simply never offered, so it is not an error to
+     * name one, and naming every time in the list is how the empty state is
+     * reached honestly rather than by handing over an empty range.
+     */
+    disableTimes: string;
+    /**
+     * Language tag the times are written in.
+     *
+     * Absent uses the runtime's own.
+     */
+    locale: string;
+    /**
+     * Accessible name for the list, which has no visible one of its own.
+     */
+    label: string;
+    /**
+     * How many times can be held at once.
+     *
+     * Absent is one. `range` holds a start and an end with everything between
+     * them shown as part of the answer, `multiple` holds any number, and both are
+     * carried as one comma-separated value: the same shape `helix-date-picker` uses,
+     * because it is the same question asked of a different unit.
+     *
+     * **A range is two picks, and a third starts over.** That is the calendar's
+     * behavior and a reader who has met one has met both. The alternative, a
+     * separate "from" and "to" control, is two answers to what a product asks as
+     * one, and it makes the between part impossible to show.
+     *
+     * **Neither works on wheels and the appearance falls back.** A range on
+     * wheels is two sets of wheels, which is two controls; a multiple is a set,
+     * and a wheel has exactly one value by construction. Rather than draw
+     * something that cannot say what it holds, `wheels` renders as a list
+     * whenever a mode is set.
+     */
+    mode?: 'multiple' | 'range';
+    /**
+     * Whether the times are one list or a column each.
+     *
+     * `list` is the default and offers whole times, which is what a product with
+     * opening hours or slots actually has. `wheels` splits them into an hour, a
+     * minute and, where the locale uses one, a meridiem: three short columns
+     * instead of ninety-six rows, and the only way to reach `23:45` without
+     * scrolling most of a day.
+     *
+     * The trade is that a wheel cannot say which *combinations* are on offer. A
+     * list of half hours from nine to five is seventeen rows and every one of them
+     * is a time the product has; the same thing as columns is an hour column and a
+     * minute column, and nothing in either says the two are only valid together.
+     * The bounds are still enforced, so a reader can be refused after the fact,
+     * which is worse than not being offered it.
+     *
+     * So: `list` where the set is the point, `wheels` where any time is allowed
+     * and the range is a whole day.
+     *
+     * **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';
+    /**
+     * Every time on offer, as minutes since midnight.
+     *
+     * Built from `min` upward rather than from midnight, so a list that starts at
+     * `09:00` steps from nine rather than offering `09:15` because that is where
+     * the quarter hours from midnight happen to land. A step that does not divide
+     * the hour is a real thing to want, twenty minutes being the obvious one, and
+     * this is the reading that makes it behave.
+     */
+    private get times();
+    /**
+     * Whether a time is barred by name.
+     *
+     * `barred`, not `disabled`, for the reason Date Picker records: this is a form
+     * control and `HelixFormElement.disabled` is a boolean about the whole of it,
+     * so a method and a flag cannot share the name.
+     *
+     * Only the named list. `min` and `max` are not consulted here because they
+     * never produce a row to bar: `times` builds the list between them, so a time
+     * outside the bounds is absent rather than present and refused.
+     */
+    private barred;
+    /**
+     * Whether every offered time in an hour is barred.
+     *
+     * `shown` is the meridiem the wheel is on, so `1` means 01:00 under AM and
+     * 13:00 under PM. Absent is a 24 hour clock, where the number is the hour.
+     */
+    private wholeHourBarred;
+    /** Whether every offered time in a half of the clock is barred. */
+    private halfBarred;
+    /** The times held, which is a list whether or not a mode is set. */
+    private get held();
+    /**
+     * Takes what the list announced and constrains it to what the mode allows.
+     *
+     * The listbox is put in `multiple` for both modes, because that is what marks
+     * more than one row and toggles on press. A range then differs only in what is
+     * kept: two, and a third pick starts again from that third one. Working out
+     * which is newest by difference rather than by position, since a toggle can
+     * remove as easily as add and the announced list is a set rather than a
+     * sequence.
+     */
+    private readonly handleChange;
+    /** Whether a time falls inside a range, which is what gets banded. */
+    private between;
+    /** The three readings a wheel shows, from the value or from `min`. */
+    private get parts();
+    /** Puts a changed column back together into a whole time. */
+    private readonly moveColumn;
+    /** Every whole hour that has at least one offered time in it. */
+    private get hours();
+    /** Every minute offered within the hour currently shown. */
+    private get minutes();
+    /**
+     * Each wheel comes to rest on its own answer.
+     *
+     * A dial that opens at midnight when it holds ten in the evening is a dial
+     * showing the wrong thing, and CSS cannot fix it: `scroll-snap-type` chooses a
+     * snap point when something scrolls, and nothing has. Measured before this,
+     * with the value at 22:00, the hour wheel sat 288 pixels above its answer.
+     *
+     * On every update rather than on the first, because the columns re-render as
+     * the value moves and the minute column's contents change with the hour.
+     *
+     * **And it is public, because an update is not the only moment that matters.**
+     * Inside a panel this element renders while the panel is still
+     * `display: none`, so every box measures zero and there is nothing to center
+     * against: measured, the hour wheel stayed 288 pixels off its answer because
+     * the only call happened before anything had a size. Whatever shows the panel
+     * calls this again afterwards. The guard below makes the early call harmless
+     * rather than wrong, which is why it can be left in.
+     */
+    reveal(): void;
+    /**
+     * 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;
+    /**
+     * Whether the form refuses to submit while nothing is chosen.
+     */
+    required: boolean;
+    /**
+     * Reports "required and empty", or clears it.
+     *
+     * Written out rather than taken from `MixinField`, which is where the seven
+     * form controls get this. That mixin brings a label, a hint and a feedback
+     * region with it, and this is a grid rather than a field: it is composed
+     * *into* the field that has those, so taking the mixin would give one control
+     * two of each. What is shared is five lines, and the anchor is what the
+     * browser points its bubble at.
+     */
+    private reportRequired;
+    /**
+     * Reports the times to the form, one entry each.
+     *
+     * **This element was form-associated, took a `name`, held a `value` and
+     * reported `valueMissing`, and never called `setFormValue` at all.** So
+     * `<helix-time-picker name="start" required>` refused the submit until a
+     * reader filled it and then submitted nothing, which is the worst shape the
+     * omission takes: every visible signal says the control is participating.
+     * Measured before the fix, one form holding both pickers, both named and
+     * both seeded: the entry list carried the date and no time.
+     *
+     * `FormData` and one entry per time, which is `DatePicker.report` exactly.
+     * `mode="multiple"` is genuinely several answers, and a server reading
+     * `times=09:00,17:00` would have to split it on a convention this library
+     * invented; `range` sends its two in order, so start and end arrive as the
+     * pair they already are.
+     *
+     * **Nothing at all without a `name`.** A `FormData` carries its own names and
+     * its entries are appended whatever the element is called, so an unnamed
+     * picker would submit empty-named times rather than being skipped the way a
+     * control reporting a plain string is. That is the same guard, for the same
+     * reason, that the calendar's own note spells out.
+     */
+    private report;
+    /**
+     * Reveals once the wheels have rendered themselves.
+     *
+     * `updated` is this element's own moment, and each wheel is a `helix-listbox`
+     * that was created during this very render: its first update has been
+     * scheduled and has not run, so it has no rows and no height and `reveal`
+     * measures zero and gives up. Measured on a standalone picker, every column
+     * sat at `scrollTop: 0` with the answer nine rows down, which reads as a wheel
+     * showing the wrong time rather than as one that failed to scroll.
+     *
+     * It survived because the case that was tested was the panel, and whatever
+     * opens a panel calls `reveal` again afterwards for the separate reason the
+     * method documents. Flat on a page there is no panel and no second call.
+     *
+     * Safe to run on every update: the listbox stops as soon as the chosen row is
+     * within a pixel of center, so a call with nothing to do costs two rect reads
+     * and changes nothing. It cannot fight a reader mid-scroll either, since
+     * scrolling a wheel changes no property and so schedules no update.
+     */
+    private revealWhenSettled;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Puts the keyboard on the list, which is the only control here. */
+    focus(options?: FocusOptions): void;
+    /**
+     * One wheel.
+     *
+     * `barred` is passed per column rather than read from `disableTimes` here,
+     * because a column holds a third of a time and only the caller knows the
+     * other two thirds. What that means differs by column and the difference is
+     * not a detail: a minute is barred when *this* hour plus it is, and an hour is
+     * barred only when every minute in it is, since one free minute is a reason to
+     * open the wheel rather than to close it.
+     */
+    protected renderColumn(part: 'hour' | 'meridiem' | 'minute', label: string, values: string[], written: (one: string) => string, value: string, barred?: (one: string) => boolean): TemplateResult;
+    private renderSpinner;
+    /**
+     * The flat list of times, for the appearance that is not wheels, 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 renderList(): 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-picker': HelixHeadlessTimePicker;
+    }
+}
+export {};