@ionic/core 8.8.19 → 8.8.20-dev.11788449221.155f9f1e

package/dist/collection/utils/sanitization/index.js

@@ -3,8 +3,26 @@
  */
 import { printIonError } from "../logging/index";
 /**
- * Does a simple sanitization of all elements
- * in an untrusted string
+ * Sanitize an untrusted HTML string.
+ *
+ * Parses the string into a detached DOM, removes blocked tags, strips
+ * attributes outside the narrow `domStringAllowedAttributes` list (refer
+ * `sanitizeElement`), and scrubs script-scheme URLs. Returns the sanitized
+ * HTML string.
+ *
+ * Use this when you have an HTML string from an unknown source and need to
+ * render it via `innerHTML`. Use `sanitizeDOMTree` instead when you already
+ * have a DOM tree and want to sanitize it in place without a string round
+ * trip. The two apply the same dangerous-vector scrubbing but different
+ * attribute allowlists: this path stays narrow so existing consumers
+ * (toast, loading, alert message, etc.) are unaffected, while
+ * `sanitizeDOMTree` uses the wider rich-content allowlist.
+ *
+ * @param untrustedString - The HTML string to sanitize. Pass an
+ * `IonicSafeString` to bypass sanitization, or `undefined` to short-circuit.
+ * @returns The sanitized HTML string, or `undefined` if the input was
+ * `undefined`. Returns `''` if sanitization fails or the input contains
+ * an inline `onload=` handler.
  */
 export const sanitizeDOMString = (untrustedString) => {
     try {
@@ -54,7 +72,7 @@ export const sanitizeDOMString = (untrustedString) => {
                 const childElements = getElementChildren(element);
                 /* eslint-disable-next-line */
                 for (let childIndex = 0; childIndex < childElements.length; childIndex++) {
-                    sanitizeElement(childElements[childIndex]);
+                    sanitizeElement(childElements[childIndex], domStringAllowedAttributes);
                 }
             }
         });
@@ -66,7 +84,7 @@ export const sanitizeDOMString = (untrustedString) => {
         const dfChildren = getElementChildren(documentFragment);
         /* eslint-disable-next-line */
         for (let childIndex = 0; childIndex < dfChildren.length; childIndex++) {
-            sanitizeElement(dfChildren[childIndex]);
+            sanitizeElement(dfChildren[childIndex], domStringAllowedAttributes);
         }
         // Append document fragment to div
         const fragmentDiv = document.createElement('div');
@@ -80,13 +98,43 @@ export const sanitizeDOMString = (untrustedString) => {
         return '';
     }
 };
+/**
+ * Sanitize an entire trusted DOM tree in place.
+ *
+ * Removes blocked tags (`script`, `iframe`, etc.) from the subtree and
+ * then sanitizes attributes on every remaining element using the wider
+ * `richContentAllowedAttributes` allowlist (refer `sanitizeElement`).
+ * Component presentational attributes (`size`, `color`, `shape`, inline
+ * SVG, `aria-*`, `data-*`) are preserved; `style`, event handlers (`on*`),
+ * form/navigation-hijack attributes, script-scheme URLs, and non-image
+ * `data:` URLs are stripped.
+ *
+ * Use this when you have a DOM tree the developer controls (e.g.
+ * cloned slot content from a component) and you need to render it
+ * elsewhere safely.
+ *
+ * @param root - The root element whose subtree will be sanitized in
+ * place. No-op when the sanitizer is disabled via `Ionic.config`.
+ */
+export const sanitizeDOMTree = (root) => {
+    if (!isSanitizerEnabled()) {
+        return;
+    }
+    blockedTags.forEach((tag) => {
+        const matches = root.querySelectorAll(tag);
+        for (let i = matches.length - 1; i >= 0; i--) {
+            matches[i].remove();
+        }
+    });
+    sanitizeElement(root, richContentAllowedAttributes, richContentAllowedAttributePrefixes);
+};
 /**
  * Clean up current element based on allowed attributes
  * and then recursively dig down into any child elements to
  * clean those up as well
  */
 // TODO(FW-2832): type (using Element triggers other type errors as well)
