@neovici/cosmoz-tooltip 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,108 @@
+# cosmoz-tooltip
+
+Tooltip web component using modern CSS APIs (CSS Anchor Positioning, Popover API) built with [@pionjs/pion](https://github.com/nicolo-ribaudo/pion).
+
+## Installation
+
+```bash
+npm install @neovici/cosmoz-tooltip
+```
+
+## Usage
+
+### Wrapping mode
+
+```html
+<script type="module">
+	import '@neovici/cosmoz-tooltip';
+</script>
+
+<cosmoz-tooltip heading="Help" description="Click to submit the form">
+	<button>Submit</button>
+</cosmoz-tooltip>
+```
+
+### For attribute mode
+
+Target elements by their `name` attribute within the same document/shadow root:
+
+```html
+<input name="email" type="email" />
+<cosmoz-tooltip
+	for="email"
+	heading="Email format"
+	description="Enter a valid email like name@domain.com"
+></cosmoz-tooltip>
+```
+
+### Rich content (wrapping mode only)
+
+```html
+<cosmoz-tooltip>
+	<button>Info</button>
+	<div slot="content">
+		<strong>Custom HTML</strong>
+		<ul>
+			<li>First item</li>
+			<li>Second item</li>
+		</ul>
+	</div>
+</cosmoz-tooltip>
+```
+
+## API
+
+| Attribute     | Type   | Default | Description                                                               |
+| ------------- | ------ | ------- | ------------------------------------------------------------------------- |
+| `heading`     | string | -       | Bold heading text                                                         |
+| `description` | string | -       | Secondary description text                                                |
+| `for`         | string | -       | Target element's `name` attribute                                         |
+| `placement`   | string | `top`   | Position: `top`, `bottom`, `left`, `right`, `top center`, `bottom center` |
+| `delay`       | number | `300`   | Delay before showing tooltip (ms)                                         |
+
+### Slots
+
+| Slot      | Description                                        |
+| --------- | -------------------------------------------------- |
+| (default) | Trigger element (wrapping mode)                    |
+| `content` | Rich HTML content for tooltip (wrapping mode only) |
+
+## Features
+
+- **CSS Anchor Positioning** — tooltip automatically anchors to trigger element
+- **Popover API** — proper layering without z-index hacks
+- **Automatic flip** — repositions when constrained by viewport via `position-try-fallbacks`
+- **Smooth animations** — uses `@starting-style` and `allow-discrete` transitions
+- **Non-blocking** — `pointer-events: none` ensures tooltips never block interactions
+- **Keyboard accessible** — shows on focus, hides on blur
+
+## Design decisions
+
+### No arrow/caret
+
+CSS Anchor Positioning's `position-try-fallbacks` can flip the tooltip to the opposite side when constrained by the viewport. There is no pure CSS way to detect when a flip occurs, so an arrow's direction cannot reliably match the actual tooltip position.
+
+### No rich content in `for=""` mode
+
+The `for=""` mode creates the popover in the light DOM (required for CSS Anchor Positioning to work across elements). Since there's no shadow boundary, slot projection isn't available — content is limited to `heading` and `description` attributes.
+
+## Browser support
+
+This component uses [CSS Anchor Positioning](https://caniuse.com/css-anchor-positioning) and [Popover API](https://caniuse.com/mdn-api_htmlelement_popover), both Baseline 2026.
+
+## Development
+
+```bash
+npm install
+npm run storybook:start  # Start Storybook on port 8000
+npm test                 # Run tests
+npm run build            # Build for production
+```
+
+## License
+
+Apache-2.0
+
+---
+
+Built with [@pionjs/pion](https://github.com/pionjs/pion)

package/dist/cosmoz-tooltip-content.d.ts

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

package/dist/cosmoz-tooltip-content.js

@@ -0,0 +1,28 @@
+import { normalize } from '@neovici/cosmoz-tokens/normalize';
+import { component, css } from '@pionjs/pion';
+import { html } from 'lit-html';
+const style = css `
+	:host {
+		display: flex;
+		flex-direction: column;
+		gap: var(--cz-spacing);
+		font-family: var(--cz-font-body);
+		font-size: var(--cz-text-xs);
+		line-height: var(--cz-text-xs-line-height);
+	}
+
+	::slotted([slot='heading']) {
+		font-weight: var(--cz-font-weight-semibold);
+		display: block;
+	}
+
+	::slotted([slot='description']) {
+		margin: 0;
+		color: var(--cz-color-gray-300);
+	}
+`;
+customElements.define('cosmoz-tooltip-content', component(() => html `
+			<slot name="heading"></slot>
+			<slot name="description"></slot>
+			<slot></slot>
+		`, { styleSheets: [normalize, style] }));

package/dist/cosmoz-tooltip.d.ts

@@ -0,0 +1,10 @@
+import './cosmoz-tooltip-content.js';
+interface TooltipProps {
+    heading?: string;
+    description?: string;
+    for?: string;
+    placement?: string;
+    delay?: number;
+}
+declare const CosmozTooltip: (host: HTMLElement & TooltipProps) => import("lit-html").TemplateResult<1>;
+export { CosmozTooltip };

package/dist/cosmoz-tooltip.js

@@ -0,0 +1,76 @@
+import { normalize } from '@neovici/cosmoz-tokens/normalize';
+import { component, css, useCallback, useRef } from '@pionjs/pion';
+import { html } from 'lit-html';
+import { ref } from 'lit-html/directives/ref.js';
+import { when } from 'lit-html/directives/when.js';
+import './cosmoz-tooltip-content.js';
+import { popoverStyle } from './popover-style.js';
+import { useForTooltip } from './use-for-tooltip.js';
+/**
+ * Host-specific styles (shadow DOM only).
+ * The wrapping mode popover binds to the host's anchor name.
+ */
+const style = css `
+	:host {
+		display: inline-block;
+		anchor-name: --tooltip-anchor;
+	}
+
+	:host([for]) {
+		display: contents;
+		anchor-name: unset;
+	}
+
+	.cosmoz-tooltip-popover {
+		position-anchor: --tooltip-anchor;
+	}
+`;
+const CosmozTooltip = (host) => {
+    const { heading, description, for: forAttr, placement = 'top', delay = 300, } = host;
+    const popover = useRef();
+    const timeoutId = useRef();
+    const show = useCallback(() => {
+        clearTimeout(timeoutId.current);
+        timeoutId.current = window.setTimeout(() => {
+            popover.current?.showPopover();
+        }, delay);
+    }, [delay]);
+    const hide = useCallback(() => {
+        clearTimeout(timeoutId.current);
+        popover.current?.hidePopover();
+    }, []);
+    // Delegate for="" mode to hook
+    useForTooltip(host, { for: forAttr, heading, description, placement, delay });
+    // For attribute mode: nothing to render in shadow DOM
+    if (forAttr)
+        return html ``;
+    // Wrapping mode: render slot + popover in shadow DOM
+    return html `
+		<slot
+			@pointerenter=${show}
+			@pointerleave=${hide}
+			@focusin=${show}
+			@focusout=${hide}
+		></slot>
+		<div
+			class="cosmoz-tooltip-popover"
+			popover="manual"
+			role="tooltip"
+			style="position-area: ${placement}"
+			${ref((el) => {
+        popover.current = el;
+    })}
+		>
+			<cosmoz-tooltip-content>
+				${when(heading, () => html `<strong slot="heading">${heading}</strong>`)}
+				${when(description, () => html `<p slot="description">${description}</p>`)}
+				<slot name="content"></slot>
+			</cosmoz-tooltip-content>
+		</div>
+	`;
+};
+customElements.define('cosmoz-tooltip', component(CosmozTooltip, {
+    styleSheets: [normalize, popoverStyle, style],
+    observedAttributes: ['heading', 'description', 'for', 'placement', 'delay'],
+}));
+export { CosmozTooltip };

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { CosmozTooltip } from './cosmoz-tooltip';

package/dist/index.js

@@ -0,0 +1 @@
+export { CosmozTooltip } from './cosmoz-tooltip';

package/dist/popover-style.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared popover styles used in both shadow DOM (wrapping mode)
+ * and light DOM (for="" mode).
+ *
+ * Design decision: No arrow/caret pointing to the anchor.
+ *
+ * CSS Anchor Positioning's position-try-fallbacks can flip the tooltip
+ * to the opposite side when constrained by the viewport. There is no
+ * pure CSS way to detect when a flip occurs (@position-try descriptors
+ * cannot set custom properties or pseudo-element styles), so the arrow
+ * direction cannot reliably match the actual tooltip position.
+ * A JS-based detection (getBoundingClientRect) was considered but
+ * rejected to keep the component purely CSS-positioned.
+ */
+export declare const popoverStyle: CSSStyleSheet;

package/dist/popover-style.js

@@ -0,0 +1,65 @@
+import { css, sheet } from '@pionjs/pion';
+/**
+ * Shared popover styles used in both shadow DOM (wrapping mode)
+ * and light DOM (for="" mode).
+ *
+ * Design decision: No arrow/caret pointing to the anchor.
+ *
+ * CSS Anchor Positioning's position-try-fallbacks can flip the tooltip
+ * to the opposite side when constrained by the viewport. There is no
+ * pure CSS way to detect when a flip occurs (@position-try descriptors
+ * cannot set custom properties or pseudo-element styles), so the arrow
+ * direction cannot reliably match the actual tooltip position.
+ * A JS-based detection (getBoundingClientRect) was considered but
+ * rejected to keep the component purely CSS-positioned.
+ */
+export const popoverStyle = sheet(css `
+	.cosmoz-tooltip-popover {
+		position: fixed;
+		inset: unset;
+		pointer-events: none;
+		text-align: left;
+		margin: calc(var(--cz-spacing) * 2);
+		position-try-fallbacks:
+			flip-block,
+			flip-inline,
+			flip-block flip-inline;
+
+		/* Reset popover defaults */
+		border: none;
+		padding: calc(var(--cz-spacing) * 2) calc(var(--cz-spacing) * 3);
+		background: var(--cz-color-gray-900);
+		color: var(--cz-color-white);
+		border-radius: var(--cz-radius-sm);
+		max-width: 20rem;
+		box-shadow: var(--cz-shadow-lg);
+
+		/* Animation - open state */
+		opacity: 1;
+		transform: translateY(0) scale(1);
+
+		transition:
+			opacity 150ms ease-out,
+			transform 150ms ease-out,
+			overlay 150ms ease-out allow-discrete,
+			display 150ms ease-out allow-discrete;
+	}
+
+	@starting-style {
+		.cosmoz-tooltip-popover:popover-open {
+			opacity: 0;
+			transform: translateY(4px) scale(0.96);
+		}
+	}
+
+	.cosmoz-tooltip-popover:not(:popover-open) {
+		opacity: 0;
+		transform: translateY(4px) scale(0.96);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.cosmoz-tooltip-popover {
+			transition: none;
+		}
+	}
+`);

package/dist/use-for-tooltip.d.ts

@@ -0,0 +1,17 @@
+import './cosmoz-tooltip-content.js';
+declare global {
+    interface CSSStyleDeclaration {
+        anchorName: string;
+        positionAnchor: string;
+        positionArea: string;
+    }
+}
+interface ForTooltipOptions {
+    for?: string;
+    heading?: string;
+    description?: string;
+    placement?: string;
+    delay?: number;
+}
+export declare const useForTooltip: (host: HTMLElement, opts: ForTooltipOptions) => void;
+export {};

package/dist/use-for-tooltip.js

@@ -0,0 +1,106 @@
+import { render, useEffect, useRef } from '@pionjs/pion';
+import { html } from 'lit-html';
+import { when } from 'lit-html/directives/when.js';
+import './cosmoz-tooltip-content.js';
+import { popoverStyle } from './popover-style.js';
+/**
+ * Design decision: No rich content support in for="" mode.
+ *
+ * Wrapping mode can use <slot name="content"> to project arbitrary HTML
+ * into the tooltip popover. The for="" mode popover lives in the light DOM
+ * (outside the component's shadow root), so slots are not available —
+ * there is no shadow boundary to project through. Content is limited to
+ * the heading and description attributes.
+ */
+const renderContent = (popoverEl, heading, description) => render(html `<cosmoz-tooltip-content>
+			${when(heading, () => html `<strong slot="heading">${heading}</strong>`)}
+			${when(description, () => html `<p slot="description">${description}</p>`)}
+		</cosmoz-tooltip-content>`, popoverEl);
+export const useForTooltip = (host, opts) => {
+    const { for: forAttr, heading, description, placement = 'top', delay = 300, } = opts;
+    const popover = useRef();
+    // eslint-disable-next-line max-statements
+    useEffect(() => {
+        if (!forAttr)
+            return;
+        const root = host.getRootNode();
+        // Adopt shared popover stylesheet on root (idempotent)
+        const sheets = root.adoptedStyleSheets ?? [];
+        if (!sheets.includes(popoverStyle)) {
+            root.adoptedStyleSheets = [...sheets, popoverStyle];
+        }
+        // Create light-DOM popover element
+        const popoverEl = document.createElement('div');
+        popoverEl.setAttribute('popover', 'manual');
+        popoverEl.setAttribute('role', 'tooltip');
+        popoverEl.classList.add('cosmoz-tooltip-popover');
+        // Insert after host to keep it in the same container scope
+        host.after(popoverEl);
+        popover.current = popoverEl;
+        // Render initial content
+        renderContent(popoverEl, heading, description);
+        const selector = `[name="${forAttr}"]`;
+        const anchorName = `--tooltip-anchor-${forAttr}`;
+        let showTimeout;
+        const showForTarget = (target) => {
+            clearTimeout(showTimeout);
+            // Set CSS anchor positioning
+            target.style.anchorName = anchorName;
+            popoverEl.style.positionAnchor = anchorName;
+            popoverEl.style.positionArea = placement;
+            showTimeout = window.setTimeout(() => popoverEl.showPopover(), delay);
+        };
+        const hidePopover = () => {
+            clearTimeout(showTimeout);
+            popoverEl.hidePopover();
+        };
+        const onPointerover = (e) => {
+            const target = e.target.closest?.(selector);
+            if (!target)
+                return;
+            showForTarget(target);
+        };
+        const onPointerout = (e) => {
+            const target = e.target.closest?.(selector);
+            if (!target)
+                return;
+            const related = e.relatedTarget;
+            // Still inside the target element? Ignore.
+            if (related && target.contains(related))
+                return;
+            hidePopover();
+        };
+        const onFocusin = (e) => {
+            const target = e.target.closest?.(selector);
+            if (!target)
+                return;
+            showForTarget(target);
+        };
+        const onFocusout = (e) => {
+            const target = e.target.closest?.(selector);
+            if (!target)
+                return;
+            hidePopover();
+        };
+        root.addEventListener('pointerover', onPointerover);
+        root.addEventListener('pointerout', onPointerout);
+        root.addEventListener('focusin', onFocusin);
+        root.addEventListener('focusout', onFocusout);
+        return () => {
+            clearTimeout(showTimeout);
+            root.removeEventListener('pointerover', onPointerover);
+            root.removeEventListener('pointerout', onPointerout);
+            root.removeEventListener('focusin', onFocusin);
+            root.removeEventListener('focusout', onFocusout);
+            popoverEl.hidePopover();
+            popoverEl.remove();
+            popover.current = undefined;
+        };
+    }, [forAttr, placement, delay]);
+    // Re-render light-DOM popover content when heading/description change
+    useEffect(() => {
+        if (!forAttr || !popover.current)
+            return;
+        renderContent(popover.current, heading, description);
+    }, [heading, description, forAttr]);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neovici/cosmoz-tooltip",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Tooltip component using CSS Anchor Positioning and Popover API",
   "keywords": [
     "web-components",