ux4g-components-web 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,75 @@
+# ux4g-components-web
+
+The CSS system, design tokens, utilities, and shared Class_Builder types for the UX4G Design System.
+
+## Installation
+
+```bash
+npm install ux4g-components-web
+```
+
+## Usage
+
+### CSS Bundle
+
+Import the full CSS bundle in your application entry point:
+
+```ts
+// JavaScript/TypeScript
+import 'ux4g-components-web/styles.css';
+```
+
+```html
+<!-- HTML -->
+<link rel="stylesheet" href="node_modules/ux4g-components-web/styles/ux4g.css" />
+```
+
+```css
+/* CSS */
+@import 'ux4g-components-web/styles.css';
+```
+
+The bundle includes:
+- Design tokens (CSS custom properties)
+- Semantic layer (semantic aliases)
+- All 27 utility modules
+- Approved component CSS
+- Layout utilities
+- Cascade fixes
+
+### Shared Types (Class_Builders)
+
+Framework wrapper packages import Class_Builder functions from this package:
+
+```ts
+import { buildButtonClasses, ButtonVariant, ButtonSize } from 'ux4g-components-web/types';
+
+const classes = buildButtonClasses('primary', 'md', false, false);
+// → "ux4g-btn-primary ux4g-btn-md"
+```
+
+### Utility Classes
+
+Use utility classes directly in HTML — no wrapper component needed:
+
+```html
+<div class="ux4g-d-flex ux4g-gap-4 ux4g-p-m ux4g-bg-primary-soft ux4g-radius-md">
+  <span class="ux4g-body-m-default ux4g-text-neutral-primary">Content</span>
+</div>
+```
+
+## What's Included
+
+| Export | Description |
+|--------|-------------|
+| `ux4g-components-web/styles.css` | Pre-built CSS bundle (~7MB, fonts embedded as base64) |
+| `ux4g-components-web/types` | Class_Builder functions and TypeScript types |
+
+## Related Packages
+
+- [`ux4g-components-react`](https://www.npmjs.com/package/ux4g-components-react) — React wrapper components
+- [`ux4g-components-angular`](https://www.npmjs.com/package/ux4g-components-angular) — Angular wrapper components
+
+## License
+
+MIT

package/dist/runtime/bootstrap.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var index = require('./index');
+
+/**
+ * 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.
+ */
+index.initRuntime();

package/dist/runtime/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/bootstrap.mjs

@@ -0,0 +1,14 @@
+import { initRuntime } from './index';
+
+/**
+ * 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.
+ */
+initRuntime();

package/dist/runtime/index.cjs

@@ -0,0 +1,300 @@
+'use strict';
+
+/**
+ * UX4G Runtime Module
+ *
+ * Framework-agnostic runtime that encapsulates all interactive behaviors
+ * previously delivered via CDN scripts (ux4g.js, ux4g-custom.js).
+ *
+ * Behaviors: dropdown toggling, modal management, tooltip positioning,
+ * accordion expand/collapse, carousel sliding, drawer open/close.
+ *
+ * Uses a singleton guard (window.__UX4G_RUNTIME_INITIALIZED__) to ensure
+ * initialization happens exactly once, even when multiple components import
+ * the bootstrap module.
+ */
+/** Registry of all active event listeners for cleanup */
+let activeListeners = [];
+/** Registry of active MutationObservers for cleanup */
+let activeObservers = [];
+// ─── Helper: register a listener for later cleanup ───────────────────────────
+function addListener(target, event, handler) {
+    target.addEventListener(event, handler);
+    activeListeners.push({ target, event, handler });
+}
+// ─── Dropdown Toggling ───────────────────────────────────────────────────────
+function initDropdowns() {
+    const handler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-dropdown-toggle]');
+        if (trigger) {
+            e.preventDefault();
+            const dropdown = trigger.closest('.ux4g-dropdown');
+            if (dropdown) {
+                const isOpen = dropdown.classList.contains('is-open');
+                // Close all other open dropdowns
+                document.querySelectorAll('.ux4g-dropdown.is-open').forEach((el) => {
+                    if (el !== dropdown)
+                        el.classList.remove('is-open');
+                });
+                dropdown.classList.toggle('is-open', !isOpen);
+            }
+            return;
+        }
+        // Close dropdowns when clicking outside
+        if (!target.closest('.ux4g-dropdown')) {
+            document.querySelectorAll('.ux4g-dropdown.is-open').forEach((el) => {
+                el.classList.remove('is-open');
+            });
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Modal Management ────────────────────────────────────────────────────────
+function initModals() {
+    const openHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-modal-open]');
+        if (trigger) {
+            e.preventDefault();
+            const modalId = trigger.getAttribute('data-ux4g-modal-open');
+            if (modalId) {
+                const backdrop = document.getElementById(modalId);
+                if (backdrop) {
+                    backdrop.classList.add('is-open');
+                    document.body.style.overflow = 'hidden';
+                }
+            }
+        }
+    };
+    const closeHandler = (e) => {
+        const target = e.target;
+        // Close button inside modal
+        const closeBtn = target.closest('[data-ux4g-modal-close]');
+        if (closeBtn) {
+            e.preventDefault();
+            const backdrop = closeBtn.closest('.ux4g-modal-backdrop');
+            if (backdrop) {
+                backdrop.classList.remove('is-open');
+                document.body.style.overflow = '';
+            }
+            return;
+        }
+        // Click on backdrop (outside modal box) closes modal
+        if (target.classList.contains('ux4g-modal-backdrop') && target.classList.contains('is-open')) {
+            target.classList.remove('is-open');
+            document.body.style.overflow = '';
+        }
+    };
+    const keyHandler = (e) => {
+        if (e.key === 'Escape') {
+            const openModal = document.querySelector('.ux4g-modal-backdrop.is-open');
+            if (openModal) {
+                openModal.classList.remove('is-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    addListener(document, 'click', openHandler);
+    addListener(document, 'click', closeHandler);
+    addListener(document, 'keydown', keyHandler);
+}
+// ─── Tooltip Positioning ─────────────────────────────────────────────────────
+function initTooltips() {
+    const showHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-tooltip]');
+        if (trigger) {
+            const tooltipId = trigger.getAttribute('data-ux4g-tooltip');
+            if (tooltipId) {
+                const tooltip = document.getElementById(tooltipId);
+                if (tooltip) {
+                    tooltip.classList.add('show');
+                }
+            }
+        }
+    };
+    const hideHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-tooltip]');
+        if (trigger) {
+            const tooltipId = trigger.getAttribute('data-ux4g-tooltip');
+            if (tooltipId) {
+                const tooltip = document.getElementById(tooltipId);
+                if (tooltip) {
+                    tooltip.classList.remove('show');
+                }
+            }
+        }
+    };
+    addListener(document, 'mouseenter', showHandler);
+    addListener(document, 'mouseleave', hideHandler);
+    addListener(document, 'focusin', showHandler);
+    addListener(document, 'focusout', hideHandler);
+}
+// ─── Accordion Expand/Collapse ───────────────────────────────────────────────
+function initAccordions() {
+    const handler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-accordion-toggle]');
+        if (trigger) {
+            e.preventDefault();
+            const item = trigger.closest('.ux4g-accordion-item');
+            if (item) {
+                const isExpanded = item.classList.contains('is-expanded');
+                item.classList.toggle('is-expanded', !isExpanded);
+                // Update aria-expanded attribute
+                trigger.setAttribute('aria-expanded', String(!isExpanded));
+                // Toggle the panel visibility
+                const panel = item.querySelector('.ux4g-accordion-panel');
+                if (panel) {
+                    panel.style.display = isExpanded ? 'none' : '';
+                }
+            }
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Carousel Sliding ────────────────────────────────────────────────────────
+function initCarousels() {
+    const handler = (e) => {
+        const target = e.target;
+        // Next button
+        const nextBtn = target.closest('[data-ux4g-carousel-next]');
+        if (nextBtn) {
+            e.preventDefault();
+            const carousel = nextBtn.closest('.ux4g-carousel');
+            if (carousel) {
+                const items = carousel.querySelectorAll('.ux4g-carousel-item');
+                const activeItem = carousel.querySelector('.ux4g-carousel-item.active');
+                if (activeItem && items.length > 0) {
+                    const currentIndex = Array.from(items).indexOf(activeItem);
+                    const nextIndex = (currentIndex + 1) % items.length;
+                    activeItem.classList.remove('active');
+                    items[nextIndex].classList.add('active');
+                }
+            }
+            return;
+        }
+        // Previous button
+        const prevBtn = target.closest('[data-ux4g-carousel-prev]');
+        if (prevBtn) {
+            e.preventDefault();
+            const carousel = prevBtn.closest('.ux4g-carousel');
+            if (carousel) {
+                const items = carousel.querySelectorAll('.ux4g-carousel-item');
+                const activeItem = carousel.querySelector('.ux4g-carousel-item.active');
+                if (activeItem && items.length > 0) {
+                    const currentIndex = Array.from(items).indexOf(activeItem);
+                    const prevIndex = (currentIndex - 1 + items.length) % items.length;
+                    activeItem.classList.remove('active');
+                    items[prevIndex].classList.add('active');
+                }
+            }
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Drawer Open/Close ───────────────────────────────────────────────────────
+function initDrawers() {
+    const openHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-drawer-open]');
+        if (trigger) {
+            e.preventDefault();
+            const drawerId = trigger.getAttribute('data-ux4g-drawer-open');
+            if (drawerId) {
+                const drawer = document.getElementById(drawerId);
+                if (drawer) {
+                    drawer.classList.add('ux4g-drawer-open');
+                    document.body.style.overflow = 'hidden';
+                }
+            }
+        }
+    };
+    const closeHandler = (e) => {
+        const target = e.target;
+        const closeBtn = target.closest('[data-ux4g-drawer-close]');
+        if (closeBtn) {
+            e.preventDefault();
+            const drawer = closeBtn.closest('.ux4g-drawer');
+            if (drawer) {
+                drawer.classList.remove('ux4g-drawer-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    const keyHandler = (e) => {
+        if (e.key === 'Escape') {
+            const openDrawer = document.querySelector('.ux4g-drawer.ux4g-drawer-open');
+            if (openDrawer) {
+                openDrawer.classList.remove('ux4g-drawer-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    addListener(document, 'click', openHandler);
+    addListener(document, 'click', closeHandler);
+    addListener(document, 'keydown', keyHandler);
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Initialize the UX4G runtime.
+ *
+ * Encapsulates all interactive behaviors from the CDN scripts (ux4g.js, ux4g-custom.js):
+ * - Dropdown toggling
+ * - Modal management (open/close/escape/backdrop click)
+ * - Tooltip positioning (show/hide on hover/focus)
+ * - Accordion expand/collapse
+ * - Carousel sliding (next/prev)
+ * - Drawer open/close
+ *
+ * Uses a singleton guard to ensure initialization happens exactly once.
+ * Safe for SSR — no-ops when window/document are unavailable.
+ */
+function initRuntime() {
+    // Guard against non-browser environments (SSR/Node.js)
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return;
+    }
+    // Singleton guard: prevent duplicate initialization
+    if (window.__UX4G_RUNTIME_INITIALIZED__) {
+        return;
+    }
+    // Initialize all interactive behaviors
+    initDropdowns();
+    initModals();
+    initTooltips();
+    initAccordions();
+    initCarousels();
+    initDrawers();
+    // Mark as initialized
+    window.__UX4G_RUNTIME_INITIALIZED__ = true;
+}
+/**
+ * Destroy the UX4G runtime.
+ *
+ * Resets the singleton guard and removes all event listeners.
+ * Useful for testing and SSR cleanup.
+ */
+function destroyRuntime() {
+    // Guard against non-browser environments
+    if (typeof window === 'undefined') {
+        return;
+    }
+    // Remove all registered event listeners
+    for (const { target, event, handler } of activeListeners) {
+        target.removeEventListener(event, handler);
+    }
+    activeListeners = [];
+    // Disconnect all observers
+    for (const observer of activeObservers) {
+        observer.disconnect();
+    }
+    activeObservers = [];
+    // Reset the singleton guard
+    window.__UX4G_RUNTIME_INITIALIZED__ = undefined;
+}
+
+exports.destroyRuntime = destroyRuntime;
+exports.initRuntime = initRuntime;

package/dist/runtime/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * UX4G Runtime Module
+ *
+ * Framework-agnostic runtime that encapsulates all interactive behaviors
+ * previously delivered via CDN scripts (ux4g.js, ux4g-custom.js).
+ *
+ * Behaviors: dropdown toggling, modal management, tooltip positioning,
+ * accordion expand/collapse, carousel sliding, drawer open/close.
+ *
+ * Uses a singleton guard (window.__UX4G_RUNTIME_INITIALIZED__) to ensure
+ * initialization happens exactly once, even when multiple components import
+ * the bootstrap module.
+ */
+declare global {
+    interface Window {
+        __UX4G_RUNTIME_INITIALIZED__?: boolean;
+    }
+}
+/**
+ * Initialize the UX4G runtime.
+ *
+ * Encapsulates all interactive behaviors from the CDN scripts (ux4g.js, ux4g-custom.js):
+ * - Dropdown toggling
+ * - Modal management (open/close/escape/backdrop click)
+ * - Tooltip positioning (show/hide on hover/focus)
+ * - Accordion expand/collapse
+ * - Carousel sliding (next/prev)
+ * - Drawer open/close
+ *
+ * Uses a singleton guard to ensure initialization happens exactly once.
+ * Safe for SSR — no-ops when window/document are unavailable.
+ */
+export declare function initRuntime(): void;
+/**
+ * Destroy the UX4G runtime.
+ *
+ * Resets the singleton guard and removes all event listeners.
+ * Useful for testing and SSR cleanup.
+ */
+export declare function destroyRuntime(): void;

package/dist/runtime/index.mjs

@@ -0,0 +1,297 @@
+/**
+ * UX4G Runtime Module
+ *
+ * Framework-agnostic runtime that encapsulates all interactive behaviors
+ * previously delivered via CDN scripts (ux4g.js, ux4g-custom.js).
+ *
+ * Behaviors: dropdown toggling, modal management, tooltip positioning,
+ * accordion expand/collapse, carousel sliding, drawer open/close.
+ *
+ * Uses a singleton guard (window.__UX4G_RUNTIME_INITIALIZED__) to ensure
+ * initialization happens exactly once, even when multiple components import
+ * the bootstrap module.
+ */
+/** Registry of all active event listeners for cleanup */
+let activeListeners = [];
+/** Registry of active MutationObservers for cleanup */
+let activeObservers = [];
+// ─── Helper: register a listener for later cleanup ───────────────────────────
+function addListener(target, event, handler) {
+    target.addEventListener(event, handler);
+    activeListeners.push({ target, event, handler });
+}
+// ─── Dropdown Toggling ───────────────────────────────────────────────────────
+function initDropdowns() {
+    const handler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-dropdown-toggle]');
+        if (trigger) {
+            e.preventDefault();
+            const dropdown = trigger.closest('.ux4g-dropdown');
+            if (dropdown) {
+                const isOpen = dropdown.classList.contains('is-open');
+                // Close all other open dropdowns
+                document.querySelectorAll('.ux4g-dropdown.is-open').forEach((el) => {
+                    if (el !== dropdown)
+                        el.classList.remove('is-open');
+                });
+                dropdown.classList.toggle('is-open', !isOpen);
+            }
+            return;
+        }
+        // Close dropdowns when clicking outside
+        if (!target.closest('.ux4g-dropdown')) {
+            document.querySelectorAll('.ux4g-dropdown.is-open').forEach((el) => {
+                el.classList.remove('is-open');
+            });
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Modal Management ────────────────────────────────────────────────────────
+function initModals() {
+    const openHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-modal-open]');
+        if (trigger) {
+            e.preventDefault();
+            const modalId = trigger.getAttribute('data-ux4g-modal-open');
+            if (modalId) {
+                const backdrop = document.getElementById(modalId);
+                if (backdrop) {
+                    backdrop.classList.add('is-open');
+                    document.body.style.overflow = 'hidden';
+                }
+            }
+        }
+    };
+    const closeHandler = (e) => {
+        const target = e.target;
+        // Close button inside modal
+        const closeBtn = target.closest('[data-ux4g-modal-close]');
+        if (closeBtn) {
+            e.preventDefault();
+            const backdrop = closeBtn.closest('.ux4g-modal-backdrop');
+            if (backdrop) {
+                backdrop.classList.remove('is-open');
+                document.body.style.overflow = '';
+            }
+            return;
+        }
+        // Click on backdrop (outside modal box) closes modal
+        if (target.classList.contains('ux4g-modal-backdrop') && target.classList.contains('is-open')) {
+            target.classList.remove('is-open');
+            document.body.style.overflow = '';
+        }
+    };
+    const keyHandler = (e) => {
+        if (e.key === 'Escape') {
+            const openModal = document.querySelector('.ux4g-modal-backdrop.is-open');
+            if (openModal) {
+                openModal.classList.remove('is-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    addListener(document, 'click', openHandler);
+    addListener(document, 'click', closeHandler);
+    addListener(document, 'keydown', keyHandler);
+}
+// ─── Tooltip Positioning ─────────────────────────────────────────────────────
+function initTooltips() {
+    const showHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-tooltip]');
+        if (trigger) {
+            const tooltipId = trigger.getAttribute('data-ux4g-tooltip');
+            if (tooltipId) {
+                const tooltip = document.getElementById(tooltipId);
+                if (tooltip) {
+                    tooltip.classList.add('show');
+                }
+            }
+        }
+    };
+    const hideHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-tooltip]');
+        if (trigger) {
+            const tooltipId = trigger.getAttribute('data-ux4g-tooltip');
+            if (tooltipId) {
+                const tooltip = document.getElementById(tooltipId);
+                if (tooltip) {
+                    tooltip.classList.remove('show');
+                }
+            }
+        }
+    };
+    addListener(document, 'mouseenter', showHandler);
+    addListener(document, 'mouseleave', hideHandler);
+    addListener(document, 'focusin', showHandler);
+    addListener(document, 'focusout', hideHandler);
+}
+// ─── Accordion Expand/Collapse ───────────────────────────────────────────────
+function initAccordions() {
+    const handler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-accordion-toggle]');
+        if (trigger) {
+            e.preventDefault();
+            const item = trigger.closest('.ux4g-accordion-item');
+            if (item) {
+                const isExpanded = item.classList.contains('is-expanded');
+                item.classList.toggle('is-expanded', !isExpanded);
+                // Update aria-expanded attribute
+                trigger.setAttribute('aria-expanded', String(!isExpanded));
+                // Toggle the panel visibility
+                const panel = item.querySelector('.ux4g-accordion-panel');
+                if (panel) {
+                    panel.style.display = isExpanded ? 'none' : '';
+                }
+            }
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Carousel Sliding ────────────────────────────────────────────────────────
+function initCarousels() {
+    const handler = (e) => {
+        const target = e.target;
+        // Next button
+        const nextBtn = target.closest('[data-ux4g-carousel-next]');
+        if (nextBtn) {
+            e.preventDefault();
+            const carousel = nextBtn.closest('.ux4g-carousel');
+            if (carousel) {
+                const items = carousel.querySelectorAll('.ux4g-carousel-item');
+                const activeItem = carousel.querySelector('.ux4g-carousel-item.active');
+                if (activeItem && items.length > 0) {
+                    const currentIndex = Array.from(items).indexOf(activeItem);
+                    const nextIndex = (currentIndex + 1) % items.length;
+                    activeItem.classList.remove('active');
+                    items[nextIndex].classList.add('active');
+                }
+            }
+            return;
+        }
+        // Previous button
+        const prevBtn = target.closest('[data-ux4g-carousel-prev]');
+        if (prevBtn) {
+            e.preventDefault();
+            const carousel = prevBtn.closest('.ux4g-carousel');
+            if (carousel) {
+                const items = carousel.querySelectorAll('.ux4g-carousel-item');
+                const activeItem = carousel.querySelector('.ux4g-carousel-item.active');
+                if (activeItem && items.length > 0) {
+                    const currentIndex = Array.from(items).indexOf(activeItem);
+                    const prevIndex = (currentIndex - 1 + items.length) % items.length;
+                    activeItem.classList.remove('active');
+                    items[prevIndex].classList.add('active');
+                }
+            }
+        }
+    };
+    addListener(document, 'click', handler);
+}
+// ─── Drawer Open/Close ───────────────────────────────────────────────────────
+function initDrawers() {
+    const openHandler = (e) => {
+        const target = e.target;
+        const trigger = target.closest('[data-ux4g-drawer-open]');
+        if (trigger) {
+            e.preventDefault();
+            const drawerId = trigger.getAttribute('data-ux4g-drawer-open');
+            if (drawerId) {
+                const drawer = document.getElementById(drawerId);
+                if (drawer) {
+                    drawer.classList.add('ux4g-drawer-open');
+                    document.body.style.overflow = 'hidden';
+                }
+            }
+        }
+    };
+    const closeHandler = (e) => {
+        const target = e.target;
+        const closeBtn = target.closest('[data-ux4g-drawer-close]');
+        if (closeBtn) {
+            e.preventDefault();
+            const drawer = closeBtn.closest('.ux4g-drawer');
+            if (drawer) {
+                drawer.classList.remove('ux4g-drawer-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    const keyHandler = (e) => {
+        if (e.key === 'Escape') {
+            const openDrawer = document.querySelector('.ux4g-drawer.ux4g-drawer-open');
+            if (openDrawer) {
+                openDrawer.classList.remove('ux4g-drawer-open');
+                document.body.style.overflow = '';
+            }
+        }
+    };
+    addListener(document, 'click', openHandler);
+    addListener(document, 'click', closeHandler);
+    addListener(document, 'keydown', keyHandler);
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Initialize the UX4G runtime.
+ *
+ * Encapsulates all interactive behaviors from the CDN scripts (ux4g.js, ux4g-custom.js):
+ * - Dropdown toggling
+ * - Modal management (open/close/escape/backdrop click)
+ * - Tooltip positioning (show/hide on hover/focus)
+ * - Accordion expand/collapse
+ * - Carousel sliding (next/prev)
+ * - Drawer open/close
+ *
+ * Uses a singleton guard to ensure initialization happens exactly once.
+ * Safe for SSR — no-ops when window/document are unavailable.
+ */
+function initRuntime() {
+    // Guard against non-browser environments (SSR/Node.js)
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return;
+    }
+    // Singleton guard: prevent duplicate initialization
+    if (window.__UX4G_RUNTIME_INITIALIZED__) {
+        return;
+    }
+    // Initialize all interactive behaviors
+    initDropdowns();
+    initModals();
+    initTooltips();
+    initAccordions();
+    initCarousels();
+    initDrawers();
+    // Mark as initialized
+    window.__UX4G_RUNTIME_INITIALIZED__ = true;
+}
+/**
+ * Destroy the UX4G runtime.
+ *
+ * Resets the singleton guard and removes all event listeners.
+ * Useful for testing and SSR cleanup.
+ */
+function destroyRuntime() {
+    // Guard against non-browser environments
+    if (typeof window === 'undefined') {
+        return;
+    }
+    // Remove all registered event listeners
+    for (const { target, event, handler } of activeListeners) {
+        target.removeEventListener(event, handler);
+    }
+    activeListeners = [];
+    // Disconnect all observers
+    for (const observer of activeObservers) {
+        observer.disconnect();
+    }
+    activeObservers = [];
+    // Reset the singleton guard
+    window.__UX4G_RUNTIME_INITIALIZED__ = undefined;
+}
+
+export { destroyRuntime, initRuntime };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ux4g-components-web",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "UX4G Design System — CSS bundle, design tokens, utilities, and shared Class_Builder types",
   "scripts": {
@@ -19,19 +19,38 @@
       "import": "./dist/types/index.mjs",
       "require": "./dist/types/index.cjs",
       "default": "./dist/types/index.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.mjs",
+      "require": "./dist/runtime/index.cjs",
+      "default": "./dist/runtime/index.mjs"
+    },
+    "./runtime/bootstrap": {
+      "types": "./dist/runtime/bootstrap.d.ts",
+      "import": "./dist/runtime/bootstrap.mjs",
+      "require": "./dist/runtime/bootstrap.cjs",
+      "default": "./dist/runtime/bootstrap.mjs"
     }
   },
   "typesVersions": {
     "*": {
       "types": [
         "./dist/types/index.d.ts"
+      ],
+      "runtime": [
+        "./dist/runtime/index.d.ts"
+      ],
+      "runtime/bootstrap": [
+        "./dist/runtime/bootstrap.d.ts"
       ]
     }
   },
   "files": [
     "styles/ux4g.css",
     "styles/cascade-fixes.css",
-    "dist/"
+    "dist/",
+    "dist/runtime/"
   ],
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.0.0",