igniteui-webcomponents 7.2.3 → 7.3.0-beta.0

package/internals/utils/dom.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Returns whether an element has a Left-to-Right directionality.
+ */
+export declare function isLTR(element: HTMLElement): boolean;
+/**
+ * Resolves a CSS length to pixels in the context of `element`.
+ *
+ * A registered custom property computes to an absolute length, which lets the
+ * browser do the conversion for font, viewport and container relative units
+ * instead of them being read as raw numbers. Percentages are not lengths -
+ * resolve those against whatever basis applies to the property at hand.
+ *
+ * Returns 0 for percentages, for values that are not valid lengths, and where
+ * the resolution is unavailable - during server-side rendering, or without
+ * support for registered custom properties. Guessing from the raw token would
+ * read `5rem` as 5 pixels, so callers get an obvious zero instead.
+ *
+ * @example
+ * ```typescript
+ * resolveCssLength(element, '5rem'); // 80
+ * resolveCssLength(element, '2em'); // 2 x the element font size
+ * ```
+ */
+export declare function resolveCssLength(element: HTMLElement, value: string): number;
+export type IterNodesOptions<T = Node> = {
+    show?: keyof typeof NodeFilter;
+    filter?: (node: T) => boolean;
+};
+/**
+ * Iterates over the DOM subtree of `root` in document order, yielding the nodes
+ * matching the passed {@link IterNodesOptions | options}.
+ *
+ * @example
+ * ```typescript
+ * for (const button of iterNodes<HTMLButtonElement>(root, { show: 'SHOW_ELEMENT', filter: isButton })) { ... }
+ * ```
+ */
+export declare function iterNodes<T extends Node>(root: Node, options?: IterNodesOptions<T>): Generator<T>;
+/**
+ * Iterates over `node` and its ancestors, crossing shadow DOM boundaries.
+ *
+ * Shadow roots are traversed through their host, so only elements are yielded.
+ *
+ * @example
+ * ```typescript
+ * for (const ancestor of iterAncestors(element)) { ... }
+ * ```
+ */
+export declare function iterAncestors(node?: Node | null): Generator<Element>;
+/** Returns the root node (document or shadow root) of the given element. */
+export declare function getRoot(element: Element, options?: GetRootNodeOptions): Document | ShadowRoot;
+/** Returns the element with the given id in the root node of `root`, if any. */
+export declare function getElementByIdFromRoot(root: HTMLElement, id: string): HTMLElement | null;
+export declare function isElement(node: unknown): node is Element;
+export declare function isDocument(node: unknown): node is Document;
+/** Returns the center x/y coordinate of a given element. */
+export declare function getCenterPoint(element: Element): {
+    x: number;
+    y: number;
+};
+/** Returns whether the given client coordinates lie within the bounding box of the element. */
+export declare function isPointInsideElement(element: Element, x: number, y: number): boolean;
+/** Returns the scale factor of a given element based on its bounding client rect and offset dimensions. */
+export declare function getScaleFactor(element: HTMLElement): {
+    x: number;
+    y: number;
+};
+/** Rounds a CSS pixel value to the closest device-pixel boundary to avoid blurry rendering. */
+export declare function roundByDPR(value: number): number;
+/** Null-safe `Element.scrollIntoView` defaulting to the nearest block/inline position. */
+export declare function scrollIntoView(element?: HTMLElement | null, config?: ScrollIntoViewOptions): void;
+/** Applies the given CSS declarations to the inline style of the element. */
+export declare function setStyles(element: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
+/** Returns whether the given input has at least one selected file. */
+export declare function hasFiles(input: {
+    files: FileList | null;
+}): boolean;
+/**
+ * Returns whether the given element is currently an open popover or not.
+ * This is useful to determine if the popover is open without relying on the `open` property, which may not be in sync with the actual popover state if the opening/closing animations are still running.
+ * Note: This function only works for elements that use the `:popover-open` pseudo-class to indicate
+ */
+export declare function isPopoverOpen(element?: Element): boolean;
+/**
+ * Returns whether the given element, or any of its ancestors across shadow DOM
+ * boundaries, is positioned as `sticky`.
+ */
+export declare function hasStickyAncestor(element: Element): boolean;
+/**
+ * Returns the nearest visible ancestor of a given node, traversing through shadow DOM boundaries if necessary. If no visible ancestor is found, returns null.
+ */
+export declare function getVisibleAncestor(startNode: Node): HTMLElement | null;

package/internals/utils/dom.js

@@ -0,0 +1,143 @@
+import { isServer } from 'lit';
+import { asNumber, numberInRangeInclusive } from './math.js';
+import { merge } from './objects.js';
+import { isDefined } from './types.js';
+export function isLTR(element) {
+    return element.matches(':dir(ltr)');
+}
+const LENGTH_PROPERTY = '--igc-resolved-length';
+const SUPPORTS_REGISTERED_PROPERTIES = !isServer && typeof CSS !== 'undefined' && 'registerProperty' in CSS;
+let lengthPropertyUsable;
+function canResolveLengths() {
+    if (lengthPropertyUsable === undefined) {
+        lengthPropertyUsable = SUPPORTS_REGISTERED_PROPERTIES;
+        if (lengthPropertyUsable) {
+            try {
+                CSS.registerProperty({
+                    name: LENGTH_PROPERTY,
+                    syntax: '<length>',
+                    inherits: false,
+                    initialValue: '0px',
+                });
+            }
+            catch {
+            }
+        }
+    }
+    return lengthPropertyUsable;
+}
+export function resolveCssLength(element, value) {
+    if (!canResolveLengths()) {
+        return 0;
+    }
+    const { style } = element;
+    const previous = style.getPropertyValue(LENGTH_PROPERTY);
+    const priority = style.getPropertyPriority(LENGTH_PROPERTY);
+    style.setProperty(LENGTH_PROPERTY, value);
+    const resolved = getComputedStyle(element).getPropertyValue(LENGTH_PROPERTY);
+    if (previous) {
+        style.setProperty(LENGTH_PROPERTY, previous, priority);
+    }
+    else {
+        style.removeProperty(LENGTH_PROPERTY);
+    }
+    return asNumber(resolved);
+}
+function createNodeFilter(predicate) {
+    return {
+        acceptNode: (node) => predicate(node) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP,
+    };
+}
+export function* iterNodes(root, options) {
+    if (!isDefined(globalThis.document)) {
+        return;
+    }
+    const whatToShow = options?.show
+        ? NodeFilter[options.show]
+        : NodeFilter.SHOW_ALL;
+    const nodeFilter = options?.filter
+        ? createNodeFilter(options.filter)
+        : undefined;
+    const treeWalker = document.createTreeWalker(root, whatToShow, nodeFilter);
+    while (treeWalker.nextNode()) {
+        yield treeWalker.currentNode;
+    }
+}
+export function* iterAncestors(node) {
+    let current = node;
+    while (current) {
+        if (isElement(current)) {
+            yield current;
+        }
+        current = current instanceof ShadowRoot ? current.host : current.parentNode;
+    }
+}
+export function getRoot(element, options) {
+    return element.getRootNode(options);
+}
+export function getElementByIdFromRoot(root, id) {
+    return getRoot(root).getElementById(id);
+}
+export function isElement(node) {
+    return node instanceof Node && node.nodeType === Node.ELEMENT_NODE;
+}
+export function isDocument(node) {
+    return node instanceof Node && node.nodeType === Node.DOCUMENT_NODE;
+}
+export function getCenterPoint(element) {
+    const { left, top, width, height } = element.getBoundingClientRect();
+    return {
+        x: left + width * 0.5,
+        y: top + height * 0.5,
+    };
+}
+export function isPointInsideElement(element, x, y) {
+    const { left, right, top, bottom } = element.getBoundingClientRect();
+    return (numberInRangeInclusive(x, left, right) &&
+        numberInRangeInclusive(y, top, bottom));
+}
+export function getScaleFactor(element) {
+    const { offsetWidth, offsetHeight } = element;
+    const { width, height } = element.getBoundingClientRect();
+    return { x: offsetWidth / width || 1, y: offsetHeight / height || 1 };
+}
+export function roundByDPR(value) {
+    const dpr = globalThis.devicePixelRatio || 1;
+    return Math.round(value * dpr) / dpr;
+}
+export function scrollIntoView(element, config) {
+    if (!element) {
+        return;
+    }
+    element.scrollIntoView(Object.assign({
+        behavior: 'auto',
+        block: 'nearest',
+        inline: 'nearest',
+    }, config));
+}
+export function setStyles(element, styles) {
+    merge(element.style, styles);
+}
+export function hasFiles(input) {
+    return input.files != null && input.files.length > 0;
+}
+export function isPopoverOpen(element) {
+    return element?.matches(':popover-open') ?? false;
+}
+export function hasStickyAncestor(element) {
+    for (const ancestor of iterAncestors(element)) {
+        if (getComputedStyle(ancestor).position === 'sticky') {
+            return true;
+        }
+    }
+    return false;
+}
+export function getVisibleAncestor(startNode) {
+    for (const ancestor of iterAncestors(startNode.parentNode)) {
+        if (ancestor instanceof HTMLElement && ancestor.checkVisibility()) {
+            return ancestor;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=dom.js.map

package/internals/utils/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../src/internals/utils/dom.ts"],"names":[],"mappings":"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","sourcesContent":["import { isServer } from 'lit';\nimport { asNumber, numberInRangeInclusive } from './math.js';\nimport { merge } from './objects.js';\nimport { isDefined } from './types.js';\n\n/**\n * Returns whether an element has a Left-to-Right directionality.\n */\nexport function isLTR(element: HTMLElement) {\n  return element.matches(':dir(ltr)');\n}\n\nconst LENGTH_PROPERTY = '--igc-resolved-length';\n\nconst SUPPORTS_REGISTERED_PROPERTIES =\n  !isServer && typeof CSS !== 'undefined' && 'registerProperty' in CSS;\n\nlet lengthPropertyUsable: boolean | undefined;\n\nfunction canResolveLengths(): boolean {\n  if (lengthPropertyUsable === undefined) {\n    lengthPropertyUsable = SUPPORTS_REGISTERED_PROPERTIES;\n\n    if (lengthPropertyUsable) {\n      try {\n        CSS.registerProperty({\n          name: LENGTH_PROPERTY,\n          syntax: '<length>',\n          inherits: false,\n          initialValue: '0px',\n        });\n      } catch {\n        // The descriptor is a constant, so the only realistic rejection is a\n        // duplicate registration from another bundle instance - which leaves\n        // the property just as usable.\n      }\n    }\n  }\n\n  return lengthPropertyUsable;\n}\n\n/**\n * Resolves a CSS length to pixels in the context of `element`.\n *\n * A registered custom property computes to an absolute length, which lets the\n * browser do the conversion for font, viewport and container relative units\n * instead of them being read as raw numbers. Percentages are not lengths -\n * resolve those against whatever basis applies to the property at hand.\n *\n * Returns 0 for percentages, for values that are not valid lengths, and where\n * the resolution is unavailable - during server-side rendering, or without\n * support for registered custom properties. Guessing from the raw token would\n * read `5rem` as 5 pixels, so callers get an obvious zero instead.\n *\n * @example\n * ```typescript\n * resolveCssLength(element, '5rem'); // 80\n * resolveCssLength(element, '2em'); // 2 x the element font size\n * ```\n */\nexport function resolveCssLength(element: HTMLElement, value: string): number {\n  if (!canResolveLengths()) {\n    return 0;\n  }\n\n  const { style } = element;\n  const previous = style.getPropertyValue(LENGTH_PROPERTY);\n  const priority = style.getPropertyPriority(LENGTH_PROPERTY);\n\n  style.setProperty(LENGTH_PROPERTY, value);\n  const resolved = getComputedStyle(element).getPropertyValue(LENGTH_PROPERTY);\n\n  // Restore rather than remove - the caller may be using the property itself.\n  if (previous) {\n    style.setProperty(LENGTH_PROPERTY, previous, priority);\n  } else {\n    style.removeProperty(LENGTH_PROPERTY);\n  }\n\n  return asNumber(resolved);\n}\n\nexport type IterNodesOptions<T = Node> = {\n  show?: keyof typeof NodeFilter;\n  filter?: (node: T) => boolean;\n};\n\nfunction createNodeFilter<T extends Node>(predicate: (node: T) => boolean) {\n  return {\n    acceptNode: (node: T): number =>\n      predicate(node) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP,\n  };\n}\n\n/**\n * Iterates over the DOM subtree of `root` in document order, yielding the nodes\n * matching the passed {@link IterNodesOptions | options}.\n *\n * @example\n * ```typescript\n * for (const button of iterNodes<HTMLButtonElement>(root, { show: 'SHOW_ELEMENT', filter: isButton })) { ... }\n * ```\n */\nexport function* iterNodes<T extends Node>(\n  root: Node,\n  options?: IterNodesOptions<T>\n): Generator<T> {\n  if (!isDefined(globalThis.document)) {\n    return;\n  }\n\n  const whatToShow = options?.show\n    ? NodeFilter[options.show]\n    : NodeFilter.SHOW_ALL;\n\n  const nodeFilter = options?.filter\n    ? createNodeFilter(options.filter)\n    : undefined;\n\n  const treeWalker = document.createTreeWalker(root, whatToShow, nodeFilter);\n\n  while (treeWalker.nextNode()) {\n    yield treeWalker.currentNode as T;\n  }\n}\n\n/**\n * Iterates over `node` and its ancestors, crossing shadow DOM boundaries.\n *\n * Shadow roots are traversed through their host, so only elements are yielded.\n *\n * @example\n * ```typescript\n * for (const ancestor of iterAncestors(element)) { ... }\n * ```\n */\nexport function* iterAncestors(node?: Node | null): Generator<Element> {\n  let current: Node | null | undefined = node;\n\n  while (current) {\n    if (isElement(current)) {\n      yield current;\n    }\n\n    current = current instanceof ShadowRoot ? current.host : current.parentNode;\n  }\n}\n\n/** Returns the root node (document or shadow root) of the given element. */\nexport function getRoot(\n  element: Element,\n  options?: GetRootNodeOptions\n): Document | ShadowRoot {\n  return element.getRootNode(options) as Document | ShadowRoot;\n}\n\n/** Returns the element with the given id in the root node of `root`, if any. */\nexport function getElementByIdFromRoot(root: HTMLElement, id: string) {\n  return getRoot(root).getElementById(id);\n}\n\nexport function isElement(node: unknown): node is Element {\n  return node instanceof Node && node.nodeType === Node.ELEMENT_NODE;\n}\n\nexport function isDocument(node: unknown): node is Document {\n  return node instanceof Node && node.nodeType === Node.DOCUMENT_NODE;\n}\n\n/** Returns the center x/y coordinate of a given element. */\nexport function getCenterPoint(element: Element): { x: number; y: number } {\n  const { left, top, width, height } = element.getBoundingClientRect();\n\n  return {\n    x: left + width * 0.5,\n    y: top + height * 0.5,\n  };\n}\n\n/** Returns whether the given client coordinates lie within the bounding box of the element. */\nexport function isPointInsideElement(\n  element: Element,\n  x: number,\n  y: number\n): boolean {\n  const { left, right, top, bottom } = element.getBoundingClientRect();\n  return (\n    numberInRangeInclusive(x, left, right) &&\n    numberInRangeInclusive(y, top, bottom)\n  );\n}\n\n/** Returns the scale factor of a given element based on its bounding client rect and offset dimensions. */\nexport function getScaleFactor(element: HTMLElement): { x: number; y: number } {\n  const { offsetWidth, offsetHeight } = element;\n  const { width, height } = element.getBoundingClientRect();\n  return { x: offsetWidth / width || 1, y: offsetHeight / height || 1 };\n}\n\n/** Rounds a CSS pixel value to the closest device-pixel boundary to avoid blurry rendering. */\nexport function roundByDPR(value: number): number {\n  const dpr = globalThis.devicePixelRatio || 1;\n  return Math.round(value * dpr) / dpr;\n}\n\n/** Null-safe `Element.scrollIntoView` defaulting to the nearest block/inline position. */\nexport function scrollIntoView(\n  element?: HTMLElement | null,\n  config?: ScrollIntoViewOptions\n): void {\n  if (!element) {\n    return;\n  }\n\n  element.scrollIntoView(\n    Object.assign(\n      {\n        behavior: 'auto',\n        block: 'nearest',\n        inline: 'nearest',\n      },\n      config\n    )\n  );\n}\n\n/** Applies the given CSS declarations to the inline style of the element. */\nexport function setStyles(\n  element: HTMLElement,\n  styles: Partial<CSSStyleDeclaration>\n): void {\n  merge(element.style, styles);\n}\n\n/** Returns whether the given input has at least one selected file. */\nexport function hasFiles(input: { files: FileList | null }): boolean {\n  return input.files != null && input.files.length > 0;\n}\n\n/**\n * Returns whether the given element is currently an open popover or not.\n * This is useful to determine if the popover is open without relying on the `open` property, which may not be in sync with the actual popover state if the opening/closing animations are still running.\n * Note: This function only works for elements that use the `:popover-open` pseudo-class to indicate\n */\nexport function isPopoverOpen(element?: Element): boolean {\n  return element?.matches(':popover-open') ?? false;\n}\n\n/**\n * Returns whether the given element, or any of its ancestors across shadow DOM\n * boundaries, is positioned as `sticky`.\n */\nexport function hasStickyAncestor(element: Element): boolean {\n  for (const ancestor of iterAncestors(element)) {\n    if (getComputedStyle(ancestor).position === 'sticky') {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Returns the nearest visible ancestor of a given node, traversing through shadow DOM boundaries if necessary. If no visible ancestor is found, returns null.\n */\nexport function getVisibleAncestor(startNode: Node): HTMLElement | null {\n  for (const ancestor of iterAncestors(startNode.parentNode)) {\n    if (ancestor instanceof HTMLElement && ancestor.checkVisibility()) {\n      return ancestor;\n    }\n  }\n\n  return null;\n}\n"]}

package/internals/utils/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Finds the first element in the event's composed path that matches the provided predicate, which can be either a string selector or a function.
+ *
+ * @param predicate - A string representing a CSS selector or a function that takes an Element and returns a boolean indicating a match.
+ * @param event - The event whose composed path will be searched for the matching element.
+ * @returns The first Element that matches the predicate, or undefined if no match is found.
+ *
+ * @example
+ * ```typescript
+ * // Using a string selector
+ * const button = getElementFromPath('button', event);
+ * ```
+ * ```typescript
+ * // Using a predicate function
+ * const customElement = getElementFromPath((el) => el.tagName === 'MY-ELEMENT', event);
+ * ```
+ */
+export declare function getElementFromPath<K extends keyof HTMLElementTagNameMap>(predicate: K, event: Event): HTMLElementTagNameMap[K] | undefined;
+export declare function getElementFromPath<T extends Element>(predicate: string | ((element: Element) => boolean), event: Event): T | undefined;
+/** Reusable event listener that just stops the propagation of the event. */
+export declare function stopPropagation(event: Event): void;
+/**
+ * Returns whether focus has moved outside of the given host element for
+ * a `focusout`/`blur` event, that is the element gaining focus is not
+ * a descendant of the host.
+ */
+export declare function focusLeftHost(host: Element, event: FocusEvent): boolean;
+/**
+ * Adds an event listener that holds only a weak reference to the passed
+ * `listener`, thus not preventing it from being garbage collected.
+ */
+export declare function addWeakEventListener(element: Element, event: string, listener: EventListenerOrEventListenerObject, options?: AddEventListenerOptions | boolean): void;
+type EventTypeOf<T extends keyof HTMLElementEventMap | keyof WindowEventMap> = (HTMLElementEventMap & WindowEventMap)[T];
+/**
+ * Safely adds an event listener to an HTMLElement, automatically handling
+ * server-side rendering environments by doing nothing if `isServer` is true.
+ * This function also correctly binds the `handler`'s `this` context to the `target` element
+ * and ensures proper event type inference.
+ */
+export declare function addSafeEventListener<E extends keyof HTMLElementEventMap | keyof WindowEventMap>(target: HTMLElement, eventName: E, handler: (event: EventTypeOf<E>) => unknown, options?: boolean | AddEventListenerOptions): void;
+export {};

package/internals/utils/events.js

@@ -0,0 +1,37 @@
+import { isServer } from 'lit';
+import { isElement } from './dom.js';
+import { isEventListenerObject, isString } from './types.js';
+export function getElementFromPath(predicate, event) {
+    const func = isString(predicate)
+        ? (e) => e.matches(predicate)
+        : (e) => predicate(e);
+    return Iterator.from(event.composedPath()).find((item) => isElement(item) && func(item));
+}
+export function stopPropagation(event) {
+    event.stopPropagation();
+}
+export function focusLeftHost(host, event) {
+    return !host.contains(event.relatedTarget);
+}
+export function addWeakEventListener(element, event, listener, options) {
+    const weakRef = new WeakRef(listener);
+    const wrapped = (evt) => {
+        const handler = weakRef.deref();
+        if (!handler) {
+            element.removeEventListener(event, wrapped, options);
+            return;
+        }
+        return isEventListenerObject(handler)
+            ? handler.handleEvent(evt)
+            : handler(evt);
+    };
+    element.addEventListener(event, wrapped, options);
+}
+export function addSafeEventListener(target, eventName, handler, options) {
+    if (isServer) {
+        return;
+    }
+    const boundHandler = (event) => handler.call(target, event);
+    target.addEventListener(eventName, boundHandler, options);
+}
+//# sourceMappingURL=events.js.map

package/internals/utils/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/internals/utils/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2B7D,MAAM,UAAU,kBAAkB,CAChC,SAAmD,EACnD,KAAY;IAEZ,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC;QAC9B,CAAC,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QACtC,CAAC,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAEjC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,IAAI,CAC7C,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CACjB,CAAC;AAC3B,CAAC;AAGD,MAAM,UAAU,eAAe,CAAC,KAAY;IAC1C,KAAK,CAAC,eAAe,EAAE,CAAC;AAC1B,CAAC;AAOD,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,KAAiB;IAC5D,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,aAA4B,CAAC,CAAC;AAC5D,CAAC;AAMD,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,KAAa,EACb,QAA4C,EAC5C,OAA2C;IAE3C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;QAEhC,IAAI,CAAC,OAAO,EAAE,CAAC;YAEb,OAAO,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QAED,OAAO,qBAAqB,CAAC,OAAO,CAAC;YACnC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC;YAC1B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAWD,MAAM,UAAU,oBAAoB,CAGlC,MAAmB,EACnB,SAAY,EACZ,OAA2C,EAC3C,OAA2C;IAE3C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,MAAM,YAAY,GAAG,CAAC,KAAY,EAAE,EAAE,CACpC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAuB,CAAC,CAAC;IAEhD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;AAC5D,CAAC","sourcesContent":["import { isServer } from 'lit';\nimport { isElement } from './dom.js';\nimport { isEventListenerObject, isString } from './types.js';\n\n/**\n * Finds the first element in the event's composed path that matches the provided predicate, which can be either a string selector or a function.\n *\n * @param predicate - A string representing a CSS selector or a function that takes an Element and returns a boolean indicating a match.\n * @param event - The event whose composed path will be searched for the matching element.\n * @returns The first Element that matches the predicate, or undefined if no match is found.\n *\n * @example\n * ```typescript\n * // Using a string selector\n * const button = getElementFromPath('button', event);\n * ```\n * ```typescript\n * // Using a predicate function\n * const customElement = getElementFromPath((el) => el.tagName === 'MY-ELEMENT', event);\n * ```\n */\nexport function getElementFromPath<K extends keyof HTMLElementTagNameMap>(\n  predicate: K,\n  event: Event\n): HTMLElementTagNameMap[K] | undefined;\nexport function getElementFromPath<T extends Element>(\n  predicate: string | ((element: Element) => boolean),\n  event: Event\n): T | undefined;\nexport function getElementFromPath(\n  predicate: string | ((element: Element) => boolean),\n  event: Event\n) {\n  const func = isString(predicate)\n    ? (e: Element) => e.matches(predicate)\n    : (e: Element) => predicate(e);\n\n  return Iterator.from(event.composedPath()).find(\n    (item) => isElement(item) && func(item)\n  ) as Element | undefined;\n}\n\n/** Reusable event listener that just stops the propagation of the event. */\nexport function stopPropagation(event: Event): void {\n  event.stopPropagation();\n}\n\n/**\n * Returns whether focus has moved outside of the given host element for\n * a `focusout`/`blur` event, that is the element gaining focus is not\n * a descendant of the host.\n */\nexport function focusLeftHost(host: Element, event: FocusEvent): boolean {\n  return !host.contains(event.relatedTarget as Node | null);\n}\n\n/**\n * Adds an event listener that holds only a weak reference to the passed\n * `listener`, thus not preventing it from being garbage collected.\n */\nexport function addWeakEventListener(\n  element: Element,\n  event: string,\n  listener: EventListenerOrEventListenerObject,\n  options?: AddEventListenerOptions | boolean\n): void {\n  const weakRef = new WeakRef(listener);\n  const wrapped = (evt: Event) => {\n    const handler = weakRef.deref();\n\n    if (!handler) {\n      // The listener has been garbage collected - detach the wrapper as well\n      element.removeEventListener(event, wrapped, options);\n      return;\n    }\n\n    return isEventListenerObject(handler)\n      ? handler.handleEvent(evt)\n      : handler(evt);\n  };\n\n  element.addEventListener(event, wrapped, options);\n}\n\ntype EventTypeOf<T extends keyof HTMLElementEventMap | keyof WindowEventMap> =\n  (HTMLElementEventMap & WindowEventMap)[T];\n\n/**\n * Safely adds an event listener to an HTMLElement, automatically handling\n * server-side rendering environments by doing nothing if `isServer` is true.\n * This function also correctly binds the `handler`'s `this` context to the `target` element\n * and ensures proper event type inference.\n */\nexport function addSafeEventListener<\n  E extends keyof HTMLElementEventMap | keyof WindowEventMap,\n>(\n  target: HTMLElement,\n  eventName: E,\n  handler: (event: EventTypeOf<E>) => unknown,\n  options?: boolean | AddEventListenerOptions\n): void {\n  if (isServer) {\n    return;\n  }\n\n  const boundHandler = (event: Event) =>\n    handler.call(target, event as EventTypeOf<E>);\n\n  target.addEventListener(eventName, boundHandler, options);\n}\n"]}

package/internals/utils/lit.d.ts

@@ -0,0 +1,8 @@
+import { type TemplateResult } from 'lit';
+/**
+ * Similar to Lit's `ifDefined` directive except one can check `assertion`
+ * and bind a different `value` through this wrapper.
+ */
+export declare function bindIf<T>(assertion: unknown, value: T): NonNullable<T>;
+/** @internal */
+export declare function trimmedHtml(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;

package/internals/utils/lit.js

@@ -0,0 +1,15 @@
+import { html, nothing } from 'lit';
+export function bindIf(assertion, value) {
+    return assertion
+        ? (value ?? nothing)
+        : nothing;
+}
+const trimmedCache = new WeakMap();
+export function trimmedHtml(strings, ...values) {
+    if (!trimmedCache.has(strings)) {
+        const trimmedStrings = strings.map((s) => s.trim().replaceAll('\n', ''));
+        trimmedCache.set(strings, Object.assign([...trimmedStrings], { raw: [...strings.raw] }));
+    }
+    return html(trimmedCache.get(strings), ...values);
+}
+//# sourceMappingURL=lit.js.map

package/internals/utils/lit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lit.js","sourceRoot":"","sources":["../../../src/internals/utils/lit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAuB,MAAM,KAAK,CAAC;AAMzD,MAAM,UAAU,MAAM,CAAI,SAAkB,EAAE,KAAQ;IACpD,OAAO,SAAS;QACd,CAAC,CAAC,CAAC,KAAK,IAAK,OAA0B,CAAC;QACxC,CAAC,CAAE,OAA0B,CAAC;AAClC,CAAC;AAED,MAAM,YAAY,GAAG,IAAI,OAAO,EAA8C,CAAC;AAG/E,MAAM,UAAU,WAAW,CACzB,OAA6B,EAC7B,GAAG,MAAiB;IAEpB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QACzE,YAAY,CAAC,GAAG,CACd,OAAO,EACP,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,cAAc,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAE,EAAE,GAAG,MAAM,CAAC,CAAC;AACrD,CAAC","sourcesContent":["import { html, nothing, type TemplateResult } from 'lit';\n\n/**\n * Similar to Lit's `ifDefined` directive except one can check `assertion`\n * and bind a different `value` through this wrapper.\n */\nexport function bindIf<T>(assertion: unknown, value: T): NonNullable<T> {\n  return assertion\n    ? (value ?? (nothing as NonNullable<T>))\n    : (nothing as NonNullable<T>);\n}\n\nconst trimmedCache = new WeakMap<TemplateStringsArray, TemplateStringsArray>();\n\n/** @internal */\nexport function trimmedHtml(\n  strings: TemplateStringsArray,\n  ...values: unknown[]\n): TemplateResult {\n  if (!trimmedCache.has(strings)) {\n    const trimmedStrings = strings.map((s) => s.trim().replaceAll('\\n', ''));\n    trimmedCache.set(\n      strings,\n      Object.assign([...trimmedStrings], { raw: [...strings.raw] })\n    );\n  }\n\n  return html(trimmedCache.get(strings)!, ...values);\n}\n"]}

package/internals/utils/math.d.ts

@@ -0,0 +1,50 @@
+/** Returns `part` as a percentage of `whole`. */
+export declare function asPercent(part: number, whole: number): number;
+/** Clamps the given number between the min and max bounds (inclusive). */
+export declare function clamp(number: number, min: number, max: number): number;
+/** Returns the number of decimal places of the given number. */
+export declare function numberOfDecimals(number: number): number;
+/**
+ * Rounds a number to the given order of magnitude (number of decimal places).
+ *
+ * @example
+ * ```typescript
+ * roundPrecise(3.14159, 2); // 3.14
+ * ```
+ */
+export declare function roundPrecise(number: number, magnitude?: number): number;
+/** Returns whether the given value lies between the min and max bounds (inclusive). */
+export declare function numberInRangeInclusive(value: number, min: number, max: number): boolean;
+/**
+ * Parse the passed `value` as a number or return the `fallback` if it can't be done.
+ *
+ * @example
+ * ```typescript
+ * asNumber('5'); // 5
+ * asNumber('3.14'); // 3.14
+ * asNumber('five'); // 0
+ * asNumber('five', 5); // 5
+ * asNumber(undefined, 10); // 10
+ * asNumber(null, 10); // 10
+ * asNumber(NaN, 10); // 10
+ * asNumber(Infinity, 10); // 10
+ * asNumber(-Infinity, 10); // 10
+ * ```
+ */
+export declare function asNumber(value: unknown, fallback?: number): number;
+/**
+ * Returns the value wrapped between the min and max bounds.
+ *
+ * If the value is greater than max, returns the min and vice-versa.
+ * If the value is between the bounds, it is returned unchanged.
+ *
+ * @example
+ * ```typescript
+ * wrap(1, 4, 2); // 2
+ * wrap(1, 4, 5); // 1
+ * wrap(1, 4, -1); // 4
+ * ```
+ */
+export declare function wrap(min: number, max: number, value: number): number;
+/** Euclidean modulo — like `%` but the result always has the sign of the divisor. */
+export declare function modulo(n: number, d: number): number;

package/internals/utils/math.js

@@ -0,0 +1,38 @@
+export function asPercent(part, whole) {
+    return (part / whole) * 100;
+}
+export function clamp(number, min, max) {
+    return Math.max(min, Math.min(number, max));
+}
+export function numberOfDecimals(number) {
+    if (!Number.isFinite(number) || Number.isInteger(number)) {
+        return 0;
+    }
+    const [mantissa, exponent] = number.toString().split('e-');
+    const decimals = mantissa.split('.')[1]?.length ?? 0;
+    return exponent ? decimals + Number(exponent) : decimals;
+}
+export function roundPrecise(number, magnitude = 1) {
+    const factor = 10 ** magnitude;
+    return Math.round(number * factor) / factor;
+}
+export function numberInRangeInclusive(value, min, max) {
+    return value >= min && value <= max;
+}
+export function asNumber(value, fallback = 0) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function wrap(min, max, value) {
+    if (value < min) {
+        return max;
+    }
+    if (value > max) {
+        return min;
+    }
+    return value;
+}
+export function modulo(n, d) {
+    return ((n % d) + d) % d;
+}
+//# sourceMappingURL=math.js.map

package/internals/utils/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../../../src/internals/utils/math.ts"],"names":[],"mappings":"AACA,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AAC9B,CAAC;AAGD,MAAM,UAAU,KAAK,CAAC,MAAc,EAAE,GAAW,EAAE,GAAW;IAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC9C,CAAC;AAGD,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;IAGD,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;IAErD,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC;AAUD,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,SAAS,GAAG,CAAC;IACxD,MAAM,MAAM,GAAG,EAAE,IAAI,SAAS,CAAC;IAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAC9C,CAAC;AAGD,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,GAAW,EACX,GAAW;IAEX,OAAO,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC;AACtC,CAAC;AAkBD,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,QAAQ,GAAG,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAe,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC;AAeD,MAAM,UAAU,IAAI,CAAC,GAAW,EAAE,GAAW,EAAE,KAAa;IAC1D,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAGD,MAAM,UAAU,MAAM,CAAC,CAAS,EAAE,CAAS;IACzC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC","sourcesContent":["/** Returns `part` as a percentage of `whole`. */\nexport function asPercent(part: number, whole: number): number {\n  return (part / whole) * 100;\n}\n\n/** Clamps the given number between the min and max bounds (inclusive). */\nexport function clamp(number: number, min: number, max: number): number {\n  return Math.max(min, Math.min(number, max));\n}\n\n/** Returns the number of decimal places of the given number. */\nexport function numberOfDecimals(number: number): number {\n  if (!Number.isFinite(number) || Number.isInteger(number)) {\n    return 0;\n  }\n\n  // Exponential notation, e.g. `1.5e-7` -> 1 mantissa decimal + 7 exponent places\n  const [mantissa, exponent] = number.toString().split('e-');\n  const decimals = mantissa.split('.')[1]?.length ?? 0;\n\n  return exponent ? decimals + Number(exponent) : decimals;\n}\n\n/**\n * Rounds a number to the given order of magnitude (number of decimal places).\n *\n * @example\n * ```typescript\n * roundPrecise(3.14159, 2); // 3.14\n * ```\n */\nexport function roundPrecise(number: number, magnitude = 1): number {\n  const factor = 10 ** magnitude;\n  return Math.round(number * factor) / factor;\n}\n\n/** Returns whether the given value lies between the min and max bounds (inclusive). */\nexport function numberInRangeInclusive(\n  value: number,\n  min: number,\n  max: number\n) {\n  return value >= min && value <= max;\n}\n\n/**\n * Parse the passed `value` as a number or return the `fallback` if it can't be done.\n *\n * @example\n * ```typescript\n * asNumber('5'); // 5\n * asNumber('3.14'); // 3.14\n * asNumber('five'); // 0\n * asNumber('five', 5); // 5\n * asNumber(undefined, 10); // 10\n * asNumber(null, 10); // 10\n * asNumber(NaN, 10); // 10\n * asNumber(Infinity, 10); // 10\n * asNumber(-Infinity, 10); // 10\n * ```\n */\nexport function asNumber(value: unknown, fallback = 0): number {\n  const parsed = Number.parseFloat(value as string);\n  return Number.isFinite(parsed) ? parsed : fallback;\n}\n\n/**\n * Returns the value wrapped between the min and max bounds.\n *\n * If the value is greater than max, returns the min and vice-versa.\n * If the value is between the bounds, it is returned unchanged.\n *\n * @example\n * ```typescript\n * wrap(1, 4, 2); // 2\n * wrap(1, 4, 5); // 1\n * wrap(1, 4, -1); // 4\n * ```\n */\nexport function wrap(min: number, max: number, value: number) {\n  if (value < min) {\n    return max;\n  }\n  if (value > max) {\n    return min;\n  }\n\n  return value;\n}\n\n/** Euclidean modulo — like `%` but the result always has the sign of the divisor. */\nexport function modulo(n: number, d: number) {\n  return ((n % d) + d) % d;\n}\n"]}

package/internals/utils/objects.d.ts

@@ -0,0 +1,25 @@
+/** Pairs currently being compared, so a cycle terminates without swallowing real differences. */
+type Visited = WeakMap<object, WeakSet<object>>;
+/**
+ * Performs a deep structural equality check between two values, handling
+ * arrays, Maps, Sets, RegExps, POJOs and circular references.
+ */
+export declare function equal<T>(a: unknown, b: T, visited?: Visited): boolean;
+/**
+ * Merges the properties of `source` into `target` performing a recursive deep merge over POJOs and arrays.
+ *
+ * @remarks
+ * This function mutates the `target` object.
+ * If that is not the desired outcome, see {@link toMerged} for another approach.
+ */
+export declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
+/**
+ * Just like {@link merge} but it does not mutate the `target` object instead
+ * mutating a structured clone of it.
+ *
+ * @remarks
+ * Since it relies on `structuredClone`, the `target` must not contain
+ * non-cloneable values such as functions, DOM nodes or class instances.
+ */
+export declare function toMerged<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
+export {};

package/internals/utils/objects.js

@@ -0,0 +1,125 @@
+import { isObject, isPlainObject, isRegExp } from './types.js';
+function isUnsafeProperty(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+export function equal(a, b, visited = new WeakMap()) {
+    if (Object.is(a, b))
+        return true;
+    if (!isObject(a) || !isObject(b))
+        return false;
+    if (a.constructor !== b.constructor)
+        return false;
+    let pending = visited.get(a);
+    if (pending?.has(b))
+        return true;
+    if (!pending) {
+        pending = new WeakSet();
+        visited.set(a, pending);
+    }
+    pending.add(b);
+    try {
+        return compare(a, b, visited);
+    }
+    finally {
+        pending.delete(b);
+    }
+}
+function compare(a, b, visited) {
+    if (isRegExp(a) && isRegExp(b))
+        return a.source === b.source && a.flags === b.flags;
+    if (a instanceof Map && b instanceof Map) {
+        if (a.size !== b.size)
+            return false;
+        for (const [keyA, valueA] of a.entries()) {
+            let found = false;
+            for (const [keyB, valueB] of b.entries()) {
+                if (equal(keyA, keyB, visited) && equal(valueA, valueB, visited)) {
+                    found = true;
+                    break;
+                }
+            }
+            if (!found)
+                return false;
+        }
+        return true;
+    }
+    if (a instanceof Set && b instanceof Set) {
+        if (a.size !== b.size)
+            return false;
+        for (const valueA of a) {
+            let found = false;
+            for (const valueB of b) {
+                if (equal(valueA, valueB, visited)) {
+                    found = true;
+                    break;
+                }
+            }
+            if (!found)
+                return false;
+        }
+        return true;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const length = a.length;
+        if (length !== b.length)
+            return false;
+        for (let i = 0; i < length; i++) {
+            if (!equal(a[i], b[i], visited))
+                return false;
+        }
+        return true;
+    }
+    if (a.valueOf !== Object.prototype.valueOf)
+        return a.valueOf() === b.valueOf();
+    if (a.toString !== Object.prototype.toString)
+        return a.toString() === b.toString();
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!Object.hasOwn(b, key))
+            return false;
+    }
+    for (const key of aKeys) {
+        if (!equal(a[key], b[key], visited))
+            return false;
+    }
+    return true;
+}
+export function merge(target, source) {
+    const sourceKeys = Object.keys(source);
+    const length = sourceKeys.length;
+    for (let i = 0; i < length; i++) {
+        const key = sourceKeys[i];
+        if (isUnsafeProperty(key)) {
+            continue;
+        }
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        if (Array.isArray(sourceValue)) {
+            if (Array.isArray(targetValue)) {
+                target[key] = merge(targetValue, sourceValue);
+            }
+            else {
+                target[key] = merge([], sourceValue);
+            }
+        }
+        else if (isPlainObject(sourceValue)) {
+            if (isPlainObject(targetValue)) {
+                target[key] = merge(targetValue, sourceValue);
+            }
+            else {
+                target[key] = merge({}, sourceValue);
+            }
+        }
+        else if (targetValue === undefined || sourceValue !== undefined) {
+            target[key] = sourceValue;
+        }
+    }
+    return target;
+}
+export function toMerged(target, source) {
+    return merge(structuredClone(target), source);
+}
+//# sourceMappingURL=objects.js.map