-const sanitizeElement = (element) => {
+const sanitizeElement = (element, allowedAttributes, allowedAttributePrefixes = []) => {
     // IE uses childNodes, so ignore nodes that are not elements
     if (element.nodeType && element.nodeType !== 1) {
         return;
@@ -101,29 +149,60 @@ const sanitizeElement = (element) => {
         element.remove();
         return;
     }
+    /**
+     * Always strip `style` (CSS injection, `background:url()` beaconing, UI
+     * spoofing). It is never on the allowlist, but it is removed explicitly
+     * here because some engines (e.g. jsdom) don't enumerate the CSSOM-backed
+     * `style` attribute in `element.attributes`, which would let the loop
+     * below skip over it.
+     */
+    element.removeAttribute('style');
     for (let i = element.attributes.length - 1; i >= 0; i--) {
         const attribute = element.attributes.item(i);
         const attributeName = attribute.name;
-        // remove non-allowed attribs
-        if (!allowedAttributes.includes(attributeName.toLowerCase())) {
+        const lowerName = attributeName.toLowerCase();
+        /**
+         * Remove any attribute that is not on the allowlist. This drops event
+         * handlers (`on*`), `style`, the form/navigation-hijack attributes
+         * (`formaction`, `action`, `target`), namespaced attributes like
+         * `xlink:href`, and anything else not explicitly known to be safe.
+         */
+        if (!isAttributeAllowed(lowerName, allowedAttributes, allowedAttributePrefixes)) {
             element.removeAttribute(attributeName);
             continue;
         }
         // clean up any allowed attribs
         // that attempt to do any JS funny-business
         const attributeValue = attribute.value;
+        if (attributeValue == null) {
+            continue;
+        }
         /**
-         * We also need to check the property value
-         * as javascript: can allow special characters
-         * such as &Tab; and still be valid (i.e. java&Tab;script)
+         * Scrub dangerous schemes from the value. The value is normalized first
+         * (whitespace and ASCII control characters removed) so entity-obfuscated
+         * payloads such as `java&#9;script:`, which the parser decodes to
+         * `java\tscript:`, are still caught. Normalizing the value also covers
+         * namespaced attributes, where the previous `element[attributeName]`
+         * property reflection returned `undefined` and let them slip through.
          */
-        const propertyValue = element[attributeName];
-        /* eslint-disable */
-        if ((attributeValue != null && attributeValue.toLowerCase().includes('javascript:')) ||
-            (propertyValue != null && propertyValue.toLowerCase().includes('javascript:'))) {
+        const normalizedValue = attributeValue.replace(controlCharactersAndWhitespace, '').toLowerCase();
+        // Script schemes are never allowed, on any attribute.
+        if (normalizedValue.includes('javascript:') || normalizedValue.includes('vbscript:')) {
+            element.removeAttribute(attributeName);
+            continue;
+        }
+        /**
+         * For URL-bearing attributes, allow `data:` URIs only for raster
+         * images. Document-bearing types (`text/html`, `image/svg+xml`,
+         * `application/*`, etc.) can carry markup or script when navigated to
+         * or rendered, so they are stripped, while safe image types are kept so
+         * inline images keep working.
+         */
+        if (urlAttributes.includes(lowerName) &&
+            normalizedValue.startsWith('data:') &&
+            !safeDataImageUri.test(normalizedValue)) {
             element.removeAttribute(attributeName);
         }
-        /* eslint-enable */
     }
     /**
      * Sanitize any nested children
@@ -131,7 +210,7 @@ const sanitizeElement = (element) => {
     const childElements = getElementChildren(element);
     /* eslint-disable-next-line */
     for (let i = 0; i < childElements.length; i++) {
-        sanitizeElement(childElements[i]);
+        sanitizeElement(childElements[i], allowedAttributes, allowedAttributePrefixes);
     }
 };
 /**
@@ -156,8 +235,185 @@ const isSanitizerEnabled = () => {
     }
     return true;
 };
-const allowedAttributes = ['class', 'id', 'href', 'src', 'name', 'slot'];
-const blockedTags = ['script', 'style', 'iframe', 'meta', 'link', 'object', 'embed'];
+/**
+ * Mirror known custom-element DOM properties onto attributes so they
+ * survive `cloneNode`. Call this on a DOM subtree before cloning it for
+ * rendering elsewhere (e.g. cloning slotted option content into an
+ * overlay).
+ *
+ * Only sets the attribute when the property holds a non-empty string
+ * and the attribute isn't already present, so existing attributes
+ * take precedence.
+ *
+ * @param root - The root element whose subtree (and itself) will be
+ * inspected.
+ */
+export const reflectPropertiesToAttributes = (root) => {
+    const candidates = [];
+    if (root.tagName in elementPropsToReflect) {
+        candidates.push(root);
+    }
+    for (const tagName of Object.keys(elementPropsToReflect)) {
+        candidates.push(...Array.from(root.querySelectorAll(tagName.toLowerCase())));
+    }
+    for (const el of candidates) {
+        if (!(el.tagName in elementPropsToReflect)) {
+            continue;
+        }
+        const props = elementPropsToReflect[el.tagName];
+        for (const prop of props) {
+            const value = el[prop];
+            if (typeof value === 'string' && value.length > 0 && !el.hasAttribute(prop)) {
+                el.setAttribute(prop, value);
+            }
+        }
+    }
+};
+/**
+ * Attribute allowlist for `sanitizeDOMString`. Intentionally narrow: this
+ * path sanitizes developer HTML strings rendered via `innerHTML` by
+ * `ion-toast`, `ion-loading`, the `ion-alert` message,
+ * `ion-refresher-content`, and `ion-infinite-scroll-content`, so the list
+ * is kept to the minimum those have always needed. Broadening it here would
+ * change sanitization output for all of those consumers, so the wider
+ * rich-content allowlist below is deliberately scoped to `sanitizeDOMTree`
+ * instead.
+ */
+const domStringAllowedAttributes = ['class', 'id', 'href', 'src', 'name', 'slot'];
+/**
+ * Attribute allowlist for `sanitizeDOMTree` (the select rich-content path).
+ * Covers global HTML attributes, the Ionic component presentational props
+ * that cloned rich content (e.g. `ion-select-option` markup) relies on, and
+ * the inert SVG presentation attributes used by inline icons.
+ *
+ * `aria-*` and `data-*` are allowed separately by prefix (refer
+ * `richContentAllowedAttributePrefixes`) since they are inert and not worth
+ * enumerating. URL-bearing names (`href`, `src`) are allowed here, but
+ * their values are still scrubbed for script schemes in `sanitizeElement`.
+ *
+ * Notably absent: `style`, event handlers (`on*`), and the
+ * form/navigation-hijack attributes (`formaction`, `action`, `target`),
+ * which are therefore stripped.
+ */
+const richContentAllowedAttributes = [
+    // Global / structural
+    'class',
+    'id',
+    'slot',
+    'name',
+    'title',
+    'alt',
+    'lang',
+    'dir',
+    'role',
+    'type',
+    'value',
+    'disabled',
+    'width',
+    'height',
+    'href',
+    'src',
+    // Ionic component presentational props
+    'color',
+    'size',
+    'shape',
+    'fill',
+    'expand',
+    'mode',
+    'theme',
+    'icon',
+    'label',
+    'label-placement',
+    'justify',
+    'inset',
+    'lines',
+    'ios',
+    'md',
+    // SVG presentation attributes (compared lowercased, e.g. `viewBox`)
+    'xmlns',
+    'viewbox',
+    'preserveaspectratio',
+    'stroke',
+    'stroke-width',
+    'stroke-linecap',
+    'stroke-linejoin',
+    'stroke-opacity',
+    'stroke-dasharray',
+    'fill-rule',
+    'fill-opacity',
+    'clip-rule',
+    'd',
+    'points',
+    'cx',
+    'cy',
+    'r',
+    'rx',
+    'ry',
+    'x',
+    'y',
+    'x1',
+    'y1',
+    'x2',
+    'y2',
+    'transform',
+    'opacity',
+];
+/**
+ * Attribute-name prefixes that are always safe to keep in the rich-content
+ * path. `aria-*` and `data-*` attributes cannot execute script or load
+ * resources, so they are allowed wholesale rather than enumerated by name.
+ */
+const richContentAllowedAttributePrefixes = ['aria-', 'data-'];
+/**
+ * Whether an attribute name (already lowercased) is safe to keep, by exact
+ * match or by an allowed prefix.
+ */
+const isAttributeAllowed = (lowerName, allowedAttributes, allowedAttributePrefixes) => {
+    if (allowedAttributes.includes(lowerName)) {
+        return true;
+    }
+    return allowedAttributePrefixes.some((prefix) => lowerName.startsWith(prefix));
+};
+/**
+ * Matches ASCII control characters and whitespace (including the
+ * non-breaking space). Used to normalize attribute values before matching
+ * a URL scheme so entity-obfuscated payloads such as `java&#9;script:`
+ * (decoded by the parser to `java\tscript:`) can't smuggle a scheme past
+ * the check.
+ */
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const controlCharactersAndWhitespace = /[\u0000-\u0020\u007f-\u00a0]/g;
+/**
+ * Attributes whose values are URLs. Their values are scheme-checked in
+ * `sanitizeElement` (e.g. `data:` filtering) beyond the script-scheme scrub
+ * applied to every attribute.
+ */
+const urlAttributes = ['href', 'src'];
+/**
+ * Matches a `data:` URI for a raster image type that cannot carry script.
+ * `image/svg+xml` is deliberately excluded (SVG can execute script), as are
+ * document types like `text/html` and `application/*`. The value is already
+ * lowercased and whitespace-stripped before this is tested.
+ */
+const safeDataImageUri = /^data:image\/(?:png|jpe?g|gif|webp|bmp|avif|x-icon|vnd\.microsoft\.icon)[;,]/;
+/**
+ * Tags removed entirely (with their subtree) before attribute sanitization.
+ * Exported so tests can assert the set without hardcoding it.
+ */
+export const blockedTags = ['script', 'style', 'iframe', 'meta', 'link', 'object', 'embed', 'base'];
+/**
+ * Properties on custom elements that frameworks (Vue, Angular) often
+ * set as DOM properties rather than attributes. `cloneNode` only copies
+ * attributes, so these values are lost when slotted content is cloned
+ * into an overlay. For each known custom element, we mirror the listed
+ * properties onto attributes so the cloned copy still has the data it
+ * needs to render.
+ *
+ * Keyed by uppercased tagName so the lookup matches `Element.tagName`.
+ */
+const elementPropsToReflect = {
+    'ION-ICON': ['icon', 'name', 'src', 'ios', 'md'],
+};
 export class IonicSafeString {
     constructor(value) {
         this.value = value;

package/dist/collection/utils/scroll-hide-controller.js

@@ -0,0 +1,178 @@
+/*!
+ * (C) Ionic http://ionicframework.com - MIT License
+ */
+import { readTask, writeTask } from "@stencil/core";
+import { getScrollElement } from "./content";
+const TOP_VISIBLE_THRESHOLD = 80;
+const SCROLL_HIDE_THRESHOLD = 60;
+const WHEEL_SUPPRESS_DURATION_MS = 80;
+const SUPPRESS_SHOW_DURATION_MS = 400;
+/**
+ * Creates a controller that manages scroll-based hide/show behavior
+ * for headers, footers, and tab bars.
+ *
+ * Listens to both wheel and scroll events. Wheel events (desktop mice)
+ * give direction instantly via deltaY. Scroll events cover touch,
+ * trackpad, and programmatic scrolling where wheel doesn't fire.
+ * A short suppression window stops them from double-processing the
+ * same gesture.
+ *
+ * When the user reverses scroll direction, we save that position as
+ * an anchor. The bar only hides after scrolling 60px past that
+ * anchor, which prevents flickering on small or jittery movements.
+ * Showing is immediate on direction change.
+ *
+ * When `options` is provided, the controller also handles the DOM
+ * setup: ResizeObserver for height tracking, CSS variable read/write,
+ * content partner/hidden class toggling, inert/aria-hidden, and
+ * full teardown cleanup. This avoids duplicating the same setup
+ * across header, footer, and tab-bar.
+ *
+ * @internal
+ * @param contentEl The content element to resolve the scroll element from.
+ * @param options Configuration for DOM setup (classes, CSS vars, a11y).
+ */
+export const createScrollHideController = async (contentEl, options) => {
+    const { el, cssVar, hiddenClass, contentPartnerClass, contentHiddenClass, shouldKeepAriaHidden } = options;
+    let controllerIsHidden = false;
+    let resizeObserver;
+    // --- DOM setup: height tracking, classes, a11y ---
+    const updateHideHeight = () => {
+        readTask(() => {
+            const heightPx = el.offsetHeight;
+            writeTask(() => {
+                el.style.setProperty(cssVar, `${heightPx}px`);
+                contentEl.style.setProperty(cssVar, `${heightPx}px`);
+            });
+        });
+    };
+    const setHidden = (hidden) => {
+        controllerIsHidden = hidden;
+        el.classList.toggle(hiddenClass, hidden);
+        if (hidden) {
+            el.setAttribute('inert', '');
+            el.setAttribute('aria-hidden', 'true');
+        }
+        else {
+            el.removeAttribute('inert');
+            if (!shouldKeepAriaHidden || !shouldKeepAriaHidden()) {
+                el.removeAttribute('aria-hidden');
+            }
+        }
+        contentEl.classList.toggle(contentHiddenClass, hidden);
+    };
+    // --- Scroll math ---
+    const scrollEl = await getScrollElement(contentEl);
+    let lastScrollPosition = 0;
+    let scrollPositionAtDirectionChange = 0;
+    let lastWheelEventTimestamp = 0;
+    let suppressShowUntil = 0;
+    const commitHide = (hidden) => {
+        if (hidden) {
+            suppressShowUntil = Date.now() + SUPPRESS_SHOW_DURATION_MS;
+        }
+        else {
+            suppressShowUntil = 0;
+        }
+        setHidden(hidden);
+    };
+    const handleWheel = (wheelEvent) => {
+        lastWheelEventTimestamp = Date.now();
+        readTask(() => {
+            const currentScrollTop = scrollEl.scrollTop;
+            // Both wheel and scroll events fire for mouse wheel input.
+            // Scroll events are suppressed for 80ms after a wheel event,
+            // but when they resume, handleScroll needs an up-to-date
+            // lastScrollPosition or it may detect the wrong direction.
+            lastScrollPosition = currentScrollTop;
+            if (currentScrollTop <= TOP_VISIBLE_THRESHOLD) {
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+                return;
+            }
+            if (wheelEvent.deltaY < 0) {
+                scrollPositionAtDirectionChange = currentScrollTop;
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+            }
+            else if (wheelEvent.deltaY > 0) {
+                const scrolledSinceDirectionChange = currentScrollTop - scrollPositionAtDirectionChange;
+                if (scrolledSinceDirectionChange >= SCROLL_HIDE_THRESHOLD && !controllerIsHidden) {
+                    writeTask(() => commitHide(true));
+                }
+            }
+        });
+    };
+    const handleScroll = () => {
+        if (Date.now() - lastWheelEventTimestamp < WHEEL_SUPPRESS_DURATION_MS) {
+            return;
+        }
+        readTask(() => {
+            const currentScrollTop = scrollEl.scrollTop;
+            if (currentScrollTop <= TOP_VISIBLE_THRESHOLD) {
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+                lastScrollPosition = currentScrollTop;
+                return;
+            }
+            if (currentScrollTop === lastScrollPosition) {
+                return;
+            }
+            const isScrollingDown = currentScrollTop > lastScrollPosition;
+            const wasScrollingDown = lastScrollPosition > scrollPositionAtDirectionChange;
+            if (isScrollingDown !== wasScrollingDown) {
+                scrollPositionAtDirectionChange = lastScrollPosition;
+            }
+            const scrolledSinceDirectionChange = Math.abs(currentScrollTop - scrollPositionAtDirectionChange);
+            const requiredScrollDistance = isScrollingDown ? SCROLL_HIDE_THRESHOLD : 0;
+            lastScrollPosition = currentScrollTop;
+            if (scrolledSinceDirectionChange < requiredScrollDistance) {
+                return;
+            }
+            const shouldHide = isScrollingDown;
+            if (shouldHide !== controllerIsHidden) {
+                if (!shouldHide && Date.now() < suppressShowUntil) {
+                    return;
+                }
+                writeTask(() => commitHide(shouldHide));
+            }
+        });
+    };
+    // --- Controller ---
+    let initialized = false;
+    const init = () => {
+        initialized = true;
+        updateHideHeight();
+        if (typeof ResizeObserver !== 'undefined') {
+            resizeObserver = new ResizeObserver(() => updateHideHeight());
+            resizeObserver.observe(el);
+        }
+        scrollEl.addEventListener('scroll', handleScroll, { passive: true });
+        scrollEl.addEventListener('wheel', handleWheel, { passive: true });
+        contentEl.classList.add(contentPartnerClass);
+    };
+    const destroy = () => {
+        if (!initialized)
+            return;
+        scrollEl.removeEventListener('scroll', handleScroll);
+        scrollEl.removeEventListener('wheel', handleWheel);
+        if (resizeObserver) {
+            resizeObserver.disconnect();
+            resizeObserver = undefined;
+        }
+        contentEl.classList.remove(contentPartnerClass, contentHiddenClass);
+        contentEl.style.removeProperty(cssVar);
+        if (controllerIsHidden) {
+            el.classList.remove(hiddenClass);
+            el.removeAttribute('inert');
+            el.removeAttribute('aria-hidden');
+            controllerIsHidden = false;
+        }
+        el.style.removeProperty(cssVar);
+    };
+    const isHidden = () => controllerIsHidden;
+    return { isHidden, init, destroy };
+};

package/dist/collection/utils/select-option-render.js

@@ -0,0 +1,119 @@
+/*!
+ * (C) Ionic http://ionicframework.com - MIT License
+ */
+import { h } from "@stencil/core";
+import { sanitizeDOMTree } from "./sanitization/index";
+/**
+ * Converts a DOM node into a Stencil VNode (or text string) so the
+ * resulting tree is rendered through the component's normal render
+ * path. Rendering through Stencil ensures that scoped CSS classes
+ * (e.g. `sc-ion-action-sheet-ionic`) are applied to every element.
+ *
+ * Highly recommended to pre-sanitize the source DOM (see
+ * `getOptionContent` in select.tsx). This function performs pure
+ * structural conversion — no security filtering.
+ *
+ * Preserves attributes only — properties set imperatively on the source
+ * element (e.g. `input.value` after a user types) won't carry through.
+ * In practice this isn't a concern: interactive controls shouldn't
+ * appear in select-option rich content since they'd nest inside the
+ * overlay's button/radio/checkbox wrapper, which is invalid HTML and
+ * an accessibility issue.
+ *
+ * @param node - The DOM node to convert. Text nodes become strings,
+ * element nodes become VNodes, and any other node types are skipped.
+ * @param keyPrefix - String prefix used to build a stable VNode key,
+ * so Stencil's diff can preserve elements across re-renders.
+ * @param index - Position of this node among its siblings. Combined
+ * with `keyPrefix` to form the final unique key.
+ * @returns The converted VNode, a text string, or `null` if the node
+ * type isn't supported.
+ *
+ * @internal Exported only so it can be unit tested; not part of the
+ * public API.
+ */
+export const cloneToVNode = (node, keyPrefix, index) => {
+    var _a;
+    if (node.nodeType === Node.TEXT_NODE) {
+        return (_a = node.textContent) !== null && _a !== void 0 ? _a : '';
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+        return null;
+    }
+    const el = node;
+    const tag = el.tagName.toLowerCase();
+    const key = `${keyPrefix}-${index}`;
+    const attrs = { key };
+    for (let i = 0; i < el.attributes.length; i++) {
+        const attr = el.attributes.item(i);
+        attrs[attr.name] = attr.value;
+    }
+    const children = Array.from(el.childNodes)
+        .map((child, i) => cloneToVNode(child, key, i))
+        .filter((c) => c !== null);
+    return h(tag, attrs, children);
+};
+/**
+ * Renders cloned DOM content as Stencil JSX. Walking the source DOM
+ * into VNodes (rather than injecting it via innerHTML) keeps the
+ * content inside Stencil's render path, so scoped CSS classes are
+ * applied automatically and component attributes like `size` or
+ * `color` survive intact.
+ *
+ * Span elements should be used when this content renders within buttons,
+ * depending on the select interface. Buttons can only have phrasing
+ * content to prevent accessibility issues.
+ *
+ * @param id - Unique identifier for generating stable virtual DOM keys.
+ * @param content - The HTMLElement container whose child nodes will be cloned.
+ * @param className - CSS class applied to the wrapper element.
+ * @param useSpan - Whether to use a span element instead of a div for the wrapper.
+ */
+const renderClonedContent = (id, content, className, useSpan = false) => {
+    const Tag = useSpan ? 'span' : 'div';
+    const keyPrefix = `${className}-${id}`;
+    /**
+     * Do not remove. This is the only sanitization pass for callers that pass
+     * an `HTMLElement` straight to `renderOptionLabel` (e.g. vanilla JS)
+     * without going through `getOptionContent`, which sanitizes upstream.
+     * `cloneToVNode` does pure structural conversion and no security
+     * filtering, so dropping this call would reopen an XSS hole on the
+     * direct `HTMLElement` path.
+     */
+    sanitizeDOMTree(content);
+    return (h(Tag, { class: className, key: keyPrefix }, Array.from(content.childNodes).map((child, i) => cloneToVNode(child, keyPrefix, i))));
+};
+/**
+ * Renders the label content for a select option within an overlay
+ * interface based on the presence of rich content.
+ *
+ * Span elements should be used when this content renders within buttons,
+ * depending on the select interface. Buttons can only have phrasing
+ * content to prevent accessibility issues.
+ *
+ * @param option - The content option data containing label, slots,
+ * and description.
+ * @param className - The base CSS class for the label element.
+ * @param useSpan - Whether to use a span element instead of a div for the label.
+ */
+export const renderOptionLabel = (option, className, useSpan = false) => {
+    const { id, label, startContent, endContent, description } = option;
+    const hasRichContent = !!startContent || !!endContent || !!description;
+    const Tag = useSpan ? 'span' : 'div';
+    // Render simple string label if there is no rich content to display
+    if (!hasRichContent && (typeof label === 'string' || !label)) {
+        return (h(Tag, { class: className, key: `${className}-${id}` }, label));
+    }
+    // Render the main label
+    const labelEl = typeof label === 'string' || !label ? (
+    // Label is a simple string or undefined
+    h(Tag, { key: `${className}-label-${id}` }, label)) : (
+    // Label is an HTMLElement with potential rich content
+    renderClonedContent(id, label, `${className}-text`, useSpan));
+    // No rich content, render just the label
+    if (!hasRichContent) {
+        return (h(Tag, { class: className, key: `${className}-${id}` }, labelEl));
+    }
+    // Render label with rich content (start, end, description)
+    return (h(Tag, { class: `${className} ${className}-has-rich-content`, key: `${className}-${id}` }, startContent && renderClonedContent(id, startContent, 'select-option-start', useSpan), h(Tag, { class: "select-option-content", key: `${className}-content-${id}` }, labelEl, description && (h(Tag, { class: "select-option-description", key: `${className}-desc-${id}` }, description))), endContent && renderClonedContent(id, endContent, 'select-option-end', useSpan)));
+};