@ticatec/uniface-element 5.0.1 → 5.0.3

package/dist/overlay/common/FloatingPanel.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
     import {type Snippet} from "svelte";
+    import {outsideClick} from "./outsideClick";
 
     interface Props {
         /** 锚定目标元素；面板会出现在目标下方 */
@@ -33,14 +34,6 @@
         };
     };
 
-    const handleClickOutside = (e: MouseEvent) => {
-        if (!panelEl) return;
-        const t = e.target as Node;
-        if (panelEl.contains(t)) return;
-        if (target && target.contains(t)) return;
-        onclose?.();
-    };
-
     // 把面板挂到 body 下，跳出任何父容器的 overflow / stacking context。
     // 不依赖 Portal 库，直接 DOM API。
     const mountToBody = (node: HTMLElement) => {
@@ -55,12 +48,10 @@
     $effect(() => {
         if (!panelEl) return;
         updatePosition();
-        document.addEventListener('click', handleClickOutside, true);
         window.addEventListener('resize', updatePosition);
         // 捕获阶段监听所有 scroll（包括内部容器），保证面板跟随目标
         window.addEventListener('scroll', updatePosition, true);
         return () => {
-            document.removeEventListener('click', handleClickOutside, true);
             window.removeEventListener('resize', updatePosition);
             window.removeEventListener('scroll', updatePosition, true);
         };
@@ -70,8 +61,9 @@
 <div
     bind:this={panelEl}
     class="floating-panel {className}"
-    style="position: fixed; top: {coords.top}px; left: {coords.left}px; z-index: 1000;"
+    style="position: fixed; top: {coords.top}px; left: {coords.left}px; z-index: var(--uniface-z-floating-panel, 1010);"
     use:mountToBody
+    use:outsideClick={{ callback: () => onclose?.(), exclude: [target] }}
 >
     {@render children?.()}
 </div>

package/dist/overlay/common/FullscreenOverlay.svelte

@@ -1,17 +1,41 @@
 <script lang="ts">
 
     import Portal from "svelte-portal";
+    import {onMount} from "svelte";
+    import type {Snippet} from "svelte";
+    import {acquireScrollLock} from "./scrollLock";
+    import {registerEscapeHandler} from "./escapeClose";
 
-    export let visible: boolean = false;
+    interface Props {
+        visible?: boolean;
+        children?: Snippet;
+    }
 
+    let {visible = $bindable(false), children}: Props = $props();
+
+    // Regression: this modal surface previously never locked body scroll or
+    // closed on Escape.
+    onMount(() => {
+        const release = acquireScrollLock();
+        const unregisterEscape = registerEscapeHandler(() => { visible = false; });
+        return () => {
+            release();
+            unregisterEscape();
+        };
+    });
 </script>
 
 {#if visible}
     <Portal target="body">
         <div class="uniface-mask-overlay">
+            <!-- Backdrop click-to-close convenience only; aria-hidden must not be used
+                 here since it would hide the real, arbitrary interactive content
+                 rendered via `children` from assistive tech. -->
+            <!-- svelte-ignore a11y_click_events_have_key_events -->
+            <!-- svelte-ignore a11y_no_static_element_interactions -->
             <div style="position: relative; width: 100%; height: 100%; overflow: hidden"
-                 on:click={()=>{visible = false}} aria-hidden="true">
-                <slot></slot>
+                 onclick={()=>{visible = false}}>
+                {@render children?.()}
             </div>
         </div>
     </Portal>

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

@@ -1,29 +1,8 @@
-interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
-        $$bindings?: Bindings;
-    } & Exports;
-    (internal: unknown, props: Props & {
-        $$events?: Events;
-        $$slots?: Slots;
-    }): Exports & {
-        $set?: any;
-        $on?: any;
-    };
-    z_$$bindings?: Bindings;
-}
-type $$__sveltets_2_PropsWithChildren<Props, Slots> = Props & (Slots extends {
-    default: any;
-} ? Props extends Record<string, never> ? any : {
-    children?: any;
-} : {});
-declare const FullscreenOverlay: $$__sveltets_2_IsomorphicComponent<$$__sveltets_2_PropsWithChildren<{
+import type { Snippet } from "svelte";
+interface Props {
     visible?: boolean;
-}, {
-    default: {};
-}>, {
-    [evt: string]: CustomEvent<any>;
-}, {
-    default: {};
-}, {}, string>;
-type FullscreenOverlay = InstanceType<typeof FullscreenOverlay>;
+    children?: Snippet;
+}
+declare const FullscreenOverlay: import("svelte").Component<Props, {}, "visible">;
+type FullscreenOverlay = ReturnType<typeof FullscreenOverlay>;
 export default FullscreenOverlay;

package/dist/overlay/common/ModalPopover.svelte

@@ -1,6 +1,8 @@
 <script lang="ts">
     import {type Snippet, onMount} from "svelte";
     import Portal from "svelte-portal";
+    import {acquireScrollLock} from "./scrollLock";
+    import {registerEscapeHandler} from "./escapeClose";
 
     interface Props {
         visible?: boolean;
@@ -20,15 +22,29 @@
 
     onMount(() => {
         setTimeout(() => hidden = false, 100);
+        // Regression: this modal surface previously never locked body scroll
+        // or closed on Escape.
+        const release = acquireScrollLock();
+        const unregisterEscape = registerEscapeHandler(() => {
+            if (canClose) visible = false;
+        });
+        return () => {
+            release();
+            unregisterEscape();
+        };
     });
 </script>
 
 {#if visible}
     <Portal target="body">
         <div class="uniface-mask-overlay" class:hidden data-theme={theme}>
+            <!-- Backdrop click-to-close convenience only; aria-hidden must not be used
+                 here since it would hide the real, arbitrary interactive content
+                 rendered via `children` from assistive tech. -->
+            <!-- svelte-ignore a11y_click_events_have_key_events -->
+            <!-- svelte-ignore a11y_no_static_element_interactions -->
             <div class="uniface-mask-center"
-                 onclick={() => { if (canClose) visible = false; }}
-                 aria-hidden="true">
+                 onclick={() => { if (canClose) visible = false; }}>
                 <div style="flex: 0 0 auto">
                     {@render children()}
                 </div>

package/dist/overlay/common/Popover.svelte

@@ -1,6 +1,9 @@
 <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;
@@ -27,25 +30,6 @@
         children
     }: Props = $props();
 
-    export function outerClick(node: HTMLElement, callback: () => void) {
-        const handleClick = (event: MouseEvent) => {
-            // 如果点击目标不在node内，则触发回调
-            if (!node.contains(event.target as Node)) {
-                callback();
-            }
-        };
-
-        // 监听全局点击事件（useCapture=true，避免事件冒泡造成的问题）
-        document.addEventListener('click', handleClick, true);
-
-        // action 必须返回一个对象，可以选实现 update 和 destroy
-        return {
-            destroy() {
-                document.removeEventListener('click', handleClick, true);
-            }
-        };
-    }
-
     let position = $state({top: 0, left: 0, width: 0, height: 0});
     let hidden = $state(true);
     let width = $state(0);
@@ -70,18 +54,19 @@
             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') {
-                if (position.left + position.width < width) {
-                    horzPos = "left: 0";
-                } else {
-                    horzPos = `right: 0`;
-                }
+                horzPos = (position.left + width > w) ? "right: 0" : "left: 0";
             } else {
-                if (position.left + position.width > width) {
-                    horzPos = `right: 0`;
-                } else {
-                    horzPos = "left: 0";
-                }
+                horzPos = (position.left + position.width - width < 0) ? "left: 0" : "right: 0";
             }
             if (autoFit) {
                 horzPos += '; width: 100%'
@@ -89,45 +74,59 @@
         }
     }
 
-    const checkPosition = () => {
-        if (!hidden && target) {
-            const rect = target.getBoundingClientRect();
-            if (rect.top != position.top || rect.left != position.left) {
-                updatePosition();
-            }
-        }
-    }
-
+    // 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 overflowY = window.getComputedStyle(document.body).overflowY;
-        document.body.style.overflowY = 'hidden';
-        setTimeout(() => {
-            updatePosition();
+        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;
-            setTimeout(() => {
-                document.body.style.overflowY = overflowY;
-            }, 50);
+            scheduleUpdate();
         }, 50);  // 延迟显示 portal
-        window.addEventListener("resize", updatePosition);
+        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", updatePosition, true);
-        const interval = setInterval(checkPosition, 10); // 每 10ms 检测一次
-        const resizeObserver = new ResizeObserver(entries => {
-            for (let entry of entries) {
-                updatePosition();
-            }
-        });
+        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 () => {
-            window.removeEventListener("resize", updatePosition);
-            window.removeEventListener("scroll", updatePosition, true);
+            clearTimeout(showTimeout);
+            clearTimeout(releaseTimeout);
+            release();
+            unregisterEscape();
+            window.removeEventListener("resize", scheduleUpdate);
+            window.removeEventListener("scroll", scheduleUpdate, true);
             resizeObserver.disconnect();
-            clearInterval(interval);
+            if (rafId != null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+            }
         };
     });
 
@@ -140,7 +139,7 @@
 <Portal target="body">
     <div class="uniface-popover-wrapper" class:hidden={hidden}
          style="{vertPos}; height: auto; left: {position.left-margin}px; width: {position.width}px; ">
-        <div class="uniface-popover" use:outerClick={close}>
+        <div class="uniface-popover" use:outsideClick={close}>
             <div bind:this={contentPanel} style="{horzPos}">
                 <div class="contents" style="{style}">
                     <div class="contents-inner {bodyClass}">

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

@@ -11,10 +11,6 @@ interface Props {
     bodyClass?: string;
     children?: Snippet;
 }
-declare const Popover: import("svelte").Component<Props, {
-    outerClick: (node: HTMLElement, callback: () => void) => {
-        destroy(): void;
-    };
-}, "">;
+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,27 @@
+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.
+ *
+ * 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,45 @@
+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.
+ *
+ * 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;
+        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
+ * uniface-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;