snice 4.14.0 → 4.16.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.13.0
+ * snice v4.15.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
@@ -1810,10 +1810,12 @@ var Snice = (function (exports) {
             this.defaultChild = null;
             this.currentChild = null;
             this.caseElement = caseElement;
+            this.caseElement.style.display = 'contents';
             // Build map and store children in fragments initially
             for (const child of Array.from(this.caseElement.children)) {
                 const childTag = child.tagName.toLowerCase();
                 if (childTag === 'when') {
+                    child.style.display = 'contents';
                     const whenValue = child.getAttribute('value') || '';
                     this.childrenMap.set(whenValue, child);
                     const fragment = document.createDocumentFragment();
@@ -1821,6 +1823,7 @@ var Snice = (function (exports) {
                     this.fragments.set(child, fragment);
                 }
                 else if (childTag === 'default') {
+                    child.style.display = 'contents';
                     this.defaultChild = child;
                     const fragment = document.createDocumentFragment();
                     fragment.appendChild(child);
@@ -2307,7 +2310,7 @@ var Snice = (function (exports) {
         setupResponseHandlers(controllerInstance, element);
         // Setup @on event handlers for controller
         setupEventHandlers(controllerInstance, element);
-        element.dispatchEvent(new CustomEvent('@snice/controller-attached', {
+        element.dispatchEvent(new CustomEvent('controller-attached', {
             detail: { name: controllerName, controller: controllerInstance }
         }));
     }
@@ -2347,7 +2350,7 @@ var Snice = (function (exports) {
         delete element[CONTROLLER_KEY];
         delete element[CONTROLLER_NAME_KEY];
         delete element[CONTROLLER_OPERATIONS];
-        element.dispatchEvent(new CustomEvent('@snice/controller-detached', {
+        element.dispatchEvent(new CustomEvent('controller-detached', {
             detail: { name: controllerName, controller: controllerInstance }
         }));
     }
@@ -3189,10 +3192,12 @@ var Snice = (function (exports) {
         if (!observedAttributes.includes('controller')) {
             observedAttributes.push('controller');
         }
-        // Add all properties to observed attributes (not just reflected ones)
+        // Add all properties to observed attributes (skip attribute: false)
         const properties = constructor[PROPERTIES];
         if (properties) {
             for (const [propName, propOptions] of properties) {
+                if (propOptions.attribute === false)
+                    continue;
                 const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
                 if (!observedAttributes.includes(attributeName)) {
                     observedAttributes.push(attributeName);
@@ -3279,6 +3284,9 @@ var Snice = (function (exports) {
                 const properties = constructor[PROPERTIES];
                 if (properties) {
                     for (const [propName, propOptions] of properties) {
+                        // Skip properties that opted out of attribute sync
+                        if (propOptions.attribute === false)
+                            continue;
                         // Check for attribute using proper attribute name
                         const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
                         if (this.hasAttribute(attributeName)) {
@@ -3595,6 +3603,16 @@ var Snice = (function (exports) {
                 if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
                     const descriptor = {
                         get() {
+                            // attribute: false — use internal storage only, no DOM sync
+                            if (finalOptions?.attribute === false) {
+                                if (this[PROPERTY_VALUES] && propertyKey in this[PROPERTY_VALUES]) {
+                                    return this[PROPERTY_VALUES][propertyKey];
+                                }
+                                if (this[PRE_INIT_PROPERTY_VALUES]?.has(propertyKey)) {
+                                    return this[PRE_INIT_PROPERTY_VALUES].get(propertyKey);
+                                }
+                                return initialValue;
+                            }
                             // Always read from DOM attribute - no internal state
                             const attributeName = typeof finalOptions?.attribute === 'string' ? finalOptions?.attribute : propertyKey.toLowerCase();
                             const attrValue = this.getAttribute?.(attributeName);
@@ -3632,28 +3650,37 @@ var Snice = (function (exports) {
                                 this[PRE_INIT_PROPERTY_VALUES].set(propertyKey, newValue);
                                 return;
                             }
-                            // Reflect to DOM - properties are backed by attributes
-                            const attributeName = typeof finalOptions.attribute === 'string' ? finalOptions.attribute : propertyKey.toLowerCase();
-                            const attributeValue = valueToAttribute(newValue, finalOptions, initialValue);
-                            // Mark as explicitly set for boolean handling
-                            if (!this[EXPLICITLY_SET_PROPERTIES]) {
-                                this[EXPLICITLY_SET_PROPERTIES] = new Set();
-                            }
-                            this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
-                            // Flag to prevent attributeChangedCallback from triggering watchers for this change
-                            if (!this._settingFromProperty)
-                                this._settingFromProperty = new Set();
-                            this._settingFromProperty.add(attributeName.toLowerCase());
-                            if (attributeValue === null) {
-                                this.removeAttribute?.(attributeName);
+                            // attribute: false — store internally, skip DOM reflection
+                            if (finalOptions?.attribute === false) {
+                                if (!this[PROPERTY_VALUES]) {
+                                    this[PROPERTY_VALUES] = {};
+                                }
+                                this[PROPERTY_VALUES][propertyKey] = newValue;
                             }
                             else {
-                                this.setAttribute?.(attributeName, attributeValue);
+                                // Reflect to DOM - properties are backed by attributes
+                                const attributeName = typeof finalOptions.attribute === 'string' ? finalOptions.attribute : propertyKey.toLowerCase();
+                                const attributeValue = valueToAttribute(newValue, finalOptions, initialValue);
+                                // Mark as explicitly set for boolean handling
+                                if (!this[EXPLICITLY_SET_PROPERTIES]) {
+                                    this[EXPLICITLY_SET_PROPERTIES] = new Set();
+                                }
+                                this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
+                                // Flag to prevent attributeChangedCallback from triggering watchers for this change
+                                if (!this._settingFromProperty)
+                                    this._settingFromProperty = new Set();
+                                this._settingFromProperty.add(attributeName.toLowerCase());
+                                if (attributeValue === null) {
+                                    this.removeAttribute?.(attributeName);
+                                }
+                                else {
+                                    this.setAttribute?.(attributeName, attributeValue);
+                                }
+                                // Remove the flag after a short delay to allow attributeChangedCallback to run
+                                setTimeout(() => {
+                                    this._settingFromProperty?.delete(attributeName.toLowerCase());
+                                }, 0);
                             }
-                            // Remove the flag after a short delay to allow attributeChangedCallback to run
-                            setTimeout(() => {
-                                this._settingFromProperty?.delete(attributeName.toLowerCase());
-                            }, 0);
                             // Trigger watchers directly with proper parsed values
                             const constructor = this.constructor;
                             const watchers = constructor[PROPERTY_WATCHERS];
@@ -4796,6 +4823,8 @@ var Snice = (function (exports) {
      * @returns An object containing the router's API methods.
      */
     function Router(options) {
+        const win = options.window ?? window;
+        const doc = options.document ?? document;
         const routes = [];
         let is_sorted = false;
         let placards = []; // Store collected placards
@@ -4859,11 +4888,11 @@ var Snice = (function (exports) {
                     delete this[CONTEXT_HANDLER];
                 };
                 // Define the custom element (skip if already registered)
-                if (customElements.get(pageOptions.tag)) {
+                if (win.customElements.get(pageOptions.tag)) {
                     console.warn(`[snice] Page "${pageOptions.tag}" is already registered. Skipping duplicate registration.`);
                 }
                 else {
-                    customElements.define(pageOptions.tag, constructor);
+                    win.customElements.define(pageOptions.tag, constructor);
                 }
                 // Register the routes with guards, layout, and placard
                 pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout, pageOptions.placard));
@@ -4894,8 +4923,8 @@ var Snice = (function (exports) {
             const isHashType = options.type === 'hash';
             const isPushStateType = options.type === 'pushstate';
             if (isHashType) {
-                window.addEventListener('hashchange', () => {
-                    const targetExists = !!document.querySelector(options.target);
+                win.addEventListener('hashchange', () => {
+                    const targetExists = !!doc.querySelector(options.target);
                     if (!targetExists) {
                         return;
                     }
@@ -4904,8 +4933,8 @@ var Snice = (function (exports) {
                 });
             }
             if (isPushStateType) {
-                window.addEventListener('popstate', () => {
-                    const targetExists = !!document.querySelector(options.target);
+                win.addEventListener('popstate', () => {
+                    const targetExists = !!doc.querySelector(options.target);
                     if (!targetExists) {
                         return;
                     }
@@ -4920,7 +4949,7 @@ var Snice = (function (exports) {
          * initialize();
          */
         function initialize() {
-            const target = document.querySelector(options.target);
+            const target = doc.querySelector(options.target);
             if (!target) {
                 throw new Error(`Target element not found: ${options.target}`);
             }
@@ -4965,20 +4994,20 @@ var Snice = (function (exports) {
         function getPath() {
             switch (options.type) {
                 case 'hash':
-                    return window.location.hash.slice(1);
+                    return win.location.hash.slice(1);
                 case 'pushstate':
-                    return window.location.pathname;
+                    return win.location.pathname;
             }
         }
         function renderForbiddenPage(target) {
             let newPageElement;
             const has403Page = !!_403;
             if (has403Page) {
-                newPageElement = document.createElement(_403);
+                newPageElement = doc.createElement(_403);
                 newPageElement[ROUTER_CONTEXT] = context;
             }
             if (!has403Page) {
-                const div = document.createElement('div');
+                const div = doc.createElement('div');
                 div.className = 'default-403';
                 div.innerHTML = /*html*/ `<h1>403</h1><p>Unauthorized</p>`;
                 newPageElement = div;
@@ -5004,9 +5033,9 @@ var Snice = (function (exports) {
             return true;
         }
         function createHomeElement() {
-            const newPageElement = document.createElement(home);
+            const newPageElement = doc.createElement(home);
             newPageElement[ROUTER_CONTEXT] = context;
-            const constructor = customElements.get(home);
+            const constructor = win.customElements.get(home);
             const transition = constructor?.[PAGE_TRANSITION];
             const homeRoute = routes.find(r => r.route.match('/'));
             return { element: newPageElement, transition, layout: homeRoute?.layout };
@@ -5014,13 +5043,13 @@ var Snice = (function (exports) {
         function create404Element() {
             const has404Page = !!_404;
             if (has404Page) {
-                const newPageElement = document.createElement(_404);
+                const newPageElement = doc.createElement(_404);
                 newPageElement[ROUTER_CONTEXT] = context;
-                const constructor = customElements.get(_404);
+                const constructor = win.customElements.get(_404);
                 const transition = constructor?.[PAGE_TRANSITION];
                 return { element: newPageElement, transition, layout: undefined };
             }
-            const div = document.createElement('div');
+            const div = doc.createElement('div');
             div.className = 'default-404';
             div.innerHTML = /*html*/ `<h1>404</h1><p>Page not found</p>`;
             return { element: div, transition: undefined, layout: undefined };
@@ -5036,7 +5065,7 @@ var Snice = (function (exports) {
                 if (!guardsAllowed) {
                     return { result: RouteResult.GUARDS_FAILED };
                 }
-                const newPageElement = document.createElement(route.tag);
+                const newPageElement = doc.createElement(route.tag);
                 newPageElement[ROUTER_CONTEXT] = context;
                 newPageElement[CONTEXT_HANDLER] = navigationContext;
                 const routeParams = params;
@@ -5070,7 +5099,7 @@ var Snice = (function (exports) {
             if (shouldCreateLayout) {
                 const timestamp = Date.now();
                 currentLayoutTimestamp = timestamp;
-                const layoutElement = document.createElement(layoutToUse);
+                const layoutElement = doc.createElement(layoutToUse);
                 layoutElement[ROUTER_CONTEXT] = context;
                 layoutElement[CREATED_AT] = timestamp;
                 return { element: layoutElement, needsNewLayout: true };
@@ -5122,13 +5151,13 @@ var Snice = (function (exports) {
          * navigate('/login');
          */
         async function navigate(path) {
-            const target = document.querySelector(options.target);
+            const target = doc.querySelector(options.target);
             if (!target) {
                 throw new Error(`Target element not found: ${options.target}`);
             }
             // Collect fresh placards before navigation
             collectPlacards();
-            window.scrollTo(0, 0);
+            win.scrollTo(0, 0);
             const isHomePath = (path?.trim() === '' || path === '/') && !!home;
             if (isHomePath) {
                 const homeRoute = routes.find(r => r.route.match('/'));
@@ -5197,6 +5226,444 @@ var Snice = (function (exports) {
         };
     }
 
+    // Portal CSS inlined (from snice-tooltip-portal.css)
+    const portalCss = `.snice-tooltip--visible{opacity:1!important;transform:scale(1)!important}.snice-tooltip__arrow{position:absolute;width:0;height:0;border-style:solid;border-color:transparent}.snice-tooltip--top .snice-tooltip__arrow,.snice-tooltip--top-start .snice-tooltip__arrow,.snice-tooltip--top-end .snice-tooltip__arrow{bottom:-6px;border-width:6px 6px 0;border-top-color:hsl(0 0% 20%)}.snice-tooltip--bottom .snice-tooltip__arrow,.snice-tooltip--bottom-start .snice-tooltip__arrow,.snice-tooltip--bottom-end .snice-tooltip__arrow{top:-6px;border-width:0 6px 6px;border-bottom-color:hsl(0 0% 20%)}.snice-tooltip--left .snice-tooltip__arrow,.snice-tooltip--left-start .snice-tooltip__arrow,.snice-tooltip--left-end .snice-tooltip__arrow{right:-6px;border-width:6px 0 6px 6px;border-left-color:hsl(0 0% 20%)}.snice-tooltip--right .snice-tooltip__arrow,.snice-tooltip--right-start .snice-tooltip__arrow,.snice-tooltip--right-end .snice-tooltip__arrow{left:-6px;border-width:6px 6px 6px 0;border-right-color:hsl(0 0% 20%)}.snice-tooltip--top .snice-tooltip__arrow,.snice-tooltip--bottom .snice-tooltip__arrow{left:50%;transform:translateX(-50%)}.snice-tooltip--top-start .snice-tooltip__arrow,.snice-tooltip--bottom-start .snice-tooltip__arrow{left:16px}.snice-tooltip--top-end .snice-tooltip__arrow,.snice-tooltip--bottom-end .snice-tooltip__arrow{right:16px}.snice-tooltip--left .snice-tooltip__arrow,.snice-tooltip--right .snice-tooltip__arrow{top:50%;transform:translateY(-50%)}.snice-tooltip--left-start .snice-tooltip__arrow,.snice-tooltip--right-start .snice-tooltip__arrow{top:16px}.snice-tooltip--left-end .snice-tooltip__arrow,.snice-tooltip--right-end .snice-tooltip__arrow{bottom:16px;top:auto}`;
+    const stateMap = new WeakMap();
+    let portalStylesInjected = false;
+    function ensurePortalStyles() {
+        if (portalStylesInjected)
+            return;
+        try {
+            if ('adoptedStyleSheets' in document && 'CSSStyleSheet' in window) {
+                const sheet = new CSSStyleSheet();
+                sheet.replaceSync(portalCss);
+                document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+            }
+            else {
+                const style = document.createElement('style');
+                style.textContent = portalCss;
+                document.head.appendChild(style);
+            }
+            portalStylesInjected = true;
+        }
+        catch (error) {
+            console.warn('Failed to inject tooltip portal styles:', error);
+        }
+    }
+    function readConfig(el) {
+        const cs = getComputedStyle(el);
+        const get = (name, fallback) => cs.getPropertyValue(name).trim() || fallback;
+        return {
+            position: get('--tooltip-position', 'top'),
+            trigger: get('--tooltip-trigger', 'hover'),
+            delay: parseInt(get('--tooltip-delay', '0'), 10),
+            hideDelay: parseInt(get('--tooltip-hide-delay', '0'), 10),
+            offset: parseInt(get('--tooltip-offset', '12'), 10),
+            arrow: get('--tooltip-arrow', 'auto') !== 'none',
+            maxWidth: parseInt(get('--tooltip-max-width', '250'), 10),
+            zIndex: parseInt(get('--tooltip-z-index', '10000'), 10),
+            strictPositioning: get('--tooltip-strict-positioning', '') === 'true',
+            bg: get('--tooltip-bg', 'hsl(0 0% 20%)'),
+            color: get('--tooltip-color', 'white'),
+            padding: get('--tooltip-padding', '8px 12px'),
+            radius: get('--tooltip-radius', '6px'),
+            fontSize: get('--tooltip-font-size', '14px'),
+        };
+    }
+    // --- Positioning (ported from snice-tooltip.ts) ---
+    function getPositionCoordinates(triggerRect, tooltipRect, position, offset, arrowSize) {
+        let left = 0;
+        let top = 0;
+        const centerX = triggerRect.left + triggerRect.width / 2;
+        const centerY = triggerRect.top + triggerRect.height / 2;
+        const verticalOffset = offset;
+        const horizontalOffset = offset + arrowSize;
+        switch (position) {
+            case 'top':
+                left = centerX - tooltipRect.width / 2;
+                top = triggerRect.top - tooltipRect.height - verticalOffset;
+                break;
+            case 'top-start':
+                left = triggerRect.left;
+                top = triggerRect.top - tooltipRect.height - verticalOffset;
+                break;
+            case 'top-end':
+                left = triggerRect.right - tooltipRect.width;
+                top = triggerRect.top - tooltipRect.height - verticalOffset;
+                break;
+            case 'bottom':
+                left = centerX - tooltipRect.width / 2;
+                top = triggerRect.bottom + verticalOffset;
+                break;
+            case 'bottom-start':
+                left = triggerRect.left;
+                top = triggerRect.bottom + verticalOffset;
+                break;
+            case 'bottom-end':
+                left = triggerRect.right - tooltipRect.width;
+                top = triggerRect.bottom + verticalOffset;
+                break;
+            case 'left':
+                left = triggerRect.left - tooltipRect.width - horizontalOffset;
+                top = centerY - tooltipRect.height / 2;
+                break;
+            case 'left-start':
+                left = triggerRect.left - tooltipRect.width - horizontalOffset;
+                top = triggerRect.top;
+                break;
+            case 'left-end':
+                left = triggerRect.left - tooltipRect.width - horizontalOffset;
+                top = triggerRect.bottom - tooltipRect.height;
+                break;
+            case 'right':
+                left = triggerRect.right + horizontalOffset;
+                top = centerY - tooltipRect.height / 2;
+                break;
+            case 'right-start':
+                left = triggerRect.right + horizontalOffset;
+                top = triggerRect.top;
+                break;
+            case 'right-end':
+                left = triggerRect.right + horizontalOffset;
+                top = triggerRect.bottom - tooltipRect.height;
+                break;
+        }
+        return { left, top };
+    }
+    function getAlternativePositions(position) {
+        const opposites = {
+            'top': ['bottom', 'left', 'right'],
+            'top-start': ['bottom-start', 'left', 'right'],
+            'top-end': ['bottom-end', 'left', 'right'],
+            'bottom': ['top', 'left', 'right'],
+            'bottom-start': ['top-start', 'left', 'right'],
+            'bottom-end': ['top-end', 'left', 'right'],
+            'left': ['right', 'top', 'bottom'],
+            'left-start': ['right-start', 'top', 'bottom'],
+            'left-end': ['right-end', 'top', 'bottom'],
+            'right': ['left', 'top', 'bottom'],
+            'right-start': ['left-start', 'top', 'bottom'],
+            'right-end': ['left-end', 'top', 'bottom'],
+        };
+        return opposites[position] || ['top', 'bottom', 'left', 'right'];
+    }
+    function calculatePosition(triggerRect, tooltipRect, position, offset, arrowSize, strictPositioning) {
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        let pos = position;
+        let coords = getPositionCoordinates(triggerRect, tooltipRect, pos, offset, arrowSize);
+        if (!strictPositioning) {
+            const fits = coords.left >= 0 &&
+                coords.top >= 0 &&
+                coords.left + tooltipRect.width <= vw &&
+                coords.top + tooltipRect.height <= vh;
+            if (!fits) {
+                for (const alt of getAlternativePositions(pos)) {
+                    const altCoords = getPositionCoordinates(triggerRect, tooltipRect, alt, offset, arrowSize);
+                    if (altCoords.left >= 0 &&
+                        altCoords.top >= 0 &&
+                        altCoords.left + tooltipRect.width <= vw &&
+                        altCoords.top + tooltipRect.height <= vh) {
+                        pos = alt;
+                        coords = altCoords;
+                        break;
+                    }
+                }
+            }
+        }
+        return { left: coords.left, top: coords.top, adjustedPosition: pos };
+    }
+    // --- Portal creation ---
+    function createPortal(config) {
+        const portal = document.createElement('div');
+        portal.className = `snice-tooltip snice-tooltip--${config.position}`;
+        portal.setAttribute('role', 'tooltip');
+        portal.style.cssText = `
+    position: fixed;
+    z-index: ${config.zIndex};
+    padding: ${config.padding};
+    background: ${config.bg};
+    color: ${config.color};
+    border-radius: ${config.radius};
+    font-size: ${config.fontSize};
+    line-height: 1.4;
+    max-width: ${config.maxWidth}px;
+    width: max-content;
+    pointer-events: none;
+    opacity: 0;
+    transform: scale(0.95);
+    transition: opacity 0.2s, transform 0.2s;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+    display: none;
+  `;
+        const content = document.createElement('div');
+        content.className = 'snice-tooltip__content';
+        portal.appendChild(content);
+        if (config.arrow) {
+            const arrow = document.createElement('div');
+            arrow.className = 'snice-tooltip__arrow';
+            arrow.style.cssText = 'position:absolute;width:0;height:0;border-style:solid;';
+            portal.appendChild(arrow);
+        }
+        document.body.appendChild(portal);
+        return portal;
+    }
+    // --- Show / Hide ---
+    function showTooltip(el) {
+        const text = el.getAttribute('tooltip');
+        if (!text)
+            return;
+        ensurePortalStyles();
+        const config = readConfig(el);
+        let state = stateMap.get(el);
+        if (!state) {
+            state = { portal: null, listeners: [], activePosition: config.position };
+            stateMap.set(el, state);
+        }
+        // Create or update portal
+        if (!state.portal) {
+            state.portal = createPortal(config);
+        }
+        else {
+            // Update styling in case CSS vars changed
+            const p = state.portal;
+            p.style.zIndex = String(config.zIndex);
+            p.style.padding = config.padding;
+            p.style.background = config.bg;
+            p.style.color = config.color;
+            p.style.borderRadius = config.radius;
+            p.style.fontSize = config.fontSize;
+            p.style.maxWidth = `${config.maxWidth}px`;
+            // Update arrow — CSS handles color via class-based rules, but we need
+            // the arrow element to exist/not-exist
+            let arrow = p.querySelector('.snice-tooltip__arrow');
+            if (config.arrow && !arrow) {
+                arrow = document.createElement('div');
+                arrow.className = 'snice-tooltip__arrow';
+                arrow.style.cssText = 'position:absolute;width:0;height:0;border-style:solid;';
+                p.appendChild(arrow);
+            }
+            else if (!config.arrow && arrow) {
+                arrow.style.display = 'none';
+            }
+            else if (config.arrow && arrow) {
+                arrow.style.display = '';
+            }
+        }
+        const portal = state.portal;
+        const contentEl = portal.querySelector('.snice-tooltip__content');
+        if (contentEl)
+            contentEl.textContent = text;
+        portal.style.display = 'block';
+        void portal.offsetHeight; // force reflow
+        // Position
+        portal.style.visibility = 'hidden';
+        portal.style.left = '-9999px';
+        portal.style.top = '-9999px';
+        const triggerRect = el.getBoundingClientRect();
+        const tooltipRect = portal.getBoundingClientRect();
+        portal.style.visibility = '';
+        const arrowSize = config.arrow ? 6 : 0;
+        const result = calculatePosition(triggerRect, tooltipRect, config.position, config.offset, arrowSize, config.strictPositioning);
+        if (result.adjustedPosition !== state.activePosition) {
+            portal.classList.remove(`snice-tooltip--${state.activePosition}`);
+            portal.classList.add(`snice-tooltip--${result.adjustedPosition}`);
+            state.activePosition = result.adjustedPosition;
+        }
+        portal.style.left = `${result.left}px`;
+        portal.style.top = `${result.top}px`;
+        portal.classList.add('snice-tooltip--visible');
+    }
+    function hideTooltip(el) {
+        const state = stateMap.get(el);
+        if (!state?.portal)
+            return;
+        state.portal.classList.remove('snice-tooltip--visible');
+        const p = state.portal;
+        setTimeout(() => {
+            if (p)
+                p.style.display = 'none';
+        }, 200);
+    }
+    function scheduleShow(el) {
+        const state = stateMap.get(el);
+        if (!state)
+            return;
+        clearTimeouts(state);
+        const config = readConfig(el);
+        if (config.delay > 0) {
+            state.showTimeout = window.setTimeout(() => showTooltip(el), config.delay);
+        }
+        else {
+            showTooltip(el);
+        }
+    }
+    function scheduleHide(el) {
+        const state = stateMap.get(el);
+        if (!state)
+            return;
+        clearTimeouts(state);
+        const config = readConfig(el);
+        if (config.hideDelay > 0) {
+            state.hideTimeout = window.setTimeout(() => hideTooltip(el), config.hideDelay);
+        }
+        else {
+            hideTooltip(el);
+        }
+    }
+    function clearTimeouts(state) {
+        if (state.showTimeout !== undefined) {
+            clearTimeout(state.showTimeout);
+            state.showTimeout = undefined;
+        }
+        if (state.hideTimeout !== undefined) {
+            clearTimeout(state.hideTimeout);
+            state.hideTimeout = undefined;
+        }
+    }
+    // --- Attach / Detach ---
+    function attachTooltip(el) {
+        // Skip if already attached
+        if (stateMap.has(el))
+            return;
+        const config = readConfig(el);
+        const state = { portal: null, listeners: [], activePosition: config.position };
+        stateMap.set(el, state);
+        const addListener = (type, fn) => {
+            el.addEventListener(type, fn);
+            state.listeners.push({ type, fn });
+        };
+        switch (config.trigger) {
+            case 'hover':
+                addListener('mouseenter', () => scheduleShow(el));
+                addListener('mouseleave', () => scheduleHide(el));
+                addListener('focusin', () => scheduleShow(el));
+                addListener('focusout', () => scheduleHide(el));
+                break;
+            case 'focus':
+                addListener('focusin', () => scheduleShow(el));
+                addListener('focusout', () => scheduleHide(el));
+                break;
+            case 'click': {
+                const clickOutside = (e) => {
+                    if (!el.contains(e.target)) {
+                        scheduleHide(el);
+                        document.removeEventListener('click', clickOutside);
+                    }
+                };
+                addListener('click', () => {
+                    const s = stateMap.get(el);
+                    const isVisible = s?.portal?.classList.contains('snice-tooltip--visible');
+                    if (isVisible) {
+                        scheduleHide(el);
+                    }
+                    else {
+                        scheduleShow(el);
+                        setTimeout(() => document.addEventListener('click', clickOutside), 0);
+                    }
+                });
+                break;
+            }
+        }
+    }
+    function detachTooltip(el) {
+        const state = stateMap.get(el);
+        if (!state)
+            return;
+        clearTimeouts(state);
+        for (const { type, fn } of state.listeners) {
+            el.removeEventListener(type, fn);
+        }
+        if (state.portal) {
+            state.portal.remove();
+        }
+        stateMap.delete(el);
+    }
+    // --- Observer ---
+    function processElement(el) {
+        if (!(el instanceof HTMLElement))
+            return;
+        const tooltip = el.getAttribute('tooltip');
+        if (tooltip) {
+            attachTooltip(el);
+        }
+    }
+    /**
+     * Initialize attribute-based tooltips.
+     * Any element with a `tooltip` attribute will show a tooltip on interaction.
+     * Configure via CSS custom properties (--tooltip-position, --tooltip-delay, etc.).
+     * Idempotent — safe to call multiple times.
+     */
+    function useTooltips() {
+        if (globalThis.sniceTooltipsInitialized)
+            return;
+        globalThis.sniceTooltipsInitialized = true;
+        const observer = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                if (mutation.type === 'attributes' && mutation.attributeName === 'tooltip') {
+                    const el = mutation.target;
+                    if (el.hasAttribute('tooltip')) {
+                        // Attribute added or changed — detach old, re-attach
+                        detachTooltip(el);
+                        attachTooltip(el);
+                    }
+                    else {
+                        // Attribute removed
+                        detachTooltip(el);
+                    }
+                }
+                else if (mutation.type === 'childList') {
+                    mutation.addedNodes.forEach(node => {
+                        if (node instanceof HTMLElement) {
+                            processElement(node);
+                            node.querySelectorAll('[tooltip]').forEach(processElement);
+                        }
+                    });
+                    mutation.removedNodes.forEach(node => {
+                        if (node instanceof HTMLElement) {
+                            detachTooltip(node);
+                            node.querySelectorAll('[tooltip]').forEach(child => {
+                                if (child instanceof HTMLElement)
+                                    detachTooltip(child);
+                            });
+                        }
+                    });
+                }
+            }
+        });
+        const start = () => {
+            document.querySelectorAll('[tooltip]').forEach(processElement);
+            observer.observe(document.body, {
+                attributes: true,
+                attributeFilter: ['tooltip'],
+                childList: true,
+                subtree: true,
+            });
+        };
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', start);
+        }
+        else {
+            start();
+        }
+        globalThis.sniceTooltipObserver = observer;
+    }
+    /**
+     * Disconnect the tooltip observer and remove all portals.
+     */
+    function cleanupTooltips() {
+        const observer = globalThis.sniceTooltipObserver;
+        if (observer) {
+            observer.disconnect();
+            globalThis.sniceTooltipObserver = undefined;
+        }
+        document.querySelectorAll('[tooltip]').forEach(el => {
+            if (el instanceof HTMLElement)
+                detachTooltip(el);
+        });
+        globalThis.sniceTooltipsInitialized = false;
+    }
+
     // @dispatch decorator - auto-dispatches custom events from method return values
     /**
      * Decorator that automatically dispatches a custom event after a method is called.
@@ -5832,6 +6299,7 @@ var Snice = (function (exports) {
     exports.SimpleArray = SimpleArray;
     exports.adopted = adopted;
     exports.applyElementFunctionality = applyElementFunctionality;
+    exports.cleanupTooltips = cleanupTooltips;
     exports.clearDebounceTimers = clearDebounceTimers;
     exports.clearMemoizeCache = clearMemoizeCache;
     exports.clearThrottleTimers = clearThrottleTimers;
@@ -5867,6 +6335,7 @@ var Snice = (function (exports) {
     exports.trackRenders = trackRenders;
     exports.unsafeHTML = unsafeHTML;
     exports.useNativeElementControllers = useNativeElementControllers;
+    exports.useTooltips = useTooltips;
     exports.waitForAllCustomElements = waitForAllCustomElements;
     exports.waitForElementDefined = waitForElementDefined;
     exports.waitForElementReady = waitForElementReady;