mtrl 0.10.0-next.2 → 0.10.0

package/dist/components/card/features.d.ts

@@ -52,27 +52,13 @@ export declare const withLoading: (config?: LoadingConfig) => (component: BaseCo
     loading: LoadingFeature;
 };
 /**
- * Higher-order function to add elevation to a card based on its variant.
+ * Did nothing visible: it wrote a `--{prefix}-card-elevation` custom property
+ * that no stylesheet reads. A card's elevation comes from its variant and
+ * state classes in the stylesheet.
  *
- * Sets the initial elevation CSS variable according to Material Design 3 guidelines:
- * - Elevated variant: 1dp elevation
- * - Filled and outlined variants: 0dp elevation
- *
- * These elevation values affect shadows and surface appearance of the card
- * to create appropriate visual hierarchy.
- *
- * @param {BaseComponent} component - Card component
- * @returns {BaseComponent} Card component with elevation applied
+ * @deprecated Since 0.10 (FLO-323): a no-op, removed in 1.0. Drop it from
+ * the composition.
  * @category Components
- * @example
- * ```typescript
- * // Apply elevation in the composition chain
- * const card = pipe(
- *   createBase,
- *   withElement(config),
- *   withElevation
- * )(baseConfig);
- * ```
  */
 export declare const withElevation: <C extends ElementComponent>(component: C) => C;
 /**

package/dist/components/card/features.js

@@ -6,7 +6,6 @@ const HIDDEN_ACTION_STYLE = {
     visibility: "hidden",
 };
 import { createElement } from "../../core/dom/create.js";
-import { CARD_ELEVATION_LEVELS } from "./config.js";
 export const withLoading = (config = {}) => (component) => {
     const initialState = config.initialState || false;
     let loadingElement = null;
@@ -50,16 +49,7 @@ export const withLoading = (config = {}) => (component) => {
         },
     };
 };
-export const withElevation = (component) => {
-    const config = component.config;
-    if (config.variant === "elevated") {
-        component.element.style.setProperty(`--${config.prefix}-card-elevation`, String(CARD_ELEVATION_LEVELS.LEVEL1));
-    }
-    else {
-        component.element.style.setProperty(`--${config.prefix}-card-elevation`, String(CARD_ELEVATION_LEVELS.LEVEL0));
-    }
-    return component;
-};
+export const withElevation = (component) => component;
 export const withExpandable = (config = {}) => (component) => {
     const initialExpanded = config.initialExpanded || false;
     let isExpanded = initialExpanded;

package/dist/components/card/index.d.ts

@@ -65,7 +65,7 @@ export { default } from "./card.js";
  *
  * These types define the structure and behavior of the Card component.
  */
-export type { CardVariant, CardElevationLevel, CardSchema, CardHeaderConfig, CardContentConfig, CardActionsConfig, CardMediaConfig, CardAriaAttributes, CardComponent, LoadingFeature, ExpandableFeature, SwipeableFeature, } from "./types.js";
+export type { CardVariant, CardElevationLevel, CardSchema, CardHeaderConfig, CardContentConfig, CardActionsConfig, CardMediaConfig, CardAriaAttributes, CardComponent, CardEvents, LoadingFeature, ExpandableFeature, SwipeableFeature, } from "./types.js";
 export { createCardContent, createCardHeader, createCardActions, createCardMedia, } from "./content.js";
 export { withAPI } from "./api.js";
 export { withLoading, withExpandable, withSwipeable, withElevation, } from "./features.js";

package/dist/components/card/types.d.ts

@@ -1,4 +1,5 @@
 import type { ButtonConfig as BaseButtonConfig } from "../button/types.js";
+import type { ForwardedEventPayload } from "../../core/dom/index.js";
 /**
  * Card variant types following Material Design 3 guidelines.
  * - elevated: Card with shadow elevation (default)
@@ -58,11 +59,18 @@ export interface ButtonConfig extends Omit<BaseButtonConfig, "variant"> {
 export interface CardSchema {
     /** Card variant type (elevated, filled, outlined) */
     variant?: CardVariant | string;
