@fusion.dev/helix-headless 0.159.0 → 0.160.0

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

@@ -1,4 +1,4 @@
-import { type CalendarView, type DateCalendar, HelixFormElement, type MonthCalendar } from '@fusion.dev/helix-core';
+import { type CalendarView, type DateCalendar, HelixFormElement, type MonthCalendar, type PickerFailure } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinPickerFeedbackInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
@@ -15,9 +15,11 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * **Dates are `YYYY-MM-DD` strings, and every calculation is in UTC**, because
  * a local-time `Date` shifts across a time zone or daylight-saving boundary.
  *
- * **The days are the Gregorian calendar's**, written in `calendar`: the
- * locale's own where its months are the Gregorian months, as `th-TH` writes
- * 2569 for 2026, and `gregory` where they are not, as for `fa-IR`.
+ * **The months are the ones `calendar` counts**: the Gregorian months for the
+ * locale's own calendar where its months are the Gregorian months, as `th-TH`
+ * writes 2569 for 2026, and `gregory` where they are not, as for `fa-IR`
+ * with no `calendar`. Name a calendar with months of its own, such as
+ * `persian`, and every view counts its days, months, and years from `Intl`.
  *
  * `month` sets which month the grid shows, separately from `value`, so paging
  * selects nothing and you can control the view. When unset, it follows the
@@ -25,7 +27,14 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  *
  * `mode` sets how many dates are held. Unset holds one, `range` holds two and
  * marks the dates between them, and `multiple` toggles each date. All three
- * read and write the same comma-separated `value`.
+ * read and write the same comma-separated `value`. With a `mode`, the grid
+ * carries `aria-multiselectable`. While a range holds one end, the grid draws
+ * the range to the day under the pointer or the focus, marking those cells
+ * `data-range-preview`.
+ *
+ * The chosen date, range, or count of dates is the grid's description, in a
+ * region screen readers announce when it changes, as React Aria's calendars
+ * do. `selection-label` words it.
  *
  * `max-view` makes the heading a button that steps back to the months of the
  * year, and with `year` to a page of years, as Zag's date picker does. The
@@ -58,7 +67,7 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * @event {Event} input - Fired after the value changes.
  *
  * @csspart cell - One column of a week row. A range is painted on the cells.
- * @csspart cell-range-end - The cell of a range's last day, beside `cell`.
+ * @csspart cell-range-end - The cell of a range's last day, beside `cell`, or of the day a waiting range is drawn to.
  * @csspart cell-range-middle - A cell between a range's ends, beside `cell`.
  * @csspart cell-range-start - The cell of a range's first day, beside `cell`.
  * @csspart day - The shape inside a cell. A single chosen date is painted on it.
@@ -84,12 +93,17 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * @csspart periods - The grid of months or years.
  * @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 selection - The chosen date or range in words, which screen readers hear when it changes. Drawn for screen readers only.
  * @csspart week - One row of days.
  * @csspart weekday - A column header naming a day of the week. It shows the short name and says the full one.
  *
  * @cssproperty --date-picker-column-count - How many month columns are drawn, capped at two. `--date-picker-columns` overrides it.
  *
