igniteui-webcomponents 7.3.1 → 7.4.0

package/internals/controllers/slot.d.ts

@@ -1,42 +1,33 @@
 import { type LitElement, type ReactiveController, type ReactiveControllerHost } from 'lit';
 type InferSlotNames<T> = T extends readonly (infer U)[] ? U : never;
-/**
- * Additional query options for the slot controller methods.
- */
 type SlotQueryOptions = {
     /**
-     * If set to `true`, it returns a sequence of both the elements assigned to the queried slot,
-     * 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.
+     * Whether the query also returns the content of the descendant slots.
+     * Defaults to `false`.
      *
      * @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`.
+     * A flattened query also returns fallback content: a slot rendered as
+     * `<slot>${this.label}</slot>` reports `label` as assigned content,
+     * although the consumer projected nothing.
      */
     flatten?: boolean;
-    /**
-     * CSS selector used to filter the elements returned.
-     */
+    /** The CSS selector that filters the returned elements. */
     selector?: string;
 };
 type SlotChangeCallback<T> = (parameters: SlotChangeCallbackParameters<T>) => void;
 type SlotChangeCallbackParameters<T> = {
-    /** The slot name that has its assigned nodes changed. */
+    /** The name of the slot with the changed assigned nodes. */
     slot: T;
-    /** `true` if the slot is the default slot. */
     isDefault: boolean;
-    /** `true` if the callback handler is called for the initial host update. */
+    /** Whether the callback runs for the first host update. */
     isInitial: boolean;
 };
 type SlotControllerOptions<T> = {
-    /** An iterable collection of slot names to observe. */
+    /** The slot names to observe. */
     slots?: Iterable<T>;
-    /** Callback function which is invoked a slot's assigned nodes change. */
+    /** Callback that runs when the assigned nodes of a slot change. */
     onChange?: SlotChangeCallback<T>;
-    /** If set to `true`, the `onChange` callback is invoked once after the host is updated for the first time. */
+    /** Whether `onChange` also runs once, after the first host update. */
     initial?: boolean;
 };
 declare const DefaultSlot = "[default]";
@@ -48,58 +39,38 @@ declare class SlotController<T> implements ReactiveController {
     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.
+     * Finds the slot element with the given name.
      *
-     * 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.
+     * @remarks
+     * The result is cached, because the accessors below run from `render`. The
+     * cache serves only a connected slot. A query before the host creates its
+     * render root reports no slot and raises no error.
      */
     private _getSlot;
     /**
-     * Returns an array of the assigned nodes for `slot`.
-     *
-     * 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.
+     * Returns the nodes assigned to `slot`. See
+     * {@link SlotQueryOptions.flatten}.
      */
     getAssignedNodes(slot: T, flatten?: boolean): Node[];
-    /**
-     * Returns an array of the assigned elements for `slot` with additional `options`.
-     *
-     * See {@link SlotQueryOptions.flatten} and {@link SlotQueryOptions.selector} for more information.
-     */
+    /** Returns the elements assigned to `slot`, as `options` selects them. */
     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.
+     * Returns the text content assigned to `slot`, trimmed and with collapsed
+     * whitespace.
      */
     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 - so a slot with
-     * fallback content always reports as having nodes. See {@link SlotQueryOptions.flatten}.
+     * Whether `slot` has assigned nodes. A flattened query counts fallback
+     * content, so a slot with fallback always reports nodes.
      */
     hasAssignedNodes(slot: T, flatten?: boolean): boolean;
-    /**
-     * Return whether `slot` has assigned elements accepting additional `options`.
-     *
-     * See {@link SlotQueryOptions.flatten} and {@link SlotQueryOptions.selector} for more information.
-     */
+    /** Whether `slot` has assigned elements, as `options` selects them. */
     hasAssignedElements(slot: T, options?: SlotQueryOptions): boolean;
     /** @internal */
-    handleEvent(event: Event): void;
-    /** @internal */
     hostConnected(): void;
     /** @internal */
     hostDisconnected(): void;
+    handleEvent(event: Event): void;
     /** @internal */
     hostUpdated(): void;
 }

package/internals/controllers/slot.js

@@ -50,6 +50,12 @@ class SlotController {
     hasAssignedElements(slot, options) {
         return !isEmpty(this.getAssignedElements(slot, options));
     }
+    hostConnected() {
+        this._host.renderRoot.addEventListener('slotchange', this);
+    }
+    hostDisconnected() {
+        this._host.renderRoot.removeEventListener('slotchange', this);
+    }
     handleEvent(event) {
         const slot = event.target;
         const name = slot.name;
@@ -64,12 +70,6 @@ class SlotController {
             this._host.requestUpdate();
         }
     }
-    hostConnected() {
-        this._host.renderRoot.addEventListener('slotchange', this);
-    }
-    hostDisconnected() {
-        this._host.renderRoot.removeEventListener('slotchange', this);
-    }
     hostUpdated() {
         if (!this._initialized && this._options.initial) {
             this._initialized = true;

package/internals/controllers/slot.js.map

@@ -1 +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"]}
+{"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\ntype SlotQueryOptions = {\n  /**\n   * Whether the query also returns the content of the descendant slots.\n   * Defaults to `false`.\n   *\n   * @remarks\n   * A flattened query also returns fallback content: a slot rendered as\n   * `<slot>${this.label}</slot>` reports `label` as assigned content,\n   * although the consumer projected nothing.\n   */\n  flatten?: boolean;\n  /** The CSS selector that filters the returned elements. */\n  selector?: string;\n};\n\ntype SlotChangeCallback<T> = (\n  parameters: SlotChangeCallbackParameters<T>\n) => void;\n\ntype SlotChangeCallbackParameters<T> = {\n  /** The name of the slot with the changed assigned nodes. */\n  slot: T;\n  isDefault: boolean;\n  /** Whether the callback runs for the first host update. */\n  isInitial: boolean;\n};\n\ntype SlotControllerOptions<T> = {\n  /** The slot names to observe. */\n  slots?: Iterable<T>;\n  /** Callback that runs when the assigned nodes of a slot change. */\n  onChange?: SlotChangeCallback<T>;\n  /** Whether `onChange` also runs once, after the first host update. */\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   * Finds the slot element with the given name.\n   *\n   * @remarks\n   * The result is cached, because the accessors below run from `render`. The\n   * cache serves only a connected slot. A query before the host creates its\n   * render root reports no slot and raises no 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 the nodes assigned to `slot`. See\n   * {@link SlotQueryOptions.flatten}.\n   */\n  public getAssignedNodes(slot: T, flatten = false): Node[] {\n    return this._getSlot(slot)?.assignedNodes({ flatten }) ?? [];\n  }\n\n  /** Returns the elements assigned to `slot`, as `options` selects them. */\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 text content assigned to `slot`, trimmed and with collapsed\n   * whitespace.\n   */\n  public getAssignedText(slot: T, flatten = false): string {\n    return normalizedTextContent(this.getAssignedNodes(slot, flatten));\n  }\n\n  /**\n   * Whether `slot` has assigned nodes. A flattened query counts fallback\n   * content, so a slot with fallback always reports nodes.\n   */\n  public hasAssignedNodes(slot: T, flatten = false): boolean {\n    return !isEmpty(this.getAssignedNodes(slot, flatten));\n  }\n\n  /** Whether `slot` has assigned elements, as `options` selects them. */\n  public hasAssignedElements(slot: T, options?: SlotQueryOptions): boolean {\n    return !isEmpty(this.getAssignedElements(slot, options));\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  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 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

@@ -1,96 +1,92 @@
 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.
+ * The events that a {@link ToggleController} sends. Include them, or a subset
+ * of them, in the event map of a host to document them.
  */
 export interface ToggleEventMap {
-    /** Emitted before opening. Cancelable - preventing it aborts the sequence. */
+    /** Sent before an open. Cancelable; a prevented event stops the sequence. */
     igcOpening: CustomEvent<unknown>;
-    /** Emitted after the host has opened and its transition has completed. */
+    /** Sent after the host opens and its transition ends. */
     igcOpened: CustomEvent<unknown>;
-    /** Emitted before closing. Cancelable - preventing it aborts the sequence. */
+    /** Sent before a close. Cancelable; a prevented event stops the sequence. */
     igcClosing: CustomEvent<unknown>;
-    /** Emitted after the host has closed and its transition has completed. */
+    /** Sent after the host closes and its transition ends. */
     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}.
+ * A toggleable host must give the `emitEvent` method of the event-emitter
+ * mixin. Extend {@link ../mixins/event-emitter.js#EventEmitterMixin | EventEmitterMixin}
+ * with the {@link ToggleEventMap}, or with a subset of it.
  */
 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.
+ * Runs the visual transition of the host to the requested state: it sets
+ * `open`, plays the animations and awaits the updates. A resolved `false`
+ * marks the transition as superseded, for example by a newer animation, and
+ * the controller then sends no 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.
+     * The host transition. Without one, the controller sets `host.open` itself
+     * and the transition always counts as complete.
      */
     transition?: ToggleTransitionFunction;
-    /** Factory for the `detail` payload of the emitted events. */
+    /** The factory for the `detail` payload of the 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.
+ * Implements the open and close sequence of every toggleable component.
  *
- * The host keeps its public `open` property, `show()`/`hide()`/`toggle()`
- * methods and event documentation, and delegates to the controller.
+ * @remarks
+ * The sequence stops when the host is already in the requested state, sends
+ * the cancelable `igcOpening` or `igcClosing` event, runs the host
+ * transition, awaits the host update, then sends `igcOpened` or `igcClosed`.
+ * The events run only when the caller asks for them.
  *
- * 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.
+ * The host keeps its public `open`, `show()`, `hide()` and `toggle()` members
+ * and delegates to the controller. Unlike the other controllers here, the
+ * host does not register it; it 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. */
+    /**
+     * The target of an operation in flight. A transition can set `host.open` at
+     * its end only.
+     */
     private _pending?;
-    /** Bumped per operation, so a superseded one can bail out instead of finishing. */
+    /** Incremented per operation. A superseded operation stops. */
     private _generation;
     constructor(host: ToggleHost, options?: ToggleControllerOptions);
     /**
-     * Events go through the host's `emitEvent` - it is the choke point
-     * consumers and framework wrappers observe.
+     * Sends the event through the host `emitEvent`. Consumers and framework
+     * wrappers observe that one method.
      */
     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.
+     * Opens the host, wrapped in the `igcOpening` and `igcOpened` events when
+     * `emitEvents` is true. Returns `false` when the host is already open or
+     * moves there, when the consumer canceled the opening event, when a later
+     * request supersedes this one, or when the transition reports an
+     * interruption.
      */
     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.
+     * Closes the host, wrapped in the `igcClosing` and `igcClosed` events when
+     * `emitEvents` is true. Returns `false` when the host is already closed or
+     * moves there, when the consumer canceled the closing event, when a later
+     * request supersedes this one, or when the transition reports an
+     * interruption.
      */
     hide(emitEvents?: boolean): Promise<boolean>;
-    /** Opens or closes the host based on its current state. */
+    /** Opens the host, or closes it, based on its current state. */
     toggle(emitEvents?: boolean): Promise<boolean>;
 }
-/** Creates and adds a {@link ToggleController} to the given host. */
+/** Creates a {@link ToggleController} for the given host. */
 export declare function addToggleController(host: ToggleHost, options?: ToggleControllerOptions): ToggleController;
 export type { ToggleController, ToggleControllerOptions, ToggleHost };

package/internals/controllers/toggle.js.map

@@ -1 +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"]}
+{"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 that a {@link ToggleController} sends. Include them, or a subset\n * of them, in the event map of a host to document them.\n */\nexport interface ToggleEventMap {\n  /** Sent before an open. Cancelable; a prevented event stops the sequence. */\n  igcOpening: CustomEvent<unknown>;\n  /** Sent after the host opens and its transition ends. */\n  igcOpened: CustomEvent<unknown>;\n  /** Sent before a close. Cancelable; a prevented event stops the sequence. */\n  igcClosing: CustomEvent<unknown>;\n  /** Sent after the host closes and its transition ends. */\n  igcClosed: CustomEvent<unknown>;\n}\n\n/**\n * A toggleable host must give the `emitEvent` method of the event-emitter\n * mixin. Extend {@link ../mixins/event-emitter.js#EventEmitterMixin | EventEmitterMixin}\n * with the {@link ToggleEventMap}, or with a subset of it.\n */\ntype ToggleHost = LitElement & {\n  open: boolean;\n  emitEvent(name: string, init?: CustomEventInit): boolean;\n};\n\n/**\n * Runs the visual transition of the host to the requested state: it sets\n * `open`, plays the animations and awaits the updates. A resolved `false`\n * marks the transition as superseded, for example by a newer animation, and\n * the controller then sends no trailing \"-ed\" event.\n */\ntype ToggleTransitionFunction = (open: boolean) => Promise<boolean> | boolean;\n\ntype ToggleControllerOptions = {\n  /**\n   * The host transition. Without one, the controller sets `host.open` itself\n   * and the transition always counts as complete.\n   */\n  transition?: ToggleTransitionFunction;\n  /** The factory for the `detail` payload of the events. */\n  detail?: () => unknown;\n};\n\n/**\n * Implements the open and close sequence of every toggleable component.\n *\n * @remarks\n * The sequence stops when the host is already in the requested state, sends\n * the cancelable `igcOpening` or `igcClosing` event, runs the host\n * transition, awaits the host update, then sends `igcOpened` or `igcClosed`.\n * The events run only when the caller asks for them.\n *\n * The host keeps its public `open`, `show()`, `hide()` and `toggle()` members\n * and delegates to the controller. Unlike the other controllers here, the\n * host does not register it; it has no life-cycle of its own.\n */\nclass ToggleController {\n  private readonly _host: ToggleHost;\n  private readonly _options: ToggleControllerOptions;\n\n  /**\n   * The target of an operation in flight. A transition can set `host.open` at\n   * its end only.\n   */\n  private _pending?: boolean;\n\n  /** Incremented per operation. A superseded operation stops. */\n  private _generation = 0;\n\n  constructor(host: ToggleHost, options?: ToggleControllerOptions) {\n    this._host = host;\n    this._options = { ...options };\n  }\n\n  /**\n   * Sends the event through the host `emitEvent`. Consumers and framework\n   * wrappers observe that one method.\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    // The init omits both keys instead of a falsy value. `emitEvent` then\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 is synchronous, so the state change and the\n    // `updateComplete` subscription stay in the microtask of the caller.\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 can take over while the update settles.\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 return the underlying promise instead of being `async`.\n   * An `async` wrapper costs extra microtask hops, which shift the timing of\n   * caller code, for example focus management, against `updateComplete`.\n   */\n\n  /**\n   * Opens the host, wrapped in the `igcOpening` and `igcOpened` events when\n   * `emitEvents` is true. Returns `false` when the host is already open or\n   * moves there, when the consumer canceled the opening event, when a later\n   * request supersedes this one, or when the transition reports an\n   * interruption.\n   */\n  public show(emitEvents = false): Promise<boolean> {\n    return this._setOpenState(true, emitEvents);\n  }\n\n  /**\n   * Closes the host, wrapped in the `igcClosing` and `igcClosed` events when\n   * `emitEvents` is true. Returns `false` when the host is already closed or\n   * moves there, when the consumer canceled the closing event, when a later\n   * request supersedes this one, or when the transition reports an\n   * interruption.\n   */\n  public hide(emitEvents = false): Promise<boolean> {\n    return this._setOpenState(false, emitEvents);\n  }\n\n  /** Opens the host, or closes it, 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 a {@link ToggleController} for 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.js.map

@@ -1 +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"]}
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/internals/date/compare.ts"],"names":[],"mappings":"AAKA,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":["/**\n * Compares two dates with the given comparator. Ignores the time portion\n * when `includeTime` is `false`, and the date portion when `includeDate` is\n * `false`.\n */\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

@@ -1,17 +1,20 @@
 import type { DateRangeValue } from '../../components/types.js';
-/** Whether `value` is a `Date` holding a valid time. */
+/** Returns whether `value` is a `Date` with 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. */
+/** Converts `value` to a `Date`, or `null` when empty or unparsable. */
 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.
+ * Converts a comma-separated string of ISO 8601 dates, or an array of dates
+ * and ISO 8601 strings, into an array of `Date` objects. Unparsable items
+ * are dropped.
  */
 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.
+ * Converts `value` to a `DateRangeValue`, parsing a string as JSON and
+ * truncating the time of both endpoints.
+ *
+ * @remarks
+ * Malformed input gives `null`, because this runs as an attribute converter.
  */
 export declare function convertToDateRange(value?: DateRangeValue | string | null): DateRangeValue | null;
 /** Converts a `Date` to an ISO 8601 string. */

package/internals/date/converters.js.map

@@ -1 +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"]}
+{"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 that starts with a four digit year. `Date` parses it. */\nconst ISO_DATE_PATTERN = /^\\d{4}/;\n\n/** Matches a time only string: `HH:MM`, with optional seconds and ms. */\nconst TIME_PATTERN = /^\\d{2}:\\d{2}/;\n\n/** Returns whether `value` is a `Date` with 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 `null` when empty or unparsable. */\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\n * and ISO 8601 strings, into an array of `Date` objects. Unparsable items\n * are dropped.\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\n * truncating the time of both endpoints.\n *\n * @remarks\n * Malformed input gives `null`, because 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/internals/date/model.d.ts

@@ -13,20 +13,19 @@ 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`. */
+/** Returns the {@link toCalendarDay} result of `date`, or `null` if empty. */
 export declare function toCalendarDayOrNull(date?: DayParameter | null): CalendarDay | null;
-/** Truncates the time portion of `date`, passing empty values through as `null`. */
+/** Truncates the time portion of `date`. An empty value gives `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.
+ * Yields the days between `start` and `end`, stepped by `unit`. Stops before
+ * `end`, unless `inclusive` is `true`.
  */
 export declare function calendarRange(options: CalendarRangeParams): Generator<CalendarDay, void, unknown>;
 export declare class CalendarDay {
     private readonly _date;
     /** Constructs and returns the current day. */
     static get today(): CalendarDay;
-    /** Constructs a new CalendarDay instance from a Date object. */
     static from(date: Date): CalendarDay;
     /**
      * Compares the date portion of two date objects.
@@ -40,18 +39,14 @@ export declare class CalendarDay {
      */
     static compare(first: DayParameter, second: DayParameter): number;
     constructor(args: CalendarDayParams);
-    /** Returns a copy of this instance. */
     clone(): CalendarDay;
     /** 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). */
     get day(): number;
-    /** Returns the full year. */
     get year(): number;
-    /** Returns the month. */
     get month(): number;
-    /** Returns the date */
     get date(): number;
     /** Returns the timestamp since epoch in milliseconds. */
     get timestamp(): number;
@@ -59,17 +54,15 @@ export declare class CalendarDay {
      * Returns the ISO 8601 week number.
      *
      * @remarks
-     * Week 1 is the week containing the first Thursday of the year.
-     * Weeks start on Monday. Some years can have 53 weeks.
+     * Week 1 holds the first Thursday of the year, weeks start on Monday, and
+     * a year can have 53 weeks.
      */
     get week(): number;
-    /** Returns the underlying native date instance. */
+    /** Returns a copy of the underlying native `Date` instance. */
     get native(): Date;
     /**
-     * Whether the current date is a weekend day.
-     *
-     * @remarks
-     * This is naive, since it does not account for locale specifics.
+     * Returns whether the current date is a weekend day. The check is naive
+     * and ignores locale specifics.
      */
     get weekend(): boolean;
     equalTo(value: DayParameter): boolean;