@ticatec/topside-elements 1.0.0

package/dist/overlay/common/Popover.svelte

@@ -0,0 +1,155 @@
+<script lang="ts">
+    import {onMount, type Snippet} from 'svelte';
+    import Portal from "svelte-portal";
+    import {acquireScrollLock} from "./scrollLock";
+    import {outsideClick} from "./outsideClick";
+    import {registerEscapeHandler} from "./escapeClose";
+
+    interface Props {
+        style?: string;
+        target: HTMLElement;
+        align?: 'left' | 'right' | 'center';
+        autoFit?: boolean;
+        theme?: string;
+        margin?: number;
+        onclose?: () => void;
+        /** 附加到 .contents-inner 上的 class（用于覆盖 overflow 等样式） */
+        /** 内容容器附加 class */
+        body$class?: string;
+        children?: Snippet;
+    }
+
+    let {
+        onclose,
+        style,
+        target,
+        theme,
+        align = 'left',
+        autoFit = true,
+        margin = 0,
+        body$class = '',
+        children
+    }: Props = $props();
+
+    let position = $state({top: 0, left: 0, width: 0, height: 0});
+    let hidden = $state(true);
+    let width = $state(0);
+    let vertPos = $state('');
+    let horzPos = $state('');
+    let contentPanel: any;
+
+    let w = $state(0);
+    let h = $state(0);
+
+
+    const updatePosition = () => {
+        if (!hidden && target) {
+            let rect = target.getBoundingClientRect();
+            position = {
+                top: rect.top,
+                left: rect.left,
+                width: rect.width,
+                height: rect.height
+            };
+            rect = contentPanel.getBoundingClientRect();
+            width = rect.width;
+            vertPos = (h - position.top - position.height) > rect.height ? `top: ${(position.top + position.height + 1)}px` : `top: ${position.top - rect.height - 1}px`;
+
+            // Regression fix: this used to compare an absolute viewport
+            // x-coordinate (position.left/position.left+position.width) against
+            // the popup's own rendered width, which doesn't express "is there
+            // room to the right/left in the viewport" at all — for a narrow
+            // anchor near the left edge it would almost always pick "left"
+            // regardless of how wide the popup actually was, clipping wide
+            // content (e.g. a multi-column cascade picker) against the right
+            // edge of the window instead of flipping side. Compare against the
+            // actual viewport width `w` instead.
+            if (align == 'left') {
+                horzPos = (position.left + width > w) ? "right: 0" : "left: 0";
+            } else {
+                horzPos = (position.left + position.width - width < 0) ? "left: 0" : "right: 0";
+            }
+            if (autoFit) {
+                horzPos += '; width: 100%'
+            }
+        }
+    }
+
+    // Coalesces bursts of triggers (resize + scroll + ResizeObserver firing in
+    // the same frame) into a single updatePosition() call instead of one per
+    // listener, so repositioning does one layout read/write pass per frame.
+    let rafId: number | null = null;
+    const scheduleUpdate = () => {
+        if (rafId != null) return;
+        rafId = requestAnimationFrame(() => {
+            rafId = null;
+            updatePosition();
+        });
+    };
+
+    onMount(() => {
+        const release = acquireScrollLock();
+        // Registered later than any overlay already open "under" this popover
+        // (e.g. a dialog), so this is topmost on the shared Escape stack and
+        // closes first.
+        const unregisterEscape = registerEscapeHandler(() => close());
+
+        // hidden must flip before updatePosition() — updatePosition() is a no-op
+        // while hidden, so calling it first (as this used to) skipped the initial
+        // positioning entirely and left the popover rendered at (0,0) until the
+        // next scroll/resize.
+        const showTimeout = setTimeout(() => {
+            hidden = false;
+            scheduleUpdate();
+        }, 50);  // 延迟显示 portal
+        const releaseTimeout = setTimeout(release, 100);
+        window.addEventListener("resize", scheduleUpdate);
+        // capture:true — scroll events don't bubble, so a listener on the bubble phase
+        // only ever sees window/document-level scroll. Capturing catches scroll on any
+        // nested scrollable ancestor (a table body, a dialog's scroll area, etc.) too,
+        // which is what keeps the popover pinned to its anchor while that container
+        // scrolls. Matches the pattern in FloatingPanel.svelte.
+        window.addEventListener("scroll", scheduleUpdate, true);
+        // Observing both the anchor and the popover body catches anchor-size changes
+        // and content-size changes, replacing the unconditional 10ms poll that used
+        // to run regardless of visibility/tab focus and forced a layout every tick.
+        const resizeObserver = new ResizeObserver(scheduleUpdate);
+        resizeObserver.observe(contentPanel);
+        resizeObserver.observe(target);
+        return () => {
+            clearTimeout(showTimeout);
+            clearTimeout(releaseTimeout);
+            release();
+            unregisterEscape();
+            window.removeEventListener("resize", scheduleUpdate);
+            window.removeEventListener("scroll", scheduleUpdate, true);
+            resizeObserver.disconnect();
+            if (rafId != null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+        };
+    });
+
+    const close = () => {
+        onclose?.();
+    };
+
+</script>
+<svelte:window bind:innerWidth={w} bind:innerHeight={h}/>
+<Portal target="body">
+    <div class="topside-popover-wrapper" class:hidden={hidden}
+         style="{vertPos}; height: auto; left: {position.left-margin}px; width: {position.width}px; ">
+        <div class="topside-popover" use:outsideClick={close}>
+            <div bind:this={contentPanel} style="{horzPos}">
+                <div class="contents" style="{style}">
+                    <div class="contents-inner {body$class}">
+                        {#if children}
+                            {@render children()}
+                        {/if}
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</Portal>

package/dist/overlay/common/Popover.svelte.d.ts

@@ -0,0 +1,17 @@
+import { type Snippet } from 'svelte';
+interface Props {
+    style?: string;
+    target: HTMLElement;
+    align?: 'left' | 'right' | 'center';
+    autoFit?: boolean;
+    theme?: string;
+    margin?: number;
+    onclose?: () => void;
+    /** 附加到 .contents-inner 上的 class（用于覆盖 overflow 等样式） */
+    /** 内容容器附加 class */
+    body$class?: string;
+    children?: Snippet;
+}
+declare const Popover: import("svelte").Component<Props, {}, "">;
+type Popover = ReturnType<typeof Popover>;
+export default Popover;

package/dist/overlay/common/escapeClose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared, stack-aware "close on Escape" primitive.
+ *
+ * Previously each modal-ish surface either reinvented this (Dialog's
+ * `svelte:window onkeydown` with a hand-rolled DOM query to special-case
+ * "defer to an open Popover first"), relied on the browser (MessageBox's
+ * native <dialog> — left alone here, it already does this correctly) or
+ * didn't handle Escape at all (Popover, ModalPopover, FullscreenOverlay,
+ * Drawer).
+ *
+ * Registered handlers form a stack. Only the topmost (most recently
+ * registered, i.e. most recently opened) handler runs on Escape — this is
+ * what "close the innermost open overlay first" means for nested overlays,
+ * and it replaces Dialog's ad-hoc "is a popover open" DOM query with the
+ * same mechanism every overlay uses.
+ */
+type EscapeHandler = () => void;
+/** Push a handler onto the stack; returns an unregister function. */
+export declare function registerEscapeHandler(handler: EscapeHandler): () => void;
+/**
+ * Svelte action form: `use:escapeClose={onclose}`. Registers for as long as
+ * the node is mounted.
+ */
+export declare function escapeClose(_node: HTMLElement, onclose: EscapeHandler): {
+    update(newOnClose: EscapeHandler): void;
+    destroy(): void;
+};
+export {};

package/dist/overlay/common/escapeClose.js

@@ -0,0 +1,47 @@
+const stack = [];
+let listenerInstalled = false;
+function handleKeyDown(e) {
+    if (e.key !== 'Escape' && e.key !== 'Esc')
+        return;
+    const top = stack[stack.length - 1];
+    if (!top)
+        return;
+    e.preventDefault();
+    top();
+}
+function ensureListener() {
+    if (listenerInstalled || typeof window === 'undefined')
+        return;
+    window.addEventListener('keydown', handleKeyDown);
+    listenerInstalled = true;
+}
+/** Push a handler onto the stack; returns an unregister function. */
+export function registerEscapeHandler(handler) {
+    ensureListener();
+    stack.push(handler);
+    let registered = true;
+    return () => {
+        if (!registered)
+            return;
+        registered = false;
+        const idx = stack.lastIndexOf(handler);
+        if (idx !== -1)
+            stack.splice(idx, 1);
+    };
+}
+/**
+ * Svelte action form: `use:escapeClose={onclose}`. Registers for as long as
+ * the node is mounted.
+ */
+export function escapeClose(_node, onclose) {
+    let unregister = registerEscapeHandler(onclose);
+    return {
+        update(newOnClose) {
+            unregister();
+            unregister = registerEscapeHandler(newOnClose);
+        },
+        destroy() {
+            unregister();
+        }
+    };
+}

package/dist/overlay/common/focusTrap.d.ts

@@ -0,0 +1,8 @@
+export interface FocusTrapOptions {
+    /** Set false to make this a no-op — lets callers keep the action wired up
+     *  unconditionally while still gating the behavior on a reactive value. */
+    enabled?: boolean;
+}
+export declare function focusTrap(node: HTMLElement, options?: FocusTrapOptions): {
+    destroy(): void;
+};

package/dist/overlay/common/focusTrap.js

@@ -0,0 +1,83 @@
+/**
+ * Shared focus-trap + focus-restore Svelte action for modal-like surfaces.
+ *
+ * Previously: Dialog and MessageBox each did a `setTimeout` +
+ * `querySelector('button')` to focus *something* on open, and nothing
+ * anywhere saved/restored the element that had focus before the overlay
+ * opened — closing a dialog silently dropped focus back to the document
+ * body instead of wherever the user was before opening it.
+ *
+ * `use:focusTrap` on a modal's root/box element will:
+ *  - save `document.activeElement` on mount
+ *  - move focus to the first focusable descendant (or the node itself)
+ *  - keep Tab/Shift+Tab cycling within the node's focusable descendants
+ *  - restore focus to the saved element on destroy
+ *
+ * Not applied to ContextMenuPanel, which already has its own working
+ * roving-focus/aria-activedescendant pattern more appropriate for a
+ * `role="menu"` — a second, competing trap there would fight it rather than
+ * help. Not applied to MessageBox, whose native <dialog> + showModal()
+ * already gives correct trap/restore behavior from the browser for free.
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'textarea:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])'
+].join(',');
+function getFocusable(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+}
+export function focusTrap(node, options = {}) {
+    if (options.enabled === false) {
+        return { destroy() { } };
+    }
+    const previouslyFocused = document.activeElement;
+    const focusFirst = () => {
+        const focusable = getFocusable(node);
+        (focusable[0] ?? node).focus();
+    };
+    // Deferred one tick: the trap is typically mounted before children with
+    // their own autofocus/initial-value logic have settled.
+    const raf = requestAnimationFrame(focusFirst);
+    const handleKeyDown = (e) => {
+        if (e.key !== 'Tab')
+            return;
+        const focusable = getFocusable(node);
+        if (focusable.length === 0) {
+            e.preventDefault();
+            return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey) {
+            if (active === first || !node.contains(active)) {
+                e.preventDefault();
+                last.focus();
+            }
+        }
+        else {
+            if (active === last || !node.contains(active)) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+    };
+    node.addEventListener('keydown', handleKeyDown);
+    return {
+        destroy() {
+            cancelAnimationFrame(raf);
+            node.removeEventListener('keydown', handleKeyDown);
+            // Only restore if focus is still somewhere inside this trap (or on
+            // the body) — if the app already moved focus elsewhere on its own
+            // (e.g. opening another overlay), don't fight it.
+            const active = document.activeElement;
+            if (previouslyFocused && (active == null || active === document.body || node.contains(active))) {
+                previouslyFocused.focus();
+            }
+        }
+    };
+}

package/dist/overlay/common/mountSingleton.d.ts

@@ -0,0 +1,28 @@
+import { type Component } from 'svelte';
+/**
+ * Attempts to mount `component` to `document.body` once. Returns whether it
+ * succeeded. SSR-safe (no-ops when window/document aren't available) and
+ * swallows mount errors (e.g. test environments where Svelte's client mount
+ * is bypassed) rather than throwing — this was silent-fallback-by-design in
+ * every controller that had its own copy of this check.
+ */
+export declare function mountToBody(component: Component): boolean;
+/**
+ * Shared "lazy-mount this controller's panel to document.body on first
+ * use, then reuse the same instance" helper.
+ *
+ * Previously each overlay controller singleton (Indicator, Toast,
+ * ContextMenu, MessageBox) carried an identical `panelMounted` flag +
+ * `ensureMounted()` pair. This is the one implementation; call the returned
+ * function at the start of whatever triggers showing the overlay (`show()`,
+ * etc.) — it's idempotent, so calling it on every show is fine. Pass the panel
+ * as a thunk (`() => Panel`) so the circular controller ⇄ panel import is resolved lazily.
+ *
+ * DialogManager is intentionally NOT migrated to this: its `<DialogBoard>`
+ * self-reports whether it's already mounted (so a board the *consumer*
+ * placed manually in their app root and the manager's own auto-mount don't
+ * both render), which needs the mounted flag to be externally observable —
+ * a different shape than this memoized-closure helper provides. It reuses
+ * `mountToBody` directly instead.
+ */
+export declare function createSingletonMounter(component: () => Component): () => void;

package/dist/overlay/common/mountSingleton.js

@@ -0,0 +1,48 @@
+import { mount } from 'svelte';
+/**
+ * Attempts to mount `component` to `document.body` once. Returns whether it
+ * succeeded. SSR-safe (no-ops when window/document aren't available) and
+ * swallows mount errors (e.g. test environments where Svelte's client mount
+ * is bypassed) rather than throwing — this was silent-fallback-by-design in
+ * every controller that had its own copy of this check.
+ */
+export function mountToBody(component) {
+    if (typeof window === 'undefined' || typeof document === 'undefined' || !document.body) {
+        return false;
+    }
+    try {
+        mount(component, { target: document.body });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Shared "lazy-mount this controller's panel to document.body on first
+ * use, then reuse the same instance" helper.
+ *
+ * Previously each overlay controller singleton (Indicator, Toast,
+ * ContextMenu, MessageBox) carried an identical `panelMounted` flag +
+ * `ensureMounted()` pair. This is the one implementation; call the returned
+ * function at the start of whatever triggers showing the overlay (`show()`,
+ * etc.) — it's idempotent, so calling it on every show is fine. Pass the panel
+ * as a thunk (`() => Panel`) so the circular controller ⇄ panel import is resolved lazily.
+ *
+ * DialogManager is intentionally NOT migrated to this: its `<DialogBoard>`
+ * self-reports whether it's already mounted (so a board the *consumer*
+ * placed manually in their app root and the manager's own auto-mount don't
+ * both render), which needs the mounted flag to be externally observable —
+ * a different shape than this memoized-closure helper provides. It reuses
+ * `mountToBody` directly instead.
+ */
+export function createSingletonMounter(component) {
+    let mounted = false;
+    return () => {
+        if (mounted)
+            return;
+        // 组件延迟到首次 show 时才取：控制器与它的 Panel 互相 import（Panel 里要调控制器方法），
+        // 模块顶层直接引用 Panel 会在 Panel 先被加载时撞上 TDZ（"Cannot access 'XxxPanel' before initialization"）
+        mounted = mountToBody(component());
+    };
+}

package/dist/overlay/common/outsideClick.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared "click outside this element" Svelte action.
+ *
+ * Previously reimplemented near-identically in Popover.svelte (`outerClick`)
+ * and FloatingPanel.svelte (`handleClickOutside` + a manual
+ * document.addEventListener), plus a third, unused variant in
+ * topside-utils.ts. This is the one canonical implementation; new
+ * outside-click needs should use this rather than adding a fourth.
+ *
+ * Uses the capture phase so it fires before the click can be stopped by a
+ * descendant's own handler, and so nested overlays (a popover inside a
+ * dialog) each see the click regardless of bubbling order.
+ */
+export type OutsideClickOptions = (() => void) | {
+    callback: () => void;
+    /**
+     * Elements that should NOT count as "outside" even though they're
+     * not inside `node` — typically the trigger/anchor element, whose
+     * own click handler usually toggles the overlay open. Without this,
+     * clicking the trigger to close would fire this callback first and
+     * then the trigger's own handler would immediately reopen it.
+     */
+    exclude?: Array<HTMLElement | null | undefined>;
+};
+export declare function outsideClick(node: HTMLElement, options: OutsideClickOptions): {
+    update(newOptions: OutsideClickOptions): void;
+    destroy(): void;
+};

package/dist/overlay/common/outsideClick.js

@@ -0,0 +1,20 @@
+export function outsideClick(node, options) {
+    let opts = typeof options === 'function' ? { callback: options } : options;
+    const handleClick = (event) => {
+        const t = event.target;
+        if (node.contains(t))
+            return;
+        if (opts.exclude?.some(el => el && el.contains(t)))
+            return;
+        opts.callback();
+    };
+    document.addEventListener('click', handleClick, true);
+    return {
+        update(newOptions) {
+            opts = typeof newOptions === 'function' ? { callback: newOptions } : newOptions;
+        },
+        destroy() {
+            document.removeEventListener('click', handleClick, true);
+        }
+    };
+}

package/dist/overlay/common/scrollLock.d.ts

@@ -0,0 +1,8 @@
+export declare function lockBodyScroll(): void;
+export declare function unlockBodyScroll(): void;
+/**
+ * Convenience wrapper for the common "lock on mount, unlock on cleanup"
+ * pattern, idempotent against being released more than once (e.g. both a
+ * timer and an unmount cleanup racing to call it).
+ */
+export declare function acquireScrollLock(): () => void;

package/dist/overlay/common/scrollLock.js

@@ -0,0 +1,49 @@
+/**
+ * Shared, reference-counted body scroll-lock.
+ *
+ * Any number of overlays (Popover, Dialog, Drawer, ModalPopover,
+ * FullscreenOverlay, ...) can call lockBodyScroll()/unlockBodyScroll()
+ * independently, in any open/close order, without one overlay's close
+ * clobbering another still-open overlay's lock. Only the very first lock
+ * captures the pre-lock overflowY value, and only the transition back to
+ * zero open locks restores it — this is what makes stacking safe.
+ *
+ * Originally lived inline in Popover.svelte; generalized here so every
+ * modal-ish overlay in the library shares one lock instead of each
+ * reinventing (or omitting) its own save/restore.
+ */
+let lockCount = 0;
+let savedOverflowY = null;
+export function lockBodyScroll() {
+    if (typeof document === 'undefined')
+        return;
+    if (lockCount === 0) {
+        savedOverflowY = window.getComputedStyle(document.body).overflowY;
+        document.body.style.overflowY = 'hidden';
+    }
+    lockCount++;
+}
+export function unlockBodyScroll() {
+    if (typeof document === 'undefined')
+        return;
+    lockCount = Math.max(0, lockCount - 1);
+    if (lockCount === 0 && savedOverflowY != null) {
+        document.body.style.overflowY = savedOverflowY;
+        savedOverflowY = null;
+    }
+}
+/**
+ * Convenience wrapper for the common "lock on mount, unlock on cleanup"
+ * pattern, idempotent against being released more than once (e.g. both a
+ * timer and an unmount cleanup racing to call it).
+ */
+export function acquireScrollLock() {
+    lockBodyScroll();
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        unlockBodyScroll();
+    };
+}

