ux4g-components-web 1.4.1 → 1.5.0

package/dist/dom-generators/modal.d.ts

@@ -0,0 +1,21 @@
+import { NodeDescriptor } from './types';
+import { ModalSize, ModalOpacity } from '../types.js';
+export interface ModalGeneratorProps {
+    open?: boolean;
+    size?: ModalSize;
+    title?: string;
+    closable?: boolean;
+    backdropOpacity?: ModalOpacity;
+    backdropBlur?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function generateModalDOM(props: ModalGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/otp.d.ts

@@ -0,0 +1,18 @@
+import { NodeDescriptor } from './types';
+import { OtpInputState } from '../types.js';
+export interface OtpGeneratorProps {
+    length: number;
+    values?: string[];
+    state?: OtpInputState;
+    disabled?: boolean;
+}
+/**
+ * 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`.
+ */
+export declare function generateOtpDOM(props: OtpGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/popover.d.ts

@@ -0,0 +1,19 @@
+import { NodeDescriptor } from './types';
+import { PopoverPlacement } from '../types.js';
+export interface PopoverGeneratorProps {
+    placement?: PopoverPlacement;
+    show?: boolean;
+    triggerId?: string;
+}
+/**
+ * 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.
+ */
+export declare function generatePopoverDOM(props: PopoverGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/progress.d.ts

@@ -0,0 +1,18 @@
+import { NodeDescriptor } from './types';
+import { ProgressIndicatorType, ProgressIndicatorSize } from '../types.js';
+export interface ProgressGeneratorProps {
+    value: number;
+    type?: ProgressIndicatorType;
+    size?: ProgressIndicatorSize;
+    label?: string;
+}
+/**
+ * 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.
+ */
+export declare function generateProgressDOM(props: ProgressGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/search.d.ts

@@ -0,0 +1,22 @@
+import { NodeDescriptor } from './types';
+import { SearchSize } from '../types.js';
+export interface SearchGeneratorProps {
+    value?: string;
+    placeholder?: string;
+    suggestions?: Array<{
+        label: string;
+        value: string;
+    }>;
+    showSuggestions?: boolean;
+    size?: SearchSize;
+}
+/**
+ * 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.
+ */
+export declare function generateSearchDOM(props: SearchGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/stepper.d.ts

@@ -0,0 +1,23 @@
+import { NodeDescriptor } from './types';
+import { StepperOrientation, StepperVariant, StepperSize } from '../types.js';
+export interface StepperGeneratorProps {
+    steps: Array<{
+        label: string;
+        description?: string;
+    }>;
+    activeStep: number;
+    orientation?: StepperOrientation;
+    variant?: StepperVariant;
+    size?: StepperSize;
+}
+/**
+ * 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.
+ */
+export declare function generateStepperDOM(props: StepperGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/table.d.ts

@@ -0,0 +1,25 @@
+import { NodeDescriptor } from './types';
+import { TableSize, TableDivider, TableZebra } from '../types.js';
+export interface TableGeneratorProps {
+    columns: Array<{
+        key: string;
+        label: string;
+        sortable?: boolean;
+        width?: string;
+    }>;
+    data: Array<Record<string, unknown>>;
+    size?: TableSize;
+    divider?: TableDivider;
+    zebra?: TableZebra;
+    interactive?: boolean;
+}
+/**
+ * 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>`.
+ */
+export declare function generateTableDOM(props: TableGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/tabs.d.ts

@@ -0,0 +1,23 @@
+import { NodeDescriptor } from './types';
+import { TabVariant, TabSize } from '../types.js';
+export interface TabsGeneratorProps {
+    tabs: Array<{
+        label: string;
+        content: string;
+        disabled?: boolean;
+    }>;
+    activeIndex?: number;
+    variant?: TabVariant;
+    size?: TabSize;
+    vertical?: boolean;
+}
+/**
+ * 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`.
+ */
+export declare function generateTabsDOM(props: TabsGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/time-picker.d.ts

@@ -0,0 +1,19 @@
+import { NodeDescriptor } from './types';
+export interface TimePickerGeneratorProps {
+    value?: string;
+    min?: string;
+    max?: string;
+    step?: number;
+    format?: '12h' | '24h';
+}
+/**
+ * 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')`.
+ */
+export declare function generateTimePickerDOM(props: TimePickerGeneratorProps): NodeDescriptor;
+

package/dist/dom-generators/tooltip.d.ts

@@ -0,0 +1,19 @@
+import { NodeDescriptor } from './types';
+import { TooltipPlacement, TooltipSize } from '../types.js';
+export interface TooltipGeneratorProps {
+    text: string;
+    placement?: TooltipPlacement;
+    size?: TooltipSize;
+    triggerId?: string;
+}
+/**
+ * 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.
+ */
+export declare function generateTooltipDOM(props: TooltipGeneratorProps): NodeDescriptor;
+
+

package/dist/dom-generators/types.d.ts

@@ -0,0 +1,155 @@
+export type ButtonVariant = 'primary' | 'outline-primary' | 'text-primary' | 'tonal-primary' | 'danger' | 'outline-danger' | 'text-danger' | 'tonal-danger' | 'outline-neutral' | 'text-neutral';
+export type ButtonSize = 'xl' | 'lg' | 'md' | 'sm' | 'xs';
+export type ButtonShape = 'rectangle' | 'pill';
+export declare const VARIANT_CLASS_MAP: Record<ButtonVariant, string>;
+export declare const SIZE_CLASS_MAP: Record<ButtonSize, string | null>;
+export declare function buildButtonClasses(variant: ButtonVariant, size: ButtonSize, disabled: boolean, loading: boolean, shape?: ButtonShape, extra?: string): string;
+export type SpinnerVariant = 'primary' | 'inverse' | 'danger';
+export type SpinnerSize = 'xl' | 'lg' | 'md' | 'sm' | 'xs';
+export type SpinnerType = 'full' | 'split' | 'partial';
+export declare const SPINNER_VARIANT_CLASS_PART: Record<SpinnerVariant, string>;
+export declare const SPINNER_SIZE_CLASS_PART: Record<SpinnerSize, string>;
+export declare const SPINNER_TYPE_CLASS_PART: Record<SpinnerType, string>;
+/** Returns the CSS class(es) for a spinner.
+ *  Base class: `ux4g-spinner-{variant}-{type}` (always present)
+ *  Size class:  `ux4g-spinner-{size}` (omitted when size is 'md' — the default)
+ *  e.g. `ux4g-spinner-primary-full` (md default)
+ *       `ux4g-spinner-primary-full ux4g-spinner-xl` (xl size)
+ */
+export declare function buildSpinnerClasses(variant: SpinnerVariant, size: SpinnerSize, type: SpinnerType, extra?: string): string;
+export type LinkVariant = 'default' | 'neutral';
+export type LinkSize = 'sm' | 'md';
+export declare function buildLinkClasses(variant: LinkVariant, size: LinkSize, extra?: string): string;
+export type BadgeType = 'dot' | 'icon' | 'digit';
+export type BadgeColor = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'secondary' | 'tertiary' | 'neutral';
+export type BadgeSize = 's' | 'm' | 'l' | 'profile-l' | 'profile-xl' | 'profile-2xl' | 'profile-3xl';
+export declare function buildBadgeClasses(type: BadgeType, color: BadgeColor, size?: BadgeSize, extra?: string): string;
+export type AvatarType = 'status' | 'profile' | 'group';
+export type AvatarSize = 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl';
+export declare function buildAvatarClasses(avatarType: AvatarType, size?: AvatarSize, extra?: string): string;
+export type ImageRatio = '1-1' | '4-3' | '3-2' | '16-10' | '16-9' | '2-1' | '5-2' | '3-1' | '1-16' | '2-3' | '3-4';
+export type ImageOverlayPosition = 'bottom' | 'top';
+export declare function buildImageContainerClasses(ratio?: ImageRatio, rounded?: boolean, overlay?: boolean, extra?: string): string;
+export type ChipType = 'filter' | 'choice' | 'input';
+export type ChipSize = 'md' | 'sm' | 'xs';
+export declare function buildChipClasses(chipType: ChipType, size: ChipSize, active?: boolean, extra?: string): string;
+export type TagVariant = 'tonal' | 'filled' | 'outline' | 'text';
+export type TagColor = 'neutral' | 'brand' | 'success' | 'warning' | 'error' | 'info';
+export declare function buildTagClasses(variant: TagVariant, color: TagColor, small?: boolean, extra?: string): string;
+export type DividerOrientation = 'horizontal' | 'vertical';
+export declare function buildDividerClasses(orientation: DividerOrientation, extra?: string): string;
+export type BreadcrumbSeparator = 'divider' | 'icon';
+export declare function buildBreadcrumbClasses(separator: BreadcrumbSeparator, extra?: string): string;
+export type CheckboxSize = 'sm' | 'md' | 'lg';
+export declare function buildCheckboxClasses(size: CheckboxSize, error?: boolean, extra?: string): string;
+export type RadioSize = 'sm' | 'md' | 'lg';
+export declare function buildRadioClasses(size: RadioSize, error?: boolean, extra?: string): string;
+export type SwitchSize = 'sm' | 'md' | 'lg';
+export declare function buildSwitchClasses(size: SwitchSize, extra?: string): string;
+export type CardVariant = 'solid' | 'outline' | 'no-fill';
+export type CardLayout = 'vertical' | 'horizontal';
+export declare function buildCardClasses(variant: CardVariant, layout: CardLayout, extra?: string): string;
+export type InputSize = 'sm' | 'md' | 'lg' | 'xl';
+export type InputState = 'default' | 'error' | 'success' | 'warning';
+export declare function buildInputContainerClasses(size: InputSize, state: InputState, extra?: string): string;
+export type ListVariant = 'default' | 'error' | 'success' | 'warning';
+export type ListSize = 's' | 'm' | 'l' | 'xl';
+export declare function buildListClasses(variant: ListVariant, size: ListSize, extra?: string): string;
+export type DropdownType = 'selection' | 'button' | 'overflow';
+export type DropdownMode = 'single' | 'multi';
+export type DropdownSize = 'sm' | 'md' | 'lg';
+export type DropdownState = 'default' | 'error' | 'success' | 'warning';
+export declare function buildDropdownClasses(type: DropdownType, mode: DropdownMode, size: DropdownSize, state: DropdownState, open?: boolean, extra?: string): string;
+export type ComboboxType = 'single' | 'multi';
+export type ComboboxSize = 'sm' | 'md' | 'lg';
+export type ComboboxState = 'default' | 'error' | 'success' | 'warning';
+export declare function buildComboboxClasses(type: ComboboxType, size: ComboboxSize, state: ComboboxState, open?: boolean, extra?: string): string;
+export type ModalSize = 's' | 'm' | 'l';
+export type ModalOpacity = '25' | '50' | '75';
+export declare function buildModalBackdropClasses(opacity: ModalOpacity, blur?: boolean, open?: boolean, extra?: string): string;
+export declare function buildModalBoxClasses(size: ModalSize, centerContent?: boolean, extra?: string): string;
+export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
+export type AlertLayout = 'fluid' | 'center' | 'wide';
+export type AlertPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export declare function buildAlertClasses(variant: AlertVariant, layout?: AlertLayout, extra?: string): string;
+export declare function buildContextAlertClasses(variant: AlertVariant, extra?: string): string;
+export declare function buildAlertContainerClasses(position: AlertPosition, extra?: string): string;
+export type SearchSize = 's' | 'm' | 'lg';
+export declare function buildSearchContainerClasses(size: SearchSize, extra?: string): string;
+export type PaginationVariant = 'default' | 'dotted';
+export type PaginationStyle = 'default' | 'solid' | 'translucent';
+export declare function buildPaginationClasses(variant: PaginationVariant, paginationStyle?: PaginationStyle, extra?: string): string;
+export type TableSize = 's' | 'm' | 'lg';
+export type TableDivider = 'row' | 'column' | 'none';
+export type TableZebra = 'none' | 'rows' | 'cols';
+export declare function buildTableClasses(size: TableSize, divider?: TableDivider, zebra?: TableZebra, interactive?: boolean, sortable?: boolean, resizable?: boolean, headerBrand?: boolean, extra?: string): string;
+export type PopoverPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+export declare function buildPopoverClasses(placement: PopoverPlacement, show?: boolean, extra?: string): string;
+export type TooltipPlacement = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'left-center' | 'right-center';
+export type TooltipSize = 's' | 'xs';
+export declare function buildTooltipClasses(placement: TooltipPlacement, size: TooltipSize, extra?: string): string;
+export type TabVariant = 'underline' | 'pill';
+export type TabSize = 'sm' | 'md' | 'lg';
+export declare function buildTabClasses(variant: TabVariant, size: TabSize, vertical?: boolean, extra?: string): string;
+export type IconButtonVariant = 'primary' | 'outline-primary' | 'tonal-primary' | 'text-primary';
+export type IconButtonSize = 'xl' | 'lg' | 'md' | 'sm' | 'xs';
+export declare function buildIconButtonClasses(variant: IconButtonVariant, size: IconButtonSize, pill?: boolean, extra?: string): string;
+export declare function buildAccessibilityBarClasses(extra?: string): string;
+export type AccordionArrowPosition = 'right' | 'left';
+export type AccordionVariant = 'default' | 'bordered';
+export declare function buildAccordionClasses(arrowPosition?: AccordionArrowPosition, variant?: AccordionVariant, extra?: string): string;
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperAlignment = 'default' | 'center' | 'left';
+export type StepperVariant = 'default' | 'bottom-line' | 'bottom-line-fill' | 'mobile' | 'progress';
+export type StepperSize = 'default' | 's';
+export declare function buildStepperClasses(orientation?: StepperOrientation, alignment?: StepperAlignment, variant?: StepperVariant, size?: StepperSize, extra?: string): string;
+export type SliderSize = 'sm' | 'md';
+export declare function buildSliderFieldClasses(size?: SliderSize, extra?: string): string;
+export type DrawerPlacement = 'right' | 'left' | 'top' | 'bottom';
+export declare function buildDrawerClasses(placement: DrawerPlacement, open?: boolean, extra?: string): string;
+export type DateTimePickerMode = 'date' | 'time';
+export declare function buildDateTimePickerClasses(mode: DateTimePickerMode, extra?: string): string;
+export type StatusPipelineOrientation = 'horizontal' | 'vertical';
+export type StatusPipelineAlignment = 'default' | 'center' | 'left';
+export type StatusPipelineVariant = 'default' | 'bottom-line' | 'bottom-line-fill' | 'mobile' | 'progress';
+export type StatusPipelineSize = 'default' | 's';
+export declare function buildStatusPipelineClasses(orientation?: StatusPipelineOrientation, alignment?: StatusPipelineAlignment, variant?: StatusPipelineVariant, size?: StatusPipelineSize, extra?: string): string;
+export type JourneyTimelineOrientation = 'vertical' | 'horizontal';
+export declare function buildJourneyTimelineClasses(orientation?: JourneyTimelineOrientation, extra?: string): string;
+export declare function buildFormFieldGroupClasses(extra?: string): string;
+export type OtpInputState = 'default' | 'success' | 'error' | 'locked';
+export declare function buildOtpInputClasses(state?: OtpInputState, extra?: string): string;
+export type FileUploadState = 'default' | 'default-vle' | 'selecting' | 'scanning' | 'uploaded' | 'uploaded-vle' | 'error';
+export declare function buildFileUploadClasses(state?: FileUploadState, extra?: string): string;
+export type ProgressIndicatorType = 'bar' | 'circle';
+export type ProgressIndicatorSize = 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl';
+export declare function buildProgressIndicatorClasses(type: ProgressIndicatorType, extra?: string): string;
+export declare function buildFeedbackClasses(extra?: string): string;
+export type DraftStatusBannerVariant = 'default' | 'auto' | 'success';
+export declare function buildDraftStatusBannerClasses(variant?: DraftStatusBannerVariant, extra?: string): string;
+export type SlaProgressIndicatorType = 'circle' | 'linear' | 'badge';
+export declare function buildSlaProgressIndicatorClasses(type: SlaProgressIndicatorType, extra?: string): string;
+export declare function buildCarouselClasses(extra?: string): string;
+export declare function buildEmptyStateClasses(extra?: string): string;
+export type ChipGroupVariant = 'filter' | 'choice';
+export declare function buildChipGroupClasses(variant?: ChipGroupVariant, active?: boolean, extra?: string): string;
+export declare function buildNavbarClasses(extra?: string): string;
+export type SocialLinksSize = 'sm' | 'md' | 'lg';
+export declare function buildSocialLinksClasses(size?: SocialLinksSize, extra?: string): string;
+export type SlotGridVariant = 'weekly' | 'compact';
+export declare function buildSlotGridClasses(variant?: SlotGridVariant, extra?: string): string;
+export type FooterTheme = 'default' | 'primary' | 'dark';
+export declare function buildFooterClasses(theme?: FooterTheme, extra?: string): string;
+export type ResultListRowVariation = 'default' | 'v1' | 'v2' | 'v3' | 'v4' | 'v5';
+export declare function buildResultListRowClasses(variation?: ResultListRowVariation, extra?: string): string;
+/** Returns the CSS class string for the mega-menu root element.
+ *  Base class: `ux4g-mega-menu` (always present)
+ *  Dropdown:   `ux4g-mega-menu--dropdown` (when dropdown is true)
+ *  Right:      `ux4g-mega-menu--dropdown-right` (only when BOTH dropdown AND dropdownRight are true)
+ */
+export declare function buildMegaMenuClasses(dropdown?: boolean, dropdownRight?: boolean, extra?: string): string;
+/** Returns the CSS class string for the mega-menu wrapper element (dropdown positioning context).
+ *  Base class: `ux4g-mega-menu-wrapper` (always present)
+ *  Active:     `ux4g-mega-menu-wrapper--active` (when active is true)
+ */
+export declare function buildMegaMenuWrapperClasses(active?: boolean, extra?: string): string;

package/dist/dom-generators/validate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Throws if the value is null or undefined.
+ */
+export declare function validateRequired(componentName: string, propName: string, value: unknown): void;
+/**
+ * Throws if typeof value does not match the expected type string.
+ */
+export declare function validateType(componentName: string, propName: string, value: unknown, expectedType: string): void;
+/**
+ * Throws if the value is not a member of the allowed values set.
+ */
+export declare function validateEnum(componentName: string, propName: string, value: unknown, allowedValues: readonly unknown[]): void;
+/**
+ * Throws if the numeric value is outside the given [min, max] range (inclusive).
+ */
+export declare function validateRange(componentName: string, propName: string, value: unknown, min: number, max: number): void;
+/**
+ * Throws if the value is not an array.
+ */
+export declare function validateArray(componentName: string, propName: string, value: unknown): void;

package/dist/runtime/bootstrap.js

@@ -0,0 +1,59 @@
+/**
+ * UX4G Runtime Auto-Bootstrap
+ *
+ * Side-effect-only module that triggers runtime initialization on import.
+ * Framework packages use this as:
+ *   import 'ux4g-components-web/runtime/bootstrap';
+ *
+ * Safe to import multiple times — initRuntime() uses a singleton guard
+ * (window.__UX4G_RUNTIME_INITIALIZED__) to ensure initialization happens
+ * exactly once.
+ *
+ * Also sets up a MutationObserver that automatically re-runs ux4g.init()
+ * when new elements are added to the DOM. This handles frameworks like
+ * React and Angular that render components AFTER DOMContentLoaded.
+ */
+import { initRuntime } from './index.js';
+initRuntime();
+// Auto-reinit: watch for new DOM elements and re-run ux4g.init()
+// This fixes the timing issue where Angular/React render after DOMContentLoaded
+if (typeof window !== 'undefined' && typeof MutationObserver !== 'undefined') {
+    let reinitTimer = null;
+    const observer = new MutationObserver((mutations) => {
+        // Check if any added nodes contain UX4G-relevant elements
+        let hasNewElements = false;
+        for (const mutation of mutations) {
+            if (mutation.addedNodes.length > 0) {
+                hasNewElements = true;
+                break;
+            }
+        }
+        if (!hasNewElements)
+            return;
+        // Debounce: wait 50ms after the last mutation before re-initializing
+        // This batches rapid DOM changes (e.g., Angular rendering a full template)
+        if (reinitTimer)
+            clearTimeout(reinitTimer);
+        reinitTimer = setTimeout(() => {
+            if (window.ux4g?.init) {
+                window.ux4g.init(document);
+            }
+        }, 50);
+    });
+    // Start observing once the body is available
+    const startObserving = () => {
+        if (document.body) {
+            observer.observe(document.body, { childList: true, subtree: true });
+        }
+        else {
+            // Body not ready yet — wait for it
+            setTimeout(startObserving, 10);
+        }
+    };
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', startObserving);
+    }
+    else {
+        startObserving();
+    }
+}

package/dist/runtime/index.js

@@ -0,0 +1,55 @@
+/**
+ * UX4G Runtime Module
+ *
+ * Injects the vendor JS (ux4g.js + ux4g-custom.js) into the page as inline scripts.
+ * These files handle all interactive behaviors: dropdowns, modals, tooltips,
+ * accordions, carousels, drawers, tabs, popovers, toasts, scrollspy, etc.
+ *
+ * The vendor JS is inlined at build time by the Rollup virtual plugin.
+ * At runtime, initRuntime() creates <script> elements with the inlined code.
+ *
+ * Uses a singleton guard (window.__UX4G_RUNTIME_INITIALIZED__) to ensure
+ * the scripts are injected exactly once.
+ */
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+/**
+ * Initialize the UX4G runtime by injecting the vendor JS scripts into the page.
+ *
+ * - Safe for SSR — no-ops when window/document are unavailable.
+ * - Singleton guard prevents double-injection.
+ * - The vendor JS handles its own DOMContentLoaded timing internally.
+ * - MutationObserver in the vendor JS auto-initializes dynamically added elements.
+ */
+export function initRuntime() {
+    if (!isBrowser)
+        return;
+    if (window.__UX4G_RUNTIME_INITIALIZED__)
+        return;
+    window.__UX4G_RUNTIME_INITIALIZED__ = true;
+    // Inject ux4g.js (sets up window.ux4g with all core components)
+    const script1 = document.createElement('script');
+    script1.setAttribute('data-ux4g-runtime', 'main');
+    script1.textContent = __UX4G_VENDOR_MAIN__;
+    document.head.appendChild(script1);
+    // Inject ux4g-custom.js (extends window.ux4g with custom behaviors)
+    const script2 = document.createElement('script');
+    script2.setAttribute('data-ux4g-runtime', 'custom');
+    script2.textContent = __UX4G_VENDOR_CUSTOM__;
+    document.head.appendChild(script2);
+}
+/**
+ * Destroy the UX4G runtime.
+ * Removes injected scripts and resets the singleton guard.
+ */
+export function destroyRuntime() {
+    if (!isBrowser)
+        return;
+    // Remove injected scripts
+    document.querySelectorAll('script[data-ux4g-runtime]').forEach(el => el.remove());
+    // Reset singleton guard
+    window.__UX4G_RUNTIME_INITIALIZED__ = undefined;
+    // Clear the global ux4g object
+    if (window.ux4g) {
+        delete window.ux4g;
+    }
+}