@openviking/react 0.1.1 → 0.1.2

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

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

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

@@ -0,0 +1,25 @@
+import type { TooltipProps } from './types.js';
+export type { TooltipLabels, TooltipPlacement, TooltipProps, TooltipTrigger, } from './types.js';
+/**
+ * 浮层：给触发元素挂一段提示或一小块可交互内容。
+ *
+ * 浮层渲染到 `document.body`，因此不会被祖先的 `overflow: hidden` 裁掉——
+ * 文件预览的面包屑、文件树的行都处在这样的容器里。定位用 fixed 视口坐标，
+ * 空间不足时翻到对侧。
+ *
+ * 触发元素必须是能接受 `ref` 的单个 React 元素；组件把事件处理与
+ * `aria-describedby` 合并进去，不额外包一层 DOM。
+ *
+ * A surface that attaches a hint or a small piece of interactive content to a
+ * trigger.
+ *
+ * It renders into `document.body`, so an ancestor's `overflow: hidden` cannot clip
+ * it — the file preview's breadcrumb and the file tree's rows both sit inside such
+ * containers. Positioning uses fixed viewport coordinates and flips sides when
+ * space runs out.
+ *
+ * The trigger must be a single React element that accepts a `ref`; the component
+ * merges its handlers and `aria-describedby` into it rather than wrapping it in
+ * another DOM node.
+ */
+export declare function Tooltip({ children, content, placement, trigger, delay, disabled, className, style, onOpenChange, labels, }: TooltipProps): import("react").JSX.Element;

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

@@ -0,0 +1,42 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+/**
+ * 浮层相对触发元素的方位。空间不足时会自动翻到对侧。
+ *
+ * Where the surface sits relative to its trigger. It flips to the opposite side
+ * when there is not enough room.
+ */
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * 触发方式。`hover` 悬停与聚焦都展示，适合按钮提示；`click` 点击切换，
+ * 适合放可交互的内容。
+ *
+ * How the surface opens. `hover` shows it on hover and focus, which suits button
+ * hints; `click` toggles it, for content the user interacts with.
+ */
+export type TooltipTrigger = 'hover' | 'click';
+export interface TooltipProps {
+    /** 触发元素，必须是能接受 ref 的单个元素。 The trigger; a single element that accepts a ref. */
+    children: ReactElement;
+    /** 浮层内容。 Surface content. */
+    content: ReactNode;
+    /** 方位，默认 `top`。 Placement, `top` by default. */
+    placement?: TooltipPlacement;
+    /** 触发方式，默认 `hover`。 Trigger mode, `hover` by default. */
+    trigger?: TooltipTrigger;
+    /** 悬停后多久展示，单位毫秒。延迟只作用于 `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;
+    /** 可替换文案。 Replaceable copy. */
+    labels?: TooltipLabels;
+}
+export interface TooltipLabels {
+    /** `click` 触发时关闭按钮的无障碍名称。 Accessible name of the close button under `click`. */
+    close?: string;
+}

package/dist/shared/components/tooltip/use-tooltip-position.d.ts

@@ -0,0 +1,38 @@
+import type { TooltipPlacement } from './types.js';
+/** 浮层与触发元素之间的间隙。 Gap between the surface and its trigger. */
+export declare const OFFSET = 6;
+export interface TooltipPosition {
+    top: number;
+    left: number;
+    /** 实际采用的方位，可能与请求的不同。 The placement actually used. */
+    placement: TooltipPlacement;
+}
+/**
+ * 按触发元素与浮层尺寸算出一个视口坐标。空间不足时翻到对侧，仍放不下就
+ * 贴着视口边缘，保证浮层始终可见。
+ *
+ * Resolves a viewport position from the trigger and surface boxes. It flips to
+ * the opposite side when space runs out and clamps to the viewport otherwise, so
+ * the surface stays visible.
+ */
+export declare function resolvePosition(trigger: DOMRect, surface: {
+    width: number;
+    height: number;
+}, placement: TooltipPlacement): TooltipPosition;
+/**
+ * 跟踪浮层的视口坐标。
+ *
+ * useLayoutEffect 必要性：坐标来自触发元素与浮层自身的布局盒，只有提交后才
+ * 可测量；浮层内容变化会改变尺寸，窗口滚动与缩放也会改变相对位置，这些都
+ * 不能靠渲染计算得出。监听 scroll（捕获阶段，覆盖内层滚动容器）与 resize，
+ * 卸载或关闭时移除，避免旧回调继续写坐标。
+ *
+ * Tracks the surface's viewport position.
+ *
+ * A layout effect is required: the coordinates come from the trigger's and the
+ * surface's boxes, measurable only after commit; content changes resize the
+ * surface, and scrolling or resizing moves it relative to the trigger — none of
+ * 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;