package/dist/overlay/common/topside-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function clickOutside(node: Node): {
+    destroy(): void;
+};

package/dist/overlay/common/topside-utils.js

@@ -0,0 +1,19 @@
+export function clickOutside(node) {
+    const handleClick = (event) => {
+        if (node && !node.contains(event.target) && !event.defaultPrevented) {
+            node.dispatchEvent(new CustomEvent('outerClick', {
+                bubbles: true, // 通常自定义事件要冒泡，方便捕获
+                cancelable: true, // 可取消
+                detail: { originalEvent: event } // 可选：传递原始事件信息
+            }));
+            event.stopPropagation();
+            event.preventDefault();
+        }
+    };
+    document.addEventListener('click', handleClick, true);
+    return {
+        destroy() {
+            document.removeEventListener('click', handleClick, true);
+        }
+    };
+}

package/dist/overlay/common/utils.d.ts

@@ -0,0 +1,13 @@
+declare const _default: {
+    isEmpty: (s: any) => boolean;
+    getNumberValue: (n: any) => number | null;
+    getStringValue: (n: any) => string | null;
+    sleep: (n: number) => Promise<void>;
+    getNumberRegex: (precision: number | null | undefined, allowNegative: boolean) => string;
+    isValidNumber: (n: number, precision: number | null | undefined, allowNegative: boolean, max?: number | null, min?: number | null) => boolean;
+    formatNumber: (n: number | string | null, precision: number | null | undefined) => string;
+    filterFiles: (files: Array<File>, accept: string) => File[];
+    getNestedObject: (obj: any, keys: string[]) => any;
+    getNestedValue: (data: any, key: string) => any;
+};
+export default _default;