snice 4.14.0 → 4.16.0

package/dist/index.esm.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.
@@ -1807,10 +1807,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();
@@ -1818,6 +1820,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);
@@ -2304,7 +2307,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 }
     }));
 }
@@ -2344,7 +2347,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 }
     }));
 }
@@ -3186,10 +3189,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);
@@ -3276,6 +3281,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)) {
@@ -3592,6 +3600,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);
@@ -3629,28 +3647,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];
@@ -4793,6 +4820,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
@@ -4856,11 +4885,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));
@@ -4891,8 +4920,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;
                 }
@@ -4901,8 +4930,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;
                 }
@@ -4917,7 +4946,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}`);
         }
@@ -4962,20 +4991,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;
@@ -5001,9 +5030,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 };
@@ -5011,13 +5040,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 };
@@ -5033,7 +5062,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;
@@ -5067,7 +5096,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 };
@@ -5119,13 +5148,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('/'));
@@ -5194,6 +5223,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.
@@ -5822,5 +6289,5 @@ class ContextAwareFetcher {
     }
 }
 
-export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, css, debounce, dispatch, dispose, element, getSymbol, html, layout, memoize, moved, noChange, nothing, observe, on, once, property, query, queryAll, ready, render, request, resetOnce, respond, setDisableElementReadyWarnings, styles, throttle, trackRenders, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
+export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, cleanupTooltips, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, css, debounce, dispatch, dispose, element, getSymbol, html, layout, memoize, moved, noChange, nothing, observe, on, once, property, query, queryAll, ready, render, request, resetOnce, respond, setDisableElementReadyWarnings, styles, throttle, trackRenders, unsafeHTML, useNativeElementControllers, useTooltips, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
 //# sourceMappingURL=index.esm.js.map