@dynamic-framework/ui-react 2.9.0 → 2.11.0

package/dist/index.esm.js

@@ -1,13 +1,13 @@
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import classNames from 'classnames';
-import React, { useEffect, useState, useCallback, useMemo, useContext, createContext, useLayoutEffect, useSyncExternalStore, createElement, forwardRef, useId, useRef, isValidElement, cloneElement, createRef } from 'react';
+import React, { useEffect, useState, useCallback, useMemo, useContext, useRef, createContext, useLayoutEffect, useSyncExternalStore, createElement, isValidElement, forwardRef, useId, cloneElement, Children } from 'react';
 import { __rest } from 'tslib';
 import * as LucideIcons from 'lucide-react';
 import { isValidElementType } from 'react-is';
 import { createPortal } from 'react-dom';
-import { AnimatePresence, motion } from 'framer-motion';
 import { fromEvent } from 'file-selector';
 import { SplideSlide, Splide, SplideTrack } from '@splidejs/react-splide';
+import { motion, AnimatePresence } from 'framer-motion';
 import currency from 'currency.js';
 import DatePicker from 'react-datepicker';
 import { getYear, format, getMonth } from 'date-fns';
@@ -25,6 +25,16 @@ import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 
 const PREFIX_BS = 'bs-';
+/**
+ * Default icon-font family configured by `DContextProvider`.
+ *
+ * `DIconBase` compares the family it receives against these values to tell an
+ * unconfigured consumer apart from one that deliberately opted into an icon
+ * font (Material Symbols, Bootstrap Icons). Only the former gets the
+ * development warning for an unresolved icon name.
+ */
+const DEFAULT_ICON_FAMILY_CLASS = 'bi';
+const DEFAULT_ICON_FAMILY_PREFIX = 'bi-';
 
 /* eslint-disable no-lonely-if */
 function useDisableBodyScrollEffect(disable) {
@@ -141,11 +151,30 @@ function getKeyboardFocusableElements(container) {
     ].filter((element) => !element.hasAttribute('disabled'));
 }
 
+const loadPortalStack = () => import('./DPortalStack-D1-GGU4C.js').then((module) => module.default);
 const DPortalContext = createContext(undefined);
 function DPortalContextProvider({ portalName, children, availablePortals, }) {
     const { created } = usePortal(portalName);
     const [stack, { push, pop }] = useStackState([]);
+    const [PortalStack, setPortalStack] = useState(null);
+    const pending = useRef([]);
+    const ready = useRef(false);
     useDisableBodyScrollEffect(Boolean(stack.length));
+    // Loads framer-motion off the critical path only when portals are configured,
+    // so the first openPortal does not wait for it.
+    const hasPortals = Object.keys(availablePortals !== null && availablePortals !== void 0 ? availablePortals : {}).length > 0;
+    useEffect(() => {
+        if (!hasPortals)
+            return;
+        loadPortalStack()
+            .then((Stack) => {
+            ready.current = true;
+            setPortalStack(() => Stack);
+        })
+            .catch(() => {
+            // openPortal retries the import and reports the failure.
+        });
+    }, [hasPortals]);
     const openPortal = useCallback(
     // eslint-disable-next-line prefer-arrow-callback
     function openPortalImpl(name, payload) {
@@ -161,10 +190,30 @@ function DPortalContextProvider({ portalName, children, availablePortals, }) {
         }
         // K is a specific member of keyof T & string so the object satisfies
         // InternalStackItem<T>, but TS can't verify generic-over-union assignability.
-        push({ name, Component, payload });
+        const item = { name, Component, payload };
+        if (ready.current) {
+            push(item);
+        }
+        else {
+            // Not loaded yet: the portal enters the stack together with its renderer.
+            pending.current.push(item);
+            loadPortalStack().then((Stack) => {
+                ready.current = true;
+                setPortalStack(() => Stack);
+                pending.current.splice(0).forEach(push);
+            }).catch((error) => {
+                pending.current = [];
+                // eslint-disable-next-line no-console
+                console.error('[DPortalContext] Could not load the portal stack', error);
+            });
+        }
         (_a = document.activeElement) === null || _a === void 0 ? void 0 : _a.blur();
     }, [availablePortals, push]);
     const closePortal = useCallback(() => {
+        if (pending.current.length > 0) {
+            pending.current.pop();
+            return;
+        }
         // pop() is safe on empty stacks, so close remains idempotent.
         pop();
     }, [pop]);
@@ -221,13 +270,10 @@ function DPortalContextProvider({ portalName, children, availablePortals, }) {
             window.removeEventListener('keydown', keyEvent);
         };
     }, [handleClose, portalName, stack.length]);
-    return (jsxs(DPortalContext.Provider, { value: value, children: [children, created && createPortal(
+    return (jsxs(DPortalContext.Provider, { value: value, children: [children, created && PortalStack && createPortal(
             // eslint-disable-next-line max-len
             // eslint-disable-next-line jsx-a11y/no-static-element-interactions
-            jsx("div", { onClick: ({ target }) => handleClose(target), onKeyDown: () => { }, children: jsx(AnimatePresence, { children: stack.flatMap(({ Component, name, payload, }) => [
-                        jsx(motion.div, { className: "backdrop", initial: { opacity: 0 }, animate: { opacity: 0.5 }, exit: { opacity: 0, transition: { delay: 0.3 } }, transition: { duration: 0.15, ease: 'linear' } }, `${name}-backdrop`),
-                        jsx(Component, { name: name, payload: payload }, name),
-                    ]) }) }), document.getElementById(portalName))] }));
+            jsx("div", { onClick: ({ target }) => handleClose(target), onKeyDown: () => { }, children: jsx(PortalStack, { stack: stack }) }), document.getElementById(portalName))] }));
 }
 /**
  * Hook to open/close registered portals (modals, offcanvas, etc.).
@@ -306,8 +352,8 @@ const DEFAULT_STATE = {
         decimal: '.',
     },
     icon: {
-        familyClass: 'bi',
-        familyPrefix: 'bi-',
+        familyClass: DEFAULT_ICON_FAMILY_CLASS,
+        familyPrefix: DEFAULT_ICON_FAMILY_PREFIX,
         materialStyle: false,
     },
     iconRegistry: undefined,
@@ -412,6 +458,79 @@ function useDContext() {
     return useContext(DContext);
 }
 
+/**
+ * Resolves a string icon name against the registry supplied through
+ * `DContextProvider`'s `iconRegistry` prop.
+ *
+ * This is the single implementation shared by `DIcon` and `DIconBase`, so both
+ * public entry points — and every Dynamic UI component that renders an icon
+ * through them — resolve names identically.
+ *
+ * A non-string `icon` is returned untouched: a component passed directly needs
+ * no lookup. A name missing from the registry is also returned untouched, so
+ * the caller can fall through to lucide-react and then to the icon-font family.
+ */
+function resolveIconFromRegistry(icon, iconRegistry) {
+    if (typeof icon !== 'string')
+        return icon;
+    return (iconRegistry === null || iconRegistry === void 0 ? void 0 : iconRegistry[icon]) || icon;
+}
+
+/**
+ * Names already reported, so a name repeated across renders or across many
+ * instances only warns once per page load.
+ */
+const warnedIconNames = new Set();
+/**
+ * True when the icon-font family is the one `DContextProvider` defaults to.
+ *
+ * The warning is limited to that case so a consumer who configured a different
+ * font — Material Symbols, for instance — is not told about names that font
+ * resolves perfectly well.
+ *
+ * It cannot tell "never configured a font" apart from "configured exactly the
+ * defaults", and those defaults are also the standard Bootstrap Icons setup, so
+ * a consumer who deliberately uses Bootstrap Icons is warned too. The message
+ * says so; silencing that case would need a new context flag, which is beyond
+ * what this helper should decide.
+ */
+function isDefaultIconFamily(familyClass, familyPrefix) {
+    return familyClass === DEFAULT_ICON_FAMILY_CLASS
+        && familyPrefix === DEFAULT_ICON_FAMILY_PREFIX;
+}
+/**
+ * Warns, once per name and only outside production builds, that an icon name
+ * resolved to neither the registry nor lucide-react and is falling back to the
+ * default icon font, which this package no longer ships.
+ *
+ * Whether that fallback renders depends on the host app: if it loads the font
+ * itself the `<i>` shows the glyph, and if it does not, nothing appears. The
+ * message states both possibilities instead of assuming the second.
+ *
+ * The `process.env.NODE_ENV` guard is what bundlers constant-fold, so the whole
+ * call — and this module — drops out of a consumer's production bundle.
+ */
+function warnUnknownIcon(name, familyClass, familyPrefix) {
+    if (!isDefaultIconFamily(familyClass, familyPrefix))
+        return;
+    if (warnedIconNames.has(name))
+        return;
+    warnedIconNames.add(name);
+    const fallbackClass = `${DEFAULT_ICON_FAMILY_CLASS} ${DEFAULT_ICON_FAMILY_PREFIX}${name}`;
+    // eslint-disable-next-line no-console
+    console.warn(`[Dynamic UI] Icon "${name}" is not in the icon registry and is not a `
+        + 'lucide-react export, so it falls back to the default icon font: '
+        + `<i class="${fallbackClass}">. That renders only if your app loads that `
+        + 'font, which this package stopped shipping in v2.0.0. '
+        + 'If the icon is missing, pass a PascalCase lucide-react name such as '
+        + '"Home", or register the component with '
+        + '<DContextProvider iconRegistry={{ MyIcon }}>. '
+        + `If you use the "${DEFAULT_ICON_FAMILY_CLASS}" font on purpose, this is a `
+        + 'false positive: the warning fires whenever the configured family equals '
+        + 'the package default, which is also the standard Bootstrap Icons setup. '
+        + 'It never appears in production builds.');
+}
+
 function subscribeToMediaQuery(query, callback) {
     const mediaQueryList = window.matchMedia(query);
     mediaQueryList.addEventListener('change', callback);
@@ -429,9 +548,43 @@ function useMediaQuery(mediaQuery, useListener = false) {
     return useSyncExternalStore(useListener ? (cb) => subscribeToMediaQuery(mediaQuery, cb) : noop, () => (mediaQuery ? checkMediaQuery(mediaQuery) : true), () => false);
 }
 
-function useMediaBreakpointUp(breakpoint, useListener = false) {
+const BREAKPOINTS = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl'];
+// Breakpoints read from the CSS on first use and shared by every component
+// that resolves responsive props: one computed-style read for the page,
+// instead of one per breakpoint per render. `dynamic-ui.css` has to be loaded
+// before rendering; if it isn't, the empty result is kept too, so a
+// misconfigured tree doesn't pay the read on every render (responsive props
+// then keep their default value and useResponsiveProp warns in development).
+let cssBreakpoints = null;
+function readCssBreakpoint(breakpoint) {
+    if (cssBreakpoints)
+        return cssBreakpoints[breakpoint];
+    if (typeof document === 'undefined')
+        return '';
+    const style = getComputedStyle(document.documentElement);
+    const read = Object.fromEntries(BREAKPOINTS.map((name) => [
+        name,
+        style.getPropertyValue(`--${PREFIX_BS}breakpoint-${name}`).trim(),
+    ]));
+    cssBreakpoints = read;
+    return read[breakpoint];
+}
+/**
+ * Pixel value of a breakpoint. `DContextProvider` reads them from the CSS and
+ * shares them through the context; outside of it (a tree without the
+ * provider, or its first render) they are read from the same CSS variables
+ * here, so responsive props resolve either way.
+ */
+function useBreakpointValue(breakpoint) {
     const { breakpoints } = useDContext();
-    const mediaQuery = useMemo(() => (`(min-width: ${breakpoints[breakpoint]})`), [breakpoint, breakpoints]);
+    const fromContext = breakpoints[breakpoint];
+    return useMemo(() => fromContext || readCssBreakpoint(breakpoint), [fromContext, breakpoint]);
+}
+function useMediaBreakpointUp(breakpoint, useListener = false) {
+    const value = useBreakpointValue(breakpoint);
+    // Without a breakpoint the query can't match; `not all` keeps it false
+    // instead of an invalid `(min-width: )`.
+    const mediaQuery = value ? `(min-width: ${value})` : 'not all';
     return useMediaQuery(mediaQuery, useListener);
 }
 function useMediaBreakpointUpXs(useListener = false) {
@@ -453,6 +606,7 @@ function useMediaBreakpointUpXxl(useListener = false) {
     return useMediaBreakpointUp('xxl', useListener);
 }
 
+let warnedMissingBreakpoints = false;
 /**
  * React hook to resolve a responsive property value based on the current viewport breakpoint.
  *
@@ -478,7 +632,16 @@ function useResponsiveProp(useListener = false) {
     const bpLgUp = useMediaBreakpointUpLg(useListener);
     const bpXlUp = useMediaBreakpointUpXl(useListener);
     const bpXxlUp = useMediaBreakpointUpXxl(useListener);
+    // `xs` is `0` and can't tell a missing variable apart, so `sm` is checked.
+    const hasBreakpoints = !!useBreakpointValue('sm');
     const responsivePropValue = useCallback((prop) => {
+        if (process.env.NODE_ENV !== 'production' && !hasBreakpoints && !warnedMissingBreakpoints) {
+            warnedMissingBreakpoints = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[Dynamic UI] The --${PREFIX_BS}breakpoint-* CSS variables are not available, so a `
+                + 'responsive prop (an object by breakpoint) falls back to its default value. Load '
+                + 'dynamic-ui.css before rendering. It never appears in production builds.');
+        }
         // Pick the highest matched breakpoint value that is defined in prop
         if (prop.xxl !== undefined && bpXxlUp)
             return prop.xxl;
@@ -494,14 +657,38 @@ function useResponsiveProp(useListener = false) {
             return prop.xs;
         // Fallback: return undefined if no breakpoint matches
         return undefined;
-    }, [bpSmUp, bpMdUp, bpLgUp, bpXlUp, bpXxlUp, bpXsUp]);
+    }, [bpSmUp, bpMdUp, bpLgUp, bpXlUp, bpXxlUp, bpXsUp, hasBreakpoints]);
     return { responsivePropValue };
 }
 
 function isIconComponent(value) {
     return typeof value !== 'string' && isValidElementType(value);
 }
-function DIconBase({ icon, color, style, className, size, useListenerSize = false, hasCircle = false, materialStyle = false, familyClass, familyPrefix, strokeWidth = 2, dataAttributes, }) {
+/**
+ * Renders an icon, resolving the `icon` prop in this order:
+ *
+ * 1. **Icon registry** — a string name found in `DContextProvider`'s
+ *    `iconRegistry` renders the component registered under it. A component
+ *    passed directly skips this step and renders as-is.
+ * 2. **lucide-react** — a PascalCase name exported by lucide-react renders that
+ *    icon. When `materialStyle` is on, this step is skipped and the name is
+ *    emitted as the text content of the icon-font element instead.
+ * 3. **Icon-font family** — anything left over renders as
+ *    `<i class="{familyClass} {familyPrefix}{name}">`, the legacy path for
+ *    Material Symbols and Bootstrap Icons. Outside production builds, a name
+ *    that reaches this step while the family is still the package default logs
+ *    a one-time warning.
+ *
+ * A name that resolves nowhere and has no family configured renders `?`.
+ *
+ * Every path is hidden from the accessibility tree by default (`aria-hidden`),
+ * since icons are overwhelmingly decorative. See `ariaHidden` / `ariaLabel` to
+ * override that for an icon that carries meaning on its own.
+ */
+function DIconBase({ icon: iconProp, color, style, className, size, useListenerSize = false, hasCircle = false, materialStyle = false, familyClass, familyPrefix, strokeWidth = 2, ariaHidden, ariaLabel, dataAttributes, }) {
+    const { iconRegistry } = useDContext();
+    // The registry wins over every other source, including Material icons.
+    const icon = resolveIconFromRegistry(iconProp, iconRegistry);
     // If materialStyle is true, use Material Design icons (legacy)
     const isStringIcon = typeof icon === 'string';
     const useMaterialIcons = materialStyle && isStringIcon;
@@ -523,6 +710,61 @@ function DIconBase({ icon, color, style, className, size, useListenerSize = fals
     }, [responsivePropValue, size]);
     const generateStyleVariables = useMemo(() => (Object.assign(Object.assign(Object.assign({}, resolvedSize && { [`--${PREFIX_BS}icon-component-size`]: resolvedSize }), hasCircle && { [`--${PREFIX_BS}icon-component-padding`]: `calc(var(--${PREFIX_BS}icon-component-size, 24px) * 0.4)` }), style)), [resolvedSize, hasCircle, style]);
     const generateClasses = useMemo(() => (Object.assign(Object.assign(Object.assign({ 'd-icon': true }, className && { [className]: true }), { 'd-icon-has-circle': hasCircle }), color && { [`d-icon-color-${color}`]: true })), [className, hasCircle, color]);
+    /**
+     * Decorative by default. `ariaHidden` and `ariaLabel` are not symmetric:
+     * hiding is absolute, so `ariaHidden` wins over a name, but `ariaHidden={false}`
+     * and `ariaLabel` agree — both expose the icon — and the name is honoured.
+     */
+    const accessibilityProps = useMemo(() => {
+        // Hiding is absolute: it wins over a name.
+        if (ariaHidden === true)
+            return { 'aria-hidden': true };
+        // A name exposes the icon, which is also what `ariaHidden={false}` asks for.
+        if (ariaLabel)
+            return { role: 'img', 'aria-label': ariaLabel };
+        // Exposed with no name: an explicit opt-out of the default, warned about below.
+        if (ariaHidden === false)
+            return {};
+        return { 'aria-hidden': true };
+    }, [ariaHidden, ariaLabel]);
+    /**
+     * `dataAttributes` is typed to `data-*`, but casting through it was the only
+     * way to reach the DOM before `ariaHidden` existed, so it still wins over the
+     * computed values — and therefore decides the effective state below.
+     */
+    const domAttributes = useMemo(() => (Object.assign(Object.assign({}, accessibilityProps), dataAttributes)), [accessibilityProps, dataAttributes]);
+    /**
+     * lucide-react hides its own `<svg>` unless it receives an a11y prop, and a
+     * registry component may do the same, which would keep the graphic out of the
+     * tree even when this wrapper is not hidden. Only matters when the icon is
+     * exposed without a name: under `role="img"` the wrapper is a leaf, so a
+     * hidden child changes nothing.
+     *
+     * A registry component that hardcodes `aria-hidden` on its own `<svg>` instead
+     * of spreading props still wins — nothing here can reach inside it.
+     */
+    const isExposedWithoutName = useMemo(() => {
+        const attributes = domAttributes;
+        const hidden = attributes['aria-hidden'];
+        return hidden !== true && hidden !== 'true' && !attributes.role;
+    }, [domAttributes]);
+    /**
+     * Diagnostics read the effective state, so a `dataAttributes` override that
+     * hides the icon after all is not reported as exposing it. Memoised like the
+     * values above, so re-rendering with the same props does not repeat them.
+     */
+    useMemo(() => {
+        if (process.env.NODE_ENV === 'production')
+            return;
+        if (ariaHidden === true && ariaLabel) {
+            // eslint-disable-next-line no-console
+            console.warn(`DIcon: ariaLabel "${ariaLabel}" is ignored because ariaHidden is true. Drop ariaHidden to expose the name.`);
+        }
+        if (ariaHidden === false && isExposedWithoutName) {
+            // eslint-disable-next-line no-console
+            console.warn('DIcon: ariaHidden={false} without an ariaLabel exposes an unnamed graphic to assistive technology. Pass ariaLabel to name it.');
+        }
+    }, [ariaHidden, ariaLabel, isExposedWithoutName]);
     const iconSize = useMemo(() => {
         if (resolvedSize) {
             const numSize = parseInt(resolvedSize, 10);
@@ -532,43 +774,46 @@ function DIconBase({ icon, color, style, className, size, useListenerSize = fals
     }, [resolvedSize]);
     // Render Material Design icon (legacy support)
     if (useMaterialIcons) {
-        return (jsx("i", Object.assign({ className: classNames(generateClasses, familyClass), style: generateStyleVariables }, dataAttributes, { children: isStringIcon ? icon : null })));
+        return (jsx("i", Object.assign({ className: classNames(generateClasses, familyClass), style: generateStyleVariables }, domAttributes, { children: isStringIcon ? icon : null })));
     }
     if (isIconComponent(icon)) {
-        return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, dataAttributes, { children: createElement(icon, {
-                width: resolvedSize || 24,
-                height: resolvedSize || 24,
-                strokeWidth,
-            }) })));
+        return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, domAttributes, { children: createElement(icon, Object.assign({ width: resolvedSize || 24, height: resolvedSize || 24, strokeWidth }, isExposedWithoutName && { 'aria-hidden': false })) })));
     }
     // Render Lucide icon
     if (!LucideIcon) {
-        if (isStringIcon && familyClass && familyPrefix) {
-            return (jsx("i", Object.assign({ className: classNames(generateClasses, familyClass, `${familyPrefix}${icon}`), style: generateStyleVariables }, dataAttributes)));
+        if (typeof icon === 'string' && familyClass && familyPrefix) {
+            if (process.env.NODE_ENV !== 'production') {
+                warnUnknownIcon(icon, familyClass, familyPrefix);
+            }
+            return (jsx("i", Object.assign({ className: classNames(generateClasses, familyClass, `${familyPrefix}${icon}`), style: generateStyleVariables }, domAttributes)));
         }
         // eslint-disable-next-line no-console
         console.warn(`Icon "${String(icon)}" not found in Lucide. Make sure to use PascalCase names (e.g., "Home", "User", "Settings")`);
-        return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, dataAttributes, { children: "?" })));
+        return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, domAttributes, { children: "?" })));
     }