-    /** Whether the card is interactive */
+    /**
+     * The hover and press states and their elevation, for a card the app
+     * makes interactive itself. Not a control: no role of button and no tab
+     * stop; `clickable` is (FLO-109).
+     */
     interactive?: boolean;
     /** Whether the card should take full width */
     fullWidth?: boolean;
-    /** Whether the card is clickable (with ripple effect) */
+    /**
+     * A card that acts on activation: a button (role, tab stop, Enter and
+     * Space click it) with the ripple (FLO-109)
+     */
     clickable?: boolean;
     /** Whether the card is draggable */
     draggable?: boolean;
@@ -109,7 +117,7 @@ export interface CardAriaAttributes {
     labelledby?: string;
     /** ARIA describedby */
     describedby?: string;
-    /** ARIA role (default is 'region' for non-interactive, 'button' for interactive) */
+    /** ARIA role (default: 'button' for a clickable card, 'article' for any other) */
     role?: string;
     /** Additional ARIA attributes as key-value pairs */
     [key: string]: string | undefined;
@@ -277,6 +285,25 @@ export interface CardComponentConfig extends CardSchema {
     /** CSS class prefix */
     prefix: string;
 }
+/**
+ * The card's events (FLO-323). A clickable card forwards `click`; an
+ * interactive one `mouseenter`, `mouseleave`, `keydown`, `focus` and `blur`;
+ * a draggable one emits `dragstart` and `dragend`.
+ */
+export interface CardEvents {
+    click: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
+    mouseenter: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
+    mouseleave: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
+    keydown: (payload: ForwardedEventPayload<KeyboardEvent, HTMLElement>) => void;
+    focus: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
+    blur: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
+    dragstart: (payload: {
+        event: DragEvent;
+    }) => void;
+    dragend: (payload: {
+        event: DragEvent;
+    }) => void;
+}
 /**
  * Card component interface with methods.
  * This is the public API of the card component that users interact with.
@@ -286,6 +313,10 @@ export interface CardComponentConfig extends CardSchema {
  * @category Components
  */
 export interface CardComponent extends BaseComponent {
+    /** Subscribes to one of the card's events (FLO-323) */
+    on: <K extends keyof CardEvents>(event: K, handler: CardEvents[K]) => CardComponent;
+    /** Removes a handler added with `on` */
+    off: <K extends keyof CardEvents>(event: K, handler: CardEvents[K]) => CardComponent;
     /**
      * Adds content to the card.
      * This method appends content to the card component.

package/dist/components/carousel/features/scroll.js

@@ -1,5 +1,6 @@
 import { CAROUSEL_DEFAULTS, CAROUSEL_EVENTS, CAROUSEL_VARIANTS } from "../constants.js";
 import { resolveLayoutDefaults } from "../config.js";
+import { cornerToken } from "../../../core/theme/shape.js";
 import { multiBrowseKeylines, heroKeylines, uncontainedKeylines, fullScreenKeylines, } from "../keylines.js";
 import { createStrategy, keylinesForScrollOffset, snapPositionOffset, maxScrollOffset, placeItem, } from "../strategy.js";
 const FLING_VELOCITY = 0.4;
@@ -14,6 +15,9 @@ export const withScroll = (config) => (component) => {
         mediumLargeThreshold: CAROUSEL_DEFAULTS.MEDIUM_LARGE_THRESHOLD,
     };
     const cornerRadius = config.cornerRadius ?? CAROUSEL_DEFAULTS.CORNER_RADIUS;
+    const corner = cornerRadius === CAROUSEL_DEFAULTS.CORNER_RADIUS
+        ? cornerToken("extra-large", cornerRadius, config.prefix)
+        : `${cornerRadius}px`;
     const reduceMotion = typeof window !== "undefined" && typeof window.matchMedia === "function"
         ? window.matchMedia("(prefers-reduced-motion: reduce)")
         : null;
@@ -121,7 +125,7 @@ export const withScroll = (config) => (component) => {
             el.style[vertical ? "height" : "width"] = `${strategy.itemSize}px`;
             el.style[vertical ? "width" : "height"] = "";
         });
-        element.style.setProperty(`--${config.prefix}-carousel-corner`, `${cornerRadius}px`);
+        element.style.setProperty(`--${config.prefix}-carousel-corner`, corner);
     };
     const layout = () => {
         if (!strategy)
@@ -152,8 +156,8 @@ export const withScroll = (config) => (component) => {
             el.style.visibility = "";
             el.style.transform = vertical ? `translate3d(0, ${start}px, 0)` : `translate3d(${start}px, 0, 0)`;
             el.style.clipPath = vertical
-                ? `inset(${inset}px 0 round ${cornerRadius}px)`
-                : `inset(0 ${inset}px round ${cornerRadius}px)`;
+                ? `inset(${inset}px 0 round ${corner})`
+                : `inset(0 ${inset}px round ${corner})`;
             el.style.setProperty(`--${config.prefix}-carousel-fade`, fade.toFixed(3));
         }
         if (pending !== null) {

package/dist/components/checkbox/config.js

@@ -1,5 +1,4 @@
 import { createComponentConfig, createElementConfig, } from "../../core/config/component.js";
-import { setHTML } from "../../core/dom/html.js";
 export const defaultConfig = {
     labelPosition: "end",
     enterToggles: false,
@@ -10,14 +9,27 @@ export const getElementConfig = (config) => createElementConfig(config, {
     className: config.class,
     interactive: true,
 });
+const SVG = "http://www.w3.org/2000/svg";
+let checkIcon = null;
+const createCheckIcon = () => {
+    if (!checkIcon) {
+        checkIcon = document.createDocumentFragment();
+        const svg = document.createElementNS(SVG, "svg");
+        svg.setAttributeNS("http://www.w3.org/2000/xmlns/", "xmlns", SVG);
+        for (const [name, value] of [["viewBox", "0 0 24 24"], ["width", "20"], ["height", "20"], ["fill", "currentColor"]]) {
+            svg.setAttribute(name, value);
+        }
+        const path = document.createElementNS(SVG, "path");
+        path.setAttribute("d", "M9.55 14.6L6.35 11.4l-1.9 1.9L9.55 18.4l10.9-10.9-1.9-1.9z");
+        svg.append("\n      ", path, "\n    ");
+        checkIcon.append("\n    ", svg, "\n  ");
+    }
+    return checkIcon.cloneNode(true);
+};
 export const withCheckIcon = (config) => (component) => {
     const icon = document.createElement("span");
     icon.className = `${config.prefix}-checkbox__icon`;
-    setHTML(icon, `
-    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" fill="currentColor">
-      <path d="M9.55 14.6L6.35 11.4l-1.9 1.9L9.55 18.4l10.9-10.9-1.9-1.9z"/>
-    </svg>
-  `);
+    icon.appendChild(createCheckIcon());
     component.element.appendChild(icon);
     return component;
 };

package/dist/components/chips/api.js

@@ -68,7 +68,7 @@ export const withAPI = (options) => (component) => {
             }
             return this;
         },
-        selectByValue(values, triggerEvent = true) {
+        selectByValue(values, triggerEvent = false) {
             if (options.chips &&
                 typeof options.chips.selectByValue === "function") {
                 options.chips.selectByValue(values, triggerEvent);

package/dist/components/chips/config.js

@@ -53,7 +53,7 @@ export const getApiConfig = (comp, config) => ({
         getChips: () => comp.chips?.getChips?.() ?? [],
         getSelectedChips: () => comp.chips?.getSelectedChips?.() ?? [],
         getSelectedValues: () => comp.chips?.getSelectedValues?.() ?? [],
-        selectByValue: (values) => comp.chips?.selectByValue?.(values),
+        selectByValue: (values, triggerEvent) => comp.chips?.selectByValue?.(values, triggerEvent),
         clearSelection: () => comp.chips?.clearSelection?.(),
         scrollToChip: (chipOrIndex) => comp.chips?.scrollToChip?.(chipOrIndex),
     },

package/dist/components/chips/features/controller.js

@@ -1,6 +1,7 @@
 import { getCleanup } from "../../../core/compose/cleanup.js";
 import createChip from "../chip/chip.js";
 import { CHIPS_EVENTS } from "../constants.js";
+import { activeElementOf } from "../../../core/dom/focus.js";
 export const withController = (config) => (component) => {
     const eventListeners = {
         change: [],
@@ -13,6 +14,11 @@ export const withController = (config) => (component) => {
             eventListeners[eventName].forEach((handler) => handler(...args));
         }
     };
+    const changeEvent = (values, changed) => {
+        const set = values.filter((value) => value !== null);
+        const value = config.multiSelect ? set : (set[0] ?? null);
+        return Object.assign([...values], { value, selected: values, changed });
+    };
     const handleSelection = (selectedChip) => {
         if (!config.multiSelect) {
             component.chipInstances.forEach((chip) => {
@@ -27,10 +33,11 @@ export const withController = (config) => (component) => {
         const selectedChips = component.chipInstances.filter((chip) => chip.isSelected());
         const selectedValues = selectedChips.map((chip) => chip.getValue());
         const changedValue = selectedChip ? selectedChip.getValue() : null;
+        const event = changeEvent(selectedValues, changedValue);
         if (typeof config.onChange === "function") {
-            config.onChange(selectedValues, changedValue);
+            config.onChange(event, changedValue);
         }
-        dispatchEvent(CHIPS_EVENTS.CHANGE, selectedValues, changedValue);
+        dispatchEvent(CHIPS_EVENTS.CHANGE, event, changedValue);
     };
     const targets = () => component.chipInstances
         .filter((chip) => !chip.isDisabled())
@@ -157,7 +164,7 @@ export const withController = (config) => (component) => {
             : component.chipInstances.indexOf(chipOrIndex);
         if (index >= 0 && index < component.chipInstances.length) {
             const chip = component.chipInstances[index];
-            const hadFocus = chip.element.contains(document.activeElement);
+            const hadFocus = chip.element.contains(activeElementOf(chip.element));
             dispatchEvent(CHIPS_EVENTS.REMOVE, chip);
             chip.element.removeEventListener("keydown", handleKeyboardNavigation);
             chip.destroy();
@@ -192,7 +199,7 @@ export const withController = (config) => (component) => {
     const getSelectedValues = () => {
         return getSelectedChips().map((chip) => chip.getValue());
     };
-    const selectByValue = (values, triggerEvent = true, exclusive = !config.multiSelect) => {
+    const selectByValue = (values, triggerEvent = false, exclusive = !config.multiSelect) => {
         const valueArray = Array.isArray(values) ? values : [values];
         let selectionChanged = false;
         if (exclusive) {
@@ -215,17 +222,17 @@ export const withController = (config) => (component) => {
         });
         if (selectionChanged && triggerEvent) {
             const selectedValues = getSelectedValues();
-            dispatchEvent(CHIPS_EVENTS.CHANGE, selectedValues, null);
+            dispatchEvent(CHIPS_EVENTS.CHANGE, changeEvent(selectedValues, null), null);
         }
     };
-    const clearSelection = (triggerEvent = true) => {
+    const clearSelection = (triggerEvent = false) => {
         const selectedValues = getSelectedValues();
         const hadSelectedChips = selectedValues.length > 0;
         component.chipInstances.forEach((chip) => {
             chip.setSelected(false);
         });
         if (hadSelectedChips && triggerEvent) {
-            dispatchEvent(CHIPS_EVENTS.CHANGE, [], null);
+            dispatchEvent(CHIPS_EVENTS.CHANGE, changeEvent([], null), null);
         }
     };
     const enableKeyboardNavigation = () => {

package/dist/components/chips/index.d.ts

@@ -1,3 +1,3 @@
 export { createAssistChip, createFilterChip, createInputChip, createSuggestionChip } from "./factories.js";
 export { default as createChips } from "./chips.js";
-export type { ChipConfig, ChipComponent, ChipType, ChipEvents, ChipChangePayload, AssistChipConfig, FilterChipConfig, InputChipConfig, SuggestionChipConfig, ChipsConfig, ChipsComponent, ChipsEvents, } from "./types.js";
+export type { ChipConfig, ChipComponent, ChipType, ChipEvents, ChipChangePayload, AssistChipConfig, FilterChipConfig, InputChipConfig, SuggestionChipConfig, ChipsConfig, ChipsComponent, ChipsEvents, ChipsChangeEvent, } from "./types.js";

package/dist/components/chips/types.d.ts

@@ -150,7 +150,7 @@ export interface ChipsConfig {
     /**
      * Callback function when chip selection changes
      */
-    onChange?: (selectedValues: (string | null)[], changedValue: string | null) => void;
+    onChange?: (event: ChipsChangeEvent, changedValue: string | null) => void;
     /**
      * Component prefix for class names
      * @default 'mtrl'
@@ -219,10 +219,29 @@ export interface ChipsFeatureComponent {
  * @internal
  */
 export type ChipsEventListeners = Record<string, EventCallback[]>;
+/**
+ * The payload of the chips set's `change`.
+ *
+ * It is still the array of selected values, with the fields added, and the
+ * changed value still comes as a second argument, so a
+ * `(selectedValues, changedValue)` handler keeps working. Both are
+ * deprecated: read `selected` and `changed`. They go in the next prerelease.
+ */
+export interface ChipsChangeEvent extends Array<string | null> {
+    /** The selection in the `value` property's shape: a string or null for a single-select set, an array for a multi-select one. */
+    value: string | string[] | null;
+    /** The values of the selected chips, in chip order (a chip without a value gives null) */
+    selected: (string | null)[];
+    /** The value of the chip the user toggled; null for a change made by a method */
+    changed: string | null;
+}
 /** Events emitted by the chips container's controller. */
 export interface ChipsEvents {
-    /** Selection values and the changed chip value (null for programmatic changes). */
-    change: (selectedValues: (string | null)[], changedValue: string | null) => void;
+    /**
+     * The selection after the change. Read `event.value`, the same field the
+     * `<m-chips>` element's `change` carries.
+     */
+    change: (event: ChipsChangeEvent, changedValue: string | null) => void;
     /** The newly created chip, after it is inserted into the container. */
     add: (chip: ChipComponent) => void;
     /** The chip being removed, before it is destroyed. */
@@ -272,12 +291,12 @@ export interface ChipsComponent {
     /**
      * Selects chips by their values
      * @param values - Value or array of values to select
-     * @param triggerEvent - Whether to trigger change event (default: true)
+     * @param triggerEvent - Emits `change` when true; silent by default (FLO-328)
      * @returns The chips instance for chaining
      */
     selectByValue: (values: string | string[], triggerEvent?: boolean) => ChipsComponent;
     /**
-     * Clears all selections
+     * Clears all selections. Silent: only the user's change emits `change`
      * @returns The chips instance for chaining
      */
     clearSelection: () => ChipsComponent;

package/dist/components/datepicker/datepicker.d.ts

@@ -1,4 +1,10 @@
-import type { DatePickerComponent, DatePickerConfig } from "./types.js";
+import type { DatePickerComponent, DatePickerConfig, DatePickerValueOf } from "./types.js";
 /** M3 calendar/input modes share a draft; modal acceptance is the commit boundary. */
-declare const createDatePicker: (config?: DatePickerConfig) => DatePickerComponent;
+/**
+ * The value's type follows a literal selectionMode (FLO-295): `'range'` makes
+ * it a pair, the default a date.
+ */
+declare const createDatePicker: <M extends string = "single">(config?: DatePickerConfig & {
+    selectionMode?: M;
+}) => DatePickerComponent<DatePickerValueOf<M>>;
 export default createDatePicker;

package/dist/components/datepicker/datepicker.js

@@ -3,12 +3,14 @@ import { createBase, withElement } from "../../core/compose/component.js";
 import { withEvents, withDisabled, withLifecycle } from "../../core/compose/features/index.js";
 import { createElement } from "../../core/dom/create.js";
 import { setHTML } from "../../core/dom/html.js";
+import { activeElementOf, deepActiveElement } from "../../core/dom/focus.js";
 import { DATEPICKER_ICONS } from "./constants.js";
 import { PREFIX } from "../../core/config.js";
 import { createBaseConfig, getContainerConfig } from "./config.js";
 import { withAPI } from "./api.js";
 import { renderCalendar } from "./render.js";
-import { addDays, addMonths, formatDate, isSameDay, parseDate, parseInputDate } from "./utils.js";
+import { addDays, addMonths, formatDate, isSameDay, parseDate, parseInputDate, toIsoValue } from "./utils.js";
+const isRangeObject = (value) => typeof value === "object" && value !== null && !(value instanceof Date) && !Array.isArray(value);
 let nextId = 0;
 const scrollLocks = new WeakMap();
 function lockScroll(doc) {
@@ -42,7 +44,7 @@ const createDatePicker = (config = {}) => {
         isAllowed: date => (!state.minDate || date >= state.minDate) && (!state.maxDate || date <= state.maxDate) && !state.specialDates.some(item => { const special = parseDate(item.date); return item.disabled && special && isSameDay(date, special); }),
     };
     const modal = state.variant !== "docked";
-    let opened = false, destroyed = false, navigationRequested = false;
+    let opened = false, destroyed = false, navigationRequested = false, readOnly = false;
     let committed = null, committedEnd = null;
     let returnFocus = null;
     let unlock;
@@ -67,7 +69,7 @@ const createDatePicker = (config = {}) => {
     trigger.setAttribute("aria-haspopup", "dialog");
     trigger.setAttribute("aria-controls", `${id}-dialog`);
     trigger.setAttribute("aria-expanded", "false");
-    const help = createElement({ tag: "div", className: cls("help"), text: state.dateFormat, attributes: { id: `${id}-help` } });
+    const help = createElement({ tag: "div", className: cls("help"), text: settings.supportingText || state.dateFormat, attributes: { id: `${id}-help` } });
     const error = createElement({ tag: "div", className: cls("error"), attributes: { id: `${id}-error`, "aria-live": "polite" } });
     const dialog = doc.createElement("dialog");
     dialog.id = `${id}-dialog`;
@@ -144,7 +146,8 @@ const createDatePicker = (config = {}) => {
         }
         else
             return;
-        const active = doc.activeElement instanceof HTMLElement ? doc.activeElement.dataset.date : undefined;
+        const focused = activeElementOf(dialog);
+        const active = focused instanceof HTMLElement ? focused.dataset.date : undefined;
         render();
         if (active)
             dialog.querySelector(`[data-date="${active}"]`)?.focus({ preventScroll: true });
@@ -173,15 +176,15 @@ const createDatePicker = (config = {}) => {
         else if (focus)
             focusCurrent();
     };
-    const emitChange = () => base.emit("change", { value: getValue(), formattedValue: formatted(committed, committedEnd) });
-    const commitDraft = (calendar = false) => {
+    const emitChange = () => {
+        const rangeEndDate = committedEnd && new Date(committedEnd);
+        base.emit("change", { value: getValue(), rangeEndDate, formattedValue: formatted(committed, committedEnd), iso: toIsoValue(getValue(), rangeEndDate) });
+    };
+    const commitDraft = () => {
         committed = state.selectedDate && new Date(state.selectedDate);
         committedEnd = state.rangeEndDate && new Date(state.rangeEndDate);
         syncInput();
-        if (calendar && committed)
-            base.emit("change", { value: new Date(committed), rangeEndDate: committedEnd && new Date(committedEnd), formattedValue: formatted(committed, committedEnd) });
-        else
-            emitChange();
+        emitChange();
     };
     const close = (restoreFocus = true) => {
         if (!opened)
@@ -201,7 +204,7 @@ const createDatePicker = (config = {}) => {
             base.emit("close", { value: getValue() });
     };
     const open = () => {
-        if (destroyed || opened || base.disabled.isDisabled())
+        if (destroyed || opened || base.disabled.isDisabled() || readOnly)
             return;
         opened = true;
         resetDraft();
@@ -215,7 +218,8 @@ const createDatePicker = (config = {}) => {
         if (!navigationRequested)
             setDisplayDate(initial);
         navigationRequested = false;
-        returnFocus = doc.activeElement instanceof HTMLElement && doc.activeElement !== doc.body ? doc.activeElement : trigger;
+        const opener = deepActiveElement();
+        returnFocus = opener instanceof HTMLElement && opener !== doc.body ? opener : trigger;
         render();
         if (modal && typeof dialog.showModal === "function" && dialog.isConnected)
             dialog.showModal();
@@ -231,7 +235,9 @@ const createDatePicker = (config = {}) => {
         focusCurrent();
         base.emit("open", { value: getValue() });
     };
-    const assignValue = (value, emit) => {
+    const assignValue = (input, emit) => {
+        const given = isRangeObject(input) ? [input.start, input.end] : input;
+        const value = state.selectionMode === "range" && !Array.isArray(given) ? [given, given] : given;
         if (destroyed || Array.isArray(value) && state.selectionMode !== "range")
             return;
         const start = parseDate(Array.isArray(value) ? value[0] : value);
@@ -247,6 +253,17 @@ const createDatePicker = (config = {}) => {
         if (emit)
             emitChange();
     };
+    const clearValue = (emit) => {
+        if (destroyed)
+            return;
+        committed = null;
+        committedEnd = null;
+        resetDraft();
+        syncInput();
+        render();
+        if (emit)
+            emitChange();
+    };
     const validateEntries = () => {
         const fields = Array.from(dialog.querySelectorAll('[data-entry]'));
         if (!fields.length)
@@ -282,7 +299,7 @@ const createDatePicker = (config = {}) => {
         if (modal || destroyed || base.disabled.isDisabled())
             return;
         if (!input.value.trim()) {
-            api.clear();
+            clearValue(true);
             return;
         }
         const pieces = state.selectionMode === "range" ? input.value.split(' - ') : [input.value];
@@ -306,8 +323,9 @@ const createDatePicker = (config = {}) => {
             state.rangeEndDate = null;
         }
         setDisplayDate(date);
-        if (!modal || settings.closeOnSelect && (state.selectionMode !== "range" || state.rangeEndDate))
-            commitDraft(true);
+        const whole = state.selectionMode !== "range" || !!state.rangeEndDate;
+        if ((!modal || settings.closeOnSelect) && whole)
+            commitDraft();
         if (settings.closeOnSelect && (state.selectionMode !== "range" || state.rangeEndDate))
             close();
         else
@@ -407,11 +425,12 @@ const createDatePicker = (config = {}) => {
         if (event.key === "Tab" && modal) {
             const elements = Array.from(dialog.querySelectorAll('button:not(:disabled):not([tabindex="-1"]), input:not(:disabled)'));
             const first = elements[0], last = elements.at(-1);
-            if (event.shiftKey && doc.activeElement === first) {
+            const focused = activeElementOf(dialog);
+            if (event.shiftKey && focused === first) {
                 event.preventDefault();
                 last?.focus();
             }
-            else if (!event.shiftKey && doc.activeElement === last) {
+            else if (!event.shiftKey && focused === last) {
                 event.preventDefault();
                 first?.focus();
             }
@@ -485,7 +504,8 @@ const createDatePicker = (config = {}) => {
         const page = Math.round(Math.abs(element.scrollLeft) / element.clientWidth) - 1;
         if (!page)
             return;
-        const active = doc.activeElement instanceof HTMLElement && dialog.contains(doc.activeElement) ? doc.activeElement : null;
+        const focused = activeElementOf(dialog);
+        const active = focused instanceof HTMLElement && dialog.contains(focused) ? focused : null;
         navigate(page);
         render(!!active?.dataset.date, active?.dataset.action);
     };
@@ -548,7 +568,26 @@ const createDatePicker = (config = {}) => {
         else
             base.disabled.enable();
         input.disabled = disabled;
-        trigger.disabled = disabled;
+        trigger.disabled = disabled || readOnly;
+    };
+    const setReadOnly = (value) => {
+        if (destroyed)
+            return;
+        readOnly = value;
+        if (value)
+            close();
+        input.readOnly = value || modal;
+        trigger.disabled = value || base.disabled.isDisabled();
+        base.element.classList.toggle(base.getClass("datepicker--readonly"), value);
+    };
+    const checkValidity = () => !(input.required && !committed);
+    const reportValidity = () => {
+        const valid = checkValidity();
+        if (!valid) {
+            input.setAttribute("aria-invalid", "true");
+            error.textContent = `Select a ${state.selectionMode === "range" ? "date range" : "date"}.`;
+        }
+        return valid;
     };
     const destroy = () => {
         if (destroyed)
@@ -575,18 +614,16 @@ const createDatePicker = (config = {}) => {
         disabled: { enable: () => setDisabled(false), disable: () => setDisabled(true), isDisabled: () => base.disabled.isDisabled() }, lifecycle: { destroy }, destroy,
         open() { open(); return api; }, close() { close(); return api; }, getValue,
         getFormattedValue: () => formatted(committed, committedEnd),
-        setValue(value) { assignValue(value, true); return api; },
-        clear() {
-            if (!destroyed) {
-                committed = null;
-                committedEnd = null;
-                resetDraft();
+        setValue(value) { assignValue(value, false); return api; },
+        setReadOnly(value) { setReadOnly(value); return api; }, isReadOnly: () => readOnly,
+        setRequired(value) {
+            input.required = value;
+            if (!value)
                 syncInput();
-                render();
-                emitChange();
-            }
             return api;
-        },
+        }, checkValidity, reportValidity,
+        setSupportingText(text) { help.textContent = text || state.dateFormat; return api; },
+        clear() { clearValue(false); return api; },
         enable() { setDisabled(false); return api; }, disable() { setDisabled(true); return api; },
         setMinDate(value) {
             const date = parseDate(value);
@@ -632,6 +669,10 @@ const createDatePicker = (config = {}) => {
         syncInput();
     dialog.append(renderCalendar(state), announcement);
     setDisabled(!!settings.disabled);
+    if (settings.required)
+        input.required = true;
+    if (settings.readOnly)
+        setReadOnly(true);
     return api;
 };
 export default createDatePicker;

package/dist/components/datepicker/index.d.ts

@@ -1,3 +1,3 @@
 export { default } from "./datepicker.js";
-export type { DatePickerConfig, DatePickerComponent, DatePickerEvents, DatePickerValue, DatePickerChangePayload, DatePickerVisibilityPayload, DatePickerTapPayload, DatePickerSwipePayload, DatePickerVariant, DatePickerView, DatePickerSelectionMode, } from "./types.js";
+export type { DatePickerConfig, DatePickerComponent, DatePickerEvents, DatePickerValue, DatePickerValueOf, DatePickerInput, DatePickerChangePayload, DatePickerVisibilityPayload, DatePickerTapPayload, DatePickerSwipePayload, DatePickerVariant, DatePickerView, DatePickerSelectionMode, } from "./types.js";
 export { DEFAULT_DATE_FORMAT } from "./types.js";