@ticatec/topside-elements 1.0.0

package/dist/overlay/tooltip/Tooltip.svelte

@@ -0,0 +1,280 @@
+<script lang="ts">
+    import { onMount } from 'svelte';
+    import snarkdown from 'snarkdown';
+    import DOMPurify from 'dompurify';
+
+    interface Props {
+        delay?: number;
+        offset?: number;
+    }
+
+    let {
+        delay = 200,
+        offset = 6
+    }: Props = $props();
+
+    let state = $state({
+        visible: false,
+        message: '',
+        html: '',
+        x: 0,
+        y: 0,
+        position: 'bottom' as 'top' | 'bottom',
+        transform: ''
+    });
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    // snarkdown does not sanitize its output: literal HTML in the source text (e.g. a
+    // data-tip built from user-supplied content) is passed straight through untouched,
+    // and link/image URLs are not scheme-checked, so `[x](javascript:...)` becomes a
+    // live href. DOMPurify sanitizes the rendered HTML, stripping disallowed tags,
+    // event-handler attributes, and dangerous URL schemes while preserving the markdown
+    // formatting the CSS below targets.
+    const DOMPURIFY_CONFIG = {
+        ALLOWED_TAGS: ['p', 'strong', 'em', 's', 'br', 'hr', 'pre', 'code', 'ul', 'ol', 'li', 'blockquote', 'a', 'img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+        ALLOWED_ATTR: ['href', 'src', 'alt', 'class']
+    };
+
+    /** 当前触发 tooltip 的元素。元素被销毁或隐藏后浏览器不再派发 mouseleave，需要由 tooltip 自己收起。 */
+    let activeTarget: HTMLElement | null = null;
+    let observer: MutationObserver | null = null;
+
+    const getTipText = (el: Element | null): string =>
+        (el?.getAttribute('data-tip') || el?.getAttribute('data-tooltip') || '');
+
+    /**
+     * 目标元素是否仍然渲染在页面上。
+     * 元素从 DOM 移除（isConnected === false），或自身/祖先被 display:none、visibility:hidden
+     * 隐藏时，浏览器不会再派发 mouseleave —— 这正是 tooltip 会一直挂在屏幕上的原因。
+     */
+    const isRendered = (el: HTMLElement | null): boolean => {
+        if (el == null || !el.isConnected) return false;
+        const checkVisibility = (el as any).checkVisibility;
+        if (typeof checkVisibility === 'function') {
+            // 现代浏览器：一次性覆盖自身及祖先的 display / visibility / content-visibility
+            return checkVisibility.call(el, {checkVisibilityCSS: true, visibilityProperty: true});
+        }
+        // 兜底（老浏览器 / jsdom）：只能判断元素自身的计算样式
+        const style = window.getComputedStyle(el);
+        return style.display !== 'none' && style.visibility !== 'hidden';
+    };
+
+    const renderTip = (text: string) => {
+        state.message = text;
+        // Parse markdown to HTML, converting \n to actual newlines first
+        const parsedText = text.replace(/\\n/g, '\n');
+        state.html = DOMPurify.sanitize(snarkdown(parsedText), DOMPURIFY_CONFIG);
+    };
+
+    /** 收起 tooltip，并解除对当前目标元素的所有监听 */
+    const hide = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        observer?.disconnect();
+        activeTarget?.removeEventListener('mouseleave', hide);
+        activeTarget = null;
+        state.visible = false;
+    };
+
+    /** 目标元素被移除 / 隐藏 / data-tip 被清空时收起；data-tip 变化时更新内容 */
+    const checkTarget = () => {
+        if (activeTarget == null) return;
+        const text = getTipText(activeTarget);
+        if (!text || !isRendered(activeTarget)) {
+            hide();
+        } else if (state.visible && text !== state.message) {
+            renderTip(text);
+        }
+    };
+
+    const watchTarget = (target: HTMLElement) => {
+        activeTarget = target;
+        target.addEventListener('mouseleave', hide);
+        if (typeof MutationObserver === 'undefined') return;
+        observer ??= new MutationObserver(checkTarget);
+        // 只在 tooltip 处于等待/显示状态时观察，空闲时不产生任何开销
+        observer.observe(document.documentElement ?? document, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['style', 'class', 'hidden', 'data-tip', 'data-tooltip']
+        });
+    };
+
+    // 全局事件监听：利用事件冒泡实现自动绑定
+    onMount(() => {
+        const handleMouseOver = (e: MouseEvent) => {
+            const el = e.target as HTMLElement;
+            if (!el || typeof el.closest !== 'function') return;
+            const target = el.closest('[data-tip], [data-tooltip]') as HTMLElement | null;
+            if (!target) return;
+
+            const text = getTipText(target);
+            if (!text) return;
+
+            // 已经在为同一个元素显示，保持不动（避免在其子元素间移动时闪烁 / 重新定位）
+            if (target === activeTarget && state.visible) return;
+
+            // 清除上一个目标的定时器与监听
+            hide();
+            // 监听该元素的移除 / 隐藏 / 离开，以便收起
+            watchTarget(target);
+
+            // 延迟触发显示
+            timer = setTimeout(() => {
+                timer = null;
+                // 延迟期间目标可能已经被销毁或隐藏
+                if (!isRendered(target)) {
+                    hide();
+                    return;
+                }
+
+                // 获取元素相对于视口的位置，用来精准定位
+                const rect = target.getBoundingClientRect();
+                // 计算触发位置（这里以元素的中心/边缘为基准，比纯鼠标坐标更稳定）
+                const x = rect.left + rect.width / 2;
+                const elementBottom = rect.bottom;
+                const elementTop = rect.top;
+
+                const position = calculateOptimalPosition(x, elementBottom, rect);
+
+                renderTip(getTipText(target) || text);
+                state.position = position;
+                state.transform = getTransformStyle(position, x, elementBottom);
+                state.x = x;
+                // For top position, use element top; for bottom, use element bottom
+                state.y = position === 'top' ? elementTop - offset : elementBottom + offset;
+                state.visible = true;
+            }, delay);
+        };
+
+        // 绑定到 document 上
+        document.addEventListener('mouseover', handleMouseOver);
+        // 指针移出整个文档、窗口失焦、页面滚动（tooltip 是 fixed 定位，滚动后会与目标脱节）
+        document.addEventListener('mouseleave', hide);
+        window.addEventListener('blur', hide);
+        window.addEventListener('scroll', hide, {capture: true, passive: true});
+
+        return () => {
+            document.removeEventListener('mouseover', handleMouseOver);
+            document.removeEventListener('mouseleave', hide);
+            window.removeEventListener('blur', hide);
+            window.removeEventListener('scroll', hide, {capture: true} as any);
+            hide();
+        };
+    });
+
+    const calculateOptimalPosition = (x: number, y: number, rect: DOMRect): 'top' | 'bottom' => {
+        const viewportHeight = window.innerHeight;
+        const hintHeight = 40; // estimated tooltip height
+
+        // Check vertical space - always prefer top/bottom positioning
+        const spaceBelow = viewportHeight - y;
+        const spaceAbove = y;
+
+        // Use bottom if there's more space below than above
+        return spaceBelow >= spaceAbove ? 'bottom' : 'top';
+    };
+
+    const getTransformStyle = (position: 'top' | 'bottom', x: number, y: number): string => {
+        const viewportWidth = window.innerWidth;
+        const tooltipWidth = 200; // estimated max width
+
+        // Vertical position
+        const translateY = position === 'top' ? '-100%' : '0';
+
+        // Horizontal positioning with edge detection
+        let translateX = '-50%'; // default center
+
+        if (x < tooltipWidth / 2) {
+            // Too close to left edge - align left
+            translateX = '0';
+        } else if (x > viewportWidth - tooltipWidth / 2) {
+            // Too close to right edge - align right
+            translateX = '-100%';
+        }
+
+        return `translate(${translateX}, ${translateY})`;
+    };
+</script>
+
+{#if state.visible}
+    <div
+            class="topside-tooltip"
+            style="position: fixed; left: {state.x}px; top: {state.y}px; z-index: var(--topside-z-tooltip, 9999); pointer-events: none; transform: {state.transform}; max-width: 50vw;"
+    >
+        {@html state.html}
+    </div>
+{/if}
+
+<style>
+    .topside-tooltip {
+        padding: var(--topside-tooltip-margin);
+        background-color: var(--topside-tooltip-color-surface, #FFFFE1);
+        color: var(--topside-tooltip-color, #374151);
+        border-radius: var(--topside-tooltip-radius);
+        font-size: 0.9rem;
+        box-shadow: var(--topside-tooltip-box-shadow);
+        opacity: 1;
+        transition: opacity 0.15s ease-in-out;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+
+    /* Markdown elements styling */
+    .topside-tooltip :global(p) {
+        margin: 0;
+    }
+
+    .topside-tooltip :global(p + p) {
+        margin-top: 0.5em;
+    }
+
+    .topside-tooltip :global(strong) {
+        font-weight: 600;
+    }
+
+    .topside-tooltip :global(em) {
+        font-style: italic;
+    }
+
+    .topside-tooltip :global(code) {
+        background: rgba(0, 0, 0, 0.1);
+        padding: 1px 4px;
+        border-radius: 3px;
+        font-family: monospace;
+        font-size: 0.9em;
+    }
+
+    .topside-tooltip :global(ul),
+    .topside-tooltip :global(ol) {
+        margin: 0.25em 0;
+        padding-left: 1.2em;
+    }
+
+    .topside-tooltip :global(li) {
+        margin: 0.1em 0;
+    }
+
+    .topside-tooltip :global(a) {
+        color: inherit;
+        text-decoration: underline;
+    }
+
+    .topside-tooltip :global(blockquote) {
+        margin: 0.25em 0;
+        padding-left: 0.75em;
+        border-left: 3px solid currentColor;
+        opacity: 0.8;
+    }
+
+    .topside-tooltip :global(hr) {
+        border: none;
+        border-top: 1px solid currentColor;
+        opacity: 0.3;
+        margin: 0.5em 0;
+    }
+</style>

package/dist/overlay/tooltip/Tooltip.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    delay?: number;
+    offset?: number;
+}
+declare const Tooltip: import("svelte").Component<Props, {}, "">;
+type Tooltip = ReturnType<typeof Tooltip>;
+export default Tooltip;

package/dist/overlay/tooltip/index.d.ts

@@ -0,0 +1,2 @@
+import Tooltip from "./Tooltip.svelte";
+export default Tooltip;

package/dist/overlay/tooltip/index.js

@@ -0,0 +1,2 @@
+import Tooltip from "./Tooltip.svelte";
+export default Tooltip;