- * @cssstate invalid - While `invalid` is set or `feedback` says what is wrong.
+ * @cssstate blank - While no date is chosen.
+ * @cssstate invalid - While `invalid` is set, `feedback` says what is wrong, the picker holds a date outside `min` and `max` or one it bars, or it is `required`, holds no date, and the reader has answered once or a form has refused it.
+ * @cssstate month-view - While the months of a year are shown, where `max-view` is set.
+ * @cssstate range-pending - While a `range` holds its first end and waits for the second.
+ * @cssstate year-view - While a page of years is shown, where `max-view` is `year`.
  */
 export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_base {
     /**
@@ -116,14 +130,16 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * `ja-JP-u-ca-japanese`, and `gregory` for every other, such as `persian`
      * for `fa-IR`.
      *
-     * `persian`, `hebrew`, `islamic-umalqura`, `islamic-civil`, `ethiopic`,
-     * `coptic`, and `indian` draw a calendar with months of its own, as React
-     * Aria's calendars do: each grid is one of that calendar's months, the
-     * Hebrew leap month and Ethiopia's five-day thirteenth month included, and
-     * Previous, Next and the page keys move by those months. `month` and
+     * `persian`, `hebrew`, `islamic`, `islamic-umalqura`, `islamic-civil`,
+     * `islamic-tbla`, `islamic-rgsa`, `ethiopic`, `ethioaa`, `coptic`,
+     * `indian`, `chinese`, and `dangi` draw a calendar with months of its own,
+     * as React Aria's calendars do: each grid is one of that calendar's months,
+     * the Hebrew and Chinese leap months and Ethiopia's five-day thirteenth
+     * month included, and Previous, Next and the page keys move by those
+     * months. With `max-view`, the months view shows that calendar's year, of
+     * twelve or thirteen months, and the years view its years. `month` and
      * `helix-navigate` then name a month by its first day, `YYYY-MM-DD`. The
-     * heading stays text, as the months and years views are drawn in Gregorian
-     * months only. The value is `YYYY-MM-DD` in every calendar.
+     * value is `YYYY-MM-DD` in every calendar.
      */
     calendar?: DateCalendar | MonthCalendar;
     /**
@@ -207,6 +223,8 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     mode?: 'range' | 'multiple';
     /** The month on show, whoever set it, and `undefined` until somebody has. */
     private monthState;
+    /** Whether the month on show is one the reader paged to, which `showChosen` forgets. */
+    private browsed;
     /**
      * The month shown, as `YYYY-MM`, or as its first day, `YYYY-MM-DD`, under a
      * `calendar` with months of its own. When it is not set, it follows
@@ -284,6 +302,21 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     private choosing;
     /** The range's ends, when there are two and the mode asks for them. */
     private get range();
+    /**
+     * The day a reader points at or moves to while a range holds one end, which
+     * the grid draws the range to before it is chosen.
+     */
+    private previewed;
+    /** Whether a range holds its first end and waits for the second. */
+    private get pending();
+    /**
+     * The range the grid draws: the chosen one, or, while one end waits for
+     * the other, the run to the day under the pointer or the focus.
+     */
+    private get drawnRange();
+    /** Draws a waiting range to the day the pointer is on. */
+    private preview;
+    private readonly handleGridLeave;
     private isSelected;
     /** The month being shown, resolved from `month`, then `value`, then today. */
     private get shown();
@@ -292,8 +325,6 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * months of its own, and the Gregorian months otherwise.
      */
     private get system();
-    /** Whether `calendar` names a calendar with months of its own. */
-    private get ownMonths();
     /**
      * The month to open on when nothing has declared one.
      *
@@ -407,6 +438,16 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * plain `focus()` on it did nothing and focus stayed on the trigger.
      */
     focus(options?: FocusOptions): void;
+    /**
+     * Shows the days again, on the month of the chosen date, with the tab stop
+     * on that date, forgetting the month and the day the reader browsed to.
+     *
+     * Date Input calls it each time its panel opens, which is where the APG
+     * date picker dialog puts focus. Measured before this: from August 4, two
+     * presses of Page Down, Escape, and Down again opened on October 4.
+     * A `month` you set stays until the reader pages away from it.
+     */
+    showChosen(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
@@ -434,6 +475,23 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * Stops the form from submitting while no date is chosen.
      */
     required: boolean;
+    /**
+     * What a screen reader hears about the chosen dates: the grid's
+     * description, said again whenever the dates change. `{kind}` is `date`,
+     * `start` while a range holds one end, `range`, or `dates` for `multiple`.
+     * `{start}` and `{end}` are dates written in `locale`, and `{count}` is how
+     * many dates are chosen.
+     */
+    selectionLabel: string;
+    /**
+     * `selectionLabel` for the dates chosen now, or nothing while there are none.
+     *
+     * React Aria's calendars describe the grid by the chosen date or range and
+     * announce it when it changes. Measured before this: a range of seven days
+     * was seven cells with `aria-selected` in a grid that said nothing of a
+     * range, and choosing its end was heard as one more selected cell.
+     */
+    private get selectionWords();
     /**
      * How far apart the selectable dates are, in days.
      *
@@ -505,6 +563,13 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * browser points its bubble at.
      */
     private reportRequired;
+    /**
+     * What is wrong with the answer, as validity flags and a message, or nothing.
+     * `reportRequired` hands it to the form, and `failure` to the mark.
+     */
+    private get problem();
+    /** A missing date waits for the reader; a refused one is marked at once. */
+    protected get failure(): PickerFailure | undefined;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * Reports validity after render, because the bubble needs somewhere to point.

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { addDays, addMonths, valueAsDate as asDate, barredBy, calendarLocale, customElement, formatWords, dateAsValue as fromDate, HelixFormElement, HelixNavigateEvent, handedLocale, hostAria, inlineStep, commaList as list, MixinControllerValue, MixinPickerFeedback, MONTH_CALENDARS, monthOf, monthOut, monthSystem, periodCells, periodKey, reportValues, requestChange, todayIn, weekendOf, weekStartOf, words, wordsLocale, YEARS_SHOWN, yearOut, yearPageOf, } from '@fusion.dev/helix-core';
+import { addDays, addMonths, valueAsDate as asDate, barredBy, calendarLocale, customElement, formatWords, dateAsValue as fromDate, HelixFormElement, HelixNavigateEvent, handedLocale, hostAria, inlineStep, commaList as list, MixinControllerValue, MixinPickerFeedback, monthOut, monthSystem, periodCells, periodKey, reportValues, requestChange, todayIn, weekendOf, weekStartOf, words, wordsLocale, YEARS_SHOWN, yearOut, yearPageOf, } 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';
@@ -34,6 +34,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         this.max = '';
         this.min = '';
         this.monthState = undefined;
+        this.browsed = false;
         this.months = 1;
         this.monthViewLabel = '{heading}. Choose a month';
         this.nextLabel = 'Next month';
@@ -45,8 +46,12 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         this.rangeOverflowMessage = 'Choose a date on or before {max}.';
         this.focused = '';
         this.choosing = false;
+        this.previewed = '';
+        this.handleGridLeave = () => {
+            this.previewed = '';
+        };
         this.handleKeydown = (event) => {
-            if (this.view !== 'day' && !this.ownMonths) {
+            if (this.view !== 'day') {
                 this.handlePeriodKeydown(event);
                 return;
             }
@@ -80,7 +85,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             }
             else {
                 const step = event.key === 'PageUp' ? -1 : 1;
-                this.moveTo(this.system.add(from, event.shiftKey ? step * 12 : step));
+                this.moveTo(event.shiftKey ? this.system.addYears(from, step) : this.system.add(from, step));
             }
             event.preventDefault();
         };
@@ -91,8 +96,9 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
                 return;
             }
             if (this.view === 'day') {
-                this.pageYear = this.shown.getUTCFullYear();
-                this.periodFocus = this.shown.getUTCMonth();
+                const { month, year } = this.system.parts(this.shown);
+                this.pageYear = year;
+                this.periodFocus = month - 1;
                 this.zoom('month');
             }
             else if (this.view === 'month' && this.maxView === 'year') {
@@ -103,6 +109,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         this.rangeUnderflowMessage = 'Choose a date on or after {min}.';
         this.readOnly = false;
         this.required = false;
+        this.selectionLabel = '{kind, select, date {Selected date: {start}} start {Range starts {start}. Choose the day it ends.} range {Selected range: {start} to {end}} other {{count, plural, one {# date selected} other {# dates selected}}}}';
         this.step = 1;
         this.stepMismatchMessage = 'Choose one of the dates the calendar offers.';
         this.timeZone = '';
@@ -120,6 +127,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     }
     set month(next) {
         const previous = this.month;
+        this.browsed = false;
         this.monthState = next;
         this.requestUpdate('month', previous);
     }
@@ -143,6 +151,30 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         const [first, second] = [dates[0], dates[1]];
         return first <= second ? [first, second] : [second, first];
     }
