@openviking/react 0.1.2 → 0.1.3

package/dist/n~0.js

@@ -1,6 +1,8 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { cloneElement, forwardRef, useCallback, useEffect, useId, useImperativeHandle, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { FolderOpenIcon, FolderIcon, ChevronRightIcon, DocumentIcon } from "./k~0.js";
+import { useOverlayPosition } from "./o~0.js";
 function FileTreeFolderIcon({ open }) {
     return /*#__PURE__*/ jsxs("span", {
         className: "ov-file-tree__folder",
@@ -59,6 +61,12 @@ const USER_SCOPE_KEY_BY_SEGMENT = {
     sessions: 'sessions',
     skills: 'skills'
 };
+const AGENT_KEY_BY_SEGMENT = {
+    endpoints: 'agentEndpoints',
+    payments: 'agentPayments',
+    skills: 'agentSkills',
+    tools: 'agentTools'
+};
 const MEMORY_KEY_BY_SEGMENT = {
     'profile.md': 'profile',
     preferences: 'preferences',
@@ -96,6 +104,10 @@ function resolveFileTreeInfoKey(uri) {
         if ('resources' === first) return 'sharedResources';
         return ROOT_KEY_BY_SEGMENT[first] ?? null;
     }
+    if (('agent' === first || 'agents' === first) && 2 === segments.length) {
+        const second = segments[1];
+        return second ? AGENT_KEY_BY_SEGMENT[second] ?? null : null;
+    }
     return null;
 }
 function showsInlineDescription(key) {
@@ -120,6 +132,10 @@ const DESCRIPTION = {
     experiences: 'Execution experience distilled automatically',
     sharedResources: 'External resources the agent can reference',
     agentRoot: 'Agent capabilities, tools and experience',
+    agentEndpoints: 'Communication endpoints shared across the account',
+    agentPayments: 'Payment capabilities shared across the account',
+    agentSkills: 'Skill definitions callable across the account',
+    agentTools: 'Tool configuration shared across the account',
     memoryRoot: 'Long-term memory and accumulated information',
     resourceRoot: 'External knowledge the agent can reference',
     sessionRoot: 'Raw session records of the user',
@@ -141,7 +157,11 @@ const TRIGGER_BEHAVIOR = {
     cases: 'A session with a clear task and an evaluable execution result is committed',
     trajectories: 'A task containing decisions, tool calls or multi-step execution is committed',
     experiences: 'Distilled from task cases and execution trajectories',
-    sharedResources: 'Imported material, uploaded to a shared resource space'
+    sharedResources: 'Imported material, uploaded to a shared resource space',
+    agentEndpoints: 'Configured when an integration endpoint is registered for the account',
+    agentPayments: 'Configured when a payment capability is enabled for the account',
+    agentSkills: 'Installed or imported as a shared skill available to every agent',
+    agentTools: 'Configured when a tool is registered for the account'
 };
 const DEFAULT_INFO_LABELS = {
     description: DESCRIPTION,
@@ -160,6 +180,131 @@ function resolveInfoCopy(key, hostLabels) {
         triggerBehavior: triggerBehavior || void 0
     };
 }
+function useMergedRef(ref, target) {
+    return useCallback((node)=>{
+        target.current = node;
+        if ('function' == typeof ref) ref(node);
+        else if (ref) ref.current = node;
+    }, [
+        ref,
+        target
+    ]);
+}
+function Popover({ children, content, placement = 'right', trigger = 'hover', delay = 300, disabled = false, className, style, onOpenChange }) {
+    const [open, setOpen] = useState(false);
+    const triggerRef = useRef(null);
+    const timerRef = useRef(void 0);
+    const [surfaceNode, setSurfaceNode] = useState(null);
+    const id = useId();
+    const position = useOverlayPosition(open, triggerRef, surfaceNode, placement);
+    const change = useCallback((next)=>{
+        setOpen(next);
+        onOpenChange?.(next);
+    }, [
+        onOpenChange
+    ]);
+    const clearTimer = useCallback(()=>{
+        if (void 0 !== timerRef.current) {
+            window.clearTimeout(timerRef.current);
+            timerRef.current = void 0;
+        }
+    }, []);
+    useEffect(()=>clearTimer, [
+        clearTimer
+    ]);
+    useEffect(()=>{
+        if (disabled) {
+            clearTimer();
+            setOpen(false);
+        }
+    }, [
+        disabled,
+        clearTimer
+    ]);
+    useEffect(()=>{
+        if (!open || 'click' !== trigger) return;
+        const onPointerDown = (event)=>{
+            const target = event.target;
+            if (surfaceNode?.contains(target) || triggerRef.current?.contains(target)) return;
+            change(false);
+        };
+        const onKeyDown = (event)=>{
+            if ('Escape' === event.key) change(false);
+        };
+        document.addEventListener('mousedown', onPointerDown);
+        document.addEventListener('keydown', onKeyDown);
+        return ()=>{
+            document.removeEventListener('mousedown', onPointerDown);
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [
+        change,
+        open,
+        surfaceNode,
+        trigger
+    ]);
+    const show = ()=>{
+        if (disabled) return;
+        if ('click' === trigger) return void change(!open);
+        clearTimer();
+        timerRef.current = window.setTimeout(()=>{
+            change(true);
+            timerRef.current = void 0;
+        }, delay);
+    };
+    const hide = ()=>{
+        if ('click' === trigger) return;
+        clearTimer();
+        change(false);
+    };
+    const child = children;
+    const childProps = child.props;
+    const childRef = child.ref;
+    const mergedRef = useMergedRef(childRef, triggerRef);
+    const declaresExpanded = 'aria-expanded' in childProps;
+    const triggerElement = /*#__PURE__*/ cloneElement(child, {
+        ref: mergedRef,
+        ...declaresExpanded ? {} : {
+            'aria-expanded': open
+        },
+        onMouseEnter: (event)=>{
+            childProps.onMouseEnter?.(event);
+            if ('hover' === trigger) show();
+        },
+        onMouseLeave: (event)=>{
+            childProps.onMouseLeave?.(event);
+            if ('hover' === trigger) hide();
+        },
+        onClick: (event)=>{
+            childProps.onClick?.(event);
+            if ('click' === trigger) show();
+        }
+    });
+    const surface = open ? /*#__PURE__*/ createPortal(/*#__PURE__*/ jsx("div", {
+        ref: setSurfaceNode,
+        id: id,
+        role: 'click' === trigger ? 'dialog' : 'note',
+        className: [
+            'ov-popover',
+            className
+        ].filter(Boolean).join(' '),
+        "data-placement": position.placement,
+        style: {
+            top: position.top,
+            left: position.left,
+            ...style
+        },
+        onMouseEnter: 'hover' === trigger ? clearTimer : void 0,
+        onMouseLeave: 'hover' === trigger ? hide : void 0,
+        children: content
+    }), document.body) : null;
+    return /*#__PURE__*/ jsxs(Fragment, {
+        children: [
+            triggerElement,
+            surface
+        ]
+    });
+}
 const DEFAULT_FIELDS = {
     description: "Description",
     triggerBehavior: 'Trigger',
@@ -167,7 +312,8 @@ const DEFAULT_FIELDS = {
 };
 function resolveFileTreeInfoCopy(row, infoLabels) {
     const key = resolveFileTreeInfoKey(row.uri);
-    const builtIn = key ? resolveInfoCopy(key, infoLabels) : {};
+    if (!key) return null;
+    const builtIn = resolveInfoCopy(key, infoLabels);
     const description = row.description ?? builtIn.description;
     if (!description && !builtIn.triggerBehavior) return null;
     return {
@@ -183,14 +329,14 @@ function resolveFileTreeInfoCopy(row, infoLabels) {
 }
 function FileTreeInfoTooltip({ copy }) {
     const { description, fields, path, title, triggerBehavior } = copy;
-    return /*#__PURE__*/ jsxs("span", {
+    return /*#__PURE__*/ jsxs("div", {
         className: "ov-file-tree__info",
         children: [
-            /*#__PURE__*/ jsx("span", {
+            /*#__PURE__*/ jsx("div", {
                 className: "ov-file-tree__info-title",
                 children: title
             }),
-            description ? /*#__PURE__*/ jsxs("span", {
+            description ? /*#__PURE__*/ jsxs("div", {
                 className: "ov-file-tree__info-row",
                 children: [
                     /*#__PURE__*/ jsx("span", {
@@ -203,7 +349,7 @@ function FileTreeInfoTooltip({ copy }) {
                     })
                 ]
             }) : null,
-            triggerBehavior ? /*#__PURE__*/ jsxs("span", {
+            triggerBehavior ? /*#__PURE__*/ jsxs("div", {
                 className: "ov-file-tree__info-row",
                 children: [
                     /*#__PURE__*/ jsx("span", {
@@ -216,7 +362,7 @@ function FileTreeInfoTooltip({ copy }) {
                     })
                 ]
             }) : null,
-            /*#__PURE__*/ jsxs("span", {
+            /*#__PURE__*/ jsxs("div", {
                 className: "ov-file-tree__info-row",
                 children: [
                     /*#__PURE__*/ jsx("span", {
@@ -232,31 +378,23 @@ function FileTreeInfoTooltip({ copy }) {
         ]
     });
 }
-function FileTreeTooltipSurface({ row, infoLabels, renderRowTooltip }) {
+function FileTreeTooltipContent({ row, infoLabels, renderRowTooltip }) {
     if (renderRowTooltip) {
         const custom = renderRowTooltip(row);
         if (null == custom || false === custom) return null;
-        return /*#__PURE__*/ jsx("span", {
-            role: "tooltip",
-            className: "ov-file-tree__tooltip",
-            children: custom
-        });
+        return custom;
     }
     const copy = resolveFileTreeInfoCopy(row, infoLabels);
     if (!copy) return null;
-    return /*#__PURE__*/ jsx("span", {
-        role: "tooltip",
-        className: "ov-file-tree__tooltip",
-        children: /*#__PURE__*/ jsx(FileTreeInfoTooltip, {
-            copy: copy
-        })
+    return /*#__PURE__*/ jsx(FileTreeInfoTooltip, {
+        copy: copy
     });
 }
-const INDENT = 20;
+const INDENT = 16;
 const CHEVRON_SIZE = 16;
 function rowStyle(depth) {
     return {
-        paddingLeft: 8 + depth * INDENT
+        paddingLeft: depth * INDENT
     };
 }
 function Guides({ depth }) {
@@ -267,14 +405,14 @@ function Guides({ depth }) {
                 "aria-hidden": "true",
                 className: "ov-file-tree__guide",
                 style: {
-                    left: 8 + level * INDENT + CHEVRON_SIZE / 2
+                    left: level * INDENT + CHEVRON_SIZE / 2
                 }
             }, level))
     });
 }
 const FILE_TREE_ROW_ATTRIBUTE = 'data-file-tree-row-id';
 function FileTreeRowView({ row, ctx }) {
-    const { text, selectedId, tooltipRowId, getRowAttributes, renderDashboard, renderRowTooltip, renderRowIcon, onSelect, onToggleExpand, onOpenRetentionSettings, onRowKeyDown, onRowEnter, onRowLeave } = ctx;
+    const { text, selectedId, getRowAttributes, renderDashboard, renderRowTooltip, renderRowIcon, onSelect, onToggleExpand, onOpenRetentionSettings, onRowKeyDown } = ctx;
     const isDirectory = 'directory' === row.type;
     const canExpand = isDirectory && false !== row.hasChildren;
     const isExpanded = Boolean(row.expanded);
@@ -293,7 +431,7 @@ function FileTreeRowView({ row, ctx }) {
         event.stopPropagation();
         onToggleExpand?.(row);
     };
-    return /*#__PURE__*/ jsxs("div", {
+    const rowNode = /*#__PURE__*/ jsxs("div", {
         role: "treeitem",
         tabIndex: 0,
         "aria-level": row.depth + 1,
@@ -315,10 +453,6 @@ function FileTreeRowView({ row, ctx }) {
         },
         onClick: handleClick,
         onKeyDown: (event)=>onRowKeyDown(event, row),
-        onMouseEnter: ()=>onRowEnter(row.id),
-        onMouseLeave: onRowLeave,
-        onFocus: ()=>onRowEnter(row.id),
-        onBlur: onRowLeave,
         children: [
             /*#__PURE__*/ jsx(Guides, {
                 depth: row.depth
@@ -382,14 +516,23 @@ function FileTreeRowView({ row, ctx }) {
             dashboard ? /*#__PURE__*/ jsx("span", {
                 className: "ov-file-tree__dashboard",
                 children: dashboard
-            }) : null,
-            tooltipRowId === row.id ? /*#__PURE__*/ jsx(FileTreeTooltipSurface, {
-                row: row,
-                infoLabels: ctx.infoLabels,
-                renderRowTooltip: renderRowTooltip
             }) : null
         ]
     });
+    const custom = renderRowTooltip?.(row);
+    const hasContent = renderRowTooltip ? null != custom && false !== custom : null !== resolveFileTreeInfoCopy(row, ctx.infoLabels);
+    if (!hasContent) return rowNode;
+    const tooltipContent = /*#__PURE__*/ jsx(FileTreeTooltipContent, {
+        row: row,
+        infoLabels: ctx.infoLabels,
+        renderRowTooltip: renderRowTooltip
+    });
+    return /*#__PURE__*/ jsx(Popover, {
+        content: tooltipContent,
+        placement: "right",
+        trigger: "hover",
+        children: rowNode
+    });
 }
 function FileTreeStateRow({ row, ctx }) {
     const { text, onLoadMore, onRetry, getRowAttributes, renderSpinner } = ctx;
@@ -567,41 +710,6 @@ function handleRowKeyDown(event, { root, row, onSelect, onToggleExpand }) {
             return;
     }
 }
-const DEFAULT_DELAY = 400;
-function useRowTooltip(delay = DEFAULT_DELAY) {
-    const [tooltipRowId, setTooltipRowId] = useState(null);
-    const timerRef = useRef(void 0);
-    const clear = useCallback(()=>{
-        if (void 0 !== timerRef.current) {
-            window.clearTimeout(timerRef.current);
-            timerRef.current = void 0;
-        }
-    }, []);
-    useEffect(()=>clear, [
-        clear
-    ]);
-    const show = useCallback((rowId)=>{
-        clear();
-        timerRef.current = window.setTimeout(()=>{
-            setTooltipRowId(rowId);
-            timerRef.current = void 0;
-        }, delay);
-    }, [
-        clear,
-        delay
-    ]);
-    const hide = useCallback(()=>{
-        clear();
-        setTooltipRowId(null);
-    }, [
-        clear
-    ]);
-    return {
-        tooltipRowId,
-        show,
-        hide
-    };
-}
 function useFileTreeActions(props) {
     const pending = useRef(new Set());
     const { select, toggleExpand, loadMore, retry, openRetentionSettings } = props.operations ?? {};
@@ -654,7 +762,6 @@ const file_tree_FileTree = /*#__PURE__*/ forwardRef(function({ rows, operations,
         ...labels,
         info: labels?.info ?? DEFAULT_LABELS.info
     };
-    const tooltip = useRowTooltip();
     const actions = useFileTreeActions({
         operations,
         onSelect,
@@ -679,7 +786,6 @@ const file_tree_FileTree = /*#__PURE__*/ forwardRef(function({ rows, operations,
         text,
         infoLabels: labels?.info,
         selectedId,
-        tooltipRowId: tooltip.tooltipRowId,
         getRowAttributes,
         renderDashboard,
         renderRowTooltip,
@@ -691,9 +797,7 @@ const file_tree_FileTree = /*#__PURE__*/ forwardRef(function({ rows, operations,
                 row,
                 onSelect: actions.onSelect,
                 onToggleExpand: actions.onToggleExpand
-            }),
-        onRowEnter: tooltip.show,
-        onRowLeave: tooltip.hide
+            })
     };
     return /*#__PURE__*/ jsxs("div", {
         ...rest,

package/dist/o~0.js

@@ -0,0 +1,103 @@
+import { useLayoutEffect, useState } from "react";
+const OVERLAY_OFFSET = 6;
+const VIEWPORT_MARGIN = 8;
+const OPPOSITE = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left'
+};
+function resolvePosition(trigger, surface, placement) {
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const fits = (side)=>{
+        if ('top' === side) return trigger.top - surface.height - OVERLAY_OFFSET >= VIEWPORT_MARGIN;
+        if ('bottom' === side) return trigger.bottom + surface.height + OVERLAY_OFFSET <= viewportHeight - VIEWPORT_MARGIN;
+        if ('left' === side) return trigger.left - surface.width - OVERLAY_OFFSET >= VIEWPORT_MARGIN;
+        return trigger.right + surface.width + OVERLAY_OFFSET <= viewportWidth - VIEWPORT_MARGIN;
+    };
+    const side = fits(placement) || !fits(OPPOSITE[placement]) ? placement : OPPOSITE[placement];
+    const clamp = (value, size, limit)=>Math.min(Math.max(value, VIEWPORT_MARGIN), limit - size - VIEWPORT_MARGIN);
+    if ('top' === side || 'bottom' === side) {
+        const top = 'top' === side ? trigger.top - surface.height - OVERLAY_OFFSET : trigger.bottom + OVERLAY_OFFSET;
+        const left = trigger.left + trigger.width / 2 - surface.width / 2;
+        return {
+            top: clamp(top, surface.height, viewportHeight),
+            left: clamp(left, surface.width, viewportWidth),
+            placement: side
+        };
+    }
+    const left = 'left' === side ? trigger.left - surface.width - OVERLAY_OFFSET : trigger.right + OVERLAY_OFFSET;
+    const top = trigger.top + trigger.height / 2 - surface.height / 2;
+    return {
+        top: clamp(top, surface.height, viewportHeight),
+        left: clamp(left, surface.width, viewportWidth),
+        placement: side
+    };
+}
+function useOverlayPosition(open, triggerRef, surface, placement) {
+    const [position, setPosition] = useState({
+        top: 0,
+        left: 0,
+        placement
+    });
+    useLayoutEffect(()=>{
+        if (!open) return;
+        const trigger = triggerRef.current;
+        if (!trigger || !surface) return;
+        const written = new Set();
+        const syncTheme = ()=>{
+            const triggerStyle = window.getComputedStyle(trigger);
+            const seen = new Set();
+            for (const name of Array.from(triggerStyle)){
+                if (!name.startsWith('--ov-ui-color-')) continue;
+                const value = triggerStyle.getPropertyValue(name).trim();
+                if (value) {
+                    seen.add(name);
+                    surface.style.setProperty(name, value);
+                }
+            }
+            for (const name of written)if (!seen.has(name)) surface.style.removeProperty(name);
+            written.clear();
+            seen.forEach((name)=>written.add(name));
+        };
+        syncTheme();
+        const themeObserver = new MutationObserver(syncTheme);
+        const observerOptions = {
+            attributes: true,
+            attributeFilter: [
+                'class',
+                'style',
+                'data-theme'
+            ]
+        };
+        for(let node = trigger; node; node = node.parentElement)themeObserver.observe(node, observerOptions);
+        const update = ()=>{
+            const triggerRect = trigger.getBoundingClientRect();
+            const surfaceRect = surface.getBoundingClientRect();
+            const next = resolvePosition(triggerRect, {
+                width: surfaceRect.width,
+                height: surfaceRect.height
+            }, placement);
+            setPosition((previous)=>previous.top === next.top && previous.left === next.left && previous.placement === next.placement ? previous : next);
+        };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(surface);
+        window.addEventListener('scroll', update, true);
+        window.addEventListener('resize', update);
+        return ()=>{
+            observer.disconnect();
+            themeObserver.disconnect();
+            window.removeEventListener('scroll', update, true);
+            window.removeEventListener('resize', update);
+        };
+    }, [
+        open,
+        placement,
+        surface,
+        triggerRef
+    ]);
+    return position;
+}
+export { useOverlayPosition };

package/dist/shared/components/divider/divider.d.ts

@@ -0,0 +1,18 @@
+import type { DividerProps } from './types.js';
+export type { DividerOrientation, DividerProps } from './types.js';
+/**
+ * 一条分隔线。并排的控件之间用竖线，堆叠的分组之间用横线。
+ *
+ * 尺寸用内联样式给：`length` 与 `thickness` 都是运行时值，写进类名只能固定成
+ * 几个预设，而调用方要的往往是「和旁边按钮一样高」这种随上下文变化的长度。
+ * 颜色默认取主题基线的边框色，宿主换主题时自动跟随。
+ *
+ * A single divider: vertical between side-by-side controls, horizontal between
+ * stacked groups.
+ *
+ * Sizing is inline because `length` and `thickness` are runtime values; baking them
+ * into class names would fix them to a few presets, while a caller usually wants a
+ * length that follows its context, such as "as tall as the button beside it". The
+ * colour defaults to the baseline border, so it follows a host theme change.
+ */
+export declare function Divider({ orientation, length, thickness, color, className, style, ...rest }: DividerProps): import("react").JSX.Element;

package/dist/shared/components/divider/index.d.ts

@@ -0,0 +1 @@
+export * from './divider.js';

package/dist/shared/components/divider/types.d.ts

@@ -0,0 +1,35 @@
+import type { CSSProperties, HTMLAttributes } from 'react';
+/**
+ * 分隔线的方向。竖线用于并排的控件之间，横线用于堆叠的分组之间。
+ * Direction of the divider: vertical between side-by-side controls, horizontal
+ * between stacked groups.
+ */
+export type DividerOrientation = 'vertical' | 'horizontal';
+/**
+ * 分隔线的属性。
+ *
+ * 它只是一个 `role="separator"` 的元素，不占交互焦点，也不读屏幕阅读器以外的
+ * 内容。长度由 `length` 决定，颜色默认取主题基线里的边框色。
+ *
+ * Props of the divider.
+ *
+ * It is just a `role="separator"` element: not focusable, and it carries no content
+ * for a screen reader. `length` sets its extent, and the colour defaults to the
+ * baseline border.
+ */
+export interface DividerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** 方向，默认竖线。Orientation; vertical by default. */
+    orientation?: DividerOrientation;
+    /**
+     * 线的长度：竖线是高度，横线是宽度。省略时由父级布局决定，横线默认铺满。
+     * Extent of the line: height for a vertical one, width for a horizontal one.
+     * Omitted leaves it to the parent layout; a horizontal one fills by default.
+     */
+    length?: number | string;
+    /** 线的粗细，缺省为 1px。Thickness, 1px by default. */
+    thickness?: number | string;
+    /** 线的颜色，缺省取主题基线的边框色。Colour; defaults to the baseline border. */
+    color?: string;
+    /** 内联样式，可覆盖上面的值。Inline styles, overriding the values above. */
+    style?: CSSProperties;
+}

package/dist/shared/components/overlay/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 浮层相对触发元素的方位。空间不足时会自动翻到对侧。
+ *
+ * Where the surface sits relative to its trigger. It flips to the opposite side
+ * when there is not enough room.
+ */
+export type OverlayPlacement = 'top' | 'bottom' | 'left' | 'right';

package/dist/shared/components/{tooltip/use-tooltip-position.d.ts → overlay/use-overlay-position.d.ts}

@@ -1,11 +1,11 @@
-import type { TooltipPlacement } from './types.js';
+import type { OverlayPlacement } from './types.js';
 /** 浮层与触发元素之间的间隙。 Gap between the surface and its trigger. */
-export declare const OFFSET = 6;
-export interface TooltipPosition {
+export declare const OVERLAY_OFFSET = 6;
+export interface OverlayPosition {
     top: number;
     left: number;
     /** 实际采用的方位，可能与请求的不同。 The placement actually used. */
-    placement: TooltipPlacement;
+    placement: OverlayPlacement;
 }
 /**
  * 按触发元素与浮层尺寸算出一个视口坐标。空间不足时翻到对侧，仍放不下就
@@ -18,7 +18,7 @@ export interface TooltipPosition {
 export declare function resolvePosition(trigger: DOMRect, surface: {
     width: number;
     height: number;
-}, placement: TooltipPlacement): TooltipPosition;
+}, placement: OverlayPlacement): OverlayPosition;
 /**
  * 跟踪浮层的视口坐标。
  *
@@ -35,4 +35,4 @@ export declare function resolvePosition(trigger: DOMRect, surface: {
  * that is derivable during render. Scroll is captured so inner scroll containers
  * count too; listeners are removed on close or unmount.
  */
-export declare function useTooltipPosition(open: boolean, triggerRef: React.RefObject<HTMLElement | null>, surface: HTMLElement | null, placement: TooltipPlacement): TooltipPosition;
+export declare function useOverlayPosition(open: boolean, triggerRef: React.RefObject<HTMLElement | null>, surface: HTMLElement | null, placement: OverlayPlacement): OverlayPosition;

package/dist/shared/components/popover/index.d.ts

@@ -0,0 +1 @@
+export * from './popover.js';

package/dist/shared/components/popover/popover.d.ts

@@ -0,0 +1,23 @@
+import type { PopoverProps } from './types.js';
+export type { PopoverPlacement, PopoverProps, PopoverTrigger, } from './types.js';
+/**
+ * 弹出层：挂一段结构化信息或一小块可交互内容。
+ *
+ * 渲染到 `document.body`，因此不会被祖先的 `overflow: hidden` 裁掉——文件树的
+ * 行就处在这样的容器里。定位用 fixed 视口坐标，空间不足时翻到对侧。
+ *
+ * 与 `Tooltip` 分开，是因为两者视觉与语义都不同：提示是深色的一句话，弹出层是
+ * 白底卡片。共用的部分（portal、定位、主题变量同步）留在 `overlay/`。
+ *
+ * A surface holding structured information or a small piece of interactive
+ * content.
+ *
+ * It renders into `document.body`, so an ancestor's `overflow: hidden` cannot clip
+ * it — the file tree's rows sit inside exactly such a container. Positioning uses
+ * fixed viewport coordinates and flips sides when space runs out.
+ *
+ * It is separate from `Tooltip` because the two differ in look and semantics: a
+ * tooltip is one dark line, a popover is a white card. What they share — the
+ * portal, positioning and theme-variable syncing — lives in `overlay/`.
+ */
+export declare function Popover({ children, content, placement, trigger, delay, disabled, className, style, onOpenChange, }: PopoverProps): import("react").JSX.Element;

package/dist/shared/components/popover/types.d.ts

@@ -0,0 +1,50 @@
+import type { OverlayPlacement } from '../overlay/types.js';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+/**
+ * 弹出层的方位，与提示共用一套取值。空间不足时自动翻到对侧。
+ * Where the popover sits relative to its trigger, sharing the tooltip's values.
+ * It flips to the opposite side when there is not enough room.
+ */
+export type PopoverPlacement = OverlayPlacement;
+/**
+ * 触发方式。`hover` 悬停与聚焦都展示，适合展示型内容；`click` 点击切换，适合
+ * 放按钮、菜单这类可交互的内容。
+ *
+ * How the popover opens. `hover` shows it on hover and focus, for display
+ * content; `click` toggles it, for interactive content such as buttons or menus.
+ */
+export type PopoverTrigger = 'hover' | 'click';
+/**
+ * 弹出层的属性。
+ *
+ * 与提示的区别是视觉与语义：提示是深色底的一句话，弹出层是白底卡片，用来放
+ * 结构化信息或可交互内容。两者共用同一套 portal 与定位，触发元素都必须是能
+ * 接受 `ref` 的单个元素。
+ *
+ * Props of the popover.
+ *
+ * It differs from the tooltip in look and semantics: a tooltip is one dark line,
+ * a popover is a white card for structured or interactive content. Both share the
+ * same portal and positioning, and the trigger must be a single element that
+ * accepts a `ref`.
+ */
+export interface PopoverProps {
+    /** 触发元素，必须是能接受 ref 的单个元素。 The trigger; a single element that accepts a ref. */
+    children: ReactElement;
+    /** 浮层内容。 Surface content. */
+    content: ReactNode;
+    /** 方位，默认 `right`——内容在行尾展开，不遮挡左侧。 Placement, `right` by default. */
+    placement?: PopoverPlacement;
+    /** 触发方式，默认 `hover`。 Trigger mode, `hover` by default. */
+    trigger?: PopoverTrigger;
+    /** 悬停后多久展示，单位毫秒。延迟只作用于 `hover`。 Hover delay in ms; `hover` only. */
+    delay?: number;
+    /** 为真时不展示浮层。 Suppresses the surface; the trigger still renders. */
+    disabled?: boolean;
+    /** 浮层容器的额外类名。 Extra class names for the surface. */
+    className?: string;
+    /** 浮层容器的内联样式，可覆盖定位以外的样式。 Inline styles for the surface. */
+    style?: CSSProperties;
+    /** 展示状态变化时触发。 Fires when the surface opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}