@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -1,4 +1,4 @@
-import { HelixFormElement } from '@fusion.dev/helix-core';
+import { type CalendarView, 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;
 /**
@@ -23,6 +23,20 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * marks the dates between them, and `multiple` toggles each date. All three
  * read and write the same comma-separated `value`.
  *
+ * `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
+ * arrows, Home, End and the page keys move there, Enter or a press chooses, and
+ * Escape goes back to the days.
+ *
+ * `isDateUnavailable` and `dayContent` are properties for a script: a rule
+ * that bars dates, and what each day shows in place of its number.
+ *
+ * The month heading is a live region, so a screen reader hears the new month
+ * when Previous or Next is pressed. Neither moves past `min` or `max`, and the
+ * keys stop at them too. A value outside the bounds, on a barred day, or off
+ * `step` reports `rangeUnderflow`, `rangeOverflow`, `badInput` or
+ * `stepMismatch`, so a form does not submit it.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -49,10 +63,17 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * @csspart grid - The grid of days.
  * @csspart header - The month name and its controls.
  * @csspart heading - The month and year being shown.
+ * @csspart heading-button - The heading as a button that shows the months or the years, where `max-view` is set.
  * @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 period - One month in the months view, or one year in the years view.
+ * @csspart period-current - This month or this year, beside `period`.
+ * @csspart period-disabled - A month or a year wholly outside `min` and `max`, beside `period`.
+ * @csspart period-row - One row of three months or years.
+ * @csspart period-selected - The month or the year on show, beside `period`.
+ * @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 week - One row of days.
@@ -69,26 +90,53 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * speaks it. Absent is the control's own sentence, in English.
      */
     badInputMessage?: string;
+    /**
+     * What each day shows, in place of its number: a function given the date as
+     * `YYYY-MM-DD` that returns text, an element or a Lit template.
+     *
+     * For a price or a dot under the number, as React Aria's `CalendarCell`
+     * takes children. The cell is still named by its whole date, so what you
+     * draw here is for the eye; say anything a reader must hear in the date's
+     * description elsewhere. Return the day's number with it where it should
+     * still show. A property only, there being no way to write a function in
+     * markup.
+     */
+    dayContent?: ((date: string) => unknown) | undefined;
     /**
      * The month to open on when `month` is not set.
      */
     defaultMonth: string;
     /**
-     * Dates that cannot be chosen, comma separated, as `YYYY-MM-DD`.
+     * Dates that cannot be chosen, as `YYYY-MM-DD`, separated by commas or
+     * spaces.
      */
     disableDates: string;
     /**
-     * Days of the week that cannot be chosen, comma separated, `0` to `6`.
+     * Days of the week that cannot be chosen, `0` for Sunday to `6` for
+     * Saturday, separated by commas or spaces.
      */
     disableDays: string;
     /**
      * First column of the week, `0` for Sunday through `6` for Saturday.
+     *
+     * Absent follows `locale`, where the engine knows the week of that language
+     * (Firefox does not), and is Sunday otherwise.
      */
-    firstDayOfWeek: number;
+    firstDayOfWeek?: number;
     /**
      * Whether the current selection fails validation.
      */
     invalid: boolean;
+    /**
+     * A rule for which dates cannot be chosen: a function given the date as
+     * `YYYY-MM-DD` that returns `true` to bar it.
+     *
+     * For what a list cannot say, such as the second Tuesday of each month or
+     * the days a server has fully booked. It bars a date as `disable-dates`
+     * does, in the grid and in validation. A property only, as React Aria's
+     * `isDateUnavailable` is a prop.
+     */
+    isDateUnavailable?: ((date: string) => boolean) | undefined;
     /**
      * Accessible name for the grid.
      */
@@ -103,6 +151,17 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * Latest selectable date, as `YYYY-MM-DD`.
      */
     max: string;
+    /**
+     * How far the heading lets a reader step back from the days: `month` to a
+     * year's months, or `year` to a page of years and then its months.
+     *
+     * Absent, the heading is text and the calendar moves a month at a time. Set,
+     * the heading is a button that shows the months, and from there the years,
+     * so a birth date forty years back is three presses rather than four hundred
+     * and eighty. Choosing a year shows its months, and choosing a month shows
+     * its days.
+     */
+    maxView?: 'month' | 'year';
     /**
      * Earliest selectable date, as `YYYY-MM-DD`.
      */
@@ -127,10 +186,23 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * How many months to show, side by side.
      */
     months: number;
+    /**
+     * The name of the heading where it shows the months, with `{heading}`
+     * filled in as the month on show.
+     */
+    monthViewLabel: string;
     /**
      * Accessible name for the control that pages forward.
      */
     nextLabel: string;
+    /**
+     * Accessible name for the control that moves forward a year, in the months.
+     */
+    nextYearLabel: string;
+    /**
+     * Accessible name for the control that moves forward a page, in the years.
+     */
+    nextYearsLabel: string;
     /**
      * Accessible name for the control that pages back.
      *
@@ -141,19 +213,18 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     previousLabel: string;
     /**
-     * Blocks changes to the dates. The value is still submitted with the form.
-     *
-     * **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.
+     * Accessible name for the control that moves back a year, in the months.
      */
-    readOnly: boolean;
+    previousYearLabel: string;
+    /**
+     * Accessible name for the control that moves back a page, in the years.
+     */
+    previousYearsLabel: string;
+    /**
+     * The validation message for a date after `max`. `{max}` is replaced with
+     * `max`, written as a date in `locale`.
+     */
+    rangeOverflowMessage?: string;
     /**
      * The date the grid's tab stop is on.
      *
@@ -162,6 +233,17 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     private focused;
     /** The selected dates, in order. */
     private get selected();
+    /** The day the week starts on: `firstDayOfWeek`, or the locale's. */
+    private get weekStart();
+    /**
+     * Whether the last date the reader moved to is this picker's own doing.
+     *
+     * A value that moves from outside, typed into Date Input or set by a script,
+     * takes the tab stop to the selected day, as the APG date picker does. A
+     * value this grid chose leaves it where the reader pressed, which in a range
+     * is the end they just picked.
+     */
+    private choosing;
     /** The range's ends, when there are two and the mode asks for them. */
     private get range();
     private isSelected;
@@ -200,6 +282,12 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * one that moves.
      */
     private barred;
+    /** Pulls a date inside `min` and `max`, so the keys stop at the bounds. */
+    private clamp;
+    /** Whether the month before the first one shown is wholly before `min`. */
+    private get atStart();
+    /** Whether the month after the last one shown is wholly after `max`. */
+    private get atEnd();
     /**
      * Moves the view, announcing it first.
      *
@@ -219,14 +307,85 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     private select;
     private readonly handleKeydown;
+    /**
+     * The year the months view shows, and the year the years view is on.
+     *
+     * Its own state rather than `month`, because looking through the months of
+     * another year chooses nothing and moves nothing on show: the month changes,
+     * and `helix-navigate` is sent, only once a month is chosen.
+     */
+    private pageYear;
+    /**
+     * Where the tab stop is among the months, as their index, or among the
+     * years, as the year.
+     */
+    private periodFocus;
+    /** The year on show in the months and the years. */
+    private get periodYear();
+    /** The index or the year the tab stop sits on in the months or the years. */
+    private get periodStop();
+    /** Whether a month, as its first day, lies wholly outside `min` and `max`. */
+    private monthOut;
+    /** Whether a year lies wholly outside `min` and `max`. */
+    private yearOut;
+    /** Changes the view, and takes focus to its tab stop once it has drawn. */
+    private zoom;
+    /**
+     * The heading's press: from the days to the months, and from the months to
+     * the years where `max-view` allows.
+     */
+    private readonly handleHeading;
+    /**
+     * Takes a month or a year: a year shows its months, and a month shows its
+     * days, moving the calendar there with `helix-navigate` first.
+     */
+    private choosePeriod;
+    /** Moves the months a year, or the years a page. */
+    private turnPage;
+    /**
+     * The keys in the months and the years: the arrows, Home, End and the page
+     * keys move, Enter and Space choose, and Escape goes back to the days.
+     *
+     * Escape is stopped here, so a Date Input around this calendar keeps its
+     * panel open: a reader backing out of the years has not asked to leave.
+     */
+    private handlePeriodKeydown;
+    /**
+     * Moves focus to the grid's tab stop: the selected day, or the day last
+     * moved to, or the first of the month.
+     *
+     * Date Input calls this when its trigger opens the calendar, which is where
+     * the APG date picker dialog puts focus. The host is not focusable, so a
+     * plain `focus()` on it did nothing and focus stayed on the trigger.
+     */
+    focus(options?: FocusOptions): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Stops the form from submitting while no date is chosen.
+     * The validation message for a date before `min`. `{min}` is replaced with
+     * `min`, written as a date in `locale`.
      */
-    required: boolean;
+    rangeUnderflowMessage?: string;
     /** Refuses every change while read-only. See `readOnly`. */
     requestValue(next: string): boolean;
+    /**
+     * Blocks changes to the dates. The value is still submitted with the form.
+     *
+     * **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;
+    /**
+     * Stops the form from submitting while no date is chosen.
+     */
+    required: boolean;
     /**
      * How far apart the selectable dates are, in days.
      *
@@ -241,10 +400,42 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * date including the one already chosen.
      */
     step: number;
+    /**
+     * The validation message for a date that `step` skips.
+     */
+    stepMismatchMessage?: string;
+    /**
+     * The validation message for a date that `disable-dates` or `disable-days`
+     * bars.
+     */
+    unavailableMessage?: string;
     /**
      * The validation message for a required date picker with no date chosen.
      */
     valueMissingMessage?: string;
+    /**
+     * What the calendar shows: the days of a month, the months of a year, or a
+     * page of years. `day` unless `max-view` lets a reader step back.
+     *
+     * Not reflected, being state. Set it to open on the months or the years.
+     */
+    view: CalendarView;
+    /**
+     * The name of the heading where it shows a page of years, with `{heading}`
+     * filled in as the year on show.
+     */
+    yearViewLabel: string;
+    /** A date written for a message, in `locale`. */
+    private spoken;
+    /**
+     * What is wrong with a date the calendar can read, as a validity flag and a
+     * message, or nothing.
+     *
+     * Measured before this: a value before `min`, after `max`, or on a barred
+     * day reported valid and was submitted, where a native date input reports
+     * the bound it is past.
+     */
+    private fault;
     /**
      * Reports "required and empty", or clears it.
      *
@@ -323,6 +514,26 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     protected renderPreviousMark(): TemplateResult;
     protected renderNextMark(): TemplateResult;
     private renderMonth;
+    /**
+     * What a day shows: its number, or what `day-content` returns for it.
+     *
+     * A seam, so a tier above can draw a day its own way, and filler days from a
+     * neighboring month keep their number, being only there to square the grid.
+     */
+    protected renderDay(date: Date, outside: boolean): unknown;
+    /**
+     * The heading's words, as a button that steps back to the months or the
+     * years where `max-view` allows, and as text everywhere else.
+     */
+    private renderHeadingText;
+    /**
+     * The months of a year, or a page of years, in rows of three, with the
+     * controls that turn the page.
+     *
+     * A grid of its own, `periods`, so a stylesheet tells it from the days, and
+     * one tab stop in it, the month or year the keys are on.
+     */
+    private renderPeriods;
     protected render(): TemplateResult;
     /**
      * The value as a `Date`, at midnight UTC, or `null` while there is no date.