+    get pending() {
+        return this.mode === 'range' && this.selected.length === 1;
+    }
+    get drawnRange() {
+        const range = this.range;
+        if (range) {
+            return { ends: range, preview: false };
+        }
+        const end = this.previewed || this.focused;
+        const start = this.selected[0];
+        if (!this.pending ||
+            start === undefined ||
+            end === '' ||
+            end === start ||
+            asDate(end) === null) {
+            return null;
+        }
+        return { ends: start <= end ? [start, end] : [end, start], preview: true };
+    }
+    preview(iso) {
+        if (this.pending && iso !== this.previewed) {
+            this.previewed = iso;
+        }
+    }
     isSelected(iso) {
         const range = this.range;
         if (range) {
@@ -161,9 +193,6 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     get system() {
         return monthSystem(this.calendar);
     }
-    get ownMonths() {
-        return MONTH_CALENDARS.includes(this.calendar ?? '');
-    }
     get derivedMonth() {
         const from = asDate(this.selected[0] ?? '') ?? asDate(todayIn(this.timeZone)) ?? new Date();
         return this.system.start(from);
@@ -226,6 +255,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         requestChange({
             apply: (month) => {
                 const previous = this.month;
+                this.browsed = true;
                 this.monthState = month;
                 this.requestUpdate('month', previous);
             },
@@ -237,6 +267,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     moveTo(wanted) {
         const date = this.clamp(wanted);
         this.focused = fromDate(date);
+        this.previewed = '';
         this.show(date);
         this.updateComplete.then(() => {
             this.renderRoot.querySelector('[part~="cell"][tabindex="0"]')?.focus();
@@ -262,23 +293,25 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             next = [iso];
         }
         this.focused = iso;
+        this.previewed = '';
         this.choosing = true;
         this.requestValue(next.join(','));
     }
     get periodYear() {
-        return this.pageYear ?? this.shown.getUTCFullYear();
+        return this.pageYear ?? this.system.parts(this.shown).year;
     }
     get periodStop() {
-        if (this.periodFocus !== undefined) {
-            return this.periodFocus;
+        if (this.view === 'year') {
+            return this.periodFocus ?? this.periodYear;
         }
-        return this.view === 'year' ? this.periodYear : this.shown.getUTCMonth();
+        const index = this.periodFocus ?? this.system.parts(this.shown).month - 1;
+        return Math.min(index, this.system.months(this.periodYear) - 1);
     }
     monthOut(first) {
-        return monthOut(first, this.min, this.max);
+        return monthOut(first, this.min, this.max, this.system);
     }
     yearOut(year) {
-        return yearOut(year, this.min, this.max);
+        return yearOut(year, this.min, this.max, this.system);
     }
     zoom(view) {
         this.view = view;
@@ -293,8 +326,8 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
                 return;
             }
             this.pageYear = at;
-            const month = this.shown.getUTCMonth();
-            const open = Array.from({ length: 12 }, (_, index) => index).filter((index) => !this.monthOut(firstOf(at, index)));
+            const month = this.system.parts(this.shown).month - 1;
+            const open = Array.from({ length: this.system.months(at) }, (_, index) => index).filter((index) => !this.monthOut(this.system.from(at, index + 1, 1)));
             this.periodFocus = open.includes(month)
                 ? month
                 : ([...open].sort((left, right) => Math.abs(left - month) - Math.abs(right - month))[0] ??
@@ -302,12 +335,12 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             this.zoom('month');
             return;
         }
-        const first = firstOf(this.periodYear, at);
+        const first = this.system.from(this.periodYear, at + 1, 1);
         if (this.monthOut(first)) {
             return;
         }
         this.show(first);
-        if (this.month !== monthOf(first)) {
+        if (this.month !== this.system.key(first)) {
             return;
         }
         this.pageYear = undefined;
@@ -344,7 +377,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             this.choosePeriod(stop);
             return;
         }
-        const moved = periodKey(this.view === 'year' ? 'year' : 'month', stop, this.periodYear, event.key, inlineStep(this, event.key));
+        const moved = periodKey(this.view === 'year' ? 'year' : 'month', stop, this.periodYear, event.key, inlineStep(this, event.key), (year) => this.system.months(year));
         if (moved === null) {
             return;
         }
@@ -354,10 +387,26 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         void this.updateComplete.then(() => this.focus());
     }
     focus(options) {
+        if (this.isUpdatePending) {
+            void this.updateComplete.then(() => this.focus(options));
+            return;
+        }
         this.renderRoot
             ?.querySelector('[part~="cell"][tabindex="0"], [part~="period"][tabindex="0"]')
             ?.focus(options);
     }
+    showChosen() {
+        this.focused = '';
+        this.pageYear = undefined;
+        this.periodFocus = undefined;
+        this.view = 'day';
+        if (this.browsed) {
+            this.browsed = false;
+            const previous = this.month;
+            this.monthState = undefined;
+            this.requestUpdate('month', previous);
+        }
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('keydown', this.handleKeydown);
@@ -372,6 +421,28 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         }
         return super.requestValue(next);
     }
+    get selectionWords() {
+        const dates = this.selected.map((one) => asDate(one));
+        const first = dates[0];
+        if (!first || dates.some((one) => one === null)) {
+            return '';
+        }
+        const { long } = this.formats;
+        const range = this.range;
+        const kind = range
+            ? 'range'
+            : this.pending
+                ? 'start'
+                : this.mode === 'multiple'
+                    ? 'dates'
+                    : 'date';
+        return formatWords(this, 'selectionLabel', {
+            count: dates.length,
+            end: range ? long.format(asDate(range[1])) : '',
+            kind,
+            start: long.format(range ? asDate(range[0]) : first),
+        });
+    }
     spoken(iso) {
         const date = asDate(iso);
         return date ? this.formats.long.format(date) : iso;
@@ -399,24 +470,38 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             : ['stepMismatch', this.stepMismatchMessage];
     }
     reportRequired() {
-        const anchor = this.partNamed('grid') ?? undefined;
-        if (this.required && this.value === '') {
-            this.internals.setValidity({ valueMissing: true }, this.valueMissingMessage, anchor);
+        const problem = this.problem;
+        if (problem) {
+            this.internals.setValidity(problem[0], problem[1], this.partNamed('grid') ?? undefined);
             return;
         }
+        this.internals.setValidity({});
+    }
+    get problem() {
+        if (this.required && this.value === '') {
+            return [{ valueMissing: true }, this.valueMissingMessage];
+        }
         const held = this.selected;
         if (held.length > 0 && held.some((one) => asDate(one) === null)) {
-            this.internals.setValidity({ badInput: true }, formatWords(this, 'badInputMessage', { mode: this.mode ?? 'single' }), anchor);
-            return;
+            return [
+                { badInput: true },
+                formatWords(this, 'badInputMessage', { mode: this.mode ?? 'single' }),
+            ];
         }
         for (const one of held) {
             const fault = this.fault(one);
             if (fault) {
-                this.internals.setValidity({ [fault[0]]: true }, fault[1], anchor);
-                return;
+                return [{ [fault[0]]: true }, fault[1]];
             }
         }
-        this.internals.setValidity({});
+        return undefined;
+    }
+    get failure() {
+        const problem = this.problem;
+        if (!problem) {
+            return undefined;
+        }
+        return problem[0].valueMissing ? 'missing' : 'refused';
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -431,6 +516,10 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
             role: 'group',
         });
         this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
+        this.toggleState('blank', this.value === '');
+        this.toggleState('range-pending', this.pending);
+        this.toggleState('month-view', this.view === 'month');
+        this.toggleState('year-view', this.view === 'year');
         this.report();
     }
     updated(changed) {
@@ -448,9 +537,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         return Math.max(1, Math.floor(this.months) || 1);
     }
     get formats() {
-        const language = this.ownMonths
-            ? `${new Intl.Locale(this.language || new Intl.DateTimeFormat().resolvedOptions().locale, { calendar: this.calendar ?? 'gregory' })}`
-            : calendarLocale(this.language, this.calendar);
+        const language = calendarLocale(this.language, this.calendar);
         if (this.cachedFormats?.locale === language) {
             return this.cachedFormats;
         }
@@ -489,7 +576,9 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         const weeks = this.weeksOf(month);
         const anchor = fromDate(this.anchor);
         const today = todayIn(this.timeZone);
-        const range = this.range;
+        const drawn = this.drawnRange;
+        const range = drawn?.ends ?? null;
+        const preview = drawn?.preview === true;
         const weekend = this.weekend;
         const first = index === 0;
         const last = index === this.monthCount - 1;
@@ -526,8 +615,11 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         part="grid"
         role="grid"
         aria-label=${heading}
+        aria-describedby=${this.selectionWords === '' ? nothing : 'selection'}
+        aria-multiselectable=${this.mode === undefined ? nothing : 'true'}
         aria-readonly=${this.readOnly ? 'true' : nothing}
         data-unset=${this.value === '' ? '' : nothing}
+        @pointerleave=${this.handleGridLeave}
       >
         <div part="week" role="row">
           ${weeks[0]?.map((date) => html `<span part="weekday" role="columnheader" aria-label=${weekdayName.format(date)}
@@ -553,11 +645,13 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
                 data-outside=${outside ? '' : nothing}
                 data-range-end=${end ? '' : nothing}
                 data-range-middle=${middle ? '' : nothing}
+                data-range-preview=${preview && (start || middle || end) ? '' : nothing}
                 data-range-start=${start ? '' : nothing}
                 data-today=${iso === today ? '' : nothing}
                 data-weekend=${weekend.includes(date.getUTCDay()) ? '' : nothing}
                 tabindex=${!outside && iso === anchor && !this.isDisabled ? '0' : '-1'}
                 @click=${outside ? nothing : () => this.select(date)}
+                @pointerenter=${outside ? nothing : () => this.preview(iso)}
                 ><span
                   part="day${!outside && selected && !middle ? ' day-selected' : ''}${iso === today ? ' day-today' : ''}${outside ? ' day-outside' : ''}${disabled ? ' day-disabled' : ''}${weekend.includes(date.getUTCDay()) ? ' day-weekend' : ''}"
                   >${this.renderDay(date, outside)}</span
@@ -573,7 +667,6 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     }
     renderHeadingText(text, label) {
         const steps = this.maxView !== undefined &&
-            !this.ownMonths &&
             (this.view === 'day' || (this.view === 'month' && this.maxView === 'year'));
         if (!steps) {
             return text;
@@ -591,14 +684,15 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         const years = this.view === 'year';
         const page = years ? yearPageOf(this.periodYear) : this.periodYear;
         const heading = years
-            ? `${yearName.format(firstOf(page, 0))} – ${yearName.format(firstOf(page + YEARS_SHOWN - 1, 0))}`
-            : yearName.format(firstOf(page, 0));
+            ? `${yearName.format(this.system.from(page, 1, 1))} – ${yearName.format(this.system.from(page + YEARS_SHOWN - 1, 1, 1))}`
+            : yearName.format(this.system.from(page, 1, 1));
         const stop = this.periodStop;
         const cells = periodCells({
             max: this.max,
             min: this.min,
             page: this.periodYear,
             shown: this.shown,
+            system: this.system,
             today: todayIn(this.timeZone),
             view: years ? 'year' : 'month',
         }).map(({ at, chosen, current, first, out }) => {
@@ -615,7 +709,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         >${words}</span
       >`;
         });
-        const rows = [0, 3, 6, 9].map((from) => html `<div part="period-row" role="row">${cells.slice(from, from + 3)}</div>`);
+        const rows = Array.from({ length: Math.ceil(cells.length / 3) }, (_, row) => row * 3).map((from) => html `<div part="period-row" role="row">${cells.slice(from, from + 3)}</div>`);
         return html `<div part="month">
       <div part="header">
         <button
@@ -644,7 +738,7 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     </div>`;
     }
     render() {
-        if (this.view !== 'day' && !this.ownMonths) {
+        if (this.view !== 'day') {
             return html `<slot name="header"></slot>
         <div part="months" style="--date-picker-column-count: 1">${this.renderPeriods()}</div>
         <slot name="footer"></slot>${this.renderPickerFeedback()}`;
@@ -655,6 +749,9 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
       <div part="months" style="--date-picker-column-count: ${Math.min(count, 2)}">
         ${Array.from({ length: count }, (_, index) => this.renderMonth(this.system.add(shown, index), index))}
       </div>
+      <span part="selection" id="selection" data-spoken aria-live="polite"
+        >${this.selectionWords}</span
+      >
       <slot name="footer"></slot>${this.renderPickerFeedback()}`;
     }
     get valueAsDate() {
@@ -755,6 +852,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessDatePicker.prototype, "focused", void 0);
+__decorate([
+    state()
+], HelixHeadlessDatePicker.prototype, "previewed", void 0);
 __decorate([
     state()
 ], HelixHeadlessDatePicker.prototype, "pageYear", void 0);
@@ -771,6 +871,10 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessDatePicker.prototype, "required", void 0);
+__decorate([
+    words,
+    property({ attribute: 'selection-label' })
+], HelixHeadlessDatePicker.prototype, "selectionLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessDatePicker.prototype, "step", void 0);

package/dist/element-events.generated.js

@@ -92,6 +92,7 @@ registerElementEvents({
         'helix-before-change',
         'helix-before-close',
         'helix-before-open',
+        'helix-clear',
         'input',
         'toggle',
     ],
@@ -268,6 +269,7 @@ registerElementEvents({
         'helix-before-change',
         'helix-before-close',
         'helix-before-open',
+        'helix-clear',
         'input',
         'toggle',
     ],

package/dist/format-date/fields.js

@@ -3,6 +3,7 @@ export const FIELD = {
     day: (value) => html `<span part="day">${value}</span>`,
     dayPeriod: (value) => html `<span part="day-period">${value}</span>`,
     era: (value) => html `<span part="era">${value}</span>`,
+    fractionalSecond: (value) => html `<span part="fractional-second">${value}</span>`,
     hour: (value) => html `<span part="hour">${value}</span>`,
     minute: (value) => html `<span part="minute">${value}</span>`,
     month: (value) => html `<span part="month">${value}</span>`,

package/dist/format-date/options.d.ts

@@ -5,7 +5,9 @@
 export interface Asked {
     dateStyle?: 'full' | 'long' | 'medium' | 'short' | undefined;
     day?: 'numeric' | '2-digit' | undefined;
+    dayPeriod?: 'long' | 'narrow' | 'short' | undefined;
     era?: 'long' | 'narrow' | 'short' | undefined;
+    fractionalSecondDigits?: 1 | 2 | 3 | undefined;
     hour?: 'numeric' | '2-digit' | undefined;
     hourCycle?: 'h11' | 'h12' | 'h23' | 'h24' | undefined;
     minute?: 'numeric' | '2-digit' | undefined;
@@ -13,7 +15,7 @@ export interface Asked {
     second?: 'numeric' | '2-digit' | undefined;
     timeStyle?: 'full' | 'long' | 'medium' | 'short' | undefined;
     timeZone?: string | undefined;
-    timeZoneName?: 'long' | 'short' | undefined;
+    timeZoneName?: 'long' | 'longGeneric' | 'longOffset' | 'short' | 'shortGeneric' | 'shortOffset' | undefined;
     weekday?: 'long' | 'short' | 'narrow' | undefined;
     year?: 'numeric' | '2-digit' | undefined;
 }

package/dist/format-date/options.js

@@ -1,5 +1,8 @@
 import { FIELD } from './fields.js';
-const FIELDS = Object.keys(FIELD);
+const FIELDS = [
+    ...Object.keys(FIELD).filter((one) => one !== 'fractionalSecond'),
+    'fractionalSecondDigits',
+];
 export const formatOptions = (asked, dateOnly = false) => {
     const options = {
         hourCycle: asked.hourCycle,