igniteui-webcomponents 7.2.4 → 7.3.0-beta.1

package/internals/controllers/roving-focus.d.ts

@@ -0,0 +1,72 @@
+import type { ReactiveControllerHost } from 'lit';
+import { type KeyBindingControllerOptions, type KeyBindingOptions } from './key-bindings.js';
+type RovingFocusHost = ReactiveControllerHost & HTMLElement;
+/**
+ * Whether an arrow axis navigates. A predicate keeps the keys bound - and
+ * their default behavior suppressed - while gating the navigation itself,
+ * for hosts that switch orientation at runtime.
+ */
+type RovingFocusAxis = boolean | (() => boolean);
+type RovingFocusControllerOptions<T extends Element> = {
+    /**
+     * The keyboard-navigable items, in order, with non-interactive ones
+     * already excluded.
+     */
+    items: () => T[];
+    /**
+     * The item navigation moves relative to - typically resolved from the
+     * focused element. Arrow navigation and activation are no-ops while nullish.
+     */
+    current: () => T | null | undefined;
+    /**
+     * Moves focus to `item`. The host owns the focus delegation and any side
+     * effects riding along with it (scrolling, selection-follows-focus).
+     */
+    focusItem: (item: T) => void;
+    /**
+     * Invoked with the current item on Enter/Space, when the item is part of
+     * {@link RovingFocusControllerOptions.items}. Omit to skip the activation
+     * binding altogether.
+     */
+    activateItem?: (item: T) => void;
+    /** Binding options for the activation keys. */
+    activateOptions?: KeyBindingOptions;
+    /**
+     * Whether ArrowLeft/ArrowRight navigate, following the writing direction.
+     * Defaults to `true`.
+     */
+    horizontal?: RovingFocusAxis;
+    /** Whether ArrowUp/ArrowDown navigate. Defaults to `false`. */
+    vertical?: RovingFocusAxis;
+    /** Whether Home/End jump to the first/last item. Defaults to `true`. */
+    homeEnd?: boolean;
+    /**
+     * How arrow navigation treats a nullish current item:
+     * - `skip` - do nothing (default)
+     * - `wrap` - navigate from just outside the list, so "next" lands on the
+     *   first item and "previous" on the last one
+     */
+    missingCurrent?: 'skip' | 'wrap';
+    /** Options forwarded to the underlying key-bindings controller. */
+    keybindings?: KeyBindingControllerOptions;
+};
+/**
+ * Implements the roving keyboard navigation shared by the container
+ * components: Home/End jumps and wrapping ArrowKey moves over a flat list of
+ * enabled items, relative to the currently focused one, with the horizontal
+ * axis following the writing direction.
+ *
+ * The host supplies the item list, the current-item resolution and the focus
+ * delegation; hierarchical structures (the tree) need their own navigation.
+ */
+declare class RovingFocusController<T extends Element> {
+    private readonly _host;
+    private readonly _options;
+    constructor(host: RovingFocusHost, options: RovingFocusControllerOptions<T>);
+    private _focus;
+    private _move;
+    private _activate;
+}
+/** Creates and adds a {@link RovingFocusController} to the given host. */
+export declare function addRovingFocusController<T extends Element>(host: RovingFocusHost, options: RovingFocusControllerOptions<T>): RovingFocusController<T>;
+export type { RovingFocusController, RovingFocusControllerOptions };

package/internals/controllers/roving-focus.js

@@ -0,0 +1,61 @@
+import { firstOf, isEmpty, lastOf } from '../utils/arrays.js';
+import { isLTR } from '../utils/dom.js';
+import { wrap } from '../utils/math.js';
+import { isFunction } from '../utils/types.js';
+import { addKeybindings, arrowDown, arrowLeft, arrowRight, arrowUp, endKey, homeKey, } from './key-bindings.js';
+class RovingFocusController {
+    constructor(host, options) {
+        this._host = host;
+        this._options = options;
+        const { horizontal = true, vertical = false, homeEnd = true, activateItem, activateOptions, keybindings, } = options;
+        const bindings = addKeybindings(host, keybindings);
+        if (horizontal) {
+            bindings
+                .set(arrowLeft, () => this._move(-1, horizontal, true))
+                .set(arrowRight, () => this._move(1, horizontal, true));
+        }
+        if (vertical) {
+            bindings
+                .set(arrowUp, () => this._move(-1, vertical, false))
+                .set(arrowDown, () => this._move(1, vertical, false));
+        }
+        if (homeEnd) {
+            bindings
+                .set(homeKey, () => this._focus(firstOf(this._options.items())))
+                .set(endKey, () => this._focus(lastOf(this._options.items())));
+        }
+        if (activateItem) {
+            bindings.setActivateHandler(() => this._activate(), activateOptions);
+        }
+    }
+    _focus(item) {
+        if (item) {
+            this._options.focusItem.call(this._host, item);
+        }
+    }
+    _move(delta, axis, rtlAware) {
+        if (isFunction(axis) && !axis.call(this._host)) {
+            return;
+        }
+        const items = this._options.items();
+        const current = this._options.current();
+        if (isEmpty(items) ||
+            (!current && this._options.missingCurrent !== 'wrap')) {
+            return;
+        }
+        const index = current ? items.indexOf(current) : -1;
+        const direction = rtlAware && !isLTR(this._host) ? -delta : delta;
+        const next = wrap(0, items.length - 1, index + direction);
+        this._focus(items[next]);
+    }
+    _activate() {
+        const current = this._options.current();
+        if (current && this._options.items().includes(current)) {
+            this._options.activateItem.call(this._host, current);
+        }
+    }
+}
+export function addRovingFocusController(host, options) {
+    return new RovingFocusController(host, options);
+}
+//# sourceMappingURL=roving-focus.js.map