-    return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, dataAttributes, { children: jsx(LucideIcon, { size: iconSize || 24, strokeWidth: strokeWidth }) })));
+    return (jsx("span", Object.assign({ className: classNames(generateClasses), style: generateStyleVariables }, domAttributes, { children: jsx(LucideIcon, Object.assign({ size: iconSize || 24, strokeWidth: strokeWidth }, isExposedWithoutName && { 'aria-hidden': false })) })));
 }
 
+/**
+ * Thin wrapper over `DIconBase` that fills the icon-font configuration
+ * (`familyClass`, `familyPrefix`, `materialStyle`) from `DContextProvider`
+ * whenever the caller does not pass it explicitly.
+ *
+ * Name resolution itself — registry, then lucide-react, then the icon-font
+ * family — lives in `DIconBase`, so both components behave identically.
+ */
 function DIcon(_a) {
     var { icon, familyClass: propFamilyClass, familyPrefix: propFamilyPrefix, materialStyle: propMaterialStyle } = _a, props = __rest(_a, ["icon", "familyClass", "familyPrefix", "materialStyle"]);
-    const { icon: { familyClass, familyPrefix, materialStyle, }, iconRegistry, } = useDContext();
-    const registryIcon = typeof icon === 'string'
-        ? iconRegistry === null || iconRegistry === void 0 ? void 0 : iconRegistry[icon]
-        : undefined;
-    const resolvedIcon = registryIcon || icon;
-    return (jsx(DIconBase, Object.assign({ icon: resolvedIcon, familyClass: propFamilyClass !== null && propFamilyClass !== void 0 ? propFamilyClass : familyClass, familyPrefix: propFamilyPrefix !== null && propFamilyPrefix !== void 0 ? propFamilyPrefix : familyPrefix, materialStyle: propMaterialStyle !== null && propMaterialStyle !== void 0 ? propMaterialStyle : materialStyle }, props)));
+    const { icon: { familyClass, familyPrefix, materialStyle, }, } = useDContext();
+    return (jsx(DIconBase, Object.assign({ icon: icon, familyClass: propFamilyClass !== null && propFamilyClass !== void 0 ? propFamilyClass : familyClass, familyPrefix: propFamilyPrefix !== null && propFamilyPrefix !== void 0 ? propFamilyPrefix : familyPrefix, materialStyle: propMaterialStyle !== null && propMaterialStyle !== void 0 ? propMaterialStyle : materialStyle }, props)));
 }
 
-function DAlert({ color = 'success', icon: iconProp, iconFamilyClass, iconFamilyPrefix, iconMaterialStyle, iconClose: iconCloseProp, iconCloseFamilyClass, iconCloseFamilyPrefix, iconCloseMaterialStyle, showClose, onClose, children, id, className, style, dataAttributes, }) {
+function DAlert({ color = 'success', role = 'alert', icon: iconProp, showIcon = true, iconFamilyClass, iconFamilyPrefix, iconMaterialStyle, iconClose: iconCloseProp, iconCloseFamilyClass, iconCloseFamilyPrefix, iconCloseMaterialStyle, showClose, closeAriaLabel = 'Close', onClose, children, id, className, style, dataAttributes, }) {
     const { icon: { materialStyle, familyClass, familyPrefix, }, iconMap: { alert, xLg, }, } = useDContext();
     const icon = useMemo(() => iconProp || alert[color], [alert, iconProp, color]);
     const iconClose = useMemo(() => (iconCloseProp || xLg), [iconCloseProp, xLg]);
     const generateClasses = useMemo(() => (Object.assign({ alert: true, [`alert-${color}`]: true, 'fade show': !!showClose }, className && { [className]: true })), [color, showClose, className]);
-    return (jsxs("div", Object.assign({ className: classNames(generateClasses), style: style, role: "alert", id: id }, dataAttributes, { children: [icon && (jsx(DIcon, { className: "alert-icon", icon: icon, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })), jsx("div", { className: "alert-text", children: children }), showClose && (jsx("button", { type: "button", className: "d-close", "aria-label": "Close", onClick: onClose, children: jsx(DIcon, { icon: iconClose, familyClass: iconCloseFamilyClass !== null && iconCloseFamilyClass !== void 0 ? iconCloseFamilyClass : familyClass, familyPrefix: iconCloseFamilyPrefix !== null && iconCloseFamilyPrefix !== void 0 ? iconCloseFamilyPrefix : familyPrefix, materialStyle: iconCloseMaterialStyle !== null && iconCloseMaterialStyle !== void 0 ? iconCloseMaterialStyle : materialStyle }) }))] })));
+    return (jsxs("div", Object.assign({ className: classNames(generateClasses), style: style }, role !== 'none' && { role }, { id: id }, dataAttributes, { children: [showIcon && icon && (jsx(DIcon, { className: "alert-icon", icon: icon, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })), jsx("div", { className: "alert-text", children: children }), showClose && (jsx("button", { type: "button", className: "d-close", "aria-label": closeAriaLabel, onClick: onClose, children: jsx(DIcon, { icon: iconClose, familyClass: iconCloseFamilyClass !== null && iconCloseFamilyClass !== void 0 ? iconCloseFamilyClass : familyClass, familyPrefix: iconCloseFamilyPrefix !== null && iconCloseFamilyPrefix !== void 0 ? iconCloseFamilyPrefix : familyPrefix, materialStyle: iconCloseMaterialStyle !== null && iconCloseMaterialStyle !== void 0 ? iconCloseMaterialStyle : materialStyle }) }))] })));
 }
 
 function DAvatar({ id, size, image, name: nameProp, useNameAsInitials = false, className, style, dataAttributes, }) {
@@ -634,6 +879,223 @@ function useProvidedRefOrCreate(providedRef) {
     return providedRef !== null && providedRef !== void 0 ? providedRef : createdRef;
 }
 
+/**
+ * Descendants the browser already exempts from a label's click forwarding.
+ *
+ * Per the HTML spec a label does nothing for events targeted at its interactive
+ * content descendants, so these need — and must get — no help from us: calling
+ * `preventDefault` on a click targeting a link, or on an image map area, would
+ * cancel the navigation it was meant to perform.
+ *
+ * The list mirrors the spec's interactive content, image maps included, since
+ * one of those carrying a `tabindex` would otherwise fall through to the
+ * pseudo-interactive branch below and be suppressed by mistake.
+ */
+const NATIVE_INTERACTIVE = 'a[href], area[href], button, input, select, textarea, details, summary, img[usemap], object[usemap], audio[controls], video[controls], embed, iframe';
+/**
+ * Descendants that act like controls without being interactive content.
+ *
+ * A tooltip or modal trigger built from a `span` with a role and a tabindex is
+ * the common case. Browsers do not exempt these, so a click on one activates
+ * the labelled control as well.
+ */
+const PSEUDO_INTERACTIVE = '[role="button"], [role="link"], [role="checkbox"], [role="switch"], [role="menuitem"], [tabindex]';
+/**
+ * Stops a click on a non-native trigger inside a `<label>` from also activating
+ * the labelled control.
+ *
+ * Verified against Chromium, which forwards the click for every one of the
+ * `PSEUDO_INTERACTIVE` selectors above while exempting the native ones. Note
+ * that jsdom does not reproduce this: its `isInteractiveContent` counts any
+ * element carrying a `tabindex` as interactive content, so a jsdom test passes
+ * whether or not this guard exists. That is why the guard is unit-tested
+ * directly rather than through a rendered component.
+ *
+ * Native interactive content returns early rather than falling through, since
+ * `preventDefault` on those clicks would cancel the link navigation or the
+ * image map the label is meant to let through.
+ *
+ * `DFormLabel` wires this in the capture phase so a trigger that stops
+ * propagation cannot skip it.
+ */
+function labelClickGuard(event) {
+    const label = event.currentTarget;
+    const target = event.target;
+    if (!(target === null || target === void 0 ? void 0 : target.closest))
+        return;
+    /**
+     * `closest` walks the whole ancestor chain, so a match may sit above the
+     * label — a card with a `role` or a `tabindex` wrapping the control and its
+     * label, say. Acting on one of those would suppress the plain label text's
+     * own click and leave the control unresponsive, so only matches inside the
+     * label count.
+     */
+    const inside = (match) => (!!match && match !== label && label.contains(match));
+    if (inside(target.closest(NATIVE_INTERACTIVE)))
+        return;
+    if (inside(target.closest(PSEUDO_INTERACTIVE))) {
+        event.preventDefault();
+    }
+}
+
+/**
+ * The `<label>` every form control renders, with the click guard already wired.
+ *
+ * Internal: it exists so the guard — and the lint exception it needs — lives in
+ * one place instead of being repeated across every input component.
+ *
+ * The guard runs in the capture phase, not on bubble: a tooltip or modal
+ * trigger that calls `stopPropagation()` in its own handler — a common pattern —
+ * would otherwise keep the guard from ever running, and the browser would go on
+ * to activate the labelled control. Confirmed in Chromium, where the same
+ * trigger toggles the control with a bubble-phase guard and does not with this
+ * one. Capturing changes nothing else: `preventDefault` applies to the default
+ * action, which is evaluated after propagation either way.
+ *
+ * The `jsx-a11y` rules below assume a click handler is being used to make a
+ * non-interactive element interactive, which then owes the keyboard an
+ * equivalent. This handler does the opposite: it suppresses a pointer-only
+ * behaviour, the click a label forwards to its control, and adds no way to
+ * activate anything. Keyboard support for a nested trigger is the consumer's:
+ * `<a href>` carries its own, while a `span` with a role and a tabindex is
+ * focusable but inert until they handle Enter and Space themselves.
+ */
+function DFormLabel({ htmlFor, className, children }) {
+    /**
+     * React 19 renders a bigint child; React 18 throws on one, and this package
+     * supports both (`react: >=18 <20`). The label helpers count bigint as text
+     * because that is what it draws as, so it is turned into its string form here
+     * — the one place every control's label passes through — rather than pushing
+     * a version check onto consumers.
+     *
+     * Only a bigint at the top level: one buried inside an array or a fragment is
+     * the consumer's own React child, and normalising it would mean walking and
+     * rebuilding the whole subtree.
+     */
+    const content = typeof children === 'bigint' ? String(children) : children;
+    return (
+    /* eslint-disable-next-line jsx-a11y/click-events-have-key-events,
+       jsx-a11y/no-noninteractive-element-interactions */
+    jsx("label", { htmlFor: htmlFor, className: className, onClickCapture: labelClickGuard, children: content }));
+}
+
+/**
+ * Whether a `label` node has something to render.
+ *
+ * The render paths cannot test `label` for truthiness: since the prop widened
+ * to `ReactNode` it also accepts `0`, which React renders as the text "0" and
+ * which `isTextLabel` counts as a text label, yet which a truthiness check
+ * would drop — leaving the control visibly unlabelled.
+ *
+ * Absent (`undefined`, `null`), empty (`''`) and boolean labels render nothing,
+ * so they are the ones that stand for "no label". The empty string matters
+ * because it is the default several components fall back to.
+ *
+ * Arrays are inspected rather than taken at face value: `label={items.map(...)}`
+ * over an empty list yields `[]`, while a list of skipped entries yields
+ * `[false, null]`. Both render nothing, so treating them as content would leave
+ * an empty `<label>` on the page — and make the naming warning fire over a
+ * label that was never there.
+ *
+ * Only arrays, though, even though `ReactNode` admits any iterable. Reading a
+ * one-shot iterator — a generator — would exhaust it here, and the component
+ * goes on to render the same value, so the label would vanish precisely because
+ * we checked for it. An array can be walked as often as needed; anything else
+ * is taken on faith.
+ *
+ * Anything else — an element, a portal, a generator — counts as content: what
+ * it renders is only knowable by rendering it, and an element that draws
+ * nothing visible is the consumer's decision rather than an absent label.
+ */
+function hasLabelContent(label) {
+    if (label === undefined || label === null || typeof label === 'boolean') {
+        return false;
+    }
+    if (typeof label === 'string') {
+        return label !== '';
+    }
+    if (isValidElement(label)) {
+        return true;
+    }
+    if (Array.isArray(label)) {
+        return label.some(hasLabelContent);
+    }
+    return true;
+}
+
+/**
+ * Narrows a `label` node to the plain-text case.
+ *
+ * `label` accepts any `ReactNode` so patterns like a terms-and-conditions link
+ * or an info trigger can live next to the field name. Anything that is not text
+ * cannot be forwarded to a string-only attribute (`aria-label`, `placeholder`)
+ * nor laid out by Bootstrap's `form-floating`, so those paths check this first.
+ *
+ * Numbers and bigints count as text: React renders them as their string form
+ * and so does `String()`, which is what the string-only attributes end up
+ * receiving. `bigint` is part of `ReactNode` under these React types, so
+ * leaving it out made a label React draws as text get treated as a rich node.
+ * React 18 cannot render one, which `DFormLabel` handles by rendering its
+ * string form — the classification stays true for every supported React.
+ */
+function isTextLabel(label) {
+    return typeof label === 'string'
+        || typeof label === 'number'
+        || typeof label === 'bigint';
+}
+
+/**
+ * Components already reported, keyed by component and reason, so the same
+ * mistake only warns once per page load however often it re-renders or however
+ * many instances exist.
+ */
+const warnedLabels = new Set();
+function warnOnce(key, message) {
+    if (warnedLabels.has(key))
+        return;
+    warnedLabels.add(key);
+    // eslint-disable-next-line no-console
+    console.warn(`[Dynamic UI] ${message} It never appears in production builds.`);
+}
+/**
+ * Warns, only outside production builds, about the two ways a non-text `label`
+ * goes wrong.
+ *
+ * A text label doubles as the control's accessible name. A `ReactNode` one does
+ * not: the name becomes whatever the subtree happens to compute to, which for a
+ * label carrying a link or an icon trigger reads as the wrong thing or as
+ * nothing at all — so an explicit name is needed. Which prop carries it differs
+ * per component, hence `accessibleNameProp`: naming the wrong one would send
+ * the developer to a prop their component rejects.
+ *
+ * `form-floating` is the second case: it animates a single line of text between
+ * the placeholder and the label position, so a node with its own height or its
+ * own interactive children breaks the layout rather than the semantics.
+ *
+ * Labels the render paths drop are skipped through the same `hasLabelContent`
+ * they use, so `label={condition && <span />}` with a false condition warns
+ * about nothing: there is no label on the page to name.
+ *
+ * The `process.env.NODE_ENV` guard belongs at the call site — that is what
+ * bundlers constant-fold, dropping this module from a consumer's production
+ * bundle.
+ */
+function warnLabelUsage({ component, label, hasAccessibleName, accessibleNameProp, floatingLabel = false, }) {
+    if (!hasLabelContent(label) || isTextLabel(label))
+        return;
+    if (!hasAccessibleName) {
+        warnOnce(`${component}:name`, `${component}: a non-text "label" does not give the control a reliable accessible name. `
+            + `Pass ${accessibleNameProp} with the plain-text name of the field, since the label `
+            + 'subtree may include links, icons or markup that read as the wrong name or as none at all.');
+    }
+    if (floatingLabel) {
+        warnOnce(`${component}:floating`, `${component}: "floatingLabel" expects a text "label". `
+            + 'The floating layout animates a single line of text, so a node with its own height '
+            + 'or its own interactive children overflows the control. '
+            + 'Use the default label layout for rich labels.');
+    }
+}
+
 function DInput(_a, ref) {
     var { id: idProp, style, className, label = '', disabled = false, loading = false, iconFamilyClass, iconFamilyPrefix, iconMaterialStyle, iconStart, iconStartDisabled, iconStartFamilyClass, iconStartFamilyPrefix, iconStartAriaLabel, iconStartTabIndex, iconStartMaterialStyle, iconEnd, iconEndDisabled, iconEndFamilyClass, iconEndFamilyPrefix, iconEndAriaLabel, iconEndTabIndex, iconEndMaterialStyle, hint, size, invalid = false, valid = false, floatingLabel = false, inputStart, inputEnd, value, placeholder = '', dataAttributes, readonly, onChange, onIconStartClick, onIconEndClick } = _a, inputProps = __rest(_a, ["id", "style", "className", "label", "disabled", "loading", "iconFamilyClass", "iconFamilyPrefix", "iconMaterialStyle", "iconStart", "iconStartDisabled", "iconStartFamilyClass", "iconStartFamilyPrefix", "iconStartAriaLabel", "iconStartTabIndex", "iconStartMaterialStyle", "iconEnd", "iconEndDisabled", "iconEndFamilyClass", "iconEndFamilyPrefix", "iconEndAriaLabel", "iconEndTabIndex", "iconEndMaterialStyle", "hint", "size", "invalid", "valid", "floatingLabel", "inputStart", "inputEnd", "value", "placeholder", "dataAttributes", "readonly", "onChange", "onIconStartClick", "onIconEndClick"]);
     const inputRef = useProvidedRefOrCreate(ref);
@@ -673,7 +1135,7 @@ function DInput(_a, ref) {
     const inputComponent = useMemo(() => (jsx("input", Object.assign({ ref: inputRef, id: id, className: classNames('form-control', {
             'is-invalid': invalid,
             'is-valid': valid,
-        }), disabled: disabled || loading, readOnly: readonly, value: value, onChange: handleOnChange }, (floatingLabel || placeholder) && { placeholder: floatingLabel ? '' : placeholder }, ariaDescribedby && { 'aria-describedby': ariaDescribedby }, inputProps))), [
+        }), disabled: disabled || loading, readOnly: readonly, value: value, onChange: handleOnChange }, (floatingLabel || placeholder) && { placeholder: floatingLabel ? '' : placeholder }, ariaDescribedby && { 'aria-describedby': ariaDescribedby }, invalid && { 'aria-invalid': true }, inputProps))), [
         ariaDescribedby,
         disabled,
         handleOnChange,
@@ -688,7 +1150,7 @@ function DInput(_a, ref) {
         value,
         readonly,
     ]);
-    const labelComponent = useMemo(() => (jsx("label", { htmlFor: id, children: label })), [
+    const labelComponent = useMemo(() => (jsx(DFormLabel, { htmlFor: id, children: label })), [
         id,
         label,
     ]);
@@ -698,11 +1160,20 @@ function DInput(_a, ref) {
         }
         return inputComponent;
     }, [floatingLabel, inputComponent, labelComponent]);
-    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [label && !floatingLabel && labelComponent, jsxs("div", { className: classNames({
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInput',
+            label,
+            hasAccessibleName: !!inputProps['aria-label'] || !!inputProps['aria-labelledby'],
+            accessibleNameProp: 'aria-label',
+            floatingLabel,
+        });
+    }
+    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [hasLabelContent(label) && !floatingLabel && labelComponent, jsxs("div", { className: classNames({
                     [`input-group-${size}`]: !!size,
                     'input-group': true,
                     'has-validation': invalid || valid,
-                }), children: [!!inputStart && (jsx("div", { className: "input-group-text", id: `${id}InputStart`, children: inputStart })), iconStart && (onIconStartClick ? (jsx("button", { type: "button", className: "input-group-text", id: `${id}Start`, onClick: handleOnIconStartClick, disabled: disabled || loading || iconStartDisabled, "aria-label": iconStartAriaLabel || (typeof iconStart === 'string' ? iconStart : 'start icon'), tabIndex: iconStartTabIndex, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle }) })) : (jsx("div", { className: "input-group-text", id: `${id}Start`, "aria-hidden": "true", tabIndex: -1, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle }) }))), dynamicComponent, (iconEnd && !loading) && (onIconEndClick ? (jsx("button", { type: "button", className: "input-group-text", id: `${id}End`, onClick: handleOnIconEndClick, disabled: disabled || loading || iconEndDisabled, "aria-label": iconEndAriaLabel || (typeof iconEnd === 'string' ? iconEnd : 'end icon'), tabIndex: iconEndTabIndex, children: jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle }) })) : (jsx("div", { className: "input-group-text", id: `${id}End`, "aria-hidden": "true", tabIndex: -1, children: jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle }) }))), loading && (jsx("div", { className: "input-group-text", id: `${id}Loading`, children: jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", "data-testid": "loading-spinner", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }) })), !!inputEnd && (jsx("div", { className: "input-group-text", id: `${id}InputEnd`, children: inputEnd }))] }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
+                }), children: [!!inputStart && (jsx("div", { className: "input-group-text", id: `${id}InputStart`, children: inputStart })), iconStart && (onIconStartClick ? (jsx("button", { type: "button", className: "input-group-text", id: `${id}Start`, onClick: handleOnIconStartClick, disabled: disabled || loading || iconStartDisabled, "aria-label": iconStartAriaLabel || (typeof iconStart === 'string' ? iconStart : 'start icon'), tabIndex: iconStartTabIndex, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle }) })) : (jsx("div", { className: "input-group-text", id: `${id}Start`, tabIndex: -1, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle }) }))), dynamicComponent, (iconEnd && !loading) && (onIconEndClick ? (jsx("button", { type: "button", className: "input-group-text", id: `${id}End`, onClick: handleOnIconEndClick, disabled: disabled || loading || iconEndDisabled, "aria-label": iconEndAriaLabel || (typeof iconEnd === 'string' ? iconEnd : 'end icon'), tabIndex: iconEndTabIndex, children: jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle }) })) : (jsx("div", { className: "input-group-text", id: `${id}End`, tabIndex: -1, children: jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle }) }))), loading && (jsx("div", { className: "input-group-text", id: `${id}Loading`, children: jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", "data-testid": "loading-spinner", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }) })), !!inputEnd && (jsx("div", { className: "input-group-text", id: `${id}InputEnd`, children: inputEnd }))] }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
 }
 const ForwardedDInput = forwardRef(DInput);
 ForwardedDInput.displayName = 'DInput';
@@ -1185,8 +1656,46 @@ const DButton = forwardRef((props, ref) => {
 });
 DButton.displayName = 'DButton';
 
+/**
+ * Controls already reported, keyed by kind and icon, so the same unlabelled one
+ * only warns once per page load however often it re-renders or however many
+ * instances exist.
+ */
+const warnedControls = new Set();
+/**
+ * Warns, once per icon and only outside production builds, that an icon-only
+ * button has no accessible name.
+ *
+ * The control has no text to fall back on and its icon is hidden from the
+ * accessibility tree, so the name has to be given explicitly. `aria-label` is
+ * the direct way; on a button `aria-labelledby` and `title` count too, since
+ * `rest` reaches the DOM there, while an anchor drops them — hence `kind`, so
+ * the advice matches what the element can actually receive.
+ *
+ * A legacy icon-font icon used to leak its ligature as the name by accident —
+ * never a good one, being unlocalised and often meaningless ("more_vert") — and
+ * no longer does, so the omission is now visible instead of silent.
+ *
+ * The `process.env.NODE_ENV` guard is what bundlers constant-fold, so the whole
+ * call — and this module — drops out of a consumer's production bundle.
+ */
+function warnMissingAccessibleName(icon, kind) {
+    const key = `${kind}:${icon}`;
+    if (warnedControls.has(key))
+        return;
+    warnedControls.add(key);
+    const alternatives = kind === 'button'
+        ? 'On a button, aria-labelledby or title work too. '
+        : 'A link renders from the href branch, which does not forward aria-labelledby or title, so aria-label is the only option. ';
+    // eslint-disable-next-line no-console
+    console.warn(`[Dynamic UI] DButtonIcon: the "${icon}" ${kind} has no accessible name. `
+        + 'Pass aria-label, since an icon-only control has no text to fall back on '
+        + `and its icon is hidden from the accessibility tree. ${alternatives}`
+        + 'It never appears in production builds.');
+}
+
 function DButtonIcon(_a) {
-    var { id, icon, size, className, variant, state, loadingAriaLabel, iconMaterialStyle, disabled = false, color = 'primary', loading = false, href, target, rel, stopPropagationEnabled = true, style, iconFamilyClass, iconFamilyPrefix, dataAttributes, onClick, 'aria-label': ariaLabelProp } = _a, rest = __rest(_a, ["id", "icon", "size", "className", "variant", "state", "loadingAriaLabel", "iconMaterialStyle", "disabled", "color", "loading", "href", "target", "rel", "stopPropagationEnabled", "style", "iconFamilyClass", "iconFamilyPrefix", "dataAttributes", "onClick", 'aria-label']);
+    var { id, icon, size, iconSize, className, variant, state, loadingAriaLabel, iconMaterialStyle, disabled = false, color = 'primary', loading = false, href, target, rel, stopPropagationEnabled = true, style, iconFamilyClass, iconFamilyPrefix, dataAttributes, onClick, 'aria-label': ariaLabelProp } = _a, rest = __rest(_a, ["id", "icon", "size", "iconSize", "className", "variant", "state", "loadingAriaLabel", "iconMaterialStyle", "disabled", "color", "loading", "href", "target", "rel", "stopPropagationEnabled", "style", "iconFamilyClass", "iconFamilyPrefix", "dataAttributes", "onClick", 'aria-label']);
     const { icon: { familyClass, familyPrefix, materialStyle, }, } = useDContext();
     const generateClasses = useMemo(() => {
         const variantClass = !variant || variant === 'solid'
@@ -1194,6 +1703,9 @@ function DButtonIcon(_a) {
             : `btn-${variant}-${color}`;
         return Object.assign(Object.assign(Object.assign({ 'btn d-button-icon': true, [variantClass]: true }, size && { [`btn-${size}`]: true }), (state && state !== 'disabled') && { [state]: true }), { loading });
     }, [variant, color, size, state, loading]);
+    // A responsive iconSize has to follow viewport changes, so DIcon only
+    // listens to breakpoints when it gets an object; a plain string needs none.
+    const useIconSizeListener = typeof iconSize === 'object';
     const isDisabled = useMemo(() => (state === 'disabled' || loading || disabled), [state, loading, disabled]);
     const clickHandler = useCallback((event) => {
         if (stopPropagationEnabled) {
@@ -1208,14 +1720,23 @@ function DButtonIcon(_a) {
     const ariaLabel = useMemo(() => (loading
         ? loadingAriaLabel || ariaLabelProp
         : ariaLabelProp), [loading, loadingAriaLabel, ariaLabelProp]);
+    /**
+     * `aria-labelledby` and `title` also name a control, but they travel in `rest`,
+     * which only the button branch spreads — an anchor drops them, so there the
+     * button really is unnamed and the warning still applies.
+     */
+    const hasAccessibleName = useMemo(() => !!ariaLabel || (!href && (!!rest['aria-labelledby'] || !!rest.title)), [ariaLabel, href, rest]);
+    if (process.env.NODE_ENV !== 'production' && !hasAccessibleName) {
+        warnMissingAccessibleName(icon, href ? 'link' : 'button');
+    }
     if (href) {
         return (jsx("a", Object.assign({ id: id, href: href, target: target, rel: rel, className: classNames(generateClasses, className), style: style, onClick: clickHandler, "aria-label": ariaLabel, "aria-disabled": isDisabled }, dataAttributes, { children: loading
                 ? (jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }))
-                : (jsx(DIcon, { icon: icon, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })) })));
+                : (jsx(DIcon, { icon: icon, size: iconSize, useListenerSize: useIconSizeListener, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })) })));
     }
     return (jsx("button", Object.assign({ className: classNames(generateClasses, className), style: style, disabled: state === 'disabled' || loading, onClick: clickHandler, "aria-label": ariaLabel }, dataAttributes, rest, { children: loading
             ? (jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }))
-            : (jsx(DIcon, { icon: icon, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })) })));
+            : (jsx(DIcon, { icon: icon, size: iconSize, useListenerSize: useIconSizeListener, familyClass: iconFamilyClass !== null && iconFamilyClass !== void 0 ? iconFamilyClass : familyClass, familyPrefix: iconFamilyPrefix !== null && iconFamilyPrefix !== void 0 ? iconFamilyPrefix : familyPrefix, materialStyle: iconMaterialStyle !== null && iconMaterialStyle !== void 0 ? iconMaterialStyle : materialStyle })) })));
 }
 
 function DCardHeader({ className, style, children, }) {
@@ -1411,24 +1932,102 @@ function DSelectPlaceholder(_a) {
     return (jsx(components.Placeholder, Object.assign({ innerProps: innerProps, selectProps: selectProps }, props, { children: children })));
 }
 
+/**
+ * Name of the elements an `aria-labelledby` points at, joined as the accessible
+ * name computation does. Read when the message is built rather than when the
+ * select renders, since the referenced elements may render after it.
+ *
+ * Each element contributes its own `aria-label` when it has one, and its text
+ * otherwise. That covers the targets a select is labelled by in practice — a
+ * heading, a span, a labelled region — without shipping the full accessible
+ * name algorithm; names derived from descendants' `aria-label`, `alt` or
+ * hidden content are not resolved, so pass `ariaLiveMessages` for those.
+ */
+function resolveLabelledBy(labelledBy) {
+    if (typeof document === 'undefined')
+        return '';
+    return labelledBy
+        .split(/\s+/)
+        .map((ref) => {
+        var _a, _b;
+        const element = document.getElementById(ref);
+        return ((_a = element === null || element === void 0 ? void 0 : element.getAttribute('aria-label')) === null || _a === void 0 ? void 0 : _a.trim()) || ((_b = element === null || element === void 0 ? void 0 : element.textContent) === null || _b === void 0 ? void 0 : _b.trim());
+    })
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Builds react-select's `guidance` live message around the control's name.
+ *
+ * react-select announces "<aria-label> is focused" on the first focus of the
+ * input, falling back to "Select" when there is no `aria-label`. Neither a text
+ * `label` nor `aria-labelledby` reaches that message, so the announcement would
+ * disagree with the name assistive technology exposes.
+ *
+ * The name follows the accessible name precedence: `aria-labelledby`, then
+ * `aria-label`, then the `<label>`. react-select does not export its default
+ * messages, so this mirrors them for every context and only swaps the name.
+ */
+function createAriaGuidance({ labelledBy, label }) {
+    return ({ 'aria-label': ariaLabel, context, isSearchable, isMulti, tabSelectsValue, isInitialFocus, }) => {
+        switch (context) {
+            case 'menu':
+                return `Use Up and Down to choose options, press Enter to select the currently focused option, press Escape to exit the menu${tabSelectsValue ? ', press Tab to select the option and exit the menu' : ''}.`;
+            case 'input': {
+                if (!isInitialFocus)
+                    return '';
+                const name = (labelledBy && resolveLabelledBy(labelledBy)) || ariaLabel || label || 'Select';
+                return `${name} is focused ${isSearchable ? ',type to refine list' : ''}, press Down to open the menu, ${isMulti ? ' press left to focus selected values' : ''}`;
+            }
+            case 'value':
+                return 'Use left and right to toggle between focused values, press Backspace to remove the currently focused value';
+            default:
+                return '';
+        }
+    };
+}
+
 function DSelect(_a) {
-    var { id: idProp, className, style, label, hint, iconFamilyClass, iconFamilyPrefix, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartAriaLabel, iconStartTabIndex, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndAriaLabel, iconEndTabIndex, invalid, valid, menuWithMaxContent = false, disabled, clearable, loading, floatingLabel = false, rtl, searchable, multi, components, defaultValue, placeholder, onIconStartClick, onIconEndClick, dataAttributes, ariaLabel = 'Search for an option' } = _a, props = __rest(_a, ["id", "className", "style", "label", "hint", "iconFamilyClass", "iconFamilyPrefix", "iconStart", "iconStartFamilyClass", "iconStartFamilyPrefix", "iconStartAriaLabel", "iconStartTabIndex", "iconEnd", "iconEndFamilyClass", "iconEndFamilyPrefix", "iconEndAriaLabel", "iconEndTabIndex", "invalid", "valid", "menuWithMaxContent", "disabled", "clearable", "loading", "floatingLabel", "rtl", "searchable", "multi", "components", "defaultValue", "placeholder", "onIconStartClick", "onIconEndClick", "dataAttributes", "ariaLabel"]);
+    var { id: idProp, inputId: inputIdProp, className, style, label, hint, iconFamilyClass, iconFamilyPrefix, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartAriaLabel, iconStartTabIndex, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndAriaLabel, iconEndTabIndex, invalid, valid, menuWithMaxContent = false, disabled, clearable, loading, floatingLabel = false, rtl, searchable, multi, components, defaultValue, placeholder, onIconStartClick, onIconEndClick, dataAttributes, ariaLabel, ariaLiveMessages } = _a, props = __rest(_a, ["id", "inputId", "className", "style", "label", "hint", "iconFamilyClass", "iconFamilyPrefix", "iconStart", "iconStartFamilyClass", "iconStartFamilyPrefix", "iconStartAriaLabel", "iconStartTabIndex", "iconEnd", "iconEndFamilyClass", "iconEndFamilyPrefix", "iconEndAriaLabel", "iconEndTabIndex", "invalid", "valid", "menuWithMaxContent", "disabled", "clearable", "loading", "floatingLabel", "rtl", "searchable", "multi", "components", "defaultValue", "placeholder", "onIconStartClick", "onIconEndClick", "dataAttributes", "ariaLabel", "ariaLiveMessages"]);
     const innerId = useId();
     const id = useMemo(() => idProp || innerId, [idProp, innerId]);
+    // The `<label>` must point at the element react-select renders the input
+    // with, so an explicit `inputId` wins over `id` for both.
+    const inputId = inputIdProp || id;
+    // A text label or `aria-labelledby` names the control without going through
+    // `aria-label`, which is all react-select's focus announcement reads, so it
+    // is handed those names explicitly. Messages passed by the consumer still
+    // take precedence.
+    const textLabel = hasLabelContent(label) && isTextLabel(label) ? String(label) : undefined;
+    const labelledBy = props['aria-labelledby'];
+    const liveMessages = useMemo(() => (textLabel || labelledBy
+        ? Object.assign({ guidance: createAriaGuidance({ labelledBy, label: textLabel }) }, ariaLiveMessages) : ariaLiveMessages), [textLabel, labelledBy, ariaLiveMessages]);
     const handleOnIconStartClick = useCallback(() => {
         onIconStartClick === null || onIconStartClick === void 0 ? void 0 : onIconStartClick(defaultValue);
     }, [onIconStartClick, defaultValue]);
     const handleOnIconEndClick = useCallback(() => {
         onIconEndClick === null || onIconEndClick === void 0 ? void 0 : onIconEndClick(defaultValue);
     }, [onIconEndClick, defaultValue]);
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DSelect',
+            label,
+            // `{...props}` is spread after `ariaLabel`, so a native `aria-label` in it
+            // is the one that reaches the input, even when it is `undefined`.
+            hasAccessibleName: !!('aria-label' in props ? props['aria-label'] : ariaLabel)
+                || !!labelledBy,
+            accessibleNameProp: 'ariaLabel',
+            floatingLabel,
+        });
+    }
     return (jsxs("div", Object.assign({ className: classNames('d-select', className, {
             'd-select-floating': floatingLabel,
             disabled: disabled || loading,
-        }), style: style }, dataAttributes, { children: [label && (jsx("label", { htmlFor: id, children: label })), jsxs("div", { className: classNames({
+        }), style: style }, dataAttributes, { children: [hasLabelContent(label) && (jsx(DFormLabel, { htmlFor: inputId, children: label })), jsxs("div", { className: classNames({
                     'input-group': true,
                     'has-validation': invalid,
                     disabled: disabled || loading,
-                }), children: [iconStart && (jsx("button", { type: "button", className: "input-group-text", id: `${id}Start`, onClick: handleOnIconStartClick, disabled: disabled || loading, "aria-label": iconStartAriaLabel, tabIndex: iconStartTabIndex, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass, familyPrefix: iconStartFamilyPrefix }) })), jsx(Select, Object.assign({ id: `${id}Container`, inputId: id, "aria-label": ariaLabel, styles: {
+                }), children: [iconStart && (jsx("button", { type: "button", className: "input-group-text", id: `${id}Start`, onClick: handleOnIconStartClick, disabled: disabled || loading, "aria-label": iconStartAriaLabel, tabIndex: iconStartTabIndex, children: jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass, familyPrefix: iconStartFamilyPrefix }) })), jsx(Select, Object.assign({ id: `${id}Container`, inputId: inputId, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (hasLabelContent(label) || props['aria-labelledby'] ? undefined : 'Search for an option'), ariaLiveMessages: liveMessages, styles: {
                             control: (base) => (Object.assign(Object.assign({}, base), { minHeight: 'unset' })),
                             container: (base) => (Object.assign(Object.assign({}, base), { flex: 1 })),
                             menu: (base) => (Object.assign(Object.assign({}, base), { width: menuWithMaxContent ? 'max-context' : '100%', zIndex: 1000 })),
@@ -1623,10 +2222,40 @@ function formatValue(value, currencyOptions) {
     }
     return currency(value, Object.assign(Object.assign({}, currencyOptions), { symbol: '' })).format();
 }
-function useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref, minValue, maxValue) {
+/**
+ * State and handlers for a currency input: a formatted string while the field
+ * is idle and the raw number while it is being edited.
+ *
+ * `minValue`/`maxValue` bound the value. With `clamp` (default `true`) an
+ * out-of-range value is brought into range whenever it is not being typed:
+ * on mount, when `value` or the bounds change, and on blur. Every time the
+ * clamp changes the value, `onChange` receives the clamped number, so the
+ * input and the consumer's state never disagree. While the field is focused
+ * the typed number is reported as is, so a partial entry is not rewritten.
+ *
+ * With `clamp: false` the value is never changed: the bounds only feed
+ * `isOverMax` / `isUnderMin`, so the consumer can show its own message (e.g.
+ * "You exceeded the limit") and keep the entered amount.
+ *
+ * Controlled usage follows the same contract as a native controlled input:
+ * reflect `onChange` into `value` in the same event (`setState` in the
+ * handler). The hook keeps showing `value` whenever it isn't being edited, so
+ * a consumer can reject a change by keeping `value` as it was. Deferring the
+ * update (a timer, awaiting a request) makes the hook see a stale `value` in
+ * between: the field can flash the previous amount and a clamp can be
+ * reported again when the deferred value arrives.
+ */
+function useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref, minValue, maxValue, clamp = true) {
     const inputRef = useProvidedRefOrCreate(ref);
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    // Last clamp reported through `onChange`, as the value it came from and the
+    // value it produced. StrictMode replays effects, and a consumer may reflect
+    // `onChange` asynchronously, both before `value` catches up: the same clamp
+    // must not be reported twice.
+    const lastReportedClampRef = useRef(null);
     const clampValue = useCallback((newValue) => {
-        if (newValue === undefined) {
+        if (newValue === undefined || !clamp) {
             return newValue;
         }
         let clampedValue = newValue;
@@ -1637,10 +2266,9 @@ function useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref
             clampedValue = Math.min(clampedValue, maxValue);
         }
         return clampedValue;
-    }, [minValue, maxValue]);
+    }, [minValue, maxValue, clamp]);
     const [innerType, setInnerType] = useState('text');
-    const [innerNumber, setInnerNumber] = useState(clampValue(value));
-    const [innerString, setInnerString] = useState(formatValue(clampValue(value), currencyOptions));
+    const [innerNumber, setInnerNumber] = useState(() => clampValue(value));
     const handleOnFocus = useCallback((event) => {
         event.stopPropagation();
         setInnerType('number');
@@ -1652,35 +2280,60 @@ function useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref
         const clampedNumber = clampValue(innerNumber);
         if (clampedNumber !== innerNumber) {
             setInnerNumber(clampedNumber);
-            setInnerString(formatValue(clampedNumber, currencyOptions));
+            // Recorded before notifying, so the sync effect that runs when editing
+            // ends doesn't report the same clamp again while `value` still holds the
+            // typed number.
+            lastReportedClampRef.current = { from: value, to: clampedNumber };
             onChange === null || onChange === void 0 ? void 0 : onChange(clampedNumber);
         }
         onBlur === null || onBlur === void 0 ? void 0 : onBlur(event);
-    }, [onBlur, innerNumber, clampValue, currencyOptions, onChange]);
+    }, [onBlur, innerNumber, clampValue, onChange, value]);
     const handleOnChange = useCallback((newValue) => {
         const newNumber = (newValue === undefined || newValue === '') ? undefined : Number(newValue);
         if (newNumber !== innerNumber) {
             setInnerNumber(newNumber);
-            setInnerString(formatValue(newNumber, currencyOptions));
             onChange === null || onChange === void 0 ? void 0 : onChange(newNumber);
         }
-    }, [currencyOptions, onChange, innerNumber]);
-    const isMountedRef = useRef(false);
+    }, [onChange, innerNumber]);
+    const isEditing = innerType === 'number';
+    // Keep the inner value in sync with `value` and the bounds. While the user
+    // is typing, the consumer echoes the typed number back through `value`, so
+    // it is taken as is; otherwise it is clamped, and a clamp that changes it is
+    // reported through `onChange`.
     useEffect(() => {
-        if (!isMountedRef.current) {
-            isMountedRef.current = true;
-            return;
+        var _a;
+        const nextNumber = isEditing ? value : clampValue(value);
+        if (nextNumber !== innerNumber) {
+            setInnerNumber(nextNumber);
+        }
+        if (nextNumber !== value) {
+            const last = lastReportedClampRef.current;
+            if (!last || last.from !== value || last.to !== nextNumber) {
+                lastReportedClampRef.current = { from: value, to: nextNumber };
+                (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, nextNumber);
+            }
         }
-        if (value !== innerNumber) {
-            setInnerNumber(value);
-            setInnerString(formatValue(value, currencyOptions));
+        else {
+            lastReportedClampRef.current = null;
         }
-    }, [value, currencyOptions, innerNumber]);
-    const innerValue = useMemo(() => { var _a; return (innerType === 'number' ? (_a = innerNumber === null || innerNumber === void 0 ? void 0 : innerNumber.toString()) !== null && _a !== void 0 ? _a : '' : innerString !== null && innerString !== void 0 ? innerString : ''); }, [innerType, innerNumber, innerString]);
+        // `innerNumber` is read, not tracked: the effect reacts to the consumer's
+        // value and to the bounds, not to its own updates.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value, clampValue, isEditing]);
+    // Derived, not stored: the formatted text always matches the current number
+    // and options, even when both change in the same render. It depends on the
+    // options object itself, so a new custom `format` function is honored too;
+    // formatting is cheap and doesn't feed the synchronization effect.
+    const innerString = useMemo(() => formatValue(innerNumber, currencyOptions), [innerNumber, currencyOptions]);
+    const innerValue = useMemo(() => { var _a; return (innerType === 'number' ? (_a = innerNumber === null || innerNumber === void 0 ? void 0 : innerNumber.toString()) !== null && _a !== void 0 ? _a : '' : innerString); }, [innerType, innerNumber, innerString]);
+    const isOverMax = maxValue !== undefined && innerNumber !== undefined && innerNumber > maxValue;
+    const isUnderMin = minValue !== undefined && innerNumber !== undefined && innerNumber < minValue;
     return {
         inputRef,
         innerValue,
         innerType,
+        isOverMax,
+        isUnderMin,
         handleOnFocus,
         handleOnChange,
         handleOnBlur,
@@ -1931,38 +2584,142 @@ function useOtp({ action, otpSize = 6, seconds = 15, }) {
     };
 }
 
+/**
+ * Backs a value that the consumer may or may not drive, so a control works in
+ * both modes without a copy of the state drifting away from the props.
+ *
+ * A control counts as controlled only when the consumer passes the value *and*
+ * an `onChange` to push it back. The value on its own has always meant "start
+ * here" in this library — `<DInputCheck type="radio" checked />` inside a radio
+ * group, for one — so treating it as controlled would silently freeze those
+ * controls, and React emits no warning to say why: the components always attach
+ * their own `onChange` handler.
+ *
+ * @param value the value coming from props, or `undefined` when not passed.
+ * @param isControlled whether the consumer can drive the value back.
+ * @param initialValue what to start from when no value is passed.
+ * @returns the value to render, and a setter to call on every user change.
+ */
+function useControlledState(value, isControlled, initialValue) {
+    const [internalValue, setInternalValue] = useState(value === undefined ? initialValue : value);
+    // The internal copy follows `value` in both modes.
+    //
+    // Uncontrolled, `value` without an `onChange` still means "start here", and a
+    // later flip of it from outside must still land — but between flips the
+    // control has to keep moving on its own, which is why this depends on `value`
+    // alone and not on `internalValue`.
+    //
+    // Controlled, the copy is not what gets rendered, but it is what the control
+    // falls back to if the consumer later stops passing a value — `value={locked
+    // ? undefined : x}`, say. Keeping it current means that hand-off carries on
+    // from where the control is instead of snapping back to the mount-time seed.
+    useEffect(() => {
+        if (value === undefined) {
+            return;
+        }
+        setInternalValue(value);
+    }, [value]);
+    const setValue = useCallback((next) => {
+        if (isControlled) {
+            return;
+        }
+        setInternalValue(next);
+    }, [isControlled]);
+    return [
+        isControlled && value !== undefined ? value : internalValue,
+        setValue,
+    ];
+}
+
 function DInputCounter(_a, ref) {
-    var { minValue, maxValue, value = minValue, invalid, iconStart: iconStartProp, iconEnd: iconEndProp, iconStartAriaLabel = 'decrease action', iconEndAriaLabel = 'increase action', style, onChange } = _a, props = __rest(_a, ["minValue", "maxValue", "value", "invalid", "iconStart", "iconEnd", "iconStartAriaLabel", "iconEndAriaLabel", "style", "onChange"]);
+    var { minValue, maxValue, value, defaultValue, invalid, iconStart: iconStartProp, iconEnd: iconEndProp, iconStartAriaLabel = 'decrease action', iconEndAriaLabel = 'increase action', style, onChange } = _a, props = __rest(_a, ["minValue", "maxValue", "value", "defaultValue", "invalid", "iconStart", "iconEnd", "iconStartAriaLabel", "iconEndAriaLabel", "style", "onChange"]);
     const { handleOnWheel, } = useDisableInputWheel(ref);
     const inputRef = useProvidedRefOrCreate(ref);
-    const [internalIsInvalid, setInternalIsInvalid] = useState(false);
-    const [internalValue, setInternalValue] = useState(value);
+    // See `useControlledState` for why `onChange` takes part in this decision.
+    const isControlled = value !== undefined && onChange !== undefined;
+    const [currentValue, setCurrentValue] = useControlledState(value, isControlled, defaultValue !== null && defaultValue !== void 0 ? defaultValue : minValue);
+    // The step handlers move *from* the current value rather than replacing it,
+    // so they need the latest one even when several clicks land in the same React
+    // batch and no render has happened in between — the functional update this
+    // replaced handled that on its own. Written on every render so it follows the
+    // props, and by `commitValue` so a second step in the same batch starts from
+    // where the first left off instead of collapsing into it.
+    const currentValueRef = useRef(currentValue);
+    currentValueRef.current = currentValue;
+    // `onChange` used to be called from an effect watching the internal value,
+    // which made controlling the counter impossible: a controlled counter never
+    // moves that value, so the effect never fired. Reporting from the handlers
+    // instead works in both modes.
+    const commitValue = useCallback((newValue) => {
+        // Clicking at a bound, or typing the value that is already there, is not a
+        // change. The effect this replaced watched the value itself and so stayed
+        // quiet too; without this a batch of clicks against `minValue` would report
+        // the same number once per click.
+        if (newValue === currentValueRef.current) {
+            return;
+        }
+        // Only the uncontrolled path moves the ref ahead of a render. There the
+        // component owns the value, so a second step in the same batch has to build
+        // on the first. Controlled, the prop is the truth and every step proposes
+        // from it: a parent that rejects without re-rendering — `onChange={() => {}}`,
+        // or a setter returning the previous state — never re-runs the assignment
+        // above, so a speculative ref would climb away from the value on screen and
+        // each further click would report a number further from it.
+        if (!isControlled) {
+            currentValueRef.current = newValue;
+        }
+        setCurrentValue(newValue);
+        onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
+    }, [isControlled, setCurrentValue, onChange]);
+    // Consumers have always been handed the starting value through `onChange` on
+    // mount, and some seed their state with it, so that one call stays. The ref
+    // keeps it to the first run: the old effect also re-fired on every render
+    // that passed a fresh inline `onChange`. Nothing is marked as reported until
+    // there is a handler to report to, so a counter mounted without `onChange`
+    // still hands over its starting value once one is attached.
+    const hasReportedInitialValue = useRef(false);
     useEffect(() => {
-        setInternalValue(value);
-    }, [value]);
+        if (hasReportedInitialValue.current || !onChange) {
+            return;
+        }
+        hasReportedInitialValue.current = true;
+        onChange(currentValue);
+    }, [onChange, currentValue]);
+    // `value` used to default to `minValue`, so a counter left to its own devices
+    // re-seeded — and reported — whenever `minValue` moved. Consumers use it as a
+    // live bound, so that stays; an explicit `value` or `defaultValue` opts out,
+    // exactly as passing `value` did before. The ref keeps this to real changes,
+    // so mounting still reports once and a click is never undone.
+    const hasExplicitStartingValue = value !== undefined || defaultValue !== undefined;
+    const previousMinValue = useRef(minValue);
     useEffect(() => {
-        onChange === null || onChange === void 0 ? void 0 : onChange(Number(internalValue));
-    }, [onChange, internalValue]);
+        if (previousMinValue.current === minValue) {
+            return;
+        }
+        previousMinValue.current = minValue;
+        if (hasExplicitStartingValue) {
+            return;
+        }
+        commitValue(minValue);
+    }, [hasExplicitStartingValue, minValue, commitValue]);
     const handleOnChange = useCallback((newValue) => {
-        setInternalValue(Number(newValue || '0'));
-    }, []);
+        commitValue(Number(newValue || '0'));
+    }, [commitValue]);
     const handleOnIconStartClick = useCallback(() => {
-        setInternalValue((prevInternalValue) => Math.max(prevInternalValue - 1, minValue));
-    }, [minValue]);
+        commitValue(Math.max(currentValueRef.current - 1, minValue));
+    }, [commitValue, minValue]);
     const handleOnIconEndClick = useCallback(() => {
-        setInternalValue((prevInternalValue) => Math.min(prevInternalValue + 1, maxValue));
-    }, [maxValue]);
+        commitValue(Math.min(currentValueRef.current + 1, maxValue));
+    }, [commitValue, maxValue]);
     const generateStyleVariables = useMemo(() => (Object.assign(Object.assign({}, style), { [`--${PREFIX_BS}form-control-component-text-align`]: 'center' })), [style]);
-    const valueString = useMemo(() => (internalValue.toString()), [internalValue]);
-    useEffect(() => {
-        setInternalIsInvalid(!(internalValue >= minValue && internalValue <= maxValue));
-    }, [internalValue, minValue, maxValue]);
+    const valueString = useMemo(() => (currentValue.toString()), [currentValue]);
+    const internalIsInvalid = useMemo(() => (!(currentValue >= minValue && currentValue <= maxValue)), [currentValue, minValue, maxValue]);
     const { iconMap: { input } } = useDContext();
     const iconEnd = useMemo(() => iconEndProp || input.increase, [iconEndProp, input.increase]);
     const iconStart = useMemo(() => iconStartProp || input.decrease, [iconStartProp, input.decrease]);
-    return (jsx(ForwardedDInput, Object.assign({ ref: inputRef, value: valueString, style: generateStyleVariables, iconStart: iconStart, iconEnd: iconEnd, invalid: internalIsInvalid || invalid, type: "number", onChange: handleOnChange, onWheel: handleOnWheel, onIconStartClick: handleOnIconStartClick, onIconEndClick: handleOnIconEndClick, iconStartAriaLabel: iconStartAriaLabel, iconEndAriaLabel: iconEndAriaLabel }, internalValue === minValue && {
+    return (jsx(ForwardedDInput, Object.assign({ ref: inputRef, value: valueString, style: generateStyleVariables, iconStart: iconStart, iconEnd: iconEnd, invalid: internalIsInvalid || invalid, type: "number", onChange: handleOnChange, onWheel: handleOnWheel, onIconStartClick: handleOnIconStartClick, onIconEndClick: handleOnIconEndClick, iconStartAriaLabel: iconStartAriaLabel, iconEndAriaLabel: iconEndAriaLabel }, currentValue === minValue && {
         iconStartDisabled: true,
-    }, internalValue === maxValue && {
+    }, currentValue === maxValue && {
         iconEndDisabled: true,
     }, props)));
 }
@@ -1970,11 +2727,16 @@ const ForwardedDInputCounter = forwardRef(DInputCounter);
 ForwardedDInputCounter.displayName = 'DInputCounter';
 
 function DInputCurrency(_a, ref) {
-    var { value, minValue, maxValue, currencyCode, onFocus, onBlur, onChange } = _a, props = __rest(_a, ["value", "minValue", "maxValue", "currencyCode", "onFocus", "onBlur", "onChange"]);
+    var { value, minValue, maxValue, clamp = true, currencyCode, onFocus, onBlur, onChange, invalid: invalidProp, valid: validProp } = _a, props = __rest(_a, ["value", "minValue", "maxValue", "clamp", "currencyCode", "onFocus", "onBlur", "onChange", "invalid", "valid"]);
     const { currency: currencyOptions } = useDContext();
     const { handleOnWheel, } = useDisableInputWheel(ref);
-    const { inputRef, innerValue, innerType, handleOnFocus, handleOnChange, handleOnBlur, } = useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref, minValue, maxValue);
-    return (jsx(ForwardedDInput, Object.assign({ ref: inputRef, value: innerValue, onChange: handleOnChange, inputMode: "decimal", type: innerType, onFocus: handleOnFocus, onBlur: handleOnBlur, onWheel: handleOnWheel, inputStart: (jsx("span", { slot: "input-start", className: "d-input-currency-symbol", children: currencyCode || currencyOptions.symbol })) }, props)));
+    const { inputRef, innerValue, innerType, isOverMax, isUnderMin, handleOnFocus, handleOnChange, handleOnBlur, } = useInputCurrency(currencyOptions, value, onFocus, onChange, onBlur, ref, minValue, maxValue, clamp);
+    const outOfRange = !clamp && (isOverMax || isUnderMin);
+    // One validation state: an explicit `invalid` wins; otherwise an
+    // out-of-range value is invalid and can't also be shown as valid.
+    const invalid = invalidProp !== null && invalidProp !== void 0 ? invalidProp : outOfRange;
+    const valid = invalid ? false : validProp;
+    return (jsx(ForwardedDInput, Object.assign({ ref: inputRef, value: innerValue, onChange: handleOnChange, inputMode: "decimal", type: innerType, onFocus: handleOnFocus, onBlur: handleOnBlur, onWheel: handleOnWheel, invalid: invalid, valid: valid, inputStart: (jsx("span", { slot: "input-start", className: "d-input-currency-symbol", children: currencyCode || currencyOptions.symbol })) }, props)));
 }
 const ForwardedDInputCurrency = forwardRef(DInputCurrency);
 ForwardedDInputCurrency.displayName = 'DInputCurrency';
@@ -2061,7 +2823,7 @@ const DEFAULT_VALIDATION_MESSAGES = {
     notMatch: 'The password confirmation and the new password do not match.',
 };
 const DEFAULT_ENABLED_CHECKS = ['uppercase', 'lowercase', 'number', 'specialChar'];
-function DPasswordStrengthMeter({ id, label = 'Password', placeholder, value = '', name, disabled = false, invalid = false, validationMessages = DEFAULT_VALIDATION_MESSAGES, enabledChecks = DEFAULT_ENABLED_CHECKS, className, style, dataAttributes, onChange, readonly = false, }) {
+function DPasswordStrengthMeter({ id, label = 'Password', 'aria-label': ariaLabel, placeholder, value = '', name, disabled = false, invalid = false, validationMessages = DEFAULT_VALIDATION_MESSAGES, enabledChecks = DEFAULT_ENABLED_CHECKS, className, style, dataAttributes, onChange, readonly = false, }) {
     const [password, setPassword] = useState(value);
     useEffect(() => {
         setPassword(value);
@@ -2070,17 +2832,31 @@ function DPasswordStrengthMeter({ id, label = 'Password', placeholder, value = '
         setPassword(newValue);
         onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
     };
-    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [jsx(ForwardedDInputPassword, { id: id, label: label, placeholder: placeholder, value: password, name: name, disabled: disabled, invalid: invalid, onChange: handleChange, readonly: readonly }), jsx(PasswordChecksList, { password: password, validationMessages: validationMessages, enabledChecks: enabledChecks })] })));
+    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [jsx(ForwardedDInputPassword, { id: id, label: label, "aria-label": ariaLabel, placeholder: placeholder, value: password, name: name, disabled: disabled, invalid: invalid, onChange: handleChange, readonly: readonly }), jsx(PasswordChecksList, { password: password, validationMessages: validationMessages, enabledChecks: enabledChecks })] })));
 }
 
 function DInputCheck(_a) {
-    var { id: idProp, type, name, label, ariaLabel, checked = false, disabled = false, invalid = false, valid = false, indeterminate, inputClassName, value, hint, onChange, className, style, dataAttributes } = _a, props = __rest(_a, ["id", "type", "name", "label", "ariaLabel", "checked", "disabled", "invalid", "valid", "indeterminate", "inputClassName", "value", "hint", "onChange", "className", "style", "dataAttributes"]);
+    var { id: idProp, type, name, label, ariaLabel, checked, defaultChecked, disabled = false, invalid = false, valid = false, indeterminate, inputClassName, value, hint, onChange, className, style, dataAttributes } = _a, props = __rest(_a, ["id", "type", "name", "label", "ariaLabel", "checked", "defaultChecked", "disabled", "invalid", "valid", "indeterminate", "inputClassName", "value", "hint", "onChange", "className", "style", "dataAttributes"]);
     const innerRef = useRef(null);
+    // See `useControlledState` for why `onChange` takes part in this decision.
+    const isControlled = checked !== undefined && onChange !== undefined;
     const innerId = useId();
     const id = useMemo(() => idProp || innerId, [idProp, innerId]);
     const handleChange = useCallback((event) => {
         onChange === null || onChange === void 0 ? void 0 : onChange(event);
-    }, [onChange]);
+        // Controlled only. Activating a checkbox clears the DOM `indeterminate`
+        // flag, and it has no HTML attribute for React to restore the way it
+        // restores `checked` when the parent rejects the change, so the mixed state
+        // would be gone after the first click — the effect below only re-runs when
+        // the prop moves. Uncontrolled keeps the browser's behaviour, where the
+        // click owns the state and `indeterminate` was only the starting look.
+        // Reapplied after `onChange` so a handler reading
+        // `event.target.indeterminate` still sees what the browser left, and a
+        // parent that does move the prop wins through that effect.
+        if (isControlled && innerRef.current) {
+            innerRef.current.indeterminate = type === 'checkbox' && Boolean(indeterminate);
+        }
+    }, [onChange, isControlled, indeterminate, type]);
     const ariaDescribedby = useMemo(() => ([
         !!hint && `${id}Hint`,
     ]
@@ -2094,15 +2870,24 @@ function DInputCheck(_a) {
             innerRef.current.indeterminate = type === 'checkbox' && Boolean(indeterminate);
         }
     }, [indeterminate, type]);
+    // Legacy path only: a `checked` with no `onChange` behind it still lands on
+    // the element, but through the DOM, so the input stays uncontrolled and both
+    // clicking it and the native radio-group behaviour keep working.
     useEffect(() => {
-        if (innerRef.current) {
-            innerRef.current.checked = checked;
+        if (isControlled || checked === undefined || !innerRef.current) {
+            return;
         }
-    }, [checked]);
-    const inputComponent = useMemo(() => (jsx("input", Object.assign({ ref: innerRef, onChange: handleChange, className: classNames('form-check-input', {
+        innerRef.current.checked = checked;
+    }, [isControlled, checked]);
+    const inputComponent = useMemo(() => (jsx("input", Object.assign({ ref: innerRef }, isControlled
+        ? { checked }
+        : defaultChecked !== undefined && { defaultChecked }, { onChange: handleChange, className: classNames('form-check-input', {
             'is-invalid': invalid,
             'is-valid': valid,
         }, inputClassName), style: style, id: id, disabled: disabled, type: type, name: name, value: value, "aria-label": ariaLabel }, ariaDescribedby && { 'aria-describedby': ariaDescribedby }, props))), [
+        isControlled,
+        checked,
+        defaultChecked,
         handleChange,
         invalid,
         valid,
@@ -2117,10 +2902,21 @@ function DInputCheck(_a) {
         ariaDescribedby,
         props,
     ]);
-    if (!label) {
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInputCheck',
+            label,
+            // `{...props}` is spread after `aria-label={ariaLabel}`, so a native
+            // `aria-label` wins — including when it is explicitly undefined.
+            hasAccessibleName: !!('aria-label' in props ? props['aria-label'] : ariaLabel)
+                || !!props['aria-labelledby'],
+            accessibleNameProp: 'ariaLabel',
+        });
+    }
+    if (!hasLabelContent(label)) {
         return inputComponent;
     }
-    return (jsxs("div", Object.assign({ className: classNames('form-check', className) }, dataAttributes, { children: [inputComponent, jsx("label", { className: "form-check-label", htmlFor: id, children: label }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
+    return (jsxs("div", Object.assign({ className: classNames('form-check', className) }, dataAttributes, { children: [inputComponent, jsx(DFormLabel, { className: "form-check-label", htmlFor: id, children: label }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
 }
 
 function DInputPin({ id: idProp, label = '', placeholder, type = 'text', disabled = false, loading = false, secret = false, characters = 4, innerInputMode = 'text', hint, invalid = false, valid = false, className, style, dataAttributes, onChange, 'aria-label': ariaLabel = 'Pin character number', }) {
@@ -2196,14 +2992,14 @@ function DInputPin({ id: idProp, label = '', placeholder, type = 'text', disable
     const wheelInput = useCallback((event) => {
         event.currentTarget.blur();
     }, []);
-    return (jsxs("div", Object.assign({ className: classNames('d-input-pin', className), style: style }, dataAttributes, { children: [label && (jsx("label", { htmlFor: "pinIndex0", children: label })), jsxs("div", { className: "d-input-pin-group", id: id, children: [Array.from({ length: characters }).map((_, index) => (jsx("input", Object.assign({ className: classNames({
+    return (jsxs("div", Object.assign({ className: classNames('d-input-pin', className), style: style }, dataAttributes, { children: [hasLabelContent(label) && (jsx(DFormLabel, { htmlFor: "pinIndex0", children: label })), jsxs("div", { className: "d-input-pin-group", id: id, children: [Array.from({ length: characters }).map((_, index) => (jsx("input", Object.assign({ className: classNames({
                             'form-control': true,
                             'is-invalid': invalid,
                             'is-valid': valid,
                         }), value: activeInput[index], type: secret ? 'password' : type, "aria-label": `${ariaLabel} ${index + 1} of ${characters}`, inputMode: innerInputMode, id: `pinIndex${index}`, name: `pin-${index}`, maxLength: 1, onInput: (event) => nextInput(event, index), onKeyDown: (event) => prevInput(event, index), onFocus: () => focusInput(index), onWheel: wheelInput, onClick: (event) => event.preventDefault(), onPaste: (event) => handlePaste(event), autoComplete: "off", placeholder: placeholder, disabled: disabled || loading, required: true }, type === 'number' && ({ min: 0, max: 9 })), index))), loading && (jsx("div", { className: "input-group-text", children: jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }) }))] }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
 }
 
-function DInputSelect({ id: idProp, name, label = '', className, style, options = [], disabled = false, loading = false, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartAriaLabel, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndAriaLabel, hint, value, size, floatingLabel = false, invalid = false, valid = false, dataAttributes, valueExtractor, labelExtractor, onChange, onBlur, onIconStartClick, onIconEndClick, }) {
+function DInputSelect({ id: idProp, name, label = '', ariaLabel, className, style, options = [], disabled = false, loading = false, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartAriaLabel, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndAriaLabel, hint, value, size, floatingLabel = false, invalid = false, valid = false, dataAttributes, valueExtractor, labelExtractor, onChange, onBlur, onIconStartClick, onIconEndClick, }) {
     const innerId = useId();
     const id = useMemo(() => idProp || innerId, [idProp, innerId]);
     const internalValueExtractor = useCallback((option) => {
@@ -2253,8 +3049,9 @@ function DInputSelect({ id: idProp, name, label = '', className, style, options
             'floating-label': floatingLabel,
             'is-invalid': invalid,
             'is-valid': valid,
-        }), "aria-label": label, disabled: disabled || loading, onChange: changeHandler, onBlur: blurHandler }, ariaDescribedby && { 'aria-describedby': ariaDescribedby }, value && { value }, { children: options.map((option) => (jsx("option", { value: internalValueExtractor(option), children: internalLabelExtractor(option) }, internalValueExtractor(option)))) }))), [
+        }), "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : (isTextLabel(label) ? String(label) : undefined), disabled: disabled || loading, onChange: changeHandler, onBlur: blurHandler }, ariaDescribedby && { 'aria-describedby': ariaDescribedby }, value && { value }, { children: options.map((option) => (jsx("option", { value: internalValueExtractor(option), children: internalLabelExtractor(option) }, internalValueExtractor(option)))) }))), [
         ariaDescribedby,
+        ariaLabel,
         blurHandler,
         changeHandler,
         disabled,
@@ -2271,7 +3068,7 @@ function DInputSelect({ id: idProp, name, label = '', className, style, options
         valid,
         size,
     ]);
-    const labelComponent = useMemo(() => (jsx("label", { htmlFor: id, children: label })), [
+    const labelComponent = useMemo(() => (jsx(DFormLabel, { htmlFor: id, children: label })), [
         id,
         label,
     ]);
@@ -2281,15 +3078,26 @@ function DInputSelect({ id: idProp, name, label = '', className, style, options
         }
         return selectComponent;
     }, [floatingLabel, labelComponent, selectComponent]);
-    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [label && !floatingLabel && (labelComponent), jsxs("div", { className: classNames({
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInputSelect',
+            label,
+            hasAccessibleName: !!ariaLabel,
+            accessibleNameProp: 'ariaLabel',
+            floatingLabel,
+        });
+    }
+    return (jsxs("div", Object.assign({ className: className, style: style }, dataAttributes, { children: [hasLabelContent(label) && !floatingLabel && (labelComponent), jsxs("div", { className: classNames({
                     'input-group': true,
                 }), children: [iconStart && (jsx("button", { type: "button", className: "input-group-text", id: `${id}Start`, onClick: iconStartClickHandler, disabled: disabled || loading, "aria-label": iconStartAriaLabel, children: iconStart && (jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass, familyPrefix: iconStartFamilyPrefix })) })), dynamicComponent, iconEnd && !loading && (jsx("button", { type: "button", className: "input-group-text", id: `${id}End`, onClick: iconEndClickHandler, disabled: disabled || loading, "aria-label": iconEndAriaLabel, children: iconEnd && (jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass, familyPrefix: iconEndFamilyPrefix })) })), loading && (jsx("div", { className: "input-group-text form-control-icon loading", children: jsx("span", { className: "spinner-border spinner-border-sm", role: "status", "aria-hidden": "true", children: jsx("span", { className: "visually-hidden", children: "Loading..." }) }) }))] }), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
 }
 
-function DInputSwitch({ id: idProp, label, ariaLabel, name, checked, disabled, invalid = false, valid = false, hint, readonly, className, style, dataAttributes, inputClassName, onChange, }) {
+function DInputSwitch({ id: idProp, label, ariaLabel, name, checked, defaultChecked = false, disabled, invalid = false, valid = false, hint, readonly, className, style, dataAttributes, inputClassName, onChange, }) {
     const innerId = useId();
     const id = useMemo(() => idProp || innerId, [idProp, innerId]);
-    const [internalIsChecked, setInternalIsChecked] = useState(checked);
+    // See `useControlledState` for why `onChange` takes part in this decision.
+    const isControlled = checked !== undefined && onChange !== undefined;
+    const [isChecked, setIsChecked] = useControlledState(checked, isControlled, defaultChecked);
     const ariaDescribedby = useMemo(() => ([
         !!hint && `${id}Hint`,
     ]
@@ -2298,18 +3106,23 @@ function DInputSwitch({ id: idProp, label, ariaLabel, name, checked, disabled, i
         id,
         hint,
     ]);
-    useEffect(() => {
-        setInternalIsChecked(checked);
-    }, [checked]);
     const changeHandler = useCallback((event) => {
         const value = event.currentTarget.checked;
-        setInternalIsChecked(value);
+        setIsChecked(value);
         onChange === null || onChange === void 0 ? void 0 : onChange(value);
-    }, [onChange]);
+    }, [setIsChecked, onChange]);
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInputSwitch',
+            label,
+            hasAccessibleName: !!ariaLabel,
+            accessibleNameProp: 'ariaLabel',
+        });
+    }
     return (jsxs("div", Object.assign({ className: classNames('form-check form-switch', className) }, dataAttributes, { children: [jsx("input", Object.assign({ id: id, name: name, onChange: readonly ? () => false : changeHandler, className: classNames('form-check-input', {
                     'is-invalid': invalid,
                     'is-valid': valid,
-                }, inputClassName), style: style, type: "checkbox", role: "switch", checked: internalIsChecked, disabled: disabled, "aria-label": ariaLabel }, ariaDescribedby && { 'aria-describedby': ariaDescribedby })), label && (jsx("label", { className: "form-check-label", htmlFor: id, children: label })), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
+                }, inputClassName), style: style, type: "checkbox", role: "switch", checked: isChecked, disabled: disabled, "aria-label": ariaLabel }, ariaDescribedby && { 'aria-describedby': ariaDescribedby })), hasLabelContent(label) && (jsx(DFormLabel, { className: "form-check-label", htmlFor: id, children: label })), hint && (jsx("div", { className: "form-text", id: `${id}Hint`, children: hint }))] })));
 }
 
 function DInputRange(_a, ref) {
@@ -2341,15 +3154,61 @@ function DInputRange(_a, ref) {
         props,
         value,
     ]);
-    if (!label) {
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInputRange',
+            label,
+            // `{...props}` is spread after `aria-label={ariaLabel}`, so a native
+            // `aria-label` wins — including when it is explicitly undefined.
+            hasAccessibleName: !!('aria-label' in props ? props['aria-label'] : ariaLabel)
+                || !!props['aria-labelledby'],
+            accessibleNameProp: 'ariaLabel',
+        });
+    }
+    if (!hasLabelContent(label)) {
         return inputComponent;
     }
-    return (jsxs(Fragment, { children: [jsx("label", { className: "form-label", htmlFor: id, children: label }), inputComponent] }));
+    return (jsxs(Fragment, { children: [jsx(DFormLabel, { className: "form-label", htmlFor: id, children: label }), inputComponent] }));
 }
 const ForwardedDInputRange = forwardRef(DInputRange);
 ForwardedDInputRange.displayName = 'DInputRange';
 
-function DListGroupItem({ as = 'li', action: actionProp, active, disabled, href, onClick, color, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartMaterialStyle, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndMaterialStyle, children, className, style, dataAttributes, }) {
+/**
+ * Element the enclosing `DListGroup` renders, so each `DListGroupItem` can
+ * check that its own element is valid content for it. `undefined` outside a
+ * `DListGroup`.
+ */
+const ListGroupContext = createContext(undefined);
+
+/**
+ * Combinations already reported, keyed by container and item element, so the
+ * same mismatch only warns once per page load however many items share it.
+ */
+const warnedCombinations = new Set();
+/**
+ * Warns, once per combination and only outside production builds, that a
+ * `DListGroupItem` renders an element its `DListGroup` container can't hold.
+ *
+ * Links and buttons inside a <ul>/<ol> are wrapped in an <li>, so the only
+ * invalid pair left is a plain item (an <li>) inside `as="div"`: an <li>
+ * outside of any list. It doesn't fail visibly, which is why it's reported.
+ *
+ * The `process.env.NODE_ENV` guard at the call site is what bundlers
+ * constant-fold, so the whole call — and this module — drops out of a
+ * consumer's production bundle.
+ */
+function warnInvalidListMarkup(container, item) {
+    const key = `${container}>${item}`;
+    if (warnedCombinations.has(key))
+        return;
+    warnedCombinations.add(key);
+    // eslint-disable-next-line no-console
+    console.warn(`[Dynamic UI] DListGroupItem: a <${item}> inside a <${container}> is invalid markup. `
+        + 'Keep the container as a list (the default `as="ul"`, or `numbered`), or render the item '
+        + 'as a link or button. It never appears in production builds.');
+}
+
+function DListGroupItem({ as = 'li', action: actionProp, active, ariaCurrent = 'true', disabled, href, onClick, color, iconStart, iconStartFamilyClass, iconStartFamilyPrefix, iconStartMaterialStyle, iconEnd, iconEndFamilyClass, iconEndFamilyPrefix, iconEndMaterialStyle, children, className, style, dataAttributes, }) {
     const { icon: { familyClass, familyPrefix, materialStyle, }, } = useDContext();
     const Tag = useMemo(() => {
         if (href) {
@@ -2360,29 +3219,45 @@ function DListGroupItem({ as = 'li', action: actionProp, active, disabled, href,
         }
         return as;
     }, [href, as, actionProp]);
-    const action = useMemo(() => {
-        if (Tag === 'a' || Tag === 'button') {
-            return true;
-        }
-        return actionProp;
-    }, [Tag, actionProp]);
+    const container = useContext(ListGroupContext);
+    const isInteractive = Tag === 'a' || Tag === 'button';
+    // Inside a <ul>/<ol>, a link or button is wrapped in the <li> that carries
+    // the item styles, so the group keeps list semantics (`list > listitem >
+    // link|button`) without breaking Bootstrap's sibling selectors.
+    const isWrapped = isInteractive && (container === 'ul' || container === 'ol');
+    if (process.env.NODE_ENV !== 'production' && container === 'div' && Tag === 'li') {
+        warnInvalidListMarkup(container, Tag);
+    }
     const generateClasses = useMemo(() => ({
         'list-group-item': true,
-        'list-group-item-action': action,
+        'list-group-item-action': isInteractive || actionProp,
+        'd-list-group-item-interactive': isWrapped,
         [`list-group-item-${color}`]: !!color,
         active,
         disabled,
-    }), [action, active, disabled, color]);
-    const ariaAttributes = useMemo(() => {
+    }), [isInteractive, actionProp, isWrapped, active, disabled, color]);
+    // A disabled link leaves the tab order and can't be activated: without
+    // `href` and `onClick`, Enter does nothing. Dropping `href` also drops the
+    // implicit link role, so it is set back explicitly. A button uses
+    // `disabled`.
+    const interactiveProps = useMemo(() => {
         if (Tag === 'button') {
-            return Object.assign(Object.assign({}, active && { 'aria-current': true }), disabled && { disabled: true });
+            return Object.assign(Object.assign(Object.assign({ type: 'button' }, onClick && { onClick }), active && { 'aria-current': ariaCurrent }), disabled && { disabled: true });
+        }
+        if (Tag === 'a') {
+            return disabled
+                ? Object.assign({ role: 'link', 'aria-disabled': true, tabIndex: -1 }, active && { 'aria-current': ariaCurrent }) : Object.assign(Object.assign(Object.assign({}, href && { href }), onClick && { onClick }), active && { 'aria-current': ariaCurrent });
         }
-        return Object.assign(Object.assign({}, active && { 'aria-current': true }), disabled && { 'aria-disabled': true });
-    }, [Tag, active, disabled]);
-    return (jsxs(Tag, Object.assign({ className: classNames(generateClasses, className), style: style }, Tag === 'a' && href && { href }, onClick && { onClick }, ariaAttributes, dataAttributes, Tag === 'button' && { type: 'button' }, { children: [iconStart && (jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle })), children, iconEnd && (jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle, className: "ms-auto" }))] })));
+        return Object.assign(Object.assign(Object.assign({}, onClick && { onClick }), active && { 'aria-current': ariaCurrent }), disabled && { 'aria-disabled': true });
+    }, [Tag, href, onClick, active, ariaCurrent, disabled]);
+    const content = (jsxs(Fragment, { children: [iconStart && (jsx(DIcon, { icon: iconStart, familyClass: iconStartFamilyClass !== null && iconStartFamilyClass !== void 0 ? iconStartFamilyClass : familyClass, familyPrefix: iconStartFamilyPrefix !== null && iconStartFamilyPrefix !== void 0 ? iconStartFamilyPrefix : familyPrefix, materialStyle: iconStartMaterialStyle !== null && iconStartMaterialStyle !== void 0 ? iconStartMaterialStyle : materialStyle })), children, iconEnd && (jsx(DIcon, { icon: iconEnd, familyClass: iconEndFamilyClass !== null && iconEndFamilyClass !== void 0 ? iconEndFamilyClass : familyClass, familyPrefix: iconEndFamilyPrefix !== null && iconEndFamilyPrefix !== void 0 ? iconEndFamilyPrefix : familyPrefix, materialStyle: iconEndMaterialStyle !== null && iconEndMaterialStyle !== void 0 ? iconEndMaterialStyle : materialStyle, className: "ms-auto" }))] }));
+    if (isWrapped) {
+        return (jsx("li", { className: classNames(generateClasses, className), style: style, children: jsx(Tag, Object.assign({ className: "d-list-group-item-link" }, interactiveProps, dataAttributes, { children: content })) }));
+    }
+    return (jsx(Tag, Object.assign({ className: classNames(generateClasses, className), style: style }, interactiveProps, dataAttributes, { children: content })));
 }
 
-function DListGroup({ as = 'ul', numbered, flush, horizontal, children, className, style, dataAttributes, }) {
+function DListGroup({ as = 'ul', numbered, flush, horizontal, ariaLabel, ariaLabelledBy, children, className, style, dataAttributes, }) {
     const Tag = useMemo(() => {
         if (numbered) {
             return 'ol';
@@ -2400,7 +3275,14 @@ function DListGroup({ as = 'ul', numbered, flush, horizontal, children, classNam
             [listGroupHorizontalClass]: !!horizontal,
         };
     }, [flush, horizontal, numbered]);
-    return (jsx(Tag, Object.assign({ className: classNames(generateClasses, className), style: style }, dataAttributes, { children: children })));
+    const labelProps = useMemo(() => {
+        if (!ariaLabelledBy && !ariaLabel)
+            return {};
+        return Object.assign(Object.assign({}, ariaLabelledBy
+            ? { 'aria-labelledby': ariaLabelledBy }
+            : { 'aria-label': ariaLabel }), Tag === 'div' && { role: 'group' });
+    }, [ariaLabel, ariaLabelledBy, Tag]);
+    return (jsx(ListGroupContext.Provider, { value: Tag, children: jsx(Tag, Object.assign({ className: classNames(generateClasses, className), style: style }, labelProps, dataAttributes, { children: children })) }));
 }
 var DListGroup$1 = Object.assign(DListGroup, {
     Item: DListGroupItem,
@@ -2586,14 +3468,20 @@ function DPopover({ children, renderComponent, open, setOpen, adjustContentToRen
                     }), ref: refs.setFloating, style: floatingStyles, "aria-labelledby": headingId }, getFloatingProps(), { children: children })) }))] })));
 }
 
-function DProgress({ className, style, currentValue, minValue = 0, maxValue = 100, hideCurrentValue = false, enableStripedAnimation = false, height, dataAttributes, }) {
-    const percentage = useMemo(() => (Math.round((currentValue * 100) / maxValue)), [currentValue, maxValue]);
+function DProgress({ className, style, currentValue, minValue = 0, maxValue = 100, hideCurrentValue = false, enableStripedAnimation = false, height, ariaLabel, ariaLabelledBy, dataAttributes, }) {
+    const percentage = useMemo(() => {
+        const range = maxValue - minValue;
+        if (range <= 0) {
+            return 0;
+        }
+        return Math.round(((currentValue - minValue) * 100) / range);
+    }, [currentValue, minValue, maxValue]);
     const formatProgress = useMemo(() => `${percentage}%`, [percentage]);
     const generateClasses = useMemo(() => ({
         'progress-bar': true,
         'progress-bar-striped progress-bar-animated': enableStripedAnimation,
     }), [enableStripedAnimation]);
-    return (jsx("div", Object.assign({ className: classNames('progress', className), style: Object.assign({ height }, style) }, dataAttributes, { children: jsx("div", { className: classNames(generateClasses), role: "progressbar", "aria-label": "Progress bar", style: { width: formatProgress }, "aria-valuenow": currentValue, "aria-valuemin": minValue, "aria-valuemax": maxValue, children: !hideCurrentValue && formatProgress }) })));
+    return (jsx("div", Object.assign({ className: classNames('progress', className), style: Object.assign({ height }, style) }, dataAttributes, { children: jsx("div", { className: classNames(generateClasses), role: "progressbar", "aria-label": ariaLabelledBy ? undefined : (ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : 'Progress bar'), "aria-labelledby": ariaLabelledBy, style: { width: formatProgress }, "aria-valuenow": currentValue, "aria-valuemin": minValue, "aria-valuemax": maxValue, children: !hideCurrentValue && formatProgress }) })));
 }
 
 function DStepper$2({ options, currentStep, iconSuccess: iconSuccessProp, iconSuccessFamilyClass, iconSuccessFamilyPrefix, iconSuccessMaterialStyle, vertical = false, completed, alignStart = false, className, style, }) {
@@ -2697,14 +3585,15 @@ function DTooltip({ className, childrenClassName, style, offSet = ARROW_HEIGHT +
 function DTimeline({ className, style, dataAttributes, items, }) {
     return (jsx("div", Object.assign({ style: style, className: classNames('d-timeline', className) }, dataAttributes, { children: items.map((item, index) => (jsxs("div", { className: classNames('d-timeline-item', {
                 [`d-timeline-item-${item.status}`]: item.status,
-            }), children: [jsx("div", { className: "d-timeline-item-connector" }), jsx("div", { className: "d-timeline-item-icon", children: jsx(DIcon, { icon: item.icon || 'check', size: "1rem" }) }), jsxs("div", { className: "d-timeline-item-content", children: [jsx("div", { className: "d-timeline-item-title", children: item.title }), item.description && jsx("div", { className: "d-timeline-item-description", children: item.description }), item.time && jsx("div", { className: "d-timeline-item-time", children: item.time }), item.children] })] }, index))) })));
+            }), children: [jsx("div", { className: "d-timeline-item-connector" }), jsx("div", { className: "d-timeline-item-icon", children: jsx(DIcon, { icon: item.icon || 'Check', size: "1rem" }) }), jsxs("div", { className: "d-timeline-item-content", children: [jsx("div", { className: "d-timeline-item-title", children: item.title }), item.description && jsx("div", { className: "d-timeline-item-description", children: item.description }), item.time && jsx("div", { className: "d-timeline-item-time", children: item.time }), item.children] })] }, index))) })));
 }
 
 const TabContext = createContext(undefined);
+const TabsStateContext = createContext(undefined);
 function useTabContext() {
     const context = useContext(TabContext);
     if (context === undefined) {
-        throw new Error('useTabContext was used outside of MTab');
+        throw new Error('useTabContext was used outside of DTabs');
     }
     return context;
 }
@@ -2714,33 +3603,44 @@ function DTabContent({ tab, children, className, style, }) {
     if (!isSelected(tab)) {
         return null;
     }
-    return (jsx("div", { className: classNames('tab-pane fade show active', className), id: `${tab}Pane`, role: "tabpanel", tabIndex: 0, "aria-labelledby": `${tab}Tab`, style: style, children: children }));
+    return (jsx("div", { className: classNames('tab-pane fade show active', className), id: `${tab}Pane`, role: "tabpanel", tabIndex: 0, "aria-labelledby": `${tab}Tab`, style: style, children: jsx(TabsStateContext.Provider, { value: undefined, children: children }) }));
 }
 
-function DTabs({ children, defaultSelected, onChange, options, className, classNameTab, style, vertical, variant = 'underline', dataAttributes, ariaLabel, ariaLabelledBy, }) {
+/**
+ * Owns the selected tab so the tab bar (`DTabs`) and its panels (`DTabs.Tab`)
+ * can live anywhere inside it, e.g. the bar in a header and the panels in
+ * another column.
+ */
+function DTabsProvider({ defaultSelected, children, }) {
     const [selected, setSelected] = useState(defaultSelected);
+    useEffect(() => {
+        setSelected(defaultSelected);
+    }, [defaultSelected]);
+    const isSelected = useCallback((tab) => (selected === tab), [selected]);
+    const state = useMemo(() => ({ selected, setSelected }), [selected]);
+    const value = useMemo(() => ({ isSelected }), [isSelected]);
+    return (jsx(TabsStateContext.Provider, { value: state, children: jsx(TabContext.Provider, { value: value, children: children }) }));
+}
+
+function DTabs({ children, defaultSelected, onChange, options, className, classNameTab, classNameContent, style, vertical, variant = 'underline', dataAttributes, ariaLabel, ariaLabelledBy, }) {
+    var _a;
+    const shared = useContext(TabsStateContext);
+    const [ownSelected, setOwnSelected] = useState(defaultSelected);
+    const selected = shared
+        ? shared.selected
+        : ownSelected !== null && ownSelected !== void 0 ? ownSelected : (_a = options.find((opt) => !opt.disabled)) === null || _a === void 0 ? void 0 : _a.tab;
+    const setSelected = shared ? shared.setSelected : setOwnSelected;
     const onSelect = useCallback((option) => {
         if (option.tab) {
             setSelected(option.tab);
         }
         onChange === null || onChange === void 0 ? void 0 : onChange(option);
-    }, [onChange]);
+    }, [onChange, setSelected]);
     useEffect(() => {
-        setSelected(defaultSelected);
+        setOwnSelected(defaultSelected);
     }, [defaultSelected]);
     const generateClasses = useMemo(() => (Object.assign({ nav: true, 'd-tabs-nav-vertical': vertical && variant !== 'tabs', [`nav-${variant}`]: true }, className && { [className]: true })), [vertical, variant, className]);
     const tabRefs = useRef([]);
-    // Always holds the latest `options` without needing to be a dependency:
-    // `options` is commonly passed as an inline array literal (e.g.
-    // `options={[{ label: 'SMS', tab: 'sms' }, ...]}`), so it's a new array
-    // reference on every parent render even when its content hasn't changed.
-    // Reading it from this ref (updated synchronously on every render) lets
-    // the focus effect below react only to `selected` changing.
-    const optionsRef = useRef(options);
-    optionsRef.current = options;
-    useEffect(() => {
-        tabRefs.current = options.map((_, i) => tabRefs.current[i] || createRef());
-    }, [options]);
     // Ensure selected is never disabled
     useEffect(() => {
         if (options.length === 0)
@@ -2751,29 +3651,16 @@ function DTabs({ children, defaultSelected, onChange, options, className, classN
             if (firstEnabled)
                 setSelected(firstEnabled.tab);
         }
-    }, [options, selected]);
-    // Declarative focus management. Wrapped in `useCallback` with an empty
-    // dependency array since it only reads from the `tabRefs` ref, so its
-    // identity stays stable across renders and it can safely be used as an
-    // effect dependency below.
+    }, [options, selected, setSelected]);
+    // Focus only moves in response to the user: arrow keys and clicks call
+    // this directly. Changes to `selected` that don't come from an interaction
+    // (mount, a new `defaultSelected`, the disabled-tab fallback above) leave
+    // focus where it is, so the page doesn't scroll to the tablist and no other
+    // element (a search field, an OTP input) loses focus.
     const focusTab = useCallback((idx) => {
         var _a;
-        if ((_a = tabRefs.current[idx]) === null || _a === void 0 ? void 0 : _a.current) {
-            tabRefs.current[idx].current.focus();
-        }
+        (_a = tabRefs.current[idx]) === null || _a === void 0 ? void 0 : _a.focus();
     }, []);
-    // Focus selected tab when selected changes.
-    // Reads `options` from `optionsRef` (see comment above) instead of
-    // depending on `options` directly, so a parent re-render that merely
-    // creates a new `options` reference with identical content doesn't call
-    // `focusTab` again and steal focus away from unrelated elements on the
-    // page (e.g. an OTP input).
-    useEffect(() => {
-        const idx = optionsRef.current.findIndex((opt) => opt.tab === selected && !opt.disabled);
-        if (idx !== -1) {
-            focusTab(idx);
-        }
-    }, [selected, focusTab]);
     const handleKeyDown = useCallback((idx, e) => {
         const count = options.length;
         if (count === 0)
@@ -2802,7 +3689,7 @@ function DTabs({ children, defaultSelected, onChange, options, className, classN
                 }
             }
         }
-    }, [options, vertical, focusTab]);
+    }, [options, vertical, focusTab, setSelected]);
     let tablistProps = {};
     if (ariaLabelledBy) {
         tablistProps = { 'aria-labelledby': ariaLabelledBy };
@@ -2819,11 +3706,17 @@ function DTabs({ children, defaultSelected, onChange, options, className, classN
                 'd-tabs-column': !vertical || variant === 'tabs',
             }), style: style }, dataAttributes, { children: [jsx("ul", Object.assign({ className: classNames(generateClasses), role: "tablist", "aria-orientation": vertical ? 'vertical' : undefined }, tablistProps, { children: options.map((option, idx) => {
                         const isTabSelected = !!option.tab && option.tab === selected;
-                        return (jsx("li", { role: "presentation", className: "nav-item", children: jsx("button", { ref: tabRefs.current[idx], id: `${option.tab}Tab`, className: classNames('nav-link', { active: isTabSelected }, classNameTab), type: "button", role: "tab", "aria-controls": `${option.tab}Pane`, "aria-selected": isTabSelected, tabIndex: isTabSelected ? 0 : -1, disabled: option.disabled, onClick: () => onSelect(option), onKeyDown: (e) => handleKeyDown(idx, e), children: option.label }) }, option.tab));
-                    }) })), jsx("div", { className: "d-tabs-content tab-content", children: children })] })) }));
+                        return (jsx("li", { role: "presentation", className: "nav-item", children: jsx("button", { ref: (element) => {
+                                    tabRefs.current[idx] = element;
+                                }, id: `${option.tab}Tab`, className: classNames('nav-link', { active: isTabSelected }, classNameTab), type: "button", role: "tab", "aria-controls": `${option.tab}Pane`, "aria-selected": isTabSelected, tabIndex: isTabSelected ? 0 : -1, disabled: option.disabled, onClick: () => {
+                                    focusTab(idx);
+                                    onSelect(option);
+                                }, onKeyDown: (e) => handleKeyDown(idx, e), children: option.label }) }, option.tab));
+                    }) })), Children.toArray(children).length > 0 && (jsx("div", { className: classNames('d-tabs-content tab-content', classNameContent), children: children }))] })) }));
 }
 var DTabs$1 = Object.assign(DTabs, {
     Tab: DTabContent,
+    Provider: DTabsProvider,
 });
 
 function DToastHeader({ children, className, style }) {
@@ -2834,8 +3727,13 @@ function DToastBody({ children, className, style }) {
     return (jsx("div", { className: classNames('toast-body', className), style: style, children: children }));
 }
 
-function DToast({ children, className, style, dataAttributes, }) {
-    return (jsx("div", Object.assign({ className: classNames('toast', className), role: "alert", "aria-live": "assertive", "aria-atomic": "true", style: style }, dataAttributes, { children: children })));
+const LIVE_REGION_ATTRIBUTES = {
+    alert: { role: 'alert', 'aria-live': 'assertive', 'aria-atomic': 'true' },
+    status: { role: 'status', 'aria-live': 'polite', 'aria-atomic': 'true' },
+    none: {},
+};
+function DToast({ children, role = 'alert', className, style, dataAttributes, }) {
+    return (jsx("div", Object.assign({ className: classNames('toast', className) }, LIVE_REGION_ATTRIBUTES[role], { style: style }, dataAttributes, { children: children })));
 }
 var DToast$1 = Object.assign(DToast, {
     Header: DToastHeader,
@@ -2874,19 +3772,19 @@ function useDToast() {
         if (typeof data === 'function') {
             return toast.custom(data, toastProps);
         }
-        const { title, description, icon, closeIcon, timestamp, color, } = data;
+        const { title, description, icon, closeIcon, timestamp, color, role, closeAriaLabel = 'Close', } = data;
         return toast.custom(({ id, visible }) => {
             if (!visible) {
                 return null;
             }
             if (!description) {
-                return (jsx(DToast$1, { className: classNames({
+                return (jsx(DToast$1, { role: role, className: classNames({
                         [`toast-${color}`]: !!color,
-                    }, 'show'), children: jsxs(DToast$1.Body, { children: [icon && (jsx(DIcon, { className: "toast-icon", icon: icon })), jsx("p", { className: "toast-title", children: title }), jsx("button", { type: "button", className: "d-close", "aria-label": "Close", onClick: () => toast.dismiss(id), children: jsx(DIcon, { icon: closeIcon || xLg }) })] }) }));
+                    }, 'show'), children: jsxs(DToast$1.Body, { children: [icon && (jsx(DIcon, { className: "toast-icon", icon: icon })), jsx("p", { className: "toast-title", children: title }), jsx("button", { type: "button", className: "d-close", "aria-label": closeAriaLabel, onClick: () => toast.dismiss(id), children: jsx(DIcon, { icon: closeIcon || xLg }) })] }) }));
             }
-            return (jsxs(DToast$1, { className: classNames({
+            return (jsxs(DToast$1, { role: role, className: classNames({
                     [`toast-${color}`]: !!color,
-                }, 'show'), children: [jsxs(DToast$1.Header, { children: [icon && (jsx(DIcon, { className: "toast-icon", icon: icon })), jsx("p", { className: "toast-title", children: title }), timestamp && (jsx("small", { className: "toast-timestamp", children: timestamp })), jsx("button", { type: "button", className: "d-close", "aria-label": "Close", onClick: () => toast.dismiss(id), children: jsx(DIcon, { icon: closeIcon || xLg }) })] }), jsx(DToast$1.Body, { children: jsx("span", { children: description }) })] }));
+                }, 'show'), children: [jsxs(DToast$1.Header, { children: [icon && (jsx(DIcon, { className: "toast-icon", icon: icon })), jsx("p", { className: "toast-title", children: title }), timestamp && (jsx("small", { className: "toast-timestamp", children: timestamp })), jsx("button", { type: "button", className: "d-close", "aria-label": closeAriaLabel, onClick: () => toast.dismiss(id), children: jsx(DIcon, { icon: closeIcon || xLg }) })] }), jsx(DToast$1.Body, { children: jsx("span", { children: description }) })] }));
         }, toastProps);
     }, [xLg]);
     return {
@@ -3122,7 +4020,7 @@ function DInputPhone(_a, ref) {
         placeholder,
         valid,
     ]);
-    const labelComponent = useMemo(() => (jsx("label", { htmlFor: id, children: label })), [
+    const labelComponent = useMemo(() => (jsx(DFormLabel, { htmlFor: id, children: label })), [
         id,
         label,
     ]);
@@ -3136,7 +4034,16 @@ function DInputPhone(_a, ref) {
         inputComponent,
         labelComponent,
     ]);
-    return (jsxs("div", Object.assign({ className: classNames('d-input-phone', className), style: style }, dataAttributes, { children: [label && !floatingLabel && labelComponent, jsxs("div", { className: classNames({
+    if (process.env.NODE_ENV !== 'production') {
+        warnLabelUsage({
+            component: 'DInputPhone',
+            label,
+            hasAccessibleName: !!inputProps['aria-label'] || !!inputProps['aria-labelledby'],
+            accessibleNameProp: 'aria-label',
+            floatingLabel,
+        });
+    }
+    return (jsxs("div", Object.assign({ className: classNames('d-input-phone', className), style: style }, dataAttributes, { children: [hasLabelContent(label) && !floatingLabel && labelComponent, jsxs("div", { className: classNames({
                     [`input-group-${size}`]: !!size,
                     'input-group': true,
                     'has-validation': invalid || valid,
@@ -3603,11 +4510,11 @@ function DOtp({ className, action, isLoading, otpSize = 6, texts = TEXT_PROPS, s
                                 }, loading: isLoading || isSubmitting }), jsx("p", { className: "d-otp-contact", children: texts.contact })] })] })] }));
 }
 
-function DefaultErrorBoundary({ resetErrorBoundary }) {
-    return (jsx(DAlert, { color: "danger", showClose: false, children: jsxs("div", { className: "d-error-boundary-content", children: [jsx("span", { children: "An unexpected error occurred." }), jsx(DButton, { color: "secondary", variant: "outline", size: "sm", onClick: resetErrorBoundary, children: "Retry" })] }) }));
+function DefaultErrorBoundary({ resetErrorBoundary, message = 'An unexpected error occurred.', retryMessage = 'Retry', }) {
+    return (jsx(DAlert, { color: "danger", showClose: false, children: jsxs("div", { className: "d-error-boundary-content", children: [jsx("span", { children: message }), jsx(DButton, { color: "secondary", variant: "outline", size: "sm", onClick: resetErrorBoundary, children: retryMessage })] }) }));
 }
 
-function DErrorBoundary({ name, fallback, resetKeys, onReset, onError, children, }) {
+function DErrorBoundary({ name, fallback, resetKeys, onReset, onError, messages, children, }) {
     const handleError = useCallback((error, info) => {
         // eslint-disable-next-line no-console
         console.error(`[DErrorBoundary${name ? `:${name}` : ''}]`, getErrorMessage(error), info);
@@ -3616,8 +4523,8 @@ function DErrorBoundary({ name, fallback, resetKeys, onReset, onError, children,
     const FallbackRender = useCallback((props) => {
         if (fallback)
             return fallback(props);
-        return (jsx(DefaultErrorBoundary, { resetErrorBoundary: props.resetErrorBoundary }));
-    }, [fallback]);
+        return (jsx(DefaultErrorBoundary, { resetErrorBoundary: props.resetErrorBoundary, message: messages === null || messages === void 0 ? void 0 : messages.error, retryMessage: messages === null || messages === void 0 ? void 0 : messages.retry }));
+    }, [fallback, messages]);
     return (jsx(ErrorBoundary, { resetKeys: resetKeys, onReset: onReset, onError: handleError, fallbackRender: FallbackRender, children: children }));
 }
 
@@ -3638,6 +4545,11 @@ function render(renderable) {
         return null;
     return typeof renderable === 'function' ? renderable() : renderable;
 }
+function isEmpty(data) {
+    if (Array.isArray(data))
+        return data.length === 0;
+    return data === null || data === undefined;
+}
 function DDataStateWrapper({ isLoading, isError, data, onRetry, messages, renderLoading, renderEmpty, renderError, children, }) {
     // 1. Loading
     if (isLoading) {
@@ -3651,13 +4563,15 @@ function DDataStateWrapper({ isLoading, isError, data, onRetry, messages, render
             return render(renderError);
         return (jsx(ErrorState, { onRetry: onRetry, message: messages === null || messages === void 0 ? void 0 : messages.error, retryMessage: messages === null || messages === void 0 ? void 0 : messages.retry }));
     }
-    // 3. Empty
-    if (!(data === null || data === void 0 ? void 0 : data.length)) {
+    // 3. Empty: no items for a collection, null/undefined for a single resource
+    if (isEmpty(data)) {
         if (renderEmpty)
             return render(renderEmpty);
         return (jsx(EmptyState, { message: messages === null || messages === void 0 ? void 0 : messages.empty }));
     }
-    // 4. Success
+    // 4. Success: the render prop gets the same shape it was given
+    // Both overloads pair `data` with its own `children` signature, so the
+    // value is handed back exactly as it was received.
     return jsx(Fragment, { children: children(data) });
 }
 
@@ -3742,5 +4656,58 @@ function DConfirmModalContainer({ nodeId }) {
     return createPortal(jsx(AnimatePresence, { children: entries.map((entry) => (jsxs(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: { delay: 0.3 } }, transition: { duration: 0.15, ease: 'linear' }, children: [jsx("div", { className: "backdrop backdrop-confirm-modal", onClick: entry.onCloseAction, role: "presentation" }), jsx(DConfirmModalUI, { entry: entry })] }, entry.id))) }), portalNode);
 }
 
-export { DAlert, DAvatar, DBadge, DBox, DBoxFile, DButton, DButtonIcon, DCard$1 as DCard, DCardBody, DCardFooter, DCardHeader, DCarousel$1 as DCarousel, DCarouselSlide, DChip, DCollapse, DConfirmModalContainer, DContext, DContextProvider, DCreditCard, DCurrencyText, DDataStateWrapper, DDatePicker, DDropdown, DErrorBoundary, DIcon, DIconBase, ForwardedDInput as DInput, DInputCheck, ForwardedDInputCounter as DInputCounter, ForwardedDInputCurrency as DInputCurrency, ForwardedDInputMask as DInputMask, ForwardedDInputPassword as DInputPassword, ForwardedDInputPhone as DInputPhone, DInputPin, ForwardedDInputRange as DInputRange, ForwardedDInputSearch as DInputSearch, DInputSelect, DInputSwitch, DLayout$1 as DLayout, DLayoutPane, DListGroup$1 as DListGroup, DListGroupItem, DModal$1 as DModal, DModalBody, DModalFooter, DModalHeader, DOffcanvas$1 as DOffcanvas, DOffcanvasBody, DOffcanvasFooter, DOffcanvasHeader, DOtp, DPaginator, DPasswordStrengthMeter, DPopover, DProgress, DSelect$1 as DSelect, DStepper, DStepper$2 as DStepperDesktop, DStepper$1 as DStepperMobile, DTabContent, DTabs$1 as DTabs, DTimeline, DToast$1 as DToast, DToastContainer, DTooltip, DVoucher, EmptyState, ErrorState, LoadingState, buildUrl, changeQueryString, checkMediaQuery, configureI8n as configureI18n, formatCurrency, getCssVariable, getQueryString, sanitizeHref, subscribeToMediaQuery, useConfirmModal, useCountdown, useDContext, useDPortalContext, useDToast, useDisableBodyScrollEffect, useDisableInputWheel, useFormatCurrency, useInputCurrency, useItemSelection, useMediaBreakpointUpLg, useMediaBreakpointUpMd, useMediaBreakpointUpSm, useMediaBreakpointUpXl, useMediaBreakpointUpXs, useMediaBreakpointUpXxl, useMediaQuery, useOtp, useProvidedRefOrCreate, useScreenshot, useScreenshotDownload, useScreenshotWebShare, useStackState, useTabContext, validatePhoneNumber };
+/**
+ * The lucide-react icons Dynamic UI renders on its own, without the consumer
+ * asking for them by name.
+ *
+ * Two sources feed this list:
+ *
+ * - The `iconMap` defaults of `DContextProvider` (`src/contexts/DContext.tsx`),
+ *   used by close buttons, chevrons, alert states, input adornments and the
+ *   stepper checkmark.
+ * - Names hard-coded in component JSX or in a prop default, such as
+ *   `DDropdown`'s toggle or `DVoucher`'s action buttons.
+ *
+ * Any bundler-level optimisation that narrows lucide-react down to the icons a
+ * widget actually uses must keep this set, or Dynamic UI components break for
+ * reasons the widget author cannot see in their own source. That is why the
+ * list ships in the package as `dist/icons-core.json` and is exported here.
+ *
+ * `src/icons/coreIcons.spec.ts` scans `src/components/**` and fails when an
+ * internally used icon name is missing from this list or absent from
+ * lucide-react, so the two cannot drift apart.
+ */
+const CORE_LUCIDE_ICONS = [
+    // iconMap defaults — src/contexts/DContext.tsx
+    'AlertCircle',
+    'AlertTriangle',
+    'Calendar',
+    'Check',
+    'CheckCircle',
+    'ChevronDown',
+    'ChevronLeft',
+    'ChevronRight',
+    'ChevronUp',
+    'Eye',
+    'EyeOff',
+    'Info',
+    'Minus',
+    'Plus',
+    'Search',
+    'Upload',
+    'X',
+    // Hard-coded in component JSX or in a prop default
+    'Circle',
+    'CircleCheck',
+    'CircleCheckBig',
+    'Download',
+    'FileText',
+    'MoreVertical',
+    'Paperclip',
+    'RefreshCw',
+    'Share2',
+    'Trash',
+];
+
+export { CORE_LUCIDE_ICONS, DAlert, DAvatar, DBadge, DBox, DBoxFile, DButton, DButtonIcon, DCard$1 as DCard, DCardBody, DCardFooter, DCardHeader, DCarousel$1 as DCarousel, DCarouselSlide, DChip, DCollapse, DConfirmModalContainer, DContext, DContextProvider, DCreditCard, DCurrencyText, DDataStateWrapper, DDatePicker, DDropdown, DErrorBoundary, DIcon, DIconBase, ForwardedDInput as DInput, DInputCheck, ForwardedDInputCounter as DInputCounter, ForwardedDInputCurrency as DInputCurrency, ForwardedDInputMask as DInputMask, ForwardedDInputPassword as DInputPassword, ForwardedDInputPhone as DInputPhone, DInputPin, ForwardedDInputRange as DInputRange, ForwardedDInputSearch as DInputSearch, DInputSelect, DInputSwitch, DLayout$1 as DLayout, DLayoutPane, DListGroup$1 as DListGroup, DListGroupItem, DModal$1 as DModal, DModalBody, DModalFooter, DModalHeader, DOffcanvas$1 as DOffcanvas, DOffcanvasBody, DOffcanvasFooter, DOffcanvasHeader, DOtp, DPaginator, DPasswordStrengthMeter, DPopover, DProgress, DSelect$1 as DSelect, DStepper, DStepper$2 as DStepperDesktop, DStepper$1 as DStepperMobile, DTabContent, DTabs$1 as DTabs, DTabsProvider, DTimeline, DToast$1 as DToast, DToastContainer, DTooltip, DVoucher, EmptyState, ErrorState, LoadingState, buildUrl, changeQueryString, checkMediaQuery, configureI8n as configureI18n, formatCurrency, getCssVariable, getQueryString, sanitizeHref, subscribeToMediaQuery, useConfirmModal, useCountdown, useDContext, useDPortalContext, useDToast, useDisableBodyScrollEffect, useDisableInputWheel, useFormatCurrency, useInputCurrency, useItemSelection, useMediaBreakpointUpLg, useMediaBreakpointUpMd, useMediaBreakpointUpSm, useMediaBreakpointUpXl, useMediaBreakpointUpXs, useMediaBreakpointUpXxl, useMediaQuery, useOtp, useProvidedRefOrCreate, useScreenshot, useScreenshotDownload, useScreenshotWebShare, useStackState, useTabContext, validatePhoneNumber };
 //# sourceMappingURL=index.esm.js.map