snice 4.14.0 → 4.16.0

package/dist/index.cjs

@@ -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.
@@ -1809,10 +1809,12 @@ class ConditionalCasePart extends Part {
         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();
@@ -1820,6 +1822,7 @@ class ConditionalCasePart extends Part {
                 this.fragments.set(child, fragment);
             }
             else if (childTag === 'default') {
+                child.style.display = 'contents';
                 this.defaultChild = child;
                 const fragment = document.createDocumentFragment();
                 fragment.appendChild(child);
@@ -2306,7 +2309,7 @@ async function attachController(element, controllerName) {
     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 }
     }));
 }
@@ -2346,7 +2349,7 @@ async function detachController(element) {
     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 }
     }));
 }
@@ -3188,10 +3191,12 @@ function applyElementFunctionality(constructor) {
     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);
@@ -3278,6 +3283,9 @@ function applyElementFunctionality(constructor) {
             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)) {
@@ -3594,6 +3602,16 @@ function property(options) {
             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);
@@ -3631,28 +3649,37 @@ function property(options) {
                             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];
@@ -4795,6 +4822,8 @@ var RouteResult;
  * @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
@@ -4858,11 +4887,11 @@ function Router(options) {
                 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));
@@ -4893,8 +4922,8 @@ function Router(options) {
         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;
                 }
@@ -4903,8 +4932,8 @@ function Router(options) {
             });
         }
         if (isPushStateType) {
-            window.addEventListener('popstate', () => {
-                const targetExists = !!document.querySelector(options.target);
+            win.addEventListener('popstate', () => {
+                const targetExists = !!doc.querySelector(options.target);
                 if (!targetExists) {
                     return;
                 }
@@ -4919,7 +4948,7 @@ function Router(options) {
      * 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}`);
         }
@@ -4964,20 +4993,20 @@ function Router(options) {
     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;
@@ -5003,9 +5032,9 @@ function Router(options) {
         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 };
@@ -5013,13 +5042,13 @@ function Router(options) {
     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 };
@@ -5035,7 +5064,7 @@ function Router(options) {
             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;
@@ -5069,7 +5098,7 @@ function Router(options) {
         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 };
@@ -5121,13 +5150,13 @@ function Router(options) {
      * 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('/'));
@@ -5196,6 +5225,444 @@ function Router(options) {
     };
 }
 
+// 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.
@@ -5831,6 +6298,7 @@ exports.Router = Router;
 exports.SimpleArray = SimpleArray;
 exports.adopted = adopted;
 exports.applyElementFunctionality = applyElementFunctionality;
+exports.cleanupTooltips = cleanupTooltips;
 exports.clearDebounceTimers = clearDebounceTimers;
 exports.clearMemoizeCache = clearMemoizeCache;
 exports.clearThrottleTimers = clearThrottleTimers;
@@ -5866,6 +6334,7 @@ exports.throttle = throttle;
 exports.trackRenders = trackRenders;
 exports.unsafeHTML = unsafeHTML;
 exports.useNativeElementControllers = useNativeElementControllers;
+exports.useTooltips = useTooltips;
 exports.waitForAllCustomElements = waitForAllCustomElements;
 exports.waitForElementDefined = waitForElementDefined;
 exports.waitForElementReady = waitForElementReady;