@fusion.dev/helix-headless 0.0.0-dev

package/dist/date-picker/root/date-picker-root.js

@@ -0,0 +1,837 @@
+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 { valueAsDate as asDate, customElement, dateAsValue as fromDate, HelixFormElement, HelixNavigateEvent, hostAria, MixinControllerValue, requestChange, } from '@fusion.dev/helix-core';
+import { caretLeft, caretRight } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/** Keys the grid answers to, per the APG date grid. */
+const KEYS = new Set([
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'ArrowUp',
+    'End',
+    'Enter',
+    'Home',
+    'PageDown',
+    'PageUp',
+    ' ',
+]);
+/**
+ * Dates are held as `YYYY-MM-DD` and computed in UTC.
+ *
+ * A local-time `Date` shifts across a timezone or a daylight-saving boundary,
+ * so the same calendar renders a different grid depending on where it is read.
+ * Parsing and formatting both in UTC makes the string the source of truth and
+ * the arithmetic total.
+ */
+const toUtc = (iso) => {
+    const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    if (!parts) {
+        return null;
+    }
+    const date = new Date(Date.UTC(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3])));
+    return Number.isNaN(date.getTime()) ? null : date;
+};
+const toIso = (date) => date.toISOString().slice(0, 10);
+/**
+ * Today, in the reader's own timezone.
+ *
+ * **`toISOString` converts to UTC first, which makes "today" a different day
+ * for most of the planet.** Anywhere west of UTC, from late afternoon onward,
+ * `toIso(new Date())` names tomorrow: the mark landed on the wrong cell and the
+ * server and the client disagreed about which one, since the two run in
+ * different zones. The parts are read locally instead and pasted together,
+ * which is the only way to get a calendar date out of a `Date` without a
+ * conversion happening on the way.
+ */
+const localToday = () => {
+    const now = new Date();
+    const month = `${now.getMonth() + 1}`.padStart(2, '0');
+    const day = `${now.getDate()}`.padStart(2, '0');
+    return `${now.getFullYear()}-${month}-${day}`;
+};
+/** Splits a comma-separated attribute, tolerating spaces and empty entries. */
+const list = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+const addDays = (date, days) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
+/** Whether two dates fall in the same month of the same year. */
+const sameMonth = (left, right) => left.getUTCFullYear() === right.getUTCFullYear() && left.getUTCMonth() === right.getUTCMonth();
+const addMonths = (date, months) => {
+    const target = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + months, 1));
+    // Clamped, so the last of a long month lands on the last of a short one
+    // instead of rolling into the month after it.
+    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last)));
+};
+/**
+ * @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.
+ */
+let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinControllerValue(HelixFormElement) {
+    constructor() {
+        super(...arguments);
+        /**
+         * How many months to show, side by side.
+         */
+        this.months = 1;
+        /**
+         * Locale for month and day names.
+         *
+         * Absent uses the runtime's own.
+         */
+        this.locale = '';
+        /**
+         * Dates that cannot be chosen, comma separated, as `YYYY-MM-DD`.
+         */
+        this.disableDates = '';
+        /**
+         * Days of the week that cannot be chosen, comma separated, `0` to `6`.
+         */
+        this.disableDays = '';
+        /**
+         * Whether the current selection fails validation.
+         */
+        this.invalid = false;
+        /**
+         * 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.
+         */
+        this.previousLabel = 'Previous month';
+        /**
+         * Accessible name for the control that pages forward.
+         */
+        this.nextLabel = 'Next month';
+        /**
+         * Month to open on, where nothing declared one.
+         */
+        this.defaultMonth = '';
+        /** The month on show, whoever set it, and `undefined` until somebody has. */
+        this.monthState = undefined;
+        /**
+         * Earliest selectable date, as `YYYY-MM-DD`.
+         */
+        this.min = '';
+        /**
+         * 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.
+         */
+        this.step = 1;
+        /**
+         * Latest selectable date, as `YYYY-MM-DD`.
+         */
+        this.max = '';
+        /**
+         * Accessible name for the grid.
+         */
+        this.label = 'Date Picker';
+        /**
+         * First column of the week, `0` for Sunday through `6` for Saturday.
+         */
+        this.firstDayOfWeek = 0;
+        /**
+         * The date the grid's tab stop is on.
+         *
+         * Absent until the grid is used.
+         */
+        this.focused = '';
+        this.handleKeydown = (event) => {
+            if (!KEYS.has(event.key) || this.disabled) {
+                return;
+            }
+            /* Grid keys, from the grid.
+             *
+             * The listener is on the host and the host holds the previous and next
+             * buttons as well, so Enter and Space pressed on one of those were read as
+             * "choose the focused day" and then `preventDefault()`ed: the button's own
+             * activation was canceled and the month never moved. Every arrow was taken
+             * from them too. */
+            const path = event.composedPath();
+            const grid = this.renderRoot?.querySelector('[part="grid"]');
+            if (!grid || !path.includes(grid)) {
+                return;
+            }
+            const from = this.anchor;
+            if (event.key === 'Enter' || event.key === ' ') {
+                this.select(from);
+            }
+            else if (event.key === 'ArrowLeft') {
+                this.moveTo(addDays(from, -1));
+            }
+            else if (event.key === 'ArrowRight') {
+                this.moveTo(addDays(from, 1));
+            }
+            else if (event.key === 'ArrowUp') {
+                this.moveTo(addDays(from, -7));
+            }
+            else if (event.key === 'ArrowDown') {
+                this.moveTo(addDays(from, 7));
+            }
+            else if (event.key === 'Home') {
+                this.moveTo(addDays(from, -((from.getUTCDay() - this.firstDayOfWeek + 7) % 7)));
+            }
+            else if (event.key === 'End') {
+                this.moveTo(addDays(from, 6 - ((from.getUTCDay() - this.firstDayOfWeek + 7) % 7)));
+            }
+            else {
+                // Shift pages by a year, which is the same move twelve months over.
+                const step = event.key === 'PageUp' ? -1 : 1;
+                this.moveTo(addMonths(from, event.shiftKey ? step * 12 : step));
+            }
+            event.preventDefault();
+        };
+        /**
+         * 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.
+         */
+        this.readOnly = false;
+        /**
+         * Whether the form refuses to submit while nothing is chosen.
+         */
+        this.required = false;
+    }
+    /**
+     * 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() {
+        /* What is on show, which is what the tag says it gives.
+         *
+         * It returned `''` while a month was plainly on display, because nothing had
+         * declared one, and `show()` compares against it before moving: the guard
+         * was dead, so the first arrow key wrote `monthState` and from then on the
+         * grid stopped following `value`. A calendar whose consumer moved the value
+         * showed the month the reader had last paged to instead. */
+        return this.monthState ?? (this.defaultMonth || toIso(this.derivedMonth).slice(0, 7));
+    }
+    set month(next) {
+        const previous = this.month;
+        this.monthState = next;
+        this.requestUpdate('month', previous);
+    }
+    /** The selected dates, in order. */
+    get selected() {
+        return list(this.value);
+    }
+    /** The range's ends, when there are two and the mode asks for them. */
+    get range() {
+        const dates = this.selected;
+        if (this.mode !== 'range' || dates.length < 2) {
+            return null;
+        }
+        const [first, second] = [dates[0], dates[1]];
+        return first <= second ? [first, second] : [second, first];
+    }
+    isSelected(iso) {
+        const range = this.range;
+        if (range) {
+            return iso >= range[0] && iso <= range[1];
+        }
+        return this.selected.includes(iso);
+    }
+    /** The month being shown, resolved from `month`, then `value`, then today. */
+    get shown() {
+        const explicit = /^(\d{4})-(\d{2})$/.exec(this.monthState ?? this.defaultMonth);
+        if (explicit) {
+            return new Date(Date.UTC(Number(explicit[1]), Number(explicit[2]) - 1, 1));
+        }
+        return this.derivedMonth;
+    }
+    /**
+     * 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.
+     */
+    get derivedMonth() {
+        const from = toUtc(this.selected[0] ?? '') ?? new Date();
+        return new Date(Date.UTC(from.getUTCFullYear(), from.getUTCMonth(), 1));
+    }
+    /**
+     * 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.
+     */
+    get anchor() {
+        const shown = this.shown;
+        for (const candidate of [toUtc(this.focused), toUtc(this.selected[0] ?? '')]) {
+            if (candidate && sameMonth(candidate, shown)) {
+                return candidate;
+            }
+        }
+        return shown;
+    }
+    /** Six weeks of dates, so a grid does not change height between months. */
+    weeksOf(month) {
+        const offset = (month.getUTCDay() - this.firstDayOfWeek + 7) % 7;
+        const start = addDays(month, -offset);
+        return Array.from({ length: 6 }, (_, week) => Array.from({ length: 7 }, (_, day) => addDays(start, week * 7 + day)));
+    }
+    /**
+     * 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.
+     */
+    barred(date) {
+        const iso = toIso(date);
+        if (this.min !== '' && iso < this.min) {
+            return true;
+        }
+        if (this.max !== '' && iso > this.max) {
+            return true;
+        }
+        if (list(this.disableDays).includes(String(date.getUTCDay()))) {
+            return true;
+        }
+        /* Counted from `min` where there is one and from the epoch where there is
+           not, which is what the platform does with a `step` and no `min`. Whole
+           days, because both ends are midnight UTC and neither carries a time. */
+        const step = Math.max(1, Math.floor(this.step) || 1);
+        if (step > 1) {
+            const base = this.min === '' ? 0 : (asDate(this.min)?.getTime() ?? 0);
+            const days = Math.round((date.getTime() - base) / 86_400_000);
+            if (days % step !== 0) {
+                return true;
+            }
+        }
+        return list(this.disableDates).includes(iso);
+    }
+    /**
+     * 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.
+     */
+    show(date) {
+        if (this.disabled) {
+            return;
+        }
+        const next = `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+        if (next === this.month) {
+            return;
+        }
+        requestChange({
+            apply: (month) => {
+                const previous = this.month;
+                this.monthState = month;
+                this.requestUpdate('month', previous);
+            },
+            event: (month) => new HelixNavigateEvent({ value: month }),
+            host: this,
+            next,
+        });
+    }
+    moveTo(date) {
+        this.focused = toIso(date);
+        this.show(date);
+        this.updateComplete.then(() => {
+            this.renderRoot.querySelector('[part="cell"][tabindex="0"]')?.focus();
+        });
+    }
+    /**
+     * 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.
+     */
+    select(date) {
+        /* `disabled` meant nothing here beyond dropping the value at submit time:
+           days still took a click, the keyboard still moved through the grid, and
+           nothing said the control was off. Refused at the source rather than at
+           each cell, so every path in is covered by one check. */
+        if (this.disabled) {
+            return;
+        }
+        if (this.barred(date)) {
+            return;
+        }
+        const iso = toIso(date);
+        const held = this.selected;
+        let next;
+        if (this.mode === 'range') {
+            next = held.length === 1 ? [...held, iso].sort() : [iso];
+        }
+        else if (this.mode === 'multiple') {
+            next = held.includes(iso) ? held.filter((entry) => entry !== iso) : [...held, iso].sort();
+        }
+        else {
+            next = [iso];
+        }
+        /* Focus moves whatever happens, because the reader pressed there and the
+           roving tab stop is about where they are rather than about what is
+           chosen. The selection is the part that can be refused. */
+        this.focused = iso;
+        /* Announced before it is written, which it was not: this set `value` and
+           then dispatched, so a listener calling `preventDefault()` was refusing a
+           date that had already been chosen. `requestChange` is the one
+           audited path its own documentation claims for every stateful change in
+           the system, and this was not on it. */
+        this.requestValue(next.join(','));
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('keydown', this.handleKeydown);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('keydown', this.handleKeydown);
+    }
+    /** Refuses every change while read-only. See `readOnly`. */
+    requestValue(next) {
+        if (this.readOnly) {
+            return false;
+        }
+        return super.requestValue(next);
+    }
+    /**
+     * 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.
+     */
+    reportRequired() {
+        const anchor = this.renderRoot?.querySelector('[part="grid"]') ?? undefined;
+        if (this.required && this.value === '') {
+            this.internals.setValidity({ valueMissing: true }, 'Choose a date.', anchor);
+            return;
+        }
+        /* **A value the calendar cannot read is bad input, and it used to be
+           valid.** The grid draws only what it can parse, so `value="not-a-date"`
+           selected nothing, said nothing, reported `:valid`, and handed the string
+           to the form: measured, a form carrying `dp=not-a-date` that submitted
+           without complaint. `DateInput` had this right all along, because it
+           relays the validity of an inner control it can ask.
+    
+           `asDate` rather than the shape alone, which is the half `DateInput`'s own
+           regex still misses: `2026-02-30` matches `YYYY-MM-DD` and is not a day,
+           and `valueAsDate` reads the parts back after constructing to say so. */
+        const held = this.selected;
+        if (held.length > 0 && held.some((one) => asDate(one) === null)) {
+            this.internals.setValidity({ badInput: true }, this.mode === undefined
+                ? 'Enter a date as YYYY-MM-DD.'
+                : 'Enter dates as YYYY-MM-DD, separated by commas.', anchor);
+            return;
+        }
+        this.internals.setValidity({});
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'group' });
+        /* Announced as off, not merely inert. Removing it from the accessibility
+           tree would take the dates with it; this says the control exists and
+           cannot be used, which is the same call `HelixFormElement` documents. */
+        /* `isDisabled` and not `disabled`, which is the whole reason the getter
+           exists: a calendar inside a disabled fieldset is disabled and its own
+           property says nothing about it. Writing `disabled` here also overwrote
+           the answer `HelixFormElement.willUpdate` had just computed. */
+        this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
+        this.internals.ariaInvalid = this.invalid ? 'true' : null;
+        this.report();
+    }
+    /**
+     * 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.
+     */
+    updated(changed) {
+        super.updated(changed);
+        this.reportRequired();
+    }
+    /**
+     * 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.
+     */
+    report() {
+        const dates = this.selected;
+        if (this.name === '' || this.disabled || dates.length === 0) {
+            this.internals.setFormValue(null);
+            return;
+        }
+        const data = new FormData();
+        for (const date of dates) {
+            data.append(this.name, date);
+        }
+        this.internals.setFormValue(data);
+    }
+    /**
+     * 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.
+     */
+    get monthCount() {
+        return Math.max(1, Math.floor(this.months) || 1);
+    }
+    get formats() {
+        if (this.cachedFormats?.locale === this.locale) {
+            return this.cachedFormats;
+        }
+        const locale = this.locale || undefined;
+        const built = {
+            full: new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeZone: 'UTC' }),
+            heading: new Intl.DateTimeFormat(locale, { month: 'long', timeZone: 'UTC', year: 'numeric' }),
+            locale: this.locale,
+            weekday: new Intl.DateTimeFormat(locale, { timeZone: 'UTC', weekday: 'short' }),
+        };
+        this.cachedFormats = built;
+        return built;
+    }
+    /**
+     * 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.
+     */
+    renderPreviousMark() {
+        return html `<slot name="previous-icon">
+      <svg part="previous-mark" fill="currentColor" viewBox=${caretLeft.viewBox} aria-hidden="true">
+        ${unsafeSVG(caretLeft.content)}
+      </svg>
+    </slot>`;
+    }
+    renderNextMark() {
+        return html `<slot name="next-icon">
+      <svg part="next-mark" fill="currentColor" viewBox=${caretRight.viewBox} aria-hidden="true">
+        ${unsafeSVG(caretRight.content)}
+      </svg>
+    </slot>`;
+    }
+    renderMonth(month, index) {
+        const { full, heading, weekday } = this.formats;
+        const weeks = this.weeksOf(month);
+        const anchor = toIso(this.anchor);
+        /* Today, which nothing marked at all: not in the accessibility tree, where
+           `aria-current="date"` is the word for it, and not on the cell either, so a
+           consumer could not add the mark from CSS. Computed once per month rather
+           than per cell. */
+        const today = localToday();
+        const range = this.range;
+        // One set of controls across the whole run: back on the first month,
+        // forward on the last. A pair per month would offer six ways to make the
+        // same move and leave the reader to work out which.
+        const first = index === 0;
+        const last = index === this.monthCount - 1;
+        return html `<div part="month">
+      <div part="header">
+        ${first
+            ? html `<button
+                part="previous"
+                type="button"
+                aria-label=${this.previousLabel}
+                @click=${() => this.show(addMonths(this.shown, -1))}
+              >
+                ${this.renderPreviousMark()}
+              </button>`
+            : nothing}
+        <span part="heading">${heading.format(month)}</span>
+        ${last
+            ? html `<button
+                part="next"
+                type="button"
+                aria-label=${this.nextLabel}
+                @click=${() => this.show(addMonths(this.shown, 1))}
+              >
+                ${this.renderNextMark()}
+              </button>`
+            : nothing}
+      </div>
+      <div
+        part="grid"
+        role="grid"
+        aria-label=${heading.format(month)}
+        data-unset=${this.value === '' ? '' : nothing}
+      >
+        <div part="week" role="row">
+          ${weeks[0]?.map((date) => html `<span part="weekday" role="columnheader">${weekday.format(date)}</span>`)}
+        </div>
+        ${weeks.map((week) => html `<div part="week" role="row">
+            ${week.map((date) => {
+            const iso = toIso(date);
+            const disabled = this.barred(date);
+            const selected = this.isSelected(iso);
+            /* A day from a neighbouring month is filler, so the grid is a
+               rectangle, and nothing else. It takes no click and shows no
+               selection.
+               It used to take both, and at `months="2"` that put the same
+               date on the page twice: September the 5th is a trailing cell in
+               August's grid and a real cell in September's, so choosing the
+               end of a range drew the dark terminus in both, and the band ran
+               through August's last row and then again through September's
+               first. Two cells cannot be the answer to one question. The band
+               now stops at the last day the grid owns and picks up in the
+               next, which is where those dates actually are. */
+            const outside = !sameMonth(date, month);
+            // The cell is the column track and the day is the shape centered
+            // in it. A range paints the track, so it runs continuously
+            // between days and stops at the ends of a row on its own.
+            return html `<span
+                part="cell"
+                role="gridcell"
+                aria-disabled=${disabled ? 'true' : nothing}
+                aria-label=${full.format(date)}
+                aria-current=${iso === today ? 'date' : nothing}
+                aria-selected=${!outside && selected ? 'true' : nothing}
+                data-outside=${outside ? '' : nothing}
+                data-range-end=${!outside && range && iso === range[1] ? '' : nothing}
+                data-range-middle=${!outside && range && iso > range[0] && iso < range[1] ? '' : nothing}
+                data-range-start=${!outside && range && iso === range[0] ? '' : nothing}
+                data-today=${iso === today ? '' : nothing}
+                tabindex=${!outside && iso === anchor ? '0' : '-1'}
+                @click=${outside ? nothing : () => this.select(date)}
+                ><span part="day">${date.getUTCDate()}</span></span
+              >`;
+        })}
+          </div>`)}
+      </div>
+    </div>`;
+    }
+    render() {
+        const shown = this.shown;
+        const count = this.monthCount;
+        /* The column count, written out for the tier above.
+           Data rather than styling, the same arrangement Slider uses for its
+           fraction: only this element knows how many months there are, and a
+           stylesheet cannot count children into a `repeat()`. Capped at two, and a
+           consumer wanting more sets `--date-picker-columns`. */
+        return html `<div part="months" style="--date-picker-column-count: ${Math.min(count, 2)}">
+      ${Array.from({ length: count }, (_, index) => this.renderMonth(addMonths(shown, index), index))}
+    </div>`;
+    }
+    /**
+     * 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() {
+        return asDate(this.value);
+    }
+    set valueAsDate(date) {
+        this.value = fromDate(date);
+    }
+    /** The value as milliseconds since the epoch, or `NaN` while there is no date. */
+    get valueAsNumber() {
+        return asDate(this.value)?.getTime() ?? Number.NaN;
+    }
+    set valueAsNumber(ms) {
+        this.value = Number.isNaN(ms) ? '' : fromDate(new Date(ms));
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessDatePicker.prototype, "mode", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessDatePicker.prototype, "months", void 0);
+__decorate([
+    property()
+], HelixHeadlessDatePicker.prototype, "locale", void 0);
+__decorate([
+    property({ attribute: 'disable-dates' })
+], HelixHeadlessDatePicker.prototype, "disableDates", void 0);
+__decorate([
+    property({ attribute: 'disable-days' })
+], HelixHeadlessDatePicker.prototype, "disableDays", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDatePicker.prototype, "invalid", void 0);
+__decorate([
+    property()
+], HelixHeadlessDatePicker.prototype, "month", null);
+__decorate([
+    property({ attribute: 'previous-label' })
+], HelixHeadlessDatePicker.prototype, "previousLabel", void 0);
+__decorate([
+    property({ attribute: 'next-label' })
+], HelixHeadlessDatePicker.prototype, "nextLabel", void 0);
+__decorate([
+    property({ attribute: 'default-month' })
+], HelixHeadlessDatePicker.prototype, "defaultMonth", void 0);
+__decorate([
+    property()
+], HelixHeadlessDatePicker.prototype, "min", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessDatePicker.prototype, "step", void 0);
+__decorate([
+    property()
+], HelixHeadlessDatePicker.prototype, "max", void 0);
+__decorate([
+    property()
+], HelixHeadlessDatePicker.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'first-day-of-week', type: Number })
+], HelixHeadlessDatePicker.prototype, "firstDayOfWeek", void 0);
+__decorate([
+    state()
+], HelixHeadlessDatePicker.prototype, "focused", void 0);
+__decorate([
+    property({ attribute: 'readonly', reflect: true, type: Boolean })
+], HelixHeadlessDatePicker.prototype, "readOnly", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDatePicker.prototype, "required", void 0);
+HelixHeadlessDatePicker = __decorate([
+    customElement('helix-headless-date-picker')
+], HelixHeadlessDatePicker);
+export { HelixHeadlessDatePicker };