package/internals/controllers/roving-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-focus.js","sourceRoot":"","sources":["../../../src/internals/controllers/roving-focus.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ReactiveControllerHost } from 'lit';\nimport { firstOf, isEmpty, lastOf } from '../utils/arrays.js';\nimport { isLTR } from '../utils/dom.js';\nimport { wrap } from '../utils/math.js';\nimport { isFunction } from '../utils/types.js';\nimport {\n  addKeybindings,\n  arrowDown,\n  arrowLeft,\n  arrowRight,\n  arrowUp,\n  endKey,\n  homeKey,\n  type KeyBindingControllerOptions,\n  type KeyBindingOptions,\n} from './key-bindings.js';\n\ntype RovingFocusHost = ReactiveControllerHost & HTMLElement;\n\n/**\n * Whether an arrow axis navigates. A predicate keeps the keys bound - and\n * their default behavior suppressed - while gating the navigation itself,\n * for hosts that switch orientation at runtime.\n */\ntype RovingFocusAxis = boolean | (() => boolean);\n\ntype RovingFocusControllerOptions<T extends Element> = {\n  /**\n   * The keyboard-navigable items, in order, with non-interactive ones\n   * already excluded.\n   */\n  items: () => T[];\n  /**\n   * The item navigation moves relative to - typically resolved from the\n   * focused element. Arrow navigation and activation are no-ops while nullish.\n   */\n  current: () => T | null | undefined;\n  /**\n   * Moves focus to `item`. The host owns the focus delegation and any side\n   * effects riding along with it (scrolling, selection-follows-focus).\n   */\n  focusItem: (item: T) => void;\n  /**\n   * Invoked with the current item on Enter/Space, when the item is part of\n   * {@link RovingFocusControllerOptions.items}. Omit to skip the activation\n   * binding altogether.\n   */\n  activateItem?: (item: T) => void;\n  /** Binding options for the activation keys. */\n  activateOptions?: KeyBindingOptions;\n  /**\n   * Whether ArrowLeft/ArrowRight navigate, following the writing direction.\n   * Defaults to `true`.\n   */\n  horizontal?: RovingFocusAxis;\n  /** Whether ArrowUp/ArrowDown navigate. Defaults to `false`. */\n  vertical?: RovingFocusAxis;\n  /** Whether Home/End jump to the first/last item. Defaults to `true`. */\n  homeEnd?: boolean;\n  /**\n   * How arrow navigation treats a nullish current item:\n   * - `skip` - do nothing (default)\n   * - `wrap` - navigate from just outside the list, so \"next\" lands on the\n   *   first item and \"previous\" on the last one\n   */\n  missingCurrent?: 'skip' | 'wrap';\n  /** Options forwarded to the underlying key-bindings controller. */\n  keybindings?: KeyBindingControllerOptions;\n};\n\n/**\n * Implements the roving keyboard navigation shared by the container\n * components: Home/End jumps and wrapping ArrowKey moves over a flat list of\n * enabled items, relative to the currently focused one, with the horizontal\n * axis following the writing direction.\n *\n * The host supplies the item list, the current-item resolution and the focus\n * delegation; hierarchical structures (the tree) need their own navigation.\n */\nclass RovingFocusController<T extends Element> {\n  private readonly _host: RovingFocusHost;\n  private readonly _options: RovingFocusControllerOptions<T>;\n\n  constructor(host: RovingFocusHost, options: RovingFocusControllerOptions<T>) {\n    this._host = host;\n    this._options = options;\n\n    const {\n      horizontal = true,\n      vertical = false,\n      homeEnd = true,\n      activateItem,\n      activateOptions,\n      keybindings,\n    } = options;\n\n    const bindings = addKeybindings(host, keybindings);\n\n    if (horizontal) {\n      bindings\n        .set(arrowLeft, () => this._move(-1, horizontal, true))\n        .set(arrowRight, () => this._move(1, horizontal, true));\n    }\n\n    if (vertical) {\n      bindings\n        .set(arrowUp, () => this._move(-1, vertical, false))\n        .set(arrowDown, () => this._move(1, vertical, false));\n    }\n\n    if (homeEnd) {\n      bindings\n        .set(homeKey, () => this._focus(firstOf(this._options.items())))\n        .set(endKey, () => this._focus(lastOf(this._options.items())));\n    }\n\n    if (activateItem) {\n      bindings.setActivateHandler(() => this._activate(), activateOptions);\n    }\n  }\n\n  private _focus(item?: T): void {\n    if (item) {\n      this._options.focusItem.call(this._host, item);\n    }\n  }\n\n  private _move(delta: -1 | 1, axis: RovingFocusAxis, rtlAware: boolean): void {\n    if (isFunction(axis) && !axis.call(this._host)) {\n      return;\n    }\n\n    const items = this._options.items();\n    const current = this._options.current();\n\n    if (\n      isEmpty(items) ||\n      (!current && this._options.missingCurrent !== 'wrap')\n    ) {\n      return;\n    }\n\n    // A current item outside the set resolves to -1 as well, wrapping the\n    // navigation in from the closest list edge.\n    const index = current ? items.indexOf(current) : -1;\n    const direction = rtlAware && !isLTR(this._host) ? -delta : delta;\n    const next = wrap(0, items.length - 1, index + direction);\n\n    this._focus(items[next]);\n  }\n\n  private _activate(): void {\n    const current = this._options.current();\n\n    if (current && this._options.items().includes(current)) {\n      this._options.activateItem!.call(this._host, current);\n    }\n  }\n}\n\n/** Creates and adds a {@link RovingFocusController} to the given host. */\nexport function addRovingFocusController<T extends Element>(\n  host: RovingFocusHost,\n  options: RovingFocusControllerOptions<T>\n): RovingFocusController<T> {\n  return new RovingFocusController(host, options);\n}\n\nexport type { RovingFocusController, RovingFocusControllerOptions };\n"]}

package/{components/common → internals}/controllers/slot.d.ts

@@ -9,6 +9,11 @@ type SlotQueryOptions = {
      * as well as elements assigned to any other slots that are descendants of this slot. If no
      * assigned elements are found, it returns the slot's fallback content.
      *
+     * @remarks
+     * Mind that fallback content when checking whether a consumer projected anything:
+     * for a slot rendered as `<slot>${this.label}</slot>`, a flattened query reports
+     * the rendered `label` as assigned content even though nothing was projected.
+     *
      * Defaults to `false`.
      */
     flatten?: boolean;
@@ -39,8 +44,18 @@ declare class SlotController<T> implements ReactiveController {
     private readonly _host;
     private readonly _options;
     private readonly _slots?;
+    private readonly _slotCache;
     private _initialized;
     constructor(host: ReactiveControllerHost & LitElement, options?: SlotControllerOptions<T>);
+    /**
+     * The query results are cached, since the accessors below are routinely called
+     * from a host's `render`. Only a still connected slot is served from the cache -
+     * one removed by a conditional template falls back to a fresh query.
+     *
+     * There is no slot to find before the host creates its render root, which happens
+     * when it connects. A query that comes earlier, such as one from an attribute that
+     * the parser applies on upgrade, reports no slot instead of an error.
+     */
     private _getSlot;
     /**
      * Returns an array of the assigned nodes for `slot`.
@@ -56,12 +71,21 @@ declare class SlotController<T> implements ReactiveController {
      * See {@link SlotQueryOptions.flatten} and {@link SlotQueryOptions.selector} for more information.
      */
     getAssignedElements<U extends Element>(slot: T, options?: SlotQueryOptions): U[];
+    /**
+     * Returns the combined text content of the nodes assigned to `slot`,
+     * trimmed and with consecutive whitespace collapsed.
+     *
+     * Useful for deriving an accessible label from projected content.
+     * See {@link SlotQueryOptions.flatten} for the `flatten` semantics.
+     */
+    getAssignedText(slot: T, flatten?: boolean): string;
     /**
      * Return whether `slot` has assigned nodes.
      *
      * If `flatten` is set to `true`, it returns a sequence of both the nodes assigned to the queried slot,
      * as well as nodes assigned to any other slots that are descendants of this slot. If no
-     * assigned nodes are found, it returns the slot's fallback content.
+     * assigned nodes are found, it returns the slot's fallback content - so a slot with
+     * fallback content always reports as having nodes. See {@link SlotQueryOptions.flatten}.
      */
     hasAssignedNodes(slot: T, flatten?: boolean): boolean;
     /**

package/{components/common → internals}/controllers/slot.js

@@ -1,8 +1,10 @@
 import { isServer, } from 'lit';
-import { isEmpty } from '../util.js';
+import { isEmpty } from '../utils/arrays.js';
+import { normalizedTextContent } from '../utils/dom.js';
 const DefaultSlot = '[default]';
 class SlotController {
     constructor(host, options) {
+        this._slotCache = new Map();
         this._initialized = false;
         this._host = host;
         this._host.addController(this);
@@ -12,10 +14,21 @@ class SlotController {
     _getSlot(slotName) {
         if (isServer)
             return null;
-        if (slotName === DefaultSlot) {
-            return this._host.renderRoot.querySelector('slot:not([name])');
+        const cached = this._slotCache.get(slotName);
+        if (cached?.isConnected) {
+            return cached;
         }
-        return this._host.renderRoot.querySelector(`slot[name="${slotName}"]`);
+        const selector = slotName === DefaultSlot
+            ? 'slot:not([name])'
+            : `slot[name="${slotName}"]`;
+        const slot = this._host.renderRoot?.querySelector(selector) ?? null;
+        if (slot) {
+            this._slotCache.set(slotName, slot);
+        }
+        else {
+            this._slotCache.delete(slotName);
+        }
+        return slot;
     }
     getAssignedNodes(slot, flatten = false) {
         return this._getSlot(slot)?.assignedNodes({ flatten }) ?? [];
@@ -28,6 +41,9 @@ class SlotController {
             ? elements.filter((e) => e.matches(options.selector))
             : elements;
     }
+    getAssignedText(slot, flatten = false) {
+        return normalizedTextContent(this.getAssignedNodes(slot, flatten));
+    }
     hasAssignedNodes(slot, flatten = false) {
         return !isEmpty(this.getAssignedNodes(slot, flatten));
     }
@@ -38,8 +54,8 @@ class SlotController {
         const slot = event.target;
         const name = slot.name;
         const isDefault = name === '';
-        if (!this._slots ||
-            this._slots.has(isDefault ? DefaultSlot : slot.name)) {
+        const observed = isDefault ? DefaultSlot : name;
+        if (!this._slots || this._slots.has(observed)) {
             this._options.onChange?.call(this._host, {
                 slot: name,
                 isDefault,

package/internals/controllers/slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.js","sourceRoot":"","sources":["../../../src/internals/controllers/slot.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  isServer,\n  type LitElement,\n  type ReactiveController,\n  type ReactiveControllerHost,\n} from 'lit';\nimport { isEmpty } from '../utils/arrays.js';\nimport { normalizedTextContent } from '../utils/dom.js';\n\ntype InferSlotNames<T> = T extends readonly (infer U)[] ? U : never;\n\n/**\n * Additional query options for the slot controller methods.\n */\ntype SlotQueryOptions = {\n  /**\n   * If set to `true`, it returns a sequence of both the elements assigned to the queried slot,\n   * as well as elements assigned to any other slots that are descendants of this slot. If no\n   * assigned elements are found, it returns the slot's fallback content.\n   *\n   * @remarks\n   * Mind that fallback content when checking whether a consumer projected anything:\n   * for a slot rendered as `<slot>${this.label}</slot>`, a flattened query reports\n   * the rendered `label` as assigned content even though nothing was projected.\n   *\n   * Defaults to `false`.\n   */\n  flatten?: boolean;\n  /**\n   * CSS selector used to filter the elements returned.\n   */\n  selector?: string;\n};\n\ntype SlotChangeCallback<T> = (\n  parameters: SlotChangeCallbackParameters<T>\n) => void;\n\ntype SlotChangeCallbackParameters<T> = {\n  /** The slot name that has its assigned nodes changed. */\n  slot: T;\n  /** `true` if the slot is the default slot. */\n  isDefault: boolean;\n  /** `true` if the callback handler is called for the initial host update. */\n  isInitial: boolean;\n};\n\ntype SlotControllerOptions<T> = {\n  /** An iterable collection of slot names to observe. */\n  slots?: Iterable<T>;\n  /** Callback function which is invoked a slot's assigned nodes change. */\n  onChange?: SlotChangeCallback<T>;\n  /** If set to `true`, the `onChange` callback is invoked once after the host is updated for the first time. */\n  initial?: boolean;\n};\n\nconst DefaultSlot = '[default]';\n\nclass SlotController<T> implements ReactiveController {\n  private readonly _host: ReactiveControllerHost & LitElement;\n  private readonly _options: SlotControllerOptions<T>;\n  private readonly _slots?: Set<T>;\n  private readonly _slotCache = new Map<T | undefined, HTMLSlotElement>();\n  private _initialized = false;\n\n  constructor(\n    host: ReactiveControllerHost & LitElement,\n    options?: SlotControllerOptions<T>\n  ) {\n    this._host = host;\n    this._host.addController(this);\n\n    this._options = { ...options };\n    this._slots = options?.slots ? new Set(options.slots) : undefined;\n  }\n\n  /**\n   * The query results are cached, since the accessors below are routinely called\n   * from a host's `render`. Only a still connected slot is served from the cache -\n   * one removed by a conditional template falls back to a fresh query.\n   *\n   * There is no slot to find before the host creates its render root, which happens\n   * when it connects. A query that comes earlier, such as one from an attribute that\n   * the parser applies on upgrade, reports no slot instead of an error.\n   */\n  private _getSlot(slotName?: T): HTMLSlotElement | null {\n    if (isServer) return null;\n\n    const cached = this._slotCache.get(slotName);\n\n    if (cached?.isConnected) {\n      return cached;\n    }\n\n    const selector =\n      slotName === DefaultSlot\n        ? 'slot:not([name])'\n        : `slot[name=\"${slotName}\"]`;\n    const slot =\n      this._host.renderRoot?.querySelector<HTMLSlotElement>(selector) ?? null;\n\n    if (slot) {\n      this._slotCache.set(slotName, slot);\n    } else {\n      this._slotCache.delete(slotName);\n    }\n\n    return slot;\n  }\n\n  /**\n   * Returns an array of the assigned nodes for `slot`.\n   *\n   * If `flatten` is set to `true`, it returns a sequence of both the nodes assigned to the queried slot,\n   * as well as nodes assigned to any other slots that are descendants of this slot. If no\n   * assigned nodes are found, it returns the slot's fallback content.\n   */\n  public getAssignedNodes(slot: T, flatten = false): Node[] {\n    return this._getSlot(slot)?.assignedNodes({ flatten }) ?? [];\n  }\n\n  /**\n   * Returns an array of the assigned elements for `slot` with additional `options`.\n   *\n   * See {@link SlotQueryOptions.flatten} and {@link SlotQueryOptions.selector} for more information.\n   */\n  public getAssignedElements<U extends Element>(\n    slot: T,\n    options?: SlotQueryOptions\n  ): U[] {\n    const elements =\n      (this._getSlot(slot)?.assignedElements({\n        flatten: options?.flatten,\n      }) as U[]) ?? [];\n\n    return options?.selector\n      ? elements.filter((e) => e.matches(options.selector!))\n      : elements;\n  }\n\n  /**\n   * Returns the combined text content of the nodes assigned to `slot`,\n   * trimmed and with consecutive whitespace collapsed.\n   *\n   * Useful for deriving an accessible label from projected content.\n   * See {@link SlotQueryOptions.flatten} for the `flatten` semantics.\n   */\n  public getAssignedText(slot: T, flatten = false): string {\n    return normalizedTextContent(this.getAssignedNodes(slot, flatten));\n  }\n\n  /**\n   * Return whether `slot` has assigned nodes.\n   *\n   * If `flatten` is set to `true`, it returns a sequence of both the nodes assigned to the queried slot,\n   * as well as nodes assigned to any other slots that are descendants of this slot. If no\n   * assigned nodes are found, it returns the slot's fallback content - so a slot with\n   * fallback content always reports as having nodes. See {@link SlotQueryOptions.flatten}.\n   */\n  public hasAssignedNodes(slot: T, flatten = false): boolean {\n    return !isEmpty(this.getAssignedNodes(slot, flatten));\n  }\n\n  /**\n   * Return whether `slot` has assigned elements accepting additional `options`.\n   *\n   * See {@link SlotQueryOptions.flatten} and {@link SlotQueryOptions.selector} for more information.\n   */\n  public hasAssignedElements(slot: T, options?: SlotQueryOptions): boolean {\n    return !isEmpty(this.getAssignedElements(slot, options));\n  }\n\n  /** @internal */\n  public handleEvent(event: Event): void {\n    const slot = event.target as HTMLSlotElement;\n    const name = slot.name as T;\n    const isDefault = name === '';\n    const observed = isDefault ? (DefaultSlot as T) : name;\n\n    if (!this._slots || this._slots.has(observed)) {\n      this._options.onChange?.call(this._host, {\n        slot: name,\n        isDefault,\n        isInitial: false,\n      });\n      this._host.requestUpdate();\n    }\n  }\n\n  /** @internal */\n  public hostConnected(): void {\n    this._host.renderRoot.addEventListener('slotchange', this);\n  }\n\n  /** @internal */\n  public hostDisconnected(): void {\n    this._host.renderRoot.removeEventListener('slotchange', this);\n  }\n\n  /** @internal */\n  public hostUpdated(): void {\n    if (!this._initialized && this._options.initial) {\n      this._initialized = true;\n      this._options.onChange?.call(this._host, {\n        slot: '<initial>' as T,\n        isDefault: false,\n        isInitial: true,\n      });\n    }\n  }\n}\n\nfunction addSlotController<K extends readonly string[]>(\n  host: ReactiveControllerHost,\n  options?: SlotControllerOptions<InferSlotNames<K>> & {\n    slots?: K;\n  }\n): SlotController<InferSlotNames<K>> {\n  return new SlotController(host as ReactiveControllerHost & LitElement, {\n    ...options,\n    slots: options?.slots as Iterable<InferSlotNames<K>>,\n  });\n}\n\nfunction setSlots<const T extends readonly string[]>(...slots: T) {\n  return [DefaultSlot, ...slots] as const;\n}\n\nexport type {\n  InferSlotNames,\n  SlotChangeCallback,\n  SlotChangeCallbackParameters,\n  SlotController,\n  SlotControllerOptions,\n  SlotQueryOptions,\n};\nexport { addSlotController, DefaultSlot, setSlots };\n"]}

package/internals/controllers/toggle.d.ts

@@ -0,0 +1,96 @@
+import type { LitElement } from 'lit';
+/**
+ * The events emitted by a {@link ToggleController}.
+ *
+ * Include (a subset of) these in a host's event map to document them.
+ */
+export interface ToggleEventMap {
+    /** Emitted before opening. Cancelable - preventing it aborts the sequence. */
+    igcOpening: CustomEvent<unknown>;
+    /** Emitted after the host has opened and its transition has completed. */
+    igcOpened: CustomEvent<unknown>;
+    /** Emitted before closing. Cancelable - preventing it aborts the sequence. */
+    igcClosing: CustomEvent<unknown>;
+    /** Emitted after the host has closed and its transition has completed. */
+    igcClosed: CustomEvent<unknown>;
+}
+/**
+ * A toggleable host must expose the event-emitter mixin's `emitEvent` -
+ * extend {@link ../mixins/event-emitter.js#EventEmitterMixin | EventEmitterMixin}
+ * with (a subset of) the {@link ToggleEventMap}.
+ */
+type ToggleHost = LitElement & {
+    open: boolean;
+    emitEvent(name: string, init?: CustomEventInit): boolean;
+};
+/**
+ * Runs the host's visual transition to the requested state - flipping `open`,
+ * playing animations, awaiting updates - in whatever order the host needs.
+ *
+ * Resolving `false` marks the transition as superseded (an animation was
+ * interrupted by a newer one), which skips the trailing "-ed" event.
+ */
+type ToggleTransitionFunction = (open: boolean) => Promise<boolean> | boolean;
+type ToggleControllerOptions = {
+    /**
+     * The host transition. When omitted, the controller flips `host.open` itself
+     * and the transition always counts as completed.
+     */
+    transition?: ToggleTransitionFunction;
+    /** Factory for the `detail` payload of the emitted events. */
+    detail?: () => unknown;
+};
+/**
+ * Implements the open/close choreography shared by every toggleable component:
+ *
+ * 1. Bail when the host is already in the requested state.
+ * 2. When emitting, fire the cancelable `igcOpening`/`igcClosing` event and
+ *    bail if the consumer prevented it.
+ * 3. Run the host transition.
+ * 4. When emitting and the transition completed, await the host update and
+ *    fire the `igcOpened`/`igcClosed` event.
+ *
+ * The host keeps its public `open` property, `show()`/`hide()`/`toggle()`
+ * methods and event documentation, and delegates to the controller.
+ *
+ * Unlike the other controllers of this directory it is not registered with the
+ * host - it drives the host on demand and has no life-cycle of its own.
+ */
+declare class ToggleController {
+    private readonly _host;
+    private readonly _options;
+    /** The target of an in-flight operation - a transition may flip `host.open` only at its end. */
+    private _pending?;
+    /** Bumped per operation, so a superseded one can bail out instead of finishing. */
+    private _generation;
+    constructor(host: ToggleHost, options?: ToggleControllerOptions);
+    /**
+     * Events go through the host's `emitEvent` - it is the choke point
+     * consumers and framework wrappers observe.
+     */
+    private _emit;
+    private _setOpenState;
+    /**
+     * Opens the host. When `emitEvents` is true, wraps the transition in
+     * `igcOpening`/`igcOpened` events.
+     *
+     * Returns `false` when the host was already open (or heading there), the
+     * opening event was canceled, or the operation was superseded - either by the
+     * transition reporting itself interrupted or by a newer request.
+     */
+    show(emitEvents?: boolean): Promise<boolean>;
+    /**
+     * Closes the host. When `emitEvents` is true, wraps the transition in
+     * `igcClosing`/`igcClosed` events.
+     *
+     * Returns `false` when the host was already closed (or heading there), the
+     * closing event was canceled, or the operation was superseded - either by the
+     * transition reporting itself interrupted or by a newer request.
+     */
+    hide(emitEvents?: boolean): Promise<boolean>;
+    /** Opens or closes the host based on its current state. */
+    toggle(emitEvents?: boolean): Promise<boolean>;
+}
+/** Creates and adds a {@link ToggleController} to the given host. */
+export declare function addToggleController(host: ToggleHost, options?: ToggleControllerOptions): ToggleController;
+export type { ToggleController, ToggleControllerOptions, ToggleHost };

package/internals/controllers/toggle.js

@@ -0,0 +1,65 @@
+class ToggleController {
+    constructor(host, options) {
+        this._generation = 0;
+        this._host = host;
+        this._options = { ...options };
+    }
+    _emit(name, cancelable) {
+        const host = this._host;
+        const detail = this._options.detail?.call(host);
+        return host.emitEvent(name, {
+            ...(cancelable && { cancelable }),
+            ...(detail !== undefined && { detail }),
+        });
+    }
+    async _setOpenState(open, emitEvents) {
+        const host = this._host;
+        const { transition } = this._options;
+        if ((this._pending ?? host.open) === open) {
+            return false;
+        }
+        if (emitEvents && !this._emit(open ? 'igcOpening' : 'igcClosing', true)) {
+            return false;
+        }
+        const generation = ++this._generation;
+        this._pending = open;
+        let completed = true;
+        try {
+            if (transition) {
+                completed = (await transition.call(host, open)) !== false;
+            }
+            else {
+                host.open = open;
+            }
+        }
+        finally {
+            if (generation === this._generation) {
+                this._pending = undefined;
+            }
+        }
+        if (generation !== this._generation) {
+            return false;
+        }
+        if (emitEvents && completed) {
+            await host.updateComplete;
+            if (generation !== this._generation) {
+                return false;
+            }
+            this._emit(open ? 'igcOpened' : 'igcClosed', false);
+        }
+        return completed;
+    }
+    show(emitEvents = false) {
+        return this._setOpenState(true, emitEvents);
+    }
+    hide(emitEvents = false) {
+        return this._setOpenState(false, emitEvents);
+    }
+    toggle(emitEvents = false) {
+        return this._host.open ? this.hide(emitEvents) : this.show(emitEvents);
+    }
+}
+export function addToggleController(host, options) {
+    return new ToggleController(host, options);
+}
+//# sourceMappingURL=toggle.js.map

package/internals/controllers/toggle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.js","sourceRoot":"","sources":["../../../src/internals/controllers/toggle.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LitElement } from 'lit';\n\n/**\n * The events emitted by a {@link ToggleController}.\n *\n * Include (a subset of) these in a host's event map to document them.\n */\nexport interface ToggleEventMap {\n  /** Emitted before opening. Cancelable - preventing it aborts the sequence. */\n  igcOpening: CustomEvent<unknown>;\n  /** Emitted after the host has opened and its transition has completed. */\n  igcOpened: CustomEvent<unknown>;\n  /** Emitted before closing. Cancelable - preventing it aborts the sequence. */\n  igcClosing: CustomEvent<unknown>;\n  /** Emitted after the host has closed and its transition has completed. */\n  igcClosed: CustomEvent<unknown>;\n}\n\n/**\n * A toggleable host must expose the event-emitter mixin's `emitEvent` -\n * extend {@link ../mixins/event-emitter.js#EventEmitterMixin | EventEmitterMixin}\n * with (a subset of) the {@link ToggleEventMap}.\n */\ntype ToggleHost = LitElement & {\n  open: boolean;\n  emitEvent(name: string, init?: CustomEventInit): boolean;\n};\n\n/**\n * Runs the host's visual transition to the requested state - flipping `open`,\n * playing animations, awaiting updates - in whatever order the host needs.\n *\n * Resolving `false` marks the transition as superseded (an animation was\n * interrupted by a newer one), which skips the trailing \"-ed\" event.\n */\ntype ToggleTransitionFunction = (open: boolean) => Promise<boolean> | boolean;\n\ntype ToggleControllerOptions = {\n  /**\n   * The host transition. When omitted, the controller flips `host.open` itself\n   * and the transition always counts as completed.\n   */\n  transition?: ToggleTransitionFunction;\n  /** Factory for the `detail` payload of the emitted events. */\n  detail?: () => unknown;\n};\n\n/**\n * Implements the open/close choreography shared by every toggleable component:\n *\n * 1. Bail when the host is already in the requested state.\n * 2. When emitting, fire the cancelable `igcOpening`/`igcClosing` event and\n *    bail if the consumer prevented it.\n * 3. Run the host transition.\n * 4. When emitting and the transition completed, await the host update and\n *    fire the `igcOpened`/`igcClosed` event.\n *\n * The host keeps its public `open` property, `show()`/`hide()`/`toggle()`\n * methods and event documentation, and delegates to the controller.\n *\n * Unlike the other controllers of this directory it is not registered with the\n * host - it drives the host on demand and has no life-cycle of its own.\n */\nclass ToggleController {\n  private readonly _host: ToggleHost;\n  private readonly _options: ToggleControllerOptions;\n\n  /** The target of an in-flight operation - a transition may flip `host.open` only at its end. */\n  private _pending?: boolean;\n\n  /** Bumped per operation, so a superseded one can bail out instead of finishing. */\n  private _generation = 0;\n\n  constructor(host: ToggleHost, options?: ToggleControllerOptions) {\n    this._host = host;\n    this._options = { ...options };\n  }\n\n  /**\n   * Events go through the host's `emitEvent` - it is the choke point\n   * consumers and framework wrappers observe.\n   */\n  private _emit(name: keyof ToggleEventMap, cancelable: boolean): boolean {\n    const host = this._host;\n    const detail = this._options.detail?.call(host);\n\n    // Both keys are omitted rather than passed as falsy, so that `emitEvent`\n    // applies its own defaults and the init of a plain event stays empty.\n    return host.emitEvent(name, {\n      ...(cancelable && { cancelable }),\n      ...(detail !== undefined && { detail }),\n    });\n  }\n\n  private async _setOpenState(\n    open: boolean,\n    emitEvents: boolean\n  ): Promise<boolean> {\n    const host = this._host;\n    const { transition } = this._options;\n\n    if ((this._pending ?? host.open) === open) {\n      return false;\n    }\n\n    if (emitEvents && !this._emit(open ? 'igcOpening' : 'igcClosing', true)) {\n      return false;\n    }\n\n    const generation = ++this._generation;\n    this._pending = open;\n\n    // The default transition runs synchronously so the state flip - and the\n    // `updateComplete` subscription below - happen within the caller's own\n    // microtask, exactly as if the host had flipped the property itself.\n    let completed = true;\n    try {\n      if (transition) {\n        completed = (await transition.call(host, open)) !== false;\n      } else {\n        host.open = open;\n      }\n    } finally {\n      // A newer operation owns the pending state from here on.\n      if (generation === this._generation) {\n        this._pending = undefined;\n      }\n    }\n\n    if (generation !== this._generation) {\n      return false;\n    }\n\n    if (emitEvents && completed) {\n      await host.updateComplete;\n\n      // A newer operation may have taken over while the update settled.\n      if (generation !== this._generation) {\n        return false;\n      }\n\n      this._emit(open ? 'igcOpened' : 'igcClosed', false);\n    }\n\n    return completed;\n  }\n\n  /*\n   * The methods below deliberately return the underlying promise instead of\n   * being `async` - every `async` wrapper that returns a promise costs extra\n   * microtask hops on resolution, which shifts the timing of caller code\n   * (e.g. focus management) relative to `updateComplete` subscribers.\n   */\n\n  /**\n   * Opens the host. When `emitEvents` is true, wraps the transition in\n   * `igcOpening`/`igcOpened` events.\n   *\n   * Returns `false` when the host was already open (or heading there), the\n   * opening event was canceled, or the operation was superseded - either by the\n   * transition reporting itself interrupted or by a newer request.\n   */\n  public show(emitEvents = false): Promise<boolean> {\n    return this._setOpenState(true, emitEvents);\n  }\n\n  /**\n   * Closes the host. When `emitEvents` is true, wraps the transition in\n   * `igcClosing`/`igcClosed` events.\n   *\n   * Returns `false` when the host was already closed (or heading there), the\n   * closing event was canceled, or the operation was superseded - either by the\n   * transition reporting itself interrupted or by a newer request.\n   */\n  public hide(emitEvents = false): Promise<boolean> {\n    return this._setOpenState(false, emitEvents);\n  }\n\n  /** Opens or closes the host based on its current state. */\n  public toggle(emitEvents = false): Promise<boolean> {\n    return this._host.open ? this.hide(emitEvents) : this.show(emitEvents);\n  }\n}\n\n/** Creates and adds a {@link ToggleController} to the given host. */\nexport function addToggleController(\n  host: ToggleHost,\n  options?: ToggleControllerOptions\n): ToggleController {\n  return new ToggleController(host, options);\n}\n\nexport type { ToggleController, ToggleControllerOptions, ToggleHost };\n"]}

package/internals/date/compare.d.ts

@@ -0,0 +1,2 @@
+export declare function isDateExceedingMax(value: Date, maxValue: Date, includeTime?: boolean, includeDate?: boolean): boolean;
+export declare function isDateLessThanMin(value: Date, minValue: Date, includeTime?: boolean, includeDate?: boolean): boolean;

package/internals/date/compare.js

@@ -0,0 +1,23 @@
+function compareDates(value, boundary, comparator, includeTime, includeDate) {
+    if (includeTime && includeDate) {
+        return comparator(value.getTime(), boundary.getTime());
+    }
+    const v = new Date(value.getTime());
+    const b = new Date(boundary.getTime());
+    if (!includeTime) {
+        v.setHours(0, 0, 0, 0);
+        b.setHours(0, 0, 0, 0);
+    }
+    if (!includeDate) {
+        v.setFullYear(0, 0, 0);
+        b.setFullYear(0, 0, 0);
+    }
+    return comparator(v.getTime(), b.getTime());
+}
+export function isDateExceedingMax(value, maxValue, includeTime = true, includeDate = true) {
+    return compareDates(value, maxValue, (a, b) => a > b, includeTime, includeDate);
+}
+export function isDateLessThanMin(value, minValue, includeTime = true, includeDate = true) {
+    return compareDates(value, minValue, (a, b) => a < b, includeTime, includeDate);
+}
+//# sourceMappingURL=compare.js.map

package/internals/date/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/internals/date/compare.ts"],"names":[],"mappings":"AACA,SAAS,YAAY,CACnB,KAAW,EACX,QAAc,EACd,UAA6C,EAC7C,WAAoB,EACpB,WAAoB;IAEpB,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;QAC/B,OAAO,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAAW,EACX,QAAc,EACd,WAAW,GAAG,IAAI,EAClB,WAAW,GAAG,IAAI;IAElB,OAAO,YAAY,CACjB,KAAK,EACL,QAAQ,EACR,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EACf,WAAW,EACX,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAW,EACX,QAAc,EACd,WAAW,GAAG,IAAI,EAClB,WAAW,GAAG,IAAI;IAElB,OAAO,YAAY,CACjB,KAAK,EACL,QAAQ,EACR,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EACf,WAAW,EACX,WAAW,CACZ,CAAC;AACJ,CAAC","sourcesContent":["/** Compares two dates, optionally ignoring their time or their date portion. */\nfunction compareDates(\n  value: Date,\n  boundary: Date,\n  comparator: (a: number, b: number) => boolean,\n  includeTime: boolean,\n  includeDate: boolean\n): boolean {\n  if (includeTime && includeDate) {\n    return comparator(value.getTime(), boundary.getTime());\n  }\n\n  const v = new Date(value.getTime());\n  const b = new Date(boundary.getTime());\n\n  if (!includeTime) {\n    v.setHours(0, 0, 0, 0);\n    b.setHours(0, 0, 0, 0);\n  }\n  if (!includeDate) {\n    v.setFullYear(0, 0, 0);\n    b.setFullYear(0, 0, 0);\n  }\n\n  return comparator(v.getTime(), b.getTime());\n}\n\nexport function isDateExceedingMax(\n  value: Date,\n  maxValue: Date,\n  includeTime = true,\n  includeDate = true\n): boolean {\n  return compareDates(\n    value,\n    maxValue,\n    (a, b) => a > b,\n    includeTime,\n    includeDate\n  );\n}\n\nexport function isDateLessThanMin(\n  value: Date,\n  minValue: Date,\n  includeTime = true,\n  includeDate = true\n): boolean {\n  return compareDates(\n    value,\n    minValue,\n    (a, b) => a < b,\n    includeTime,\n    includeDate\n  );\n}\n"]}

package/internals/date/converters.d.ts

@@ -0,0 +1,18 @@
+import type { DateRangeValue } from '../../components/types.js';
+/** Whether `value` is a `Date` holding a valid time. */
+export declare function isValidDate(value: unknown): value is Date;
+/** Converts `value` to a `Date`, or to `null` when it is empty or cannot be parsed. */
+export declare function convertToDate(value?: Date | string | null): Date | null;
+/**
+ * Converts a comma-separated string of ISO 8601 dates, or an array of dates and ISO 8601
+ * strings, into an array of `Date` objects, dropping the ones which cannot be parsed.
+ */
+export declare function convertToDates(value?: (Date | string)[] | string | null): Date[] | null;
+/**
+ * Converts `value` to a `DateRangeValue`, parsing a string as JSON and truncating the
+ * time of both endpoints. Malformed input converts to `null` rather than throwing, since
+ * this runs as an attribute converter.
+ */
+export declare function convertToDateRange(value?: DateRangeValue | string | null): DateRangeValue | null;
+/** Converts a `Date` to an ISO 8601 string. */
+export declare function getDateFormValue(value: Date | null): string | null;

package/internals/date/converters.js

@@ -0,0 +1,70 @@
+import { isPlainObject, isString } from '../utils/types.js';
+import { CalendarDay, truncateTime } from './model.js';
+const ISO_DATE_PATTERN = /^\d{4}/;
+const TIME_PATTERN = /^\d{2}:\d{2}/;
+export function isValidDate(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function getValidDate(date) {
+    return isValidDate(date) ? date : null;
+}
+function parseISODate(value) {
+    const string = value.trim();
+    if (ISO_DATE_PATTERN.test(string)) {
+        const timeComponent = !string.includes('T') ? 'T00:00:00' : '';
+        return getValidDate(new Date(`${string}${timeComponent}`));
+    }
+    if (TIME_PATTERN.test(string)) {
+        const today = CalendarDay.today;
+        const month = `${today.month + 1}`.padStart(2, '0');
+        const date = `${today.date}`.padStart(2, '0');
+        return getValidDate(new Date(`${today.year}-${month}-${date}T${string}`));
+    }
+    return null;
+}
+export function convertToDate(value) {
+    if (!value) {
+        return null;
+    }
+    return isString(value) ? parseISODate(value) : getValidDate(value);
+}
+export function convertToDates(value) {
+    if (!value) {
+        return null;
+    }
+    const values = [];
+    const sources = isString(value) ? value.split(',') : value;
+    for (const source of sources) {
+        const trimmed = isString(source) ? source.trim() : source;
+        const date = convertToDate(trimmed);
+        if (date) {
+            values.push(date);
+        }
+    }
+    return values;
+}
+export function convertToDateRange(value) {
+    if (!value) {
+        return null;
+    }
+    if (!isString(value)) {
+        return value;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(parsed)) {
+        return null;
+    }
+    const start = convertToDate(parsed.start);
+    const end = convertToDate(parsed.end);
+    return { start: truncateTime(start), end: truncateTime(end) };
+}
+export function getDateFormValue(value) {
+    return value ? value.toISOString() : null;
+}
+//# sourceMappingURL=converters.js.map

package/internals/date/converters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/internals/date/converters.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DateRangeValue } from '../../components/types.js';\nimport { isPlainObject, isString } from '../utils/types.js';\nimport { CalendarDay, truncateTime } from './model.js';\n\n/** Matches a string beginning with a four digit year, which is left to `Date` to parse. */\nconst ISO_DATE_PATTERN = /^\\d{4}/;\n\n/** Matches a time only string - `HH:MM` optionally followed by seconds and milliseconds. */\nconst TIME_PATTERN = /^\\d{2}:\\d{2}/;\n\n/** Whether `value` is a `Date` holding a valid time. */\nexport function isValidDate(value: unknown): value is Date {\n  return value instanceof Date && !Number.isNaN(value.getTime());\n}\n\nfunction getValidDate(date: Date): Date | null {\n  return isValidDate(date) ? date : null;\n}\n\n/** Parses an ISO 8601 date, or a time only string against the current date. */\nfunction parseISODate(value: string): Date | null {\n  const string = value.trim();\n\n  if (ISO_DATE_PATTERN.test(string)) {\n    const timeComponent = !string.includes('T') ? 'T00:00:00' : '';\n    return getValidDate(new Date(`${string}${timeComponent}`));\n  }\n\n  if (TIME_PATTERN.test(string)) {\n    const today = CalendarDay.today;\n    const month = `${today.month + 1}`.padStart(2, '0');\n    const date = `${today.date}`.padStart(2, '0');\n\n    return getValidDate(new Date(`${today.year}-${month}-${date}T${string}`));\n  }\n\n  return null;\n}\n\n/** Converts `value` to a `Date`, or to `null` when it is empty or cannot be parsed. */\nexport function convertToDate(value?: Date | string | null): Date | null {\n  if (!value) {\n    return null;\n  }\n\n  return isString(value) ? parseISODate(value) : getValidDate(value);\n}\n\n/**\n * Converts a comma-separated string of ISO 8601 dates, or an array of dates and ISO 8601\n * strings, into an array of `Date` objects, dropping the ones which cannot be parsed.\n */\nexport function convertToDates(\n  value?: (Date | string)[] | string | null\n): Date[] | null {\n  if (!value) {\n    return null;\n  }\n\n  const values: Date[] = [];\n  const sources = isString(value) ? value.split(',') : value;\n\n  for (const source of sources) {\n    const trimmed = isString(source) ? source.trim() : source;\n    const date = convertToDate(trimmed);\n    if (date) {\n      values.push(date);\n    }\n  }\n\n  return values;\n}\n\n/**\n * Converts `value` to a `DateRangeValue`, parsing a string as JSON and truncating the\n * time of both endpoints. Malformed input converts to `null` rather than throwing, since\n * this runs as an attribute converter.\n */\nexport function convertToDateRange(\n  value?: DateRangeValue | string | null\n): DateRangeValue | null {\n  if (!value) {\n    return null;\n  }\n\n  if (!isString(value)) {\n    return value;\n  }\n\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(value);\n  } catch {\n    return null;\n  }\n\n  if (!isPlainObject(parsed)) {\n    return null;\n  }\n\n  const start = convertToDate(parsed.start as Date | string | null);\n  const end = convertToDate(parsed.end as Date | string | null);\n\n  return { start: truncateTime(start), end: truncateTime(end) };\n}\n\n/** Converts a `Date` to an ISO 8601 string. */\nexport function getDateFormValue(value: Date | null): string | null {\n  return value ? value.toISOString() : null;\n}\n"]}

package/{components/calendar → internals/date}/model.d.ts

@@ -13,6 +13,15 @@ type CalendarDayParams = {
 };
 export declare const DAYS_IN_WEEK = 7;
 export declare function toCalendarDay(date: DayParameter): CalendarDay;
+/** Null-preserving {@link toCalendarDay}: empty values convert to `null`. */
+export declare function toCalendarDayOrNull(date?: DayParameter | null): CalendarDay | null;
+/** Truncates the time portion of `date`, passing empty values through as `null`. */
+export declare function truncateTime(date?: Date | null): Date | null;
+/**
+ * Yields the days between `start` and `end`, stepping by `unit` and stopping short of
+ * `end` unless `inclusive` is set.
+ */
+export declare function calendarRange(options: CalendarRangeParams): Generator<CalendarDay, void, unknown>;
 export declare class CalendarDay {
     private readonly _date;
     /** Constructs and returns the current day. */
@@ -33,9 +42,7 @@ export declare class CalendarDay {
     constructor(args: CalendarDayParams);
     /** Returns a copy of this instance. */
     clone(): CalendarDay;
-    /**
-     * Returns a new instance with values replaced.
-     */
+    /** Returns a new instance with the given values replaced. */
     set(args: Partial<CalendarDayParams>): CalendarDay;
     add(unit: DayInterval, value: number): CalendarDay;
     /** Returns the day of the week (Sunday = 0). */