ux4g-components-web 1.4.0 → 1.5.0

package/dist/dom-generators/index.cjs

@@ -0,0 +1,2029 @@
+'use strict';
+
+// ux4g-components-web/src/dom-generators/types.ts
+// Framework-agnostic structural descriptor for DOM generation.
+/**
+ * Error thrown when a DOM Generator receives an invalid prop value.
+ * Provides detailed context about which component, prop, and value caused the issue.
+ */
+class DOMGeneratorValidationError extends Error {
+    constructor(componentName, propName, propValue, expectedType) {
+        super(`[UX4G DOM Generator] Invalid prop "${propName}" on ${componentName}: ` +
+            `received ${JSON.stringify(propValue)}, expected ${expectedType}`);
+        this.componentName = componentName;
+        this.propName = propName;
+        this.propValue = propValue;
+        this.expectedType = expectedType;
+        this.name = 'DOMGeneratorValidationError';
+    }
+}
+
+// ux4g-components-web/src/dom-generators/id-generator.ts
+// Monotonically incrementing ID generator for document-unique element IDs.
+let counter = 0;
+/**
+ * Generates a unique ID by combining the given prefix with an incrementing counter.
+ * Produces IDs like `ux4g-dropdown-1`, `ux4g-tab-panel-2`, etc.
+ */
+function generateId(prefix) {
+    return `${prefix}-${++counter}`;
+}
+/**
+ * Resets the ID counter to zero. Useful for testing to ensure deterministic output.
+ */
+function resetIdCounter() {
+    counter = 0;
+}
+
+// ux4g-components-web/src/dom-generators/validate.ts
+// Prop validation helpers for DOM Generator functions.
+/**
+ * Throws if the value is null or undefined.
+ */
+function validateRequired(componentName, propName, value) {
+    if (value === null || value === undefined) {
+        throw new DOMGeneratorValidationError(componentName, propName, value, 'a non-null/undefined value');
+    }
+}
+/**
+ * Throws if typeof value does not match the expected type string.
+ */
+function validateType(componentName, propName, value, expectedType) {
+    if (typeof value !== expectedType) {
+        throw new DOMGeneratorValidationError(componentName, propName, value, expectedType);
+    }
+}
+/**
+ * Throws if the value is not a member of the allowed values set.
+ */
+function validateEnum(componentName, propName, value, allowedValues) {
+    if (!allowedValues.includes(value)) {
+        throw new DOMGeneratorValidationError(componentName, propName, value, `one of [${allowedValues.map((v) => JSON.stringify(v)).join(', ')}]`);
+    }
+}
+/**
+ * Throws if the numeric value is outside the given [min, max] range (inclusive).
+ */
+function validateRange(componentName, propName, value, min, max) {
+    if (typeof value !== 'number' || value < min || value > max) {
+        throw new DOMGeneratorValidationError(componentName, propName, value, `a number between ${min} and ${max}`);
+    }
+}
+/**
+ * Throws if the value is not an array.
+ */
+function validateArray(componentName, propName, value) {
+    if (!Array.isArray(value)) {
+        throw new DOMGeneratorValidationError(componentName, propName, value, 'an array');
+    }
+}
+
+// Maps variant → CSS class
+function buildAvatarClasses(avatarType, size, extra) {
+    if (avatarType === 'group') {
+        return extra ? `ux4g-avatar-group ${extra}` : 'ux4g-avatar-group';
+    }
+    const parts = ['ux4g-avatar', `ux4g-avatar-${avatarType}`];
+    if (size)
+        parts.push(`ux4g-avatar-${size}`);
+    return parts.join(' ');
+}
+function buildChipClasses(chipType, size, active, extra) {
+    // xs is only valid for input chips; filter and choice clamp to sm
+    const effectiveSize = (chipType !== 'input' && size === 'xs') ? 'sm' : size;
+    const parts = [`ux4g-${chipType}-chip-${effectiveSize}`];
+    if (active)
+        parts.push('active');
+    return parts.join(' ');
+}
+function buildDropdownClasses(type, mode, size, state, open, extra) {
+    const parts = [
+        'ux4g-dropdown',
+        `ux4g-dropdown-${type}`,
+        `ux4g-dropdown-${mode}`,
+        `ux4g-dropdown-${size}`,
+        `ux4g-dropdown-${state}`,
+    ];
+    if (open)
+        parts.push('is-open');
+    if (extra)
+        parts.push(extra);
+    return parts.join(' ');
+}
+function buildComboboxClasses(type, size, state, open, extra) {
+    const parts = [
+        'ux4g-combobox',
+        `ux4g-combobox-${type}`,
+        `ux4g-combobox-${size}`,
+        `ux4g-combobox-${state}`,
+    ];
+    if (open)
+        parts.push('is-open');
+    return parts.join(' ');
+}
+function buildModalBackdropClasses(opacity, blur, open, extra) {
+    const parts = ['ux4g-modal-backdrop', `ux4g-modal-backdrop-${opacity}`];
+    if (blur)
+        parts.push('ux4g-modal-backdrop-blur');
+    if (open)
+        parts.push('is-open');
+    return parts.join(' ');
+}
+function buildModalBoxClasses(size, centerContent, extra) {
+    const parts = ['ux4g-modal-box', `ux4g-modal-${size}`];
+    return parts.join(' ');
+}
+function buildSearchContainerClasses(size, extra) {
+    const base = `ux4g-search-container ux4g-search-${size}`;
+    return extra ? `${base} ${extra}` : base;
+}
+function buildTableClasses(size, divider, zebra, interactive, sortable, resizable, headerBrand, extra) {
+    const parts = ['ux4g-table', `ux4g-table-${size}`];
+    if (divider === 'column')
+        parts.push('ux4g-table-column-dividers');
+    else if (divider === 'none')
+        parts.push('ux4g-table-no-row-dividers');
+    if (zebra === 'rows')
+        parts.push('ux4g-table-zebra-rows');
+    else if (zebra === 'cols')
+        parts.push('ux4g-table-zebra-cols');
+    if (interactive)
+        parts.push('ux4g-table-interactive');
+    if (sortable)
+        parts.push('ux4g-table-sortable');
+    return parts.join(' ');
+}
+function buildPopoverClasses(placement, show, extra) {
+    const parts = ['ux4g-popover', `ux4g-popover-${placement}`];
+    if (show)
+        parts.push('show');
+    return parts.join(' ');
+}
+function buildTooltipClasses(placement, size, extra) {
+    const parts = ['ux4g-tooltip', `ux4g-tooltip-${placement}`, `ux4g-tooltip-${size}`];
+    return parts.join(' ');
+}
+function buildTabClasses(variant, size, vertical, extra) {
+    const parts = ['ux4g-tab', `ux4g-tab-${variant}`, `ux4g-tab-${size}`];
+    if (vertical)
+        parts.push('ux4g-tab-vertical');
+    return parts.join(' ');
+}
+function buildAccordionClasses(arrowPosition, variant, extra) {
+    const parts = ['ux4g-accordion'];
+    if (arrowPosition === 'right')
+        parts.push('ux4g-accordion-arrow-right');
+    else if (arrowPosition === 'left')
+        parts.push('ux4g-accordion-arrow-left');
+    if (variant === 'bordered')
+        parts.push('ux4g-accordion-bordered');
+    return parts.join(' ');
+}
+function buildStepperClasses(orientation, alignment, variant, size, extra) {
+    const parts = ['ux4g-stepper'];
+    if (orientation === 'vertical') {
+        parts.push('ux4g-stepper-vertical');
+    }
+    if (variant === 'bottom-line')
+        parts.push('ux4g-stepper-bottom-line');
+    else if (variant === 'bottom-line-fill') {
+        parts.push('ux4g-stepper-bottom-line');
+        parts.push('ux4g-stepper-bottom-line-fill');
+    }
+    else if (variant === 'mobile')
+        parts.push('ux4g-stepper-mobile');
+    else if (variant === 'progress')
+        parts.push('ux4g-stepper-progress');
+    if (size === 's')
+        parts.push('ux4g-stepper-s');
+    return parts.join(' ');
+}
+function buildDrawerClasses(placement, open, extra) {
+    const parts = ['ux4g-drawer', `ux4g-drawer-${placement}`];
+    if (open)
+        parts.push('ux4g-drawer-open');
+    return parts.join(' ');
+}
+function buildDateTimePickerClasses(mode, extra) {
+    const base = mode === 'date' ? 'ux4g-date-picker-container' : 'ux4g-time-picker-container';
+    return extra ? `${base} ${extra}` : base;
+}
+function buildOtpInputClasses(state, extra) {
+    const parts = ['ux4g-otp'];
+    if (state && state !== 'default')
+        parts.push(`ux4g-otp-${state}`);
+    return parts.join(' ');
+}
+function buildFileUploadClasses(state, extra) {
+    const parts = ['ux4g-upload'];
+    if (state)
+        parts.push(`ux4g-upload-state-${state}`);
+    return parts.join(' ');
+}
+function buildProgressIndicatorClasses(type, extra) {
+    const base = type === 'bar' ? 'ux4g-progress-bar' : 'ux4g-progress-circle';
+    return base;
+}
+// -- Carousel -----------------------------------------------------------------
+function buildCarouselClasses(extra) {
+    return extra ? `ux4g-carousel ${extra}` : 'ux4g-carousel';
+}
+
+// ux4g-components-web/src/dom-generators/modal.ts
+// Framework-agnostic DOM Generator for the Modal component.
+/**
+ * Generates a complete Modal DOM descriptor tree.
+ *
+ * Produces a backdrop element and a modal dialog box with `role="dialog"`,
+ * `aria-modal="true"`, an optional close button with `data-ux4g-modal-close`,
+ * and an optional title heading. Compatible with Runtime_JS
+ * MutationObserver-based initialization.
+ */
+function generateModalDOM(props) {
+    const { open = false, size = 'm', title, closable = true, backdropOpacity = '50', backdropBlur = false, } = props;
+    // Generate unique IDs
+    const modalId = generateId('ux4g-modal');
+    const titleId = generateId('ux4g-modal-title');
+    // Build backdrop element
+    const backdropClasses = buildModalBackdropClasses(backdropOpacity, backdropBlur, open);
+    const backdropNode = {
+        tag: 'div',
+        props: {
+            className: backdropClasses,
+        },
+        children: [],
+    };
+    // Build modal box children
+    const modalBoxChildren = [];
+    // Close button (if closable)
+    if (closable) {
+        const closeButton = {
+            tag: 'button',
+            props: {
+                className: 'ux4g-modal-close',
+                type: 'button',
+                'data-ux4g-modal-close': 'true',
+                'aria-label': 'Close',
+            },
+            children: [],
+        };
+        modalBoxChildren.push(closeButton);
+    }
+    // Title heading (if title provided)
+    if (title) {
+        const titleNode = {
+            tag: 'h2',
+            props: {
+                className: 'ux4g-modal-title',
+                id: titleId,
+            },
+            children: [title],
+        };
+        modalBoxChildren.push(titleNode);
+    }
+    // Build modal box element
+    const modalBoxClasses = buildModalBoxClasses(size);
+    const modalBoxProps = {
+        className: modalBoxClasses,
+        id: modalId,
+        role: 'dialog',
+        'aria-modal': 'true',
+    };
+    // Link title for accessible labelling
+    if (title) {
+        modalBoxProps['aria-labelledby'] = titleId;
+    }
+    const modalBoxNode = {
+        tag: 'div',
+        props: modalBoxProps,
+        children: modalBoxChildren,
+    };
+    // Build root wrapper containing backdrop and modal box
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-modal',
+        },
+        children: [backdropNode, modalBoxNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/carousel.ts
+// Framework-agnostic DOM Generator for the Carousel component.
+/**
+ * Generates a complete Carousel DOM descriptor tree.
+ *
+ * Produces a root element with `aria-roledescription="carousel"`, slide items with
+ * `role="group"` and `aria-roledescription="slide"`, navigation buttons with
+ * `data-ux4g-carousel-prev` and `data-ux4g-carousel-next` for Runtime_JS, and
+ * indicator dots for slide navigation.
+ */
+function generateCarouselDOM(props) {
+    const { slides, activeIndex = 0, showIndicators = true, showNavigation = true, } = props;
+    // Validate required props
+    validateArray('Carousel', 'slides', slides);
+    // Generate unique IDs for each slide
+    const slideIds = slides.map(() => generateId('ux4g-carousel-slide'));
+    // Build slide items
+    const slideItems = slides.map((slide, index) => {
+        const isActive = index === activeIndex;
+        return {
+            tag: 'div',
+            props: {
+                className: 'ux4g-carousel-slide',
+                id: slideIds[index],
+                role: 'group',
+                'aria-roledescription': 'slide',
+                'aria-label': slide.label || `Slide ${index + 1}`,
+                ...(isActive ? {} : { 'aria-hidden': 'true' }),
+            },
+            children: [slide.content],
+        };
+    });
+    // Build slide container
+    const slideContainer = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-carousel-slides',
+        },
+        children: slideItems,
+    };
+    // Build root children
+    const rootChildren = [slideContainer];
+    // Add navigation buttons if enabled
+    if (showNavigation) {
+        const prevButton = {
+            tag: 'button',
+            props: {
+                className: 'ux4g-carousel-prev',
+                type: 'button',
+                'data-ux4g-carousel-prev': 'true',
+                'aria-label': 'Previous slide',
+            },
+            children: [],
+        };
+        const nextButton = {
+            tag: 'button',
+            props: {
+                className: 'ux4g-carousel-next',
+                type: 'button',
+                'data-ux4g-carousel-next': 'true',
+                'aria-label': 'Next slide',
+            },
+            children: [],
+        };
+        rootChildren.push(prevButton, nextButton);
+    }
+    // Add indicator dots if enabled
+    if (showIndicators) {
+        const indicatorDots = slides.map((_, index) => {
+            const isActive = index === activeIndex;
+            return {
+                tag: 'button',
+                props: {
+                    className: 'ux4g-carousel-indicator',
+                    type: 'button',
+                    'aria-label': `Go to slide ${index + 1}`,
+                    ...(isActive ? { 'aria-current': 'true' } : {}),
+                },
+                children: [],
+            };
+        });
+        const indicatorContainer = {
+            tag: 'div',
+            props: {
+                className: 'ux4g-carousel-indicators',
+                role: 'tablist',
+            },
+            children: indicatorDots,
+        };
+        rootChildren.push(indicatorContainer);
+    }
+    // Build root element
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: buildCarouselClasses(),
+            'aria-roledescription': 'carousel',
+            'aria-label': 'Carousel',
+        },
+        children: rootChildren,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/dropdown.ts
+// Framework-agnostic DOM Generator for the Dropdown component.
+/**
+ * Generates a complete Dropdown DOM descriptor tree.
+ *
+ * Produces a trigger button with `data-ux4g-dropdown-toggle`, a menu container
+ * with `role="listbox"`, and option items with `role="option"` and `aria-selected`.
+ * Compatible with Runtime_JS MutationObserver-based initialization.
+ */
+function generateDropdownDOM(props) {
+    const { options, value, placeholder = 'Select...', searchable = false, multiple = false, disabled = false, size = 'md', state = 'default', open = false, } = props;
+    // Validate required props
+    validateRequired('Dropdown', 'options', options);
+    validateArray('Dropdown', 'options', options);
+    // Generate unique IDs
+    const triggerId = generateId('ux4g-dropdown-trigger');
+    const menuId = generateId('ux4g-dropdown-menu');
+    // Determine the mode based on multiple prop
+    const mode = multiple ? 'multi' : 'single';
+    // Build CSS classes via Class Builder
+    const dropdownClasses = buildDropdownClasses('selection', mode, size, state, open, disabled ? 'ux4g-dropdown-disabled' : undefined);
+    // Determine display text for the trigger
+    const selectedValues = Array.isArray(value) ? value : value != null ? [value] : [];
+    const selectedLabels = options
+        .filter((opt) => selectedValues.includes(opt.value))
+        .map((opt) => opt.label);
+    const displayText = selectedLabels.length > 0 ? selectedLabels.join(', ') : placeholder;
+    // Build trigger button
+    const triggerNode = {
+        tag: 'button',
+        props: {
+            className: 'ux4g-dropdown-trigger',
+            id: triggerId,
+            'data-ux4g-dropdown-toggle': 'true',
+            'aria-haspopup': 'listbox',
+            'aria-expanded': String(open),
+            'aria-controls': menuId,
+            type: 'button',
+            ...(disabled ? { 'aria-disabled': 'true', disabled: true } : {}),
+        },
+        children: [displayText],
+    };
+    // Build option items
+    const optionItems = options.map((opt) => {
+        const isSelected = selectedValues.includes(opt.value);
+        const optionProps = {
+            className: 'ux4g-dropdown-option',
+            role: 'option',
+            'aria-selected': String(isSelected),
+            'data-value': opt.value,
+        };
+        if (opt.disabled) {
+            optionProps['aria-disabled'] = 'true';
+        }
+        return {
+            tag: 'div',
+            props: optionProps,
+            children: [opt.label],
+        };
+    });
+    // Build menu children (search input if searchable, then options)
+    const menuChildren = [];
+    if (searchable) {
+        const searchInput = {
+            tag: 'input',
+            props: {
+                className: 'ux4g-dropdown-search',
+                type: 'text',
+                role: 'searchbox',
+                'aria-label': 'Filter options',
+                placeholder: 'Search...',
+            },
+            children: [],
+        };
+        menuChildren.push(searchInput);
+    }
+    menuChildren.push(...optionItems);
+    // Build menu container
+    const menuNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-dropdown-menu',
+            id: menuId,
+            role: 'listbox',
+            'aria-multiselectable': multiple ? 'true' : undefined,
+        },
+        children: menuChildren,
+    };
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: dropdownClasses,
+        },
+        children: [triggerNode, menuNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/tabs.ts
+// Framework-agnostic DOM Generator for the Tabs component.
+/**
+ * Generates a complete Tabs DOM descriptor tree.
+ *
+ * Produces a tablist container with `role="tablist"`, individual tabs with
+ * `role="tab"` and `aria-selected`, and corresponding panels with
+ * `role="tabpanel"` and `aria-labelledby`.
+ */
+function generateTabsDOM(props) {
+    const { tabs, activeIndex = 0, variant = 'underline', size = 'md', vertical = false, } = props;
+    // Validate required props
+    validateArray('Tabs', 'tabs', tabs);
+    // Generate paired IDs for each tab/panel
+    const tabIds = [];
+    const panelIds = [];
+    for (let i = 0; i < tabs.length; i++) {
+        tabIds.push(generateId('ux4g-tab'));
+        panelIds.push(generateId('ux4g-tab-panel'));
+    }
+    // Build tab elements
+    const tabNodes = tabs.map((tab, index) => {
+        const isActive = index === activeIndex;
+        const tabProps = {
+            className: 'ux4g-tab-item',
+            id: tabIds[index],
+            role: 'tab',
+            'aria-selected': String(isActive),
+            'aria-controls': panelIds[index],
+            tabIndex: isActive ? 0 : -1,
+        };
+        if (tab.disabled) {
+            tabProps['aria-disabled'] = 'true';
+        }
+        return {
+            tag: 'button',
+            props: tabProps,
+            children: [tab.label],
+        };
+    });
+    // Build tablist container
+    const tablistNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-tablist',
+            role: 'tablist',
+            'aria-orientation': vertical ? 'vertical' : 'horizontal',
+        },
+        children: tabNodes,
+    };
+    // Build panel elements
+    const panelNodes = tabs.map((tab, index) => {
+        const isActive = index === activeIndex;
+        const panelProps = {
+            className: 'ux4g-tab-panel',
+            id: panelIds[index],
+            role: 'tabpanel',
+            'aria-labelledby': tabIds[index],
+            tabIndex: 0,
+        };
+        if (!isActive) {
+            panelProps['aria-hidden'] = 'true';
+        }
+        return {
+            tag: 'div',
+            props: panelProps,
+            children: [tab.content],
+        };
+    });
+    // Build CSS classes via Class Builder
+    const rootClasses = buildTabClasses(variant, size, vertical);
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: rootClasses,
+        },
+        children: [tablistNode, ...panelNodes],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/accordion.ts
+// DOM Generator for the Accordion component.
+/**
+ * Generates a complete Accordion DOM descriptor tree.
+ *
+ * Produces headers with `data-ux4g-accordion-toggle` for Runtime_JS,
+ * panels with unique IDs, aria-expanded on toggles, aria-controls
+ * referencing panel IDs, and role="region" on panels.
+ */
+function generateAccordionDOM(props) {
+    const { items, arrowPosition, variant } = props;
+    validateArray('Accordion', 'items', items);
+    const accordionItems = items.map((item) => {
+        const headerId = generateId('ux4g-accordion-header');
+        const panelId = generateId('ux4g-accordion-panel');
+        const isExpanded = item.expanded ?? false;
+        const headerButtonProps = {
+            className: 'ux4g-accordion-button',
+            id: headerId,
+            'data-ux4g-accordion-toggle': 'true',
+            'aria-expanded': String(isExpanded),
+            'aria-controls': panelId,
+        };
+        if (item.disabled) {
+            headerButtonProps['aria-disabled'] = 'true';
+        }
+        const headerButton = {
+            tag: 'button',
+            props: headerButtonProps,
+            children: [item.header],
+        };
+        const header = {
+            tag: 'div',
+            props: {
+                className: 'ux4g-accordion-header',
+            },
+            children: [headerButton],
+        };
+        const panel = {
+            tag: 'div',
+            props: {
+                className: 'ux4g-accordion-panel',
+                id: panelId,
+                role: 'region',
+                'aria-labelledby': headerId,
+            },
+            children: [item.content],
+        };
+        return {
+            tag: 'div',
+            props: {
+                className: 'ux4g-accordion-item',
+            },
+            children: [header, panel],
+        };
+    });
+    return {
+        tag: 'div',
+        props: {
+            className: buildAccordionClasses(arrowPosition, variant),
+        },
+        children: accordionItems,
+    };
+}
+
+// ux4g-components-web/src/dom-generators/time-picker.ts
+// Framework-agnostic DOM Generator for the TimePicker component.
+/**
+ * Parses a time string in HH:mm format and returns hour and minute values.
+ * Returns defaults (0, 0) for invalid or missing values.
+ */
+function parseTimeValue(value) {
+    if (!value) {
+        return { hour: 0, minute: 0 };
+    }
+    const parts = value.split(':');
+    if (parts.length < 2) {
+        return { hour: 0, minute: 0 };
+    }
+    const hour = parseInt(parts[0], 10);
+    const minute = parseInt(parts[1], 10);
+    return {
+        hour: isNaN(hour) ? 0 : hour,
+        minute: isNaN(minute) ? 0 : minute,
+    };
+}
+/**
+ * Generates a complete TimePicker DOM descriptor tree.
+ *
+ * Produces hour, minute, and (for 12h format) period spinbutton elements
+ * with appropriate ARIA attributes: `role="spinbutton"`, `aria-valuemin`,
+ * `aria-valuemax`, `aria-valuenow`, and `aria-label`.
+ *
+ * The root element uses CSS classes from `buildDateTimePickerClasses('time')`.
+ */
+function generateTimePickerDOM(props) {
+    const { value, format = '24h', } = props;
+    const { hour, minute } = parseTimeValue(value);
+    // Generate unique IDs for each spinbutton
+    const hourId = generateId('ux4g-time-picker-hour');
+    const minuteId = generateId('ux4g-time-picker-minute');
+    // Determine hour range based on format
+    const is12h = format === '12h';
+    const hourMin = is12h ? 1 : 0;
+    const hourMax = is12h ? 12 : 23;
+    // Convert 24h hour to 12h display value
+    let displayHour = hour;
+    let periodValue = 0; // 0 = AM, 1 = PM
+    if (is12h) {
+        periodValue = hour >= 12 ? 1 : 0;
+        displayHour = hour % 12;
+        if (displayHour === 0) {
+            displayHour = 12;
+        }
+    }
+    // Build hour spinbutton
+    const hourSpinbutton = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-time-picker-hour',
+            id: hourId,
+            role: 'spinbutton',
+            tabIndex: 0,
+            'aria-valuemin': hourMin,
+            'aria-valuemax': hourMax,
+            'aria-valuenow': displayHour,
+            'aria-label': 'Hours',
+        },
+        children: [String(displayHour)],
+    };
+    // Build minute spinbutton
+    const minuteSpinbutton = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-time-picker-minute',
+            id: minuteId,
+            role: 'spinbutton',
+            tabIndex: 0,
+            'aria-valuemin': 0,
+            'aria-valuemax': 59,
+            'aria-valuenow': minute,
+            'aria-label': 'Minutes',
+        },
+        children: [String(minute)],
+    };
+    // Build children array
+    const children = [hourSpinbutton, minuteSpinbutton];
+    // For 12h format, add period selector
+    if (is12h) {
+        const periodId = generateId('ux4g-time-picker-period');
+        const periodSpinbutton = {
+            tag: 'div',
+            props: {
+                className: 'ux4g-time-picker-period',
+                id: periodId,
+                role: 'spinbutton',
+                tabIndex: 0,
+                'aria-valuemin': 0,
+                'aria-valuemax': 1,
+                'aria-valuenow': periodValue,
+                'aria-label': 'Period',
+            },
+            children: [periodValue === 0 ? 'AM' : 'PM'],
+        };
+        children.push(periodSpinbutton);
+    }
+    // Build root element with class from buildDateTimePickerClasses('time')
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: buildDateTimePickerClasses('time'),
+        },
+        children,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/search.ts
+// Framework-agnostic DOM Generator for the Search component.
+/**
+ * Generates a complete Search DOM descriptor tree.
+ *
+ * Produces a search input with `role="searchbox"`, a clear button visible when
+ * there is a value, and a suggestions listbox with `role="listbox"`.
+ * Compatible with Runtime_JS MutationObserver-based initialization.
+ */
+function generateSearchDOM(props) {
+    const { value = '', placeholder = 'Search...', suggestions = [], showSuggestions = false, size = 'm', } = props;
+    // Generate unique IDs
+    const inputId = generateId('ux4g-search-input');
+    const suggestionsId = generateId('ux4g-search-suggestions');
+    // Build CSS classes via Class Builder
+    const containerClasses = buildSearchContainerClasses(size);
+    // Determine if suggestions should be visible
+    const hasSuggestions = suggestions.length > 0;
+    const suggestionsVisible = showSuggestions && hasSuggestions;
+    // Build search input
+    const inputProps = {
+        className: 'ux4g-search-input',
+        id: inputId,
+        role: 'searchbox',
+        'aria-label': 'Search',
+        placeholder,
+        type: 'text',
+    };
+    if (hasSuggestions) {
+        inputProps['aria-controls'] = suggestionsId;
+    }
+    inputProps['aria-expanded'] = String(suggestionsVisible);
+    if (value) {
+        inputProps['value'] = value;
+    }
+    const inputNode = {
+        tag: 'input',
+        props: inputProps,
+        children: [],
+    };
+    // Build clear button (visible when value has content)
+    const clearButtonNode = {
+        tag: 'button',
+        props: {
+            className: 'ux4g-search-clear',
+            type: 'button',
+            'aria-label': 'Clear search',
+            ...(value ? {} : { 'aria-hidden': 'true' }),
+        },
+        children: ['×'],
+    };
+    // Build suggestion items
+    const suggestionItems = suggestions.map((suggestion) => ({
+        tag: 'div',
+        props: {
+            className: 'ux4g-search-suggestion',
+            role: 'option',
+            'data-value': suggestion.value,
+        },
+        children: [suggestion.label],
+    }));
+    // Build suggestions listbox
+    const suggestionsNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-search-suggestions',
+            id: suggestionsId,
+            role: 'listbox',
+            'aria-label': 'Search suggestions',
+            ...(!suggestionsVisible ? { 'aria-hidden': 'true' } : {}),
+        },
+        children: suggestionItems,
+    };
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: containerClasses,
+        },
+        children: [inputNode, clearButtonNode, suggestionsNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/drawer.ts
+// Framework-agnostic DOM Generator for the Drawer component.
+/**
+ * Generates a complete Drawer DOM descriptor tree.
+ *
+ * Produces a backdrop element and a drawer panel with `role="dialog"`,
+ * `aria-modal="true"`, an optional close button with `data-ux4g-drawer-close`,
+ * and an optional title heading. Compatible with Runtime_JS
+ * MutationObserver-based initialization.
+ */
+function generateDrawerDOM(props) {
+    const { open = false, placement = 'right', title, closable = true, } = props;
+    // Generate unique IDs
+    const drawerId = generateId('ux4g-drawer');
+    const titleId = generateId('ux4g-drawer-title');
+    // Build backdrop element
+    const backdropNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-drawer-backdrop',
+        },
+        children: [],
+    };
+    // Build drawer panel children
+    const drawerPanelChildren = [];
+    // Close button (if closable)
+    if (closable) {
+        const closeButton = {
+            tag: 'button',
+            props: {
+                className: 'ux4g-drawer-close',
+                type: 'button',
+                'data-ux4g-drawer-close': 'true',
+                'aria-label': 'Close',
+            },
+            children: [],
+        };
+        drawerPanelChildren.push(closeButton);
+    }
+    // Title heading (if title provided)
+    if (title) {
+        const titleNode = {
+            tag: 'h2',
+            props: {
+                className: 'ux4g-drawer-title',
+                id: titleId,
+            },
+            children: [title],
+        };
+        drawerPanelChildren.push(titleNode);
+    }
+    // Build drawer panel element
+    const drawerPanelClasses = buildDrawerClasses(placement, open);
+    const drawerPanelProps = {
+        className: drawerPanelClasses,
+        id: drawerId,
+        role: 'dialog',
+        'aria-modal': 'true',
+    };
+    // Link title for accessible labelling
+    if (title) {
+        drawerPanelProps['aria-labelledby'] = titleId;
+    }
+    const drawerPanelNode = {
+        tag: 'div',
+        props: drawerPanelProps,
+        children: drawerPanelChildren,
+    };
+    // Build root wrapper containing backdrop + drawer panel
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-drawer-wrapper',
+        },
+        children: [backdropNode, drawerPanelNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/combobox.ts
+// Framework-agnostic DOM Generator for the Combobox component.
+/**
+ * Generates a complete Combobox DOM descriptor tree.
+ *
+ * Produces an input with `role="combobox"` and `aria-autocomplete="list"`,
+ * a listbox with `role="listbox"`, and option items with `role="option"`.
+ * Supports `aria-activedescendant` pointing to the first selected option.
+ * Compatible with Runtime_JS MutationObserver-based initialization.
+ */
+function generateComboboxDOM(props) {
+    const { options, value, inputValue = '', placeholder = '', multiple = false, disabled = false, size = 'md', state = 'default', open = false, } = props;
+    // Validate required props
+    validateRequired('Combobox', 'options', options);
+    validateArray('Combobox', 'options', options);
+    // Generate unique IDs
+    const inputId = generateId('ux4g-combobox-input');
+    const listboxId = generateId('ux4g-combobox-listbox');
+    // Determine selected values
+    const selectedValues = Array.isArray(value) ? value : value != null ? [value] : [];
+    // Generate option IDs and find active descendant
+    const optionIds = options.map(() => generateId('ux4g-combobox-option'));
+    // Active descendant is the first selected option's ID (if any)
+    let activeDescendantId;
+    for (let i = 0; i < options.length; i++) {
+        if (selectedValues.includes(options[i].value)) {
+            activeDescendantId = optionIds[i];
+            break;
+        }
+    }
+    // Determine combobox type based on multiple prop
+    const type = multiple ? 'multi' : 'single';
+    // Build CSS classes via Class Builder
+    const comboboxClasses = buildComboboxClasses(type, size, state, open);
+    // Build input element
+    const inputNode = {
+        tag: 'input',
+        props: {
+            className: 'ux4g-combobox-input',
+            id: inputId,
+            role: 'combobox',
+            'aria-autocomplete': 'list',
+            'aria-expanded': String(open),
+            'aria-controls': listboxId,
+            ...(activeDescendantId ? { 'aria-activedescendant': activeDescendantId } : {}),
+            ...(placeholder ? { placeholder } : {}),
+            ...(inputValue ? { value: inputValue } : {}),
+            type: 'text',
+            ...(disabled ? { 'aria-disabled': 'true', disabled: true } : {}),
+        },
+        children: [],
+    };
+    // Build option items
+    const optionItems = options.map((opt, index) => {
+        const isSelected = selectedValues.includes(opt.value);
+        const optionProps = {
+            className: 'ux4g-combobox-option',
+            id: optionIds[index],
+            role: 'option',
+            'aria-selected': String(isSelected),
+            'data-value': opt.value,
+        };
+        if (opt.disabled) {
+            optionProps['aria-disabled'] = 'true';
+        }
+        return {
+            tag: 'div',
+            props: optionProps,
+            children: [opt.label],
+        };
+    });
+    // Build listbox container
+    const listboxNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-combobox-listbox',
+            id: listboxId,
+            role: 'listbox',
+            ...(multiple ? { 'aria-multiselectable': 'true' } : {}),
+        },
+        children: optionItems,
+    };
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: comboboxClasses,
+        },
+        children: [inputNode, listboxNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/date-picker.ts
+// Framework-agnostic DOM Generator for the DatePicker component.
+/**
+ * Returns the number of days in a given month/year.
+ */
+function getDaysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+/**
+ * Returns the day of the week (0=Sun, 6=Sat) for the first day of the given month.
+ */
+function getFirstDayOfWeek(year, month) {
+    return new Date(year, month, 1).getDay();
+}
+/**
+ * Formats a date as a full human-readable string for aria-label (e.g., "January 15, 2024").
+ */
+function formatDateLabel(year, month, day, locale) {
+    const date = new Date(year, month, day);
+    try {
+        return date.toLocaleDateString(locale, {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+        });
+    }
+    catch {
+        // Fallback for invalid locale
+        return date.toLocaleDateString('en-US', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+        });
+    }
+}
+/**
+ * Returns the month name for display in the header.
+ */
+function getMonthName(year, month, locale) {
+    const date = new Date(year, month, 1);
+    try {
+        return date.toLocaleDateString(locale, { month: 'long' });
+    }
+    catch {
+        return date.toLocaleDateString('en-US', { month: 'long' });
+    }
+}
+/**
+ * Returns the abbreviated weekday names starting from Sunday.
+ */
+function getWeekdayHeaders(locale) {
+    const weekdays = [];
+    // Jan 4, 2024 is a Thursday — use a known Sunday: Jan 7, 2024
+    const baseSunday = new Date(2024, 0, 7); // Sunday
+    for (let i = 0; i < 7; i++) {
+        const d = new Date(baseSunday);
+        d.setDate(baseSunday.getDate() + i);
+        try {
+            weekdays.push(d.toLocaleDateString(locale, { weekday: 'short' }));
+        }
+        catch {
+            weekdays.push(d.toLocaleDateString('en-US', { weekday: 'short' }));
+        }
+    }
+    return weekdays;
+}
+/**
+ * Checks if a date string (YYYY-MM-DD) represents a date that is outside the min/max range.
+ */
+function isDateDisabled(year, month, day, min, max) {
+    const dateValue = new Date(year, month, day).getTime();
+    if (min) {
+        const minParts = min.split('-');
+        const minDate = new Date(parseInt(minParts[0], 10), parseInt(minParts[1], 10) - 1, parseInt(minParts[2], 10)).getTime();
+        if (dateValue < minDate)
+            return true;
+    }
+    if (max) {
+        const maxParts = max.split('-');
+        const maxDate = new Date(parseInt(maxParts[0], 10), parseInt(maxParts[1], 10) - 1, parseInt(maxParts[2], 10)).getTime();
+        if (dateValue > maxDate)
+            return true;
+    }
+    return false;
+}
+/**
+ * Generates a complete DatePicker DOM descriptor tree.
+ *
+ * Produces a calendar grid with `role="grid"`, day cells with `role="gridcell"`,
+ * month/year navigation buttons, weekday column headers with `role="columnheader"`,
+ * and full accessibility attributes including `aria-label` on each day cell and
+ * `aria-selected`/`aria-disabled` states.
+ */
+function generateDatePickerDOM(props) {
+    const { value, min, max, locale = 'en-US', } = props;
+    // Default displayMonth/displayYear to current date or value date
+    const now = new Date();
+    let displayMonth = props.displayMonth;
+    let displayYear = props.displayYear;
+    if (displayMonth === undefined || displayYear === undefined) {
+        if (value) {
+            const valueParts = value.split('-');
+            displayMonth = displayMonth ?? (parseInt(valueParts[1], 10) - 1);
+            displayYear = displayYear ?? parseInt(valueParts[0], 10);
+        }
+        else {
+            displayMonth = displayMonth ?? now.getMonth();
+            displayYear = displayYear ?? now.getFullYear();
+        }
+    }
+    // Generate unique IDs
+    const gridId = generateId('ux4g-date-picker-grid');
+    const headerId = generateId('ux4g-date-picker-header');
+    // Build header with month/year display and navigation
+    const monthName = getMonthName(displayYear, displayMonth, locale);
+    const prevButton = {
+        tag: 'button',
+        props: {
+            className: 'ux4g-date-picker-prev',
+            type: 'button',
+            'aria-label': 'Previous month',
+        },
+        children: [],
+    };
+    const nextButton = {
+        tag: 'button',
+        props: {
+            className: 'ux4g-date-picker-next',
+            type: 'button',
+            'aria-label': 'Next month',
+        },
+        children: [],
+    };
+    const headerTitle = {
+        tag: 'span',
+        props: {
+            className: 'ux4g-date-picker-title',
+        },
+        children: [`${monthName} ${displayYear}`],
+    };
+    const header = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-date-picker-header',
+            id: headerId,
+        },
+        children: [prevButton, headerTitle, nextButton],
+    };
+    // Build weekday column headers
+    const weekdays = getWeekdayHeaders(locale);
+    const weekdayHeaders = weekdays.map((day) => ({
+        tag: 'div',
+        props: {
+            className: 'ux4g-date-picker-weekday',
+            role: 'columnheader',
+            'aria-label': day,
+        },
+        children: [day],
+    }));
+    const weekdayRow = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-date-picker-weekdays',
+            role: 'row',
+        },
+        children: weekdayHeaders,
+    };
+    // Build calendar grid with day cells
+    const daysInMonth = getDaysInMonth(displayYear, displayMonth);
+    const firstDayOfWeek = getFirstDayOfWeek(displayYear, displayMonth);
+    // Parse selected value for comparison
+    let selectedYear;
+    let selectedMonth;
+    let selectedDay;
+    if (value) {
+        const parts = value.split('-');
+        selectedYear = parseInt(parts[0], 10);
+        selectedMonth = parseInt(parts[1], 10) - 1;
+        selectedDay = parseInt(parts[2], 10);
+    }
+    // Build week rows
+    const weekRows = [];
+    let currentDay = 1;
+    let weekCells = [];
+    // Fill empty cells before the first day
+    for (let i = 0; i < firstDayOfWeek; i++) {
+        weekCells.push({
+            tag: 'div',
+            props: {
+                className: 'ux4g-date-picker-cell ux4g-date-picker-cell-empty',
+                role: 'gridcell',
+            },
+            children: [],
+        });
+    }
+    // Fill days
+    while (currentDay <= daysInMonth) {
+        const isSelected = selectedYear === displayYear &&
+            selectedMonth === displayMonth &&
+            selectedDay === currentDay;
+        const isDisabled = isDateDisabled(displayYear, displayMonth, currentDay, min, max);
+        const dateLabel = formatDateLabel(displayYear, displayMonth, currentDay, locale);
+        const cellProps = {
+            className: 'ux4g-date-picker-cell',
+            role: 'gridcell',
+            'aria-label': dateLabel,
+        };
+        if (isSelected) {
+            cellProps['aria-selected'] = 'true';
+        }
+        if (isDisabled) {
+            cellProps['aria-disabled'] = 'true';
+        }
+        weekCells.push({
+            tag: 'div',
+            props: cellProps,
+            children: [`${currentDay}`],
+        });
+        // If we've filled a week (7 cells), start a new row
+        if (weekCells.length === 7) {
+            weekRows.push({
+                tag: 'div',
+                props: {
+                    className: 'ux4g-date-picker-row',
+                    role: 'row',
+                },
+                children: weekCells,
+            });
+            weekCells = [];
+        }
+        currentDay++;
+    }
+    // Fill remaining empty cells in the last row
+    if (weekCells.length > 0) {
+        while (weekCells.length < 7) {
+            weekCells.push({
+                tag: 'div',
+                props: {
+                    className: 'ux4g-date-picker-cell ux4g-date-picker-cell-empty',
+                    role: 'gridcell',
+                },
+                children: [],
+            });
+        }
+        weekRows.push({
+            tag: 'div',
+            props: {
+                className: 'ux4g-date-picker-row',
+                role: 'row',
+            },
+            children: weekCells,
+        });
+    }
+    // Build the grid
+    const grid = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-date-picker-grid',
+            id: gridId,
+            role: 'grid',
+            'aria-labelledby': headerId,
+        },
+        children: [weekdayRow, ...weekRows],
+    };
+    // Build root element
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: buildDateTimePickerClasses('date'),
+        },
+        children: [header, grid],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/stepper.ts
+// Framework-agnostic DOM Generator for the Stepper component.
+/**
+ * Generates a complete Stepper DOM descriptor tree.
+ *
+ * Produces step indicators with completed/current/pending states.
+ * Steps before `activeStep` are marked as completed, the step at
+ * `activeStep` has `aria-current="step"`, and subsequent steps
+ * are marked as pending.
+ */
+function generateStepperDOM(props) {
+    const { steps, activeStep, orientation = 'horizontal', variant = 'default', size = 'default', } = props;
+    // Validate steps is an array
+    validateArray('Stepper', 'steps', steps);
+    // Validate activeStep is in range [0, steps.length - 1]
+    validateRange('Stepper', 'activeStep', activeStep, 0, steps.length - 1);
+    // Build root className from buildStepperClasses
+    const rootClassName = buildStepperClasses(orientation, undefined, variant, size);
+    // Generate step indicator elements
+    const stepChildren = steps.map((step, index) => {
+        let stepClassName;
+        const stepProps = {};
+        if (index < activeStep) {
+            // Completed step
+            stepClassName = 'ux4g-stepper-item completed';
+            stepProps['aria-label'] = `Completed: ${step.label}`;
+        }
+        else if (index === activeStep) {
+            // Current step
+            stepClassName = 'ux4g-stepper-item current';
+            stepProps['aria-current'] = 'step';
+            stepProps['aria-label'] = step.label;
+        }
+        else {
+            // Pending step
+            stepClassName = 'ux4g-stepper-item pending';
+            stepProps['aria-label'] = step.label;
+        }
+        stepProps.className = stepClassName;
+        // Build children for the step indicator
+        const stepItemChildren = [
+            {
+                tag: 'span',
+                props: {
+                    className: 'ux4g-stepper-indicator',
+                },
+                children: [`${index + 1}`],
+            },
+            {
+                tag: 'span',
+                props: {
+                    className: 'ux4g-stepper-label',
+                },
+                children: step.description
+                    ? [
+                        step.label,
+                        {
+                            tag: 'span',
+                            props: {
+                                className: 'ux4g-stepper-description',
+                            },
+                            children: [step.description],
+                        },
+                    ]
+                    : [step.label],
+            },
+        ];
+        return {
+            tag: 'div',
+            props: stepProps,
+            children: stepItemChildren,
+        };
+    });
+    // Build root element
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: rootClassName,
+            role: 'list',
+            'aria-label': 'Progress',
+        },
+        children: stepChildren,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/file-upload.ts
+// Framework-agnostic DOM Generator for the FileUpload component.
+/**
+ * Formats a byte value into a human-readable string (e.g., "1.5 KB", "2.3 MB").
+ */
+function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Generates a complete FileUpload DOM descriptor tree.
+ *
+ * Produces a drop zone with `role="button"`, a visually hidden file input,
+ * and a file list displaying name and size of each selected file.
+ * Compatible with Runtime_JS MutationObserver-based initialization.
+ */
+function generateFileUploadDOM(props) {
+    const { files = [], accept, maxSizeBytes, multiple = false, state, } = props;
+    // Generate unique IDs
+    const inputId = generateId('ux4g-file-upload-input');
+    const dropZoneId = generateId('ux4g-file-upload-zone');
+    // Build CSS classes via Class Builder
+    const rootClasses = buildFileUploadClasses(state);
+    // Build hidden file input
+    const inputProps = {
+        className: 'ux4g-upload-input',
+        id: inputId,
+        type: 'file',
+        'aria-hidden': 'true',
+        tabIndex: -1,
+    };
+    if (accept) {
+        inputProps['accept'] = accept;
+    }
+    if (multiple) {
+        inputProps['multiple'] = true;
+    }
+    const inputNode = {
+        tag: 'input',
+        props: inputProps,
+        children: [],
+    };
+    // Build drop zone
+    const dropZoneNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-upload-drop-zone',
+            id: dropZoneId,
+            role: 'button',
+            tabIndex: 0,
+            'aria-label': 'Drop files here or click to upload',
+            'aria-controls': inputId,
+        },
+        children: [
+            {
+                tag: 'span',
+                props: {
+                    className: 'ux4g-upload-drop-zone-text',
+                },
+                children: ['Drop files here or click to upload'],
+            },
+        ],
+    };
+    // Build file list items
+    const fileItems = files.map((file) => ({
+        tag: 'div',
+        props: {
+            className: 'ux4g-upload-file-item',
+        },
+        children: [
+            {
+                tag: 'span',
+                props: {
+                    className: 'ux4g-upload-file-name',
+                },
+                children: [file.name],
+            },
+            {
+                tag: 'span',
+                props: {
+                    className: 'ux4g-upload-file-size',
+                },
+                children: [formatFileSize(file.size)],
+            },
+        ],
+    }));
+    // Build file list container
+    const fileListNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-upload-file-list',
+            role: 'list',
+            'aria-label': 'Uploaded files',
+        },
+        children: fileItems,
+    };
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: rootClasses,
+        },
+        children: [dropZoneNode, inputNode, fileListNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/progress.ts
+// Framework-agnostic DOM Generator for the Progress Indicator component.
+const VALID_TYPES$1 = ['bar', 'circle'];
+const VALID_SIZES$2 = ['xs', 's', 'm', 'l', 'xl', '2xl', '3xl'];
+/**
+ * Generates a complete Progress Indicator DOM descriptor tree.
+ *
+ * Produces a progress element with `role="progressbar"`,
+ * `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
+ * Supports both 'bar' and 'circle' visualization types.
+ */
+function generateProgressDOM(props) {
+    const { value, type = 'bar', size, label, } = props;
+    // Validate props
+    validateRange('Progress', 'value', value, 0, 100);
+    if (type !== undefined) {
+        validateEnum('Progress', 'type', type, VALID_TYPES$1);
+    }
+    if (size !== undefined) {
+        validateEnum('Progress', 'size', size, VALID_SIZES$2);
+    }
+    const ariaLabel = label || 'Progress';
+    // Build CSS class string from the class builder
+    const className = buildProgressIndicatorClasses(type);
+    if (type === 'circle') {
+        return generateCircleProgress(value, className, size, ariaLabel);
+    }
+    return generateBarProgress(value, className, size, ariaLabel);
+}
+/**
+ * Generates a bar-type progress indicator.
+ */
+function generateBarProgress(value, className, size, ariaLabel) {
+    // The fill element represents the completed portion
+    const fillNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-progress-bar-fill',
+            'data-value': String(value),
+        },
+        children: [],
+    };
+    // The track element contains the fill
+    const trackNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-progress-bar-track',
+        },
+        children: [fillNode],
+    };
+    // Root element with ARIA progressbar role
+    const rootProps = {
+        className,
+        role: 'progressbar',
+        'aria-valuenow': value,
+        'aria-valuemin': 0,
+        'aria-valuemax': 100,
+        'aria-label': ariaLabel,
+    };
+    if (size) {
+        rootProps['data-ux-size'] = size;
+    }
+    const rootNode = {
+        tag: 'div',
+        props: rootProps,
+        children: [trackNode],
+    };
+    return rootNode;
+}
+/**
+ * Generates a circle-type progress indicator.
+ */
+function generateCircleProgress(value, className, size, ariaLabel) {
+    // The circle container element
+    const circleContainer = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-progress-circle-container',
+            'data-value': String(value),
+        },
+        children: [],
+    };
+    // Root element with ARIA progressbar role
+    const rootProps = {
+        className,
+        role: 'progressbar',
+        'aria-valuenow': value,
+        'aria-valuemin': 0,
+        'aria-valuemax': 100,
+        'aria-label': ariaLabel,
+    };
+    if (size) {
+        rootProps['data-ux-size'] = size;
+    }
+    const rootNode = {
+        tag: 'div',
+        props: rootProps,
+        children: [circleContainer],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/table.ts
+// Framework-agnostic DOM Generator for the Table component.
+/**
+ * Generates a complete Table DOM descriptor tree.
+ *
+ * Produces a `<table>` with `<thead>` containing one `<th>` per column
+ * and `<tbody>` containing one `<tr>` per data row, each with one `<td>` per column.
+ * Sortable columns receive `aria-sort="none"` on their `<th>`.
+ */
+function generateTableDOM(props) {
+    const { columns, data, size = 'm', divider, zebra, interactive = false, } = props;
+    // Validate required props
+    validateArray('Table', 'columns', columns);
+    // Determine if any column is sortable (for buildTableClasses sortable param)
+    const hasSortable = columns.some((col) => col.sortable);
+    // Build CSS classes via Class Builder
+    const tableClasses = buildTableClasses(size, divider, zebra, interactive, hasSortable);
+    // Build thead with th elements
+    const thElements = columns.map((col) => {
+        const thProps = {
+            scope: 'col',
+        };
+        if (col.sortable) {
+            thProps['aria-sort'] = 'none';
+        }
+        if (col.width) {
+            thProps['style'] = `width: ${col.width}`;
+        }
+        return {
+            tag: 'th',
+            props: thProps,
+            children: [col.label],
+        };
+    });
+    const theadRow = {
+        tag: 'tr',
+        props: {},
+        children: thElements,
+    };
+    const thead = {
+        tag: 'thead',
+        props: {},
+        children: [theadRow],
+    };
+    // Build tbody with tr/td elements
+    const bodyRows = (data || []).map((row) => {
+        const cells = columns.map((col) => {
+            const cellValue = row[col.key];
+            const cellText = cellValue != null ? String(cellValue) : '';
+            return {
+                tag: 'td',
+                props: {},
+                children: [cellText],
+            };
+        });
+        return {
+            tag: 'tr',
+            props: {},
+            children: cells,
+        };
+    });
+    const tbody = {
+        tag: 'tbody',
+        props: {},
+        children: bodyRows,
+    };
+    // Build root table element
+    const rootNode = {
+        tag: 'table',
+        props: {
+            className: tableClasses,
+        },
+        children: [thead, tbody],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/otp.ts
+// Framework-agnostic DOM Generator for the OTP Input component.
+/**
+ * Generates a complete OTP Input DOM descriptor tree.
+ *
+ * Produces individual `<input>` cells each accepting a single character,
+ * with maxLength=1. The root container gets CSS classes from `buildOtpInputClasses(state)`.
+ * When disabled, each cell receives `aria-disabled="true"` and `disabled=true`.
+ */
+function generateOtpDOM(props) {
+    const { length, values = [], state, disabled = false, } = props;
+    // Validate length is in range [4, 8]
+    validateRange('OTP', 'length', length, 4, 8);
+    // Build CSS classes via Class Builder
+    const containerClasses = buildOtpInputClasses(state);
+    // Generate individual input cells
+    const cells = [];
+    for (let i = 0; i < length; i++) {
+        const cellId = generateId('ux4g-otp-cell');
+        const cellProps = {
+            className: 'ux4g-otp-cell',
+            id: cellId,
+            type: 'text',
+            maxLength: '1',
+            'aria-label': `Digit ${i + 1}`,
+        };
+        // Set value if provided
+        if (values[i] !== undefined) {
+            cellProps['value'] = values[i];
+        }
+        // Apply disabled state
+        if (disabled) {
+            cellProps['aria-disabled'] = 'true';
+            cellProps['disabled'] = true;
+        }
+        cells.push({
+            tag: 'input',
+            props: cellProps,
+            children: [],
+        });
+    }
+    // Build root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: containerClasses,
+        },
+        children: cells,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/avatar.ts
+// Framework-agnostic DOM Generator for the Avatar (native) component.
+const VALID_SIZES$1 = ['xs', 's', 'm', 'l', 'xl', '2xl', '3xl'];
+const VALID_STATUSES = ['online', 'offline', 'busy', 'away'];
+/**
+ * Generates a complete Avatar DOM descriptor tree.
+ *
+ * Produces a container with avatar classes from buildAvatarClasses(),
+ * an img element with alt text (or fallback initials span),
+ * and an optional status indicator element.
+ */
+function generateAvatarDOM(props) {
+    const { src, alt = '', size, status, fallbackInitials, } = props;
+    // Validate props
+    if (size !== undefined) {
+        validateEnum('Avatar', 'size', size, VALID_SIZES$1);
+    }
+    if (status !== undefined) {
+        validateEnum('Avatar', 'status', status, VALID_STATUSES);
+    }
+    // Use 'status' avatar type when a status prop is provided, otherwise 'profile'
+    const avatarType = status ? 'status' : 'profile';
+    // Build CSS class string from the class builder
+    const className = buildAvatarClasses(avatarType, size);
+    // Build children
+    const children = [];
+    // Add img element or fallback initials
+    if (src) {
+        const imgNode = {
+            tag: 'img',
+            props: {
+                className: 'ux4g-avatar-img',
+                src,
+                alt,
+            },
+            children: [],
+        };
+        children.push(imgNode);
+    }
+    else if (fallbackInitials) {
+        const initialsNode = {
+            tag: 'span',
+            props: {
+                className: 'ux4g-avatar-initials',
+                'aria-label': alt || fallbackInitials,
+            },
+            children: [fallbackInitials],
+        };
+        children.push(initialsNode);
+    }
+    // Add optional status indicator
+    if (status) {
+        const statusNode = {
+            tag: 'span',
+            props: {
+                className: `ux4g-avatar-status-indicator ux4g-avatar-status-${status}`,
+                'aria-label': status,
+            },
+            children: [],
+        };
+        children.push(statusNode);
+    }
+    // Root container element
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className,
+            role: 'img',
+            'aria-label': alt || fallbackInitials || 'Avatar',
+        },
+        children,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/tooltip.ts
+// Framework-agnostic DOM Generator for the Tooltip component.
+/**
+ * Generates a complete Tooltip DOM descriptor tree.
+ *
+ * Produces a tooltip container with `role="tooltip"`, an arrow element,
+ * `data-ux4g-tooltip` on the trigger element, `data-placement` for positioning,
+ * and `aria-describedby` on the trigger referencing the tooltip ID.
+ * Compatible with Runtime_JS MutationObserver-based initialization.
+ */
+function generateTooltipDOM(props) {
+    const { text, placement = 'top-center', size = 's', triggerId, } = props;
+    // Validate required props
+    validateRequired('Tooltip', 'text', text);
+    validateType('Tooltip', 'text', text, 'string');
+    // Generate unique IDs
+    const tooltipId = generateId('ux4g-tooltip');
+    const triggerElId = triggerId || generateId('ux4g-tooltip-trigger');
+    // Build CSS classes via Class Builder
+    const tooltipClassName = buildTooltipClasses(placement, size);
+    // Map placement to the simplified data-placement value expected by Runtime_JS
+    // Runtime_JS expects: top, bottom, left, right
+    let dataPlacement;
+    if (placement.startsWith('top')) {
+        dataPlacement = 'top';
+    }
+    else if (placement.startsWith('bottom')) {
+        dataPlacement = 'bottom';
+    }
+    else if (placement.startsWith('left')) {
+        dataPlacement = 'left';
+    }
+    else {
+        dataPlacement = 'right';
+    }
+    // Build the arrow element
+    const arrowNode = {
+        tag: 'span',
+        props: {
+            className: 'ux4g-tooltip-arrow',
+        },
+        children: [],
+    };
+    // Build the tooltip content element
+    const tooltipNode = {
+        tag: 'div',
+        props: {
+            className: tooltipClassName,
+            id: tooltipId,
+            role: 'tooltip',
+            'data-placement': dataPlacement,
+        },
+        children: [arrowNode, text],
+    };
+    // Build the trigger element with data-ux4g-tooltip and aria-describedby
+    const triggerNode = {
+        tag: 'span',
+        props: {
+            className: 'ux4g-tooltip-trigger',
+            id: triggerElId,
+            'data-ux4g-tooltip': 'true',
+            'aria-describedby': tooltipId,
+            tabIndex: 0,
+        },
+        children: [],
+    };
+    // Build root wrapper containing trigger and tooltip
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-tooltip-wrapper',
+        },
+        children: [triggerNode, tooltipNode],
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/chip.ts
+// Framework-agnostic DOM Generator for the Chip (native) component.
+const VALID_TYPES = ['filter', 'choice', 'input'];
+const VALID_SIZES = ['md', 'sm', 'xs'];
+/**
+ * Generates a complete Chip DOM descriptor tree.
+ *
+ * Produces a chip container with CSS classes from `buildChipClasses()`,
+ * a label span, and an optional dismiss button with `aria-label="Remove {label}"`.
+ */
+function generateChipDOM(props) {
+    const { label, type = 'filter', size = 'md', active = false, dismissible = false, } = props;
+    // Validate required props
+    validateRequired('Chip', 'label', label);
+    validateType('Chip', 'label', label, 'string');
+    if (type !== undefined) {
+        validateEnum('Chip', 'type', type, VALID_TYPES);
+    }
+    if (size !== undefined) {
+        validateEnum('Chip', 'size', size, VALID_SIZES);
+    }
+    // Build CSS class string from the class builder
+    const className = buildChipClasses(type, size, active);
+    // Label span
+    const labelNode = {
+        tag: 'span',
+        props: {
+            className: 'ux4g-chip-label',
+        },
+        children: [label],
+    };
+    // Build children array
+    const children = [labelNode];
+    // Conditional dismiss button
+    if (dismissible) {
+        const dismissButton = {
+            tag: 'button',
+            props: {
+                className: 'ux4g-chip-dismiss',
+                type: 'button',
+                'aria-label': `Remove ${label}`,
+            },
+            children: [],
+        };
+        children.push(dismissButton);
+    }
+    // Root container
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className,
+            role: 'option',
+        },
+        children,
+    };
+    return rootNode;
+}
+
+// ux4g-components-web/src/dom-generators/popover.ts
+// Framework-agnostic DOM Generator for the Popover component.
+const VALID_PLACEMENTS = [
+    'top', 'top-start', 'top-end',
+    'bottom', 'bottom-start', 'bottom-end',
+    'left', 'left-start', 'left-end',
+    'right', 'right-start', 'right-end',
+];
+/**
+ * Generates a complete Popover DOM descriptor tree.
+ *
+ * Produces a trigger wrapper element with `data-ux4g-popover` and
+ * `aria-describedby` referencing the popover content container.
+ * The popover container uses CSS classes from `buildPopoverClasses()`
+ * for placement and visibility. Compatible with Runtime_JS
+ * MutationObserver-based initialization.
+ */
+function generatePopoverDOM(props) {
+    const { placement = 'bottom', show = false, triggerId, } = props;
+    // Validate placement prop if provided explicitly
+    if (props.placement !== undefined) {
+        validateEnum('Popover', 'placement', placement, VALID_PLACEMENTS);
+    }
+    // Generate unique IDs
+    const resolvedTriggerId = triggerId ?? generateId('ux4g-popover-trigger');
+    const popoverId = generateId('ux4g-popover-content');
+    // Build CSS classes via Class Builder
+    const popoverClasses = buildPopoverClasses(placement, show);
+    // Build trigger element
+    const triggerNode = {
+        tag: 'span',
+        props: {
+            className: 'ux4g-popover-trigger',
+            id: resolvedTriggerId,
+            'data-ux4g-popover': 'true',
+            'aria-describedby': popoverId,
+        },
+        children: [],
+    };
+    // Build popover content container
+    const popoverContentNode = {
+        tag: 'div',
+        props: {
+            className: popoverClasses,
+            id: popoverId,
+            role: 'tooltip',
+            'data-placement': placement,
+        },
+        children: [],
+    };
+    // Build root wrapper containing trigger + popover content
+    const rootNode = {
+        tag: 'div',
+        props: {
+            className: 'ux4g-popover-wrapper',
+        },
+        children: [triggerNode, popoverContentNode],
+    };
+    return rootNode;
+}
+
+exports.DOMGeneratorValidationError = DOMGeneratorValidationError;
+exports.generateAccordionDOM = generateAccordionDOM;
+exports.generateAvatarDOM = generateAvatarDOM;
+exports.generateCarouselDOM = generateCarouselDOM;
+exports.generateChipDOM = generateChipDOM;
+exports.generateComboboxDOM = generateComboboxDOM;
+exports.generateDatePickerDOM = generateDatePickerDOM;
+exports.generateDrawerDOM = generateDrawerDOM;
+exports.generateDropdownDOM = generateDropdownDOM;
+exports.generateFileUploadDOM = generateFileUploadDOM;
+exports.generateId = generateId;
+exports.generateModalDOM = generateModalDOM;
+exports.generateOtpDOM = generateOtpDOM;
+exports.generatePopoverDOM = generatePopoverDOM;
+exports.generateProgressDOM = generateProgressDOM;
+exports.generateSearchDOM = generateSearchDOM;
+exports.generateStepperDOM = generateStepperDOM;
+exports.generateTableDOM = generateTableDOM;
+exports.generateTabsDOM = generateTabsDOM;
+exports.generateTimePickerDOM = generateTimePickerDOM;
+exports.generateTooltipDOM = generateTooltipDOM;
+exports.resetIdCounter = resetIdCounter;
+exports.validateArray = validateArray;
+exports.validateEnum = validateEnum;
+exports.validateRange = validateRange;
+exports.validateRequired = validateRequired;
+exports.validateType = validateType;