@fusion.dev/helix-headless 0.142.0 → 0.143.0

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

@@ -13,7 +13,13 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  *
  * You can type a date as well as pick one. The native `<input type="date">`
  * gives a picker and locale formatting but allows almost no styling, so the
- * field is a text field.
+ * field is a text field. Typing sends `input` on each keystroke and `change`
+ * when you leave the field, as a text field does. A date picked from the
+ * calendar sends both.
+ *
+ * The trigger opens the calendar with focus on the selected day, and Escape
+ * closes it and returns focus to the field. Focusing the field opens the
+ * calendar too, and Tab out of the field closes it again.
  *
  * @since 0.1.0
  * @status stable
@@ -23,6 +29,8 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  *
  * @slot feedback - The error message under the field.
  * @slot hint - The help text under the field.
+ * @slot next-icon - The icon on the calendar's next month control.
+ * @slot previous-icon - The icon on the calendar's previous month control.
  * @slot trigger - The icon on the button that opens the calendar.
  *
  * @event {Event} change - Fired after the value changes.
@@ -30,7 +38,7 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the calendar closes. Cancelable: call `preventDefault()` to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the calendar opens. Cancelable: call `preventDefault()` to keep it closed.
  * @event {Event} input - Fired after the value changes.
- * @event {Event} toggle - Fired when the calendar opens or closes, with `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - Fired when the calendar opens or closes, with `newState` and `oldState`.
  *
  * @csspart control - The text input.
  * @csspart date - One held date, as a tag, in `multiple`.
@@ -82,6 +90,12 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      * postal code can never be filled in for a reader.
      */
     autocomplete: string;
+    /**
+     * The name of the calendar's grid of days, read by screen readers.
+     */
+    calendarLabel: string;
+    /** Typed, so a keystroke is announced as `input` alone. See `announcesInput`. */
+    protected readonly announcesInput = true;
     /**
      * How a date is written in the field: `short` through `full`, or ISO.
      *
@@ -108,19 +122,23 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      */
     dateStyle: 'full' | 'iso' | 'long' | 'medium' | 'short';
     /**
-     * Dates that cannot be chosen, as a comma-separated `YYYY-MM-DD` list.
+     * Dates that cannot be chosen, as `YYYY-MM-DD`, separated by commas or
+     * spaces.
      */
     disableDates: string;
     /**
      * Days of the week that cannot be chosen, from `0` for Sunday to `6` for
-     * Saturday.
+     * Saturday, separated by commas or spaces.
      */
     disableDays: string;
     /**
      * The day in the calendar's first column, from `0` for Sunday to `6` for
      * Saturday.
+     *
+     * Absent follows `locale`, where the engine knows the week of that language,
+     * and is Sunday otherwise.
      */
-    firstDayOfWeek: number;
+    firstDayOfWeek?: number;
     /**
      * The language tag for the names of months and days in the calendar.
      */
@@ -182,10 +200,18 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      */
     protected placed(room: number | undefined): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The name of the calendar's control that moves to the next month.
+     */
+    nextLabel: string;
     /**
      * The text the field shows before a date is entered.
      */
     placeholder: string;
+    /**
+     * The name of the calendar's control that moves to the previous month.
+     */
+    previousLabel: string;
     /**
      * The message shown when a range holds more than two dates.
      *
@@ -221,6 +247,14 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      * platform's base.
      */
     step: number;
+    /**
+     * The message shown when a date is not on `step`.
+     */
+    stepMismatchMessage?: string;
+    /**
+     * The name of the button that opens the calendar, read by screen readers.
+     */
+    triggerLabel: string;
     /**
      * What the calendar should show, which is only ever a whole date.
      *
@@ -259,10 +293,9 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
     /** What is wrong with the dates, which the text input cannot say. */
     protected validate(): string;
     /**
-     * The name of the button that opens the calendar, read by screen readers.
+     * The message shown when `disable-dates` or `disable-days` bars a date.
      */
-    triggerLabel: string;
-    protected updated(changed: PropertyValues): void;
+    unavailableMessage?: string;
     /**
      * The calendar the field opens, behind a seam the styled tier can move.
      *
@@ -273,6 +306,18 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      * one from the same template.
      */
     protected renderPicker(): TemplateResult;
+    /**
+     * Passes an icon slotted on the field to the calendar's slot of that name.
+     *
+     * **Forwarded only while the field holds one.** A forwarded slot is assigned
+     * to the calendar's slot even when it is empty, and an assigned slot does
+     * not show its fallback, so the calendar's own caret went missing whenever
+     * the field had no icon. With no `slot` attribute the forwarding slot is
+     * assigned nowhere, as the calendar has no default slot, and it still hears
+     * an icon arrive or leave.
+     */
+    private renderIconSlot;
+    private readonly handleIconChange;
     /**
      * One chosen date, as a tag, behind a seam the styled tier can move.
      *

package/dist/date-input/root/date-input-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 { AriaForwardController, valueAsDate as asDate, customElement, fillTemplate, dateAsValue as fromDate, HelixFormElement, isDateValue, MixinControllerOpen, MixinControllerValue, MixinField, MixinPickerEditing, MixinPickerField, MixinTokens, } from '@fusion.dev/helix-core';
+import { AriaForwardController, valueAsDate as asDate, customElement, fillTemplate, dateAsValue as fromDate, HelixFormElement, isDateValue, MixinControllerOpen, MixinControllerValue, MixinField, MixinPickerEditing, MixinPickerField, MixinTokens, writtenList, } from '@fusion.dev/helix-core';
 import { calendarBlank } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -24,19 +24,23 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
             target: () => this.partNamed('control'),
         });
         this.autocomplete = '';
+        this.calendarLabel = 'Date Picker';
+        this.announcesInput = true;
         this.dateStyle = 'long';
         this.disableDates = '';
         this.disableDays = '';
-        this.firstDayOfWeek = 0;
         this.locale = '';
         this.max = '';
         this.min = '';
         this.months = 1;
         this.fitted = undefined;
         this.wide = undefined;
+        this.nextLabel = 'Next month';
         this.placeholder = 'YYYY-MM-DD';
+        this.previousLabel = 'Previous month';
         this.removeLabel = 'Remove {name}';
         this.step = 1;
+        this.triggerLabel = 'Choose a date';
         this.draft = '';
         this.handleInput = (event) => {
             event.stopPropagation();
@@ -59,30 +63,36 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
             if (event.key === 'Enter' && isDateValue(this.draft)) {
                 event.preventDefault();
                 if (!held.includes(this.draft)) {
-                    this.requestValue([...held, this.draft].join(','));
+                    this.requestPicked([...held, this.draft].join(','));
                 }
                 this.draft = '';
             }
             else if (event.key === 'Backspace' && this.draft === '' && held.length > 0) {
-                this.requestValue(held.slice(0, -1).join(','));
+                this.requestPicked(held.slice(0, -1).join(','));
             }
         };
         this.removeDate = (date) => {
-            this.requestValue(dates(this.value)
+            this.requestPicked(dates(this.value)
                 .filter((one) => one !== date)
                 .join(','));
         };
         this.handleCalendarChange = (event) => {
             event.stopPropagation();
             const { value } = event.detail;
-            this.requestValue(value);
+            if (!this.requestPicked(value)) {
+                event.preventDefault();
+                this.restore();
+                return;
+            }
             this.restore();
             if (this.mode === undefined) {
                 this.requestOpen(false);
                 this.updateComplete.then(() => this.returnFocus());
             }
         };
-        this.triggerLabel = 'Choose a date';
+        this.handleIconChange = () => {
+            this.requestUpdate();
+        };
     }
     placed(room) {
         const all = Math.max(1, Math.floor(this.months) || 1);
@@ -160,17 +170,27 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
                 max: this.written(this.max),
             });
         }
+        const days = writtenList(this.disableDays);
+        const listed = writtenList(this.disableDates);
+        if (held.some((one) => listed.includes(one) || days.includes(String(asDate(one)?.getUTCDay() ?? '')))) {
+            return this.unavailableMessage || 'Choose a date that is available.';
+        }
+        const step = Math.max(1, Math.floor(this.step) || 1);
+        if (step > 1) {
+            const base = asDate(this.min)?.getTime() ?? 0;
+            const off = held.some((one) => {
+                const at = asDate(one)?.getTime();
+                return at !== undefined && Math.round((at - base) / 86_400_000) % step !== 0;
+            });
+            if (off) {
+                return this.stepMismatchMessage || 'Choose one of the dates the calendar offers.';
+            }
+        }
         if (this.mode === 'range' && held.length > 2) {
             return this.rangeLengthMessage || 'A range is two dates.';
         }
         return '';
     }
-    updated(changed) {
-        super.updated(changed);
-        if (this.open && changed.has('open')) {
-            this.partNamed('picker')?.focus();
-        }
-    }
     renderPicker() {
         return html `<${this.tag('date-picker')}
       part="picker"
@@ -188,15 +208,29 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
       .value=${this.picked}
       disable-dates=${this.disableDates || nothing}
       disable-days=${this.disableDays || nothing}
-      first-day-of-week=${this.firstDayOfWeek}
+      first-day-of-week=${this.firstDayOfWeek ?? nothing}
+      label=${this.calendarLabel}
       locale=${this.locale || nothing}
       max=${this.max || nothing}
       min=${this.min || nothing}
+      next-label=${this.nextLabel}
+      previous-label=${this.previousLabel}
       step=${this.step}
       @helix-before-change=${this.handleCalendarChange}
       @change=${this.stopInner}
       @input=${this.stopInner}
-    ></${this.tag('date-picker')}>`;
+    >
+      ${this.renderIconSlot('previous-icon')}
+      ${this.renderIconSlot('next-icon')}
+    </${this.tag('date-picker')}>`;
+    }
+    renderIconSlot(name) {
+        const given = this.querySelector?.(`:scope > [slot="${name}"]`) != null;
+        return html `<slot
+      name=${name}
+      slot=${given ? name : nothing}
+      @slotchange=${this.handleIconChange}
+    ></slot>`;
     }
     renderTag(date) {
         return html `<${this.tag('tag')}
@@ -240,19 +274,22 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
           ?readonly=${this.readOnly}
           ?required=${this.required}
           @blur=${this.handleBlur}
+          @change=${this.handleCommit}
           @focus=${this.handleFocus}
           @input=${this.handleInput}
           @keydown=${this.handleDraftKey}
+          @keypress=${this.handleKeypress}
         />
         <button
           part="trigger"
           type="button"
           aria-controls="surface"
+          aria-disabled=${this.readOnly ? 'true' : nothing}
           aria-expanded=${this.open ? 'true' : 'false'}
           aria-haspopup="dialog"
           aria-label=${this.triggerLabel}
           ?disabled=${this.isDisabled}
-          @click=${() => this.toggleOpen()}
+          @click=${this.handleTriggerClick}
         >
           ${this.renderTrigger()}
         </button>
@@ -287,6 +324,9 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
 __decorate([
     property()
 ], HelixHeadlessDateInput.prototype, "autocomplete", void 0);
+__decorate([
+    property({ attribute: 'calendar-label' })
+], HelixHeadlessDateInput.prototype, "calendarLabel", void 0);
 __decorate([
     property({ attribute: 'date-style' })
 ], HelixHeadlessDateInput.prototype, "dateStyle", void 0);
@@ -317,9 +357,15 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessDateInput.prototype, "fitted", void 0);
+__decorate([
+    property({ attribute: 'next-label' })
+], HelixHeadlessDateInput.prototype, "nextLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessDateInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'previous-label' })
+], HelixHeadlessDateInput.prototype, "previousLabel", void 0);
 __decorate([
     property({ attribute: 'range-length-message' })
 ], HelixHeadlessDateInput.prototype, "rangeLengthMessage", void 0);
@@ -336,11 +382,17 @@ __decorate([
     property({ type: Number })
 ], HelixHeadlessDateInput.prototype, "step", void 0);
 __decorate([
-    state()
-], HelixHeadlessDateInput.prototype, "draft", void 0);
+    property({ attribute: 'step-mismatch-message' })
+], HelixHeadlessDateInput.prototype, "stepMismatchMessage", void 0);
 __decorate([
     property({ attribute: 'trigger-label' })
 ], HelixHeadlessDateInput.prototype, "triggerLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessDateInput.prototype, "draft", void 0);
+__decorate([
+    property({ attribute: 'unavailable-message' })
+], HelixHeadlessDateInput.prototype, "unavailableMessage", void 0);
 HelixHeadlessDateInput = __decorate([
     customElement('helix-headless-date-input')
 ], HelixHeadlessDateInput);

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

@@ -23,6 +23,12 @@ 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`.
  *
+ * 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
@@ -74,17 +80,22 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     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.
      */
@@ -141,19 +152,10 @@ 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.
+     * The validation message for a date after `max`. `{max}` is replaced with
+     * `max`, written as a date in `locale`.
      */
-    readOnly: boolean;
+    rangeOverflowMessage?: string;
     /**
      * The date the grid's tab stop is on.
      *
@@ -162,6 +164,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 +213,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 +238,42 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     private select;
     private readonly handleKeydown;
+    /**
+     * 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 +288,30 @@ 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;
+    /** 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.
      *