@fusion.dev/helix-headless 0.0.0-dev

package/dist/date-picker/index.d.ts

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

package/dist/date-picker/index.js

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

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

@@ -0,0 +1,361 @@
+import { HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
+/**
+ * @summary Shows a month, and takes a date from it.
+ *
+ * @description
+ * A grid of days, per the APG date grid: the whole grid is one tab stop, arrows
+ * move by day and week, `PageUp` and `PageDown` move by month, and `Home` and
+ * `End` go to the ends of the week. Only the focused cell is in the tab
+ * sequence.
+ *
+ * Roving `tabindex` is written on the cells, which is free here because they
+ * are rendered into this shadow root rather than being markup a consumer wrote.
+ *
+ * Dates are `YYYY-MM-DD` strings and every calculation is in UTC. A local-time
+ * `Date` shifts across a timezone or a daylight-saving boundary, so the string
+ * is what the component holds and the arithmetic never leaves UTC.
+ *
+ * `month` is what the grid shows, separately from `value`, so paging through
+ * months does not select anything and a consumer can drive the view. Left
+ * unset, it follows the first selected date, and then the current month.
+ *
+ * `mode` decides how many dates are held. Absent takes one. `range` takes two
+ * and marks everything between them, starting over on the third click rather
+ * than replacing an end at random. `multiple` toggles, so clicking a chosen
+ * date takes it out. All three read and write the same comma-separated
+ * `value`.
+ *
+ * `locale` is worth setting where the output is compared across environments.
+ * Left unset, month and day names come from the runtime's own locale, and a
+ * server and a browser need not agree on what that is.
+ *
+ * `helix-before-change` was `helix-select`, and it moved when the calendar became
+ * form control. A control whose value changes dispatches `helix-before-change` here:
+ * `Input`, `Select`, `Listbox`, `Radio.Group` and `Toggle.Group` all do, and a
+ * calendar submitting a date is the same kind of thing. `helix-select` stays
+ * what it is elsewhere, which is a row or an item being chosen in something
+ * that reports no value at all, such as `Menu` or `Tree`.
+ *
+ * Paging is `helix-navigate` and not either of those, because it chooses
+ * nothing: the view moves and the answer does not.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Calendar, Date grid, Month view
+ * @documentation https://helix.fusion.dev/components/date-picker
+ *
+ * @slot next-icon - The glyph on the control that moves forward a month, usually a caret.
+ * @slot previous-icon - The glyph on the control that moves back a month, usually a caret.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the dates change, and cancelable.
+ * @event {HelixNavigateEvent} helix-navigate - Fired before the month on show changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart cell - One column of a row, which is what a range paints.
+ * @csspart day - The shape inside a cell, which is what a single date paints.
+ * @csspart grid - The grid of days.
+ * @csspart header - The month name and its controls.
+ * @csspart heading - The month and year being shown.
+ * @csspart month - One month, its header and its grid.
+ * @csspart months - The run of months.
+ * @csspart next - The control that moves to the next month.
+ * @csspart next-mark - The glyph on the next month control, where none is slotted.
+ * @csspart previous - The control that moves to the previous month.
+ * @csspart previous-mark - The glyph on the previous month control, where none is slotted.
+ * @csspart week - One row of days.
+ * @csspart weekday - A column header naming a day of the week.
+ *
+ * @cssproperty --date-picker-column-count - How many month columns are drawn, capped at two. `--date-picker-columns` overrides it.
+ */
+export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_base {
+    /**
+     * How many dates can be held at once.
+     */
+    mode?: 'range' | 'multiple';
+    /**
+     * How many months to show, side by side.
+     */
+    months: number;
+    /**
+     * Locale for month and day names.
+     *
+     * Absent uses the runtime's own.
+     */
+    locale: string;
+    /**
+     * Dates that cannot be chosen, comma separated, as `YYYY-MM-DD`.
+     */
+    disableDates: string;
+    /**
+     * Days of the week that cannot be chosen, comma separated, `0` to `6`.
+     */
+    disableDays: string;
+    /**
+     * Whether the current selection fails validation.
+     */
+    invalid: boolean;
+    /**
+     * The month on show, as `YYYY-MM`. Follows `value`, then the current month.
+     *
+     * Separate from `value` on purpose, so paging selects nothing and a consumer
+     * can drive the view. It said that and could not do it: the calendar wrote
+     * this when the reader paged, so a consumer holding it was overwritten and
+     * never told. Reading gives the month on show; writing declares it theirs,
+     * and `default-month` seeds one the calendar owns.
+     *
+     *
+     */
+    get month(): string;
+    set month(next: string);
+    /**
+     * Accessible name for the control that pages back.
+     *
+     * A property because this is the one component in the library that takes a
+     * `locale`, and it carried two hardcoded English names with no way to change
+     * them: a calendar rendering its own month names in Japanese still announced
+     * its controls in English. `attribute:` spelled out, since Lit lowercases a
+     * camelCase name rather than dash-casing it.
+     */
+    previousLabel: string;
+    /**
+     * Accessible name for the control that pages forward.
+     */
+    nextLabel: string;
+    /**
+     * Month to open on, where nothing declared one.
+     */
+    defaultMonth: string;
+    /** The month on show, whoever set it, and `undefined` until somebody has. */
+    private monthState;
+    /**
+     * Earliest selectable date, as `YYYY-MM-DD`.
+     */
+    min: string;
+    /**
+     * How far apart the selectable dates are, in days.
+     *
+     * `<input type="date" step>`'s own unit, counted from `min` where there is
+     * one and from 1 January 1970 where there is not, which is the platform's own
+     * base. A booking calendar that only takes Mondays is `step="7"` with a `min`
+     * on a Monday, and there was no way to say that: `disable-dates` takes a list
+     * and a year of Mondays is not a list anybody writes.
+     *
+     * One is every date and needs no rule, which is why anything below one is
+     * treated as one rather than as an error: a step of zero would block every
+     * date including the one already chosen.
+     */
+    step: number;
+    /**
+     * Latest selectable date, as `YYYY-MM-DD`.
+     */
+    max: string;
+    /**
+     * Accessible name for the grid.
+     */
+    label: string;
+    /**
+     * First column of the week, `0` for Sunday through `6` for Saturday.
+     */
+    firstDayOfWeek: number;
+    /**
+     * The date the grid's tab stop is on.
+     *
+     * Absent until the grid is used.
+     */
+    private focused;
+    /** The selected dates, in order. */
+    private get selected();
+    /** The range's ends, when there are two and the mode asks for them. */
+    private get range();
+    private isSelected;
+    /** The month being shown, resolved from `month`, then `value`, then today. */
+    private get shown();
+    /**
+     * The month to open on when nothing has declared one.
+     *
+     * Split out from `shown` so `month` can report what is on display without the
+     * two calling each other: `month` reading `shown` and `shown` reading `month`
+     * is a stack overflow, and the specs found it immediately.
+     */
+    private get derivedMonth();
+    /**
+     * The date the tab stop sits on, which is where the arrows move from.
+     *
+     * It has to be a date the grid actually renders, so the month is compared
+     * with its year. Comparing the month alone puts the stop on the same date a
+     * year away, which is rendered nowhere, and the grid is left with no tab stop
+     * at all and no way into it from the keyboard.
+     *
+     * Each candidate is tested in turn rather than the first one winning
+     * outright. Where the last date focused is in some other month, the selected
+     * date still holds the stop, and only with neither in view does it fall to
+     * the first of the month.
+     */
+    private get anchor();
+    /** Six weeks of dates, so a grid does not change height between months. */
+    private weeksOf;
+    /**
+     * Whether a date is barred, by bound, by weekday, or by name.
+     *
+     * `barred`, not `disabled`: the calendar is a form control now, and
+     * `HelixFormElement.disabled` is a boolean about the whole control. A method
+     * and a flag cannot share a name, and of the two it is the method that should
+     * move, because "disabled" on a control means one thing everywhere else in
+     * the library.
+     */
+    private barred;
+    /**
+     * Moves the view, announcing it first.
+     *
+     * `helix-navigate` and not `helix-change`: paging chooses nothing, and a
+     * consumer driving the view has to hear that it moved without being told the
+     * answer did. In controlled mode nothing moves and the consumer decides,
+     * which is the point of them holding it.
+     */
+    private show;
+    private moveTo;
+    /**
+     * Adds a date to the selection, as the mode allows.
+     *
+     * `range` starts over once it holds two, so a third click begins a new range
+     * rather than extending or replacing an end at random. `multiple` toggles, so
+     * clicking a chosen date takes it out.
+     */
+    private select;
+    private readonly handleKeydown;
+    connectedCallback(): void;
+    disconnectedCallback(): 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;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Reports validity after render, because the bubble needs somewhere to point.
+     *
+     * `updated` and not `willUpdate`: the anchor is a rendered part, and on the
+     * first pass through `willUpdate` there is no grid yet, so the browser would
+     * put the message in the corner of the viewport rather than on the calendar.
+     */
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Reports the dates to the form, one entry each.
+     *
+     * `FormData` rather than the comma-joined string the property holds, because
+     * `mode="multiple"` is genuinely several answers and a server reading
+     * `dates=2026-08-04,2026-08-06` has to know to split it on a convention this
+     * library invented. One entry per date is what every other multi-valued
+     * control on the platform sends, and `range` sends its two the same way, in
+     * order, so start and end arrive as the pair they already are.
+     *
+     * **Nothing at all without a `name`, and that is the mechanism rather than a
+     * detail.** It is what lets a calendar sit inside something that owns the
+     * form value, which is how `DatePicker` will hold one. The guard has to be
+     * explicit here in a way it does not for `Listbox`: a control reporting a
+     * plain string is skipped by the form when it has no name, but a `FormData`
+     * carries its own names and its entries are appended whatever the element is
+     * called, so an unnamed calendar would submit empty-named dates.
+     */
+    private report;
+    /**
+     * How many months are shown, clamped once.
+     *
+     * `months` was clamped at the call site and read raw where the last month is
+     * identified, so a zero, a negative or a non-numeric value rendered nothing
+     * and took the forward control with it: `index === this.months - 1` is never
+     * true for `NaN`. One getter both read.
+     */
+    private get monthCount();
+    /**
+     * The three date formatters, built once per locale rather than per render.
+     *
+     * `Intl.DateTimeFormat` is expensive to construct and these depend on nothing
+     * but `locale`, and they were built inside the per-month render: three
+     * constructions for every month on show, on every update, so a two-month
+     * calendar rebuilt six of them each time an arrow key moved the anchor.
+     * Measured elsewhere at about a quarter of a millisecond apiece, which is not
+     * a crisis and is pure waste.
+     *
+     * Keyed on the locale so a change to it is picked up, which a plain lazy
+     * field would not do.
+     */
+    private cachedFormats;
+    private get formats();
+    /**
+     * The caret saying which way the month moves, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people, which
+     * is the same pairing `Select` records on its indicator.
+     *
+     * **One of each is rendered at most**, whatever `months` is set to: the
+     * controls are drawn on the first month and the last rather than once per
+     * month, so a duplicate `<slot name="previous-icon">` cannot arise. A second
+     * slot of the same name is assigned nothing, which would have left one of two
+     * calendars with no mark and no error.
+     */
+    protected renderPreviousMark(): TemplateResult;
+    protected renderNextMark(): TemplateResult;
+    private renderMonth;
+    protected render(): TemplateResult;
+    /**
+     * The value as a `Date`, at midnight UTC, or `null` while there is no date.
+     *
+     * The platform's own pair on `<input type="date">`, and this control holds the
+     * same `YYYY-MM-DD` string, so a consumer moving from one to the other reads
+     * the same two properties. UTC because the platform chose UTC: a date that is
+     * the same date everywhere must not become a different one by crossing a
+     * timezone, and midnight local would do exactly that for anybody west of
+     * Greenwich.
+     *
+     * `null` while the value is half typed, which is most of the keystrokes a
+     * reader makes in one of these.
+     */
+    get valueAsDate(): Date | null;
+    set valueAsDate(date: Date | null);
+    /** The value as milliseconds since the epoch, or `NaN` while there is no date. */
+    get valueAsNumber(): number;
+    set valueAsNumber(ms: number);
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-date-picker': HelixHeadlessDatePicker;
+    }
+}
+export {};