@bifrostui/react 2.0.0-alpha.0 → 2.0.0-alpha.10

package/es/Tooltip/Tooltip.js

@@ -1,4 +1,6 @@
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -14,6 +16,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __objRest = (source, exclude) => {
   var target = {};
   for (var prop in source)
@@ -27,15 +30,9 @@ var __objRest = (source, exclude) => {
   return target;
 };
 import clsx from "clsx";
-import React, { useState, useRef, useEffect } from "react";
-import {
-  getStylesAndLocation,
-  triggerEventTransform,
-  parsePlacement,
-  useUniqueId,
-  throttle
-} from "@bifrostui/utils";
+import React from "react";
 import Portal from "../Portal";
+import { useTooltip } from "./useTooltip";
 import "./index.css";
 const prefixCls = "bui-tooltip";
 const Tooltip = /* @__PURE__ */ React.forwardRef((props, ref) => {
@@ -44,127 +41,80 @@ const Tooltip = /* @__PURE__ */ React.forwardRef((props, ref) => {
     style,
     children,
     title,
-    defaultOpen,
-    offsetSpacing = 0,
+    defaultOpen = false,
+    offset,
     placement = "top",
     trigger = "click",
+    open,
     onOpenChange,
-    open
+    role: role = "tooltip",
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby,
+    autoFocus = false,
+    closeOnEscape = false,
+    "aria-hidden": ariaHidden = false
   } = _a, others = __objRest(_a, [
     "className",
     "style",
     "children",
     "title",
     "defaultOpen",
-    "offsetSpacing",
+    "offset",
     "placement",
     "trigger",
+    "open",
     "onOpenChange",
-    "open"
+    // 无障碍功能相关属性
+    "role",
+    "aria-label",
+    "aria-labelledby",
+    "autoFocus",
+    "closeOnEscape",
+    "aria-hidden"
   ]);
-  const controlByUser = typeof open !== "undefined";
-  const { direction, location = "center" } = parsePlacement(placement);
-  const childrenRef = useRef();
-  const [openStatus, setOpenStatus] = useState(defaultOpen);
-  const [arrowDirection, setArrowDirection] = useState(direction);
-  const [arrowLocation, setArrowLocation] = useState(location);
-  const [tooltyles, setTooltyles] = useState({});
-  const ttId = useUniqueId();
-  const changeOpenStatus = (event, status) => {
-    if (controlByUser)
-      return;
-    setOpenStatus(status);
-    onOpenChange == null ? void 0 : onOpenChange(event, { open: status });
-  };
-  const triggerClick = (event) => {
-    event.stopPropagation();
-    const targetStatus = !openStatus;
-    changeOpenStatus(event, targetStatus);
-  };
-  const hideTooltip = (event) => {
-    changeOpenStatus(event, false);
-  };
-  const showTooltip = (event) => {
-    changeOpenStatus(event, true);
-  };
-  useEffect(() => {
-    if (!controlByUser)
-      return;
-    setOpenStatus(open);
-  }, [open]);
-  const clickEventHandler = (event) => {
-    if (trigger === "hover" || (trigger == null ? void 0 : trigger.length) === 1 && (trigger == null ? void 0 : trigger[0]) === "hover")
-      return;
-    hideTooltip(event);
-  };
-  const onRootElementMouted = throttle(() => {
-    const {
-      direction: newParsedDirection,
-      location: newParsedLocation = "center"
-    } = parsePlacement(placement);
-    const result = getStylesAndLocation({
-      childrenRef,
-      arrowDirection: newParsedDirection,
-      arrowLocation: newParsedLocation,
-      offsetSpacing,
-      selector: `[data-id="tt_${ttId}"]`
-    });
-    if (!result)
-      return;
-    const { styles, newArrowDirection, newArrowLocation } = result;
-    if (newArrowDirection !== arrowDirection) {
-      setArrowDirection(newArrowDirection);
-    }
-    if (newArrowLocation !== arrowLocation) {
-      setArrowLocation(newArrowLocation);
-    }
-    setTooltyles(styles);
-  }, 100);
-  const bindEvent = () => {
-    if (!controlByUser) {
-      document.addEventListener("click", clickEventHandler);
-    }
-    window.addEventListener("resize", onRootElementMouted);
-  };
-  const unbindEvent = () => {
-    if (!controlByUser) {
-      document.removeEventListener("click", clickEventHandler);
-    }
-    window.removeEventListener("resize", onRootElementMouted);
-  };
-  useEffect(() => {
-    bindEvent();
-    return () => {
-      unbindEvent();
-    };
-  }, []);
-  let triggerEventOption;
-  if (!controlByUser) {
-    triggerEventOption = triggerEventTransform({
-      trigger,
-      click: triggerClick,
-      show: showTooltip,
-      hide: hideTooltip
-    });
+  const {
+    getTooltipProps,
+    getChildProps,
+    getPortalProps,
+    isOpen,
+    toolStyles,
+    arrowDirection,
+    arrowLocation
+  } = useTooltip({
+    title,
+    defaultOpen,
+    open,
+    offset,
+    placement,
+    trigger,
+    onOpenChange,
+    autoFocus,
+    closeOnEscape,
+    children,
+    rootRef: ref
+  });
+  if (!React.isValidElement(children)) {
+    console.warn(
+      "BUI Tooltip: children must be a valid React element that can accept a ref."
+    );
+    return children;
   }
-  const childrenOptions = __spreadValues({
-    ref: childrenRef
-  }, triggerEventOption);
-  return /* @__PURE__ */ React.createElement(React.Fragment, null, (open || openStatus) && title ? /* @__PURE__ */ React.createElement(Portal, { onRootElementMouted, ref }, /* @__PURE__ */ React.createElement(
+  const tooltipProps = getTooltipProps(__spreadProps(__spreadValues({}, others), {
+    className: clsx(prefixCls, className, `tooltip-${arrowDirection}`),
+    style: __spreadValues(__spreadValues({}, style), toolStyles),
+    role,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby,
+    "aria-hidden": ariaHidden
+  }));
+  const childProps = getChildProps();
+  const portalProps = getPortalProps();
+  return /* @__PURE__ */ React.createElement(React.Fragment, null, isOpen && title ? /* @__PURE__ */ React.createElement(Portal, __spreadValues({}, portalProps), /* @__PURE__ */ React.createElement("div", __spreadValues({}, tooltipProps), /* @__PURE__ */ React.createElement(
     "div",
-    __spreadValues({
-      className: clsx(prefixCls, className, `tooltip-${arrowDirection}`),
-      style: __spreadValues(__spreadValues({}, style), tooltyles),
-      "data-id": `tt_${ttId}`
-    }, others),
-    /* @__PURE__ */ React.createElement(
-      "div",
-      {
-        className: clsx("bui-tooltip-arrow", `location-${arrowLocation}`)
-      }
-    ),
-    /* @__PURE__ */ React.createElement("div", { className: "bui-tooltip-content" }, title)
-  )) : null, React.isValidElement(children) ? React.cloneElement(children, childrenOptions) : children);
+    {
+      className: clsx("bui-tooltip-arrow", `location-${arrowLocation}`)
+    }
+  ), /* @__PURE__ */ React.createElement("div", { className: "bui-tooltip-content" }, title))) : null, React.cloneElement(children, childProps));
 });
 Tooltip.displayName = "BuiTooltip";
 var Tooltip_default = Tooltip;

package/es/Tooltip/Tooltip.types.d.ts

@@ -1,48 +1,99 @@
 import React from 'react';
 import { OverrideProps } from '@bifrostui/types';
-type triggerType = 'click' | 'hover';
+/**
+ * 触发 Tooltip 显示的事件类型
+ */
+export type TooltipTriggerType = 'click' | 'hover';
+/**
+ * Tooltip 的位置选项
+ */
+export type TooltipPlacement = 'top' | 'left' | 'right' | 'bottom' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'leftTop' | 'leftBottom' | 'rightTop' | 'rightBottom';
+/**
+ * onOpenChange 回调函数的数据参数
+ */
+export interface TooltipOpenChangeData {
+    /** 浮层显隐状态 */
+    open: boolean;
+}
+/**
+ * Tooltip 组件的属性接口
+ */
+export interface TooltipBaseProps {
+    /**
+     * 气泡浮层显示内容
+     * 支持文本、React 节点等
+     */
+    title?: React.ReactNode;
+    /**
+     * 默认是否显隐
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * 用于手动控制气泡浮层显隐
+     * 当提供此属性时，组件变为受控模式
+     */
+    open?: boolean;
+    /**
+     * 浮层与目标元素的偏移距离（像素）
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * 气泡框相对于目标元素的位置
+     * @default 'top'
+     */
+    placement?: TooltipPlacement;
+    /**
+     * 触发 Tooltip 显示的事件类型
+     * - 'click': 点击触发
+     * - 'hover': 悬停触发
+     * - 可以传递数组来组合多种触发方式
+     * @default 'click'
+     */
+    trigger?: TooltipTriggerType | TooltipTriggerType[];
+    /**
+     * 显隐状态变化时的回调函数
+     * @param event - 触发事件
+     * @param data - 回调数据，包含当前的显隐状态
+     */
+    onOpenChange?: (event: React.SyntheticEvent, data: TooltipOpenChangeData) => void;
+    /**
+     * 子元素，必须是可以接收 ref 的 React 元素
+     */
+    children?: React.ReactElement;
+    /**
+     * 无障碍功能：Tooltip的角色
+     * @default 'tooltip'
+     */
+    role?: 'tooltip' | 'dialog' | 'status' | 'alert';
+    /**
+     * 无障碍功能：为Tooltip提供可访问的标签
+     */
+    'aria-label'?: string;
+    /**
+     * 无障碍功能：引用描述此Tooltip的元素ID
+     */
+    'aria-labelledby'?: string;
+    /**
+     * 无障碍功能：是否自动管理焦点
+     * 当为true时，Tooltip显示时会自动获取焦点，关闭时焦点返回到触发元素
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * 无障碍功能：是否支持Escape键关闭
+     * @default false
+     */
+    closeOnEscape?: boolean;
+    /**
+     * 无障碍功能：是否对屏幕阅读器隐藏Tooltip
+     * 当为true时，Tooltip将被屏幕阅读器忽略
+     * @default false
+     */
+    'aria-hidden'?: boolean;
+}
 export type TooltipProps<D extends React.ElementType = 'div', P = {}> = OverrideProps<{
-    props: P & {
-        /**
-         * 气泡浮层显示内容
-         */
-        title?: string;
-        /**
-         * 默认是否显隐
-         * @default false
-         */
-        defaultOpen?: boolean;
-        /**
-         * 用于手动控制气泡浮层显隐
-         */
-        open?: boolean;
-        /**
-         * 用于控制气泡浮层和目标元素偏移量
-         */
-        offsetSpacing?: number;
-        /**
-         * 气泡框位置
-         * @default 'top'
-         */
-        placement?: 'top' | 'left' | 'right' | 'bottom' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'leftTop' | 'leftBottom' | 'rightTop' | 'rightBottom';
-        /**
-         * 触发行为
-         * - click: 点击触发
-         * - hover: hover触发
-         * - 或者是他们的数组
-         * @default 'click'
-         */
-        trigger?: triggerType | triggerType[];
-        /**
-         * 点击事件回调方法
-         * - event 触发事件
-         * - data.open 浮层显隐状态
-         * @returns
-         */
-        onOpenChange?: (event: React.SyntheticEvent, data: {
-            open: boolean;
-        }) => void;
-    };
+    props: P & TooltipBaseProps;
     defaultComponent: D;
 }, D>;
-export {};

package/es/Tooltip/__tests__/fixtures/A11yDemos.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+/**
+ * 自定义 Tooltip 组件 Demo 集合
+ * 这个文件包含多个测试 demo，展示如何使用 getCustomDemoCodesFromFile 进行无障碍测试
+ * 文件名必须是 A11yDemos.tsx（固定约定）
+ */
+export declare const basicTooltipDemo: () => React.JSX.Element;
+export declare const placementTooltipDemo: () => React.JSX.Element;
+export declare const triggerTooltipDemo: () => React.JSX.Element;
+export declare const accessibilityTooltipDemo: () => React.JSX.Element;
+export declare const complexInteractionTooltipDemo: () => React.JSX.Element;
+export declare const complexContentTooltipDemo: () => React.JSX.Element;
+export declare const offsetTooltipDemo: () => React.JSX.Element;
+export declare const edgeCaseTooltipDemo: () => React.JSX.Element;
+declare const _default: {
+    basicTooltipDemo: () => React.JSX.Element;
+    placementTooltipDemo: () => React.JSX.Element;
+    triggerTooltipDemo: () => React.JSX.Element;
+    accessibilityTooltipDemo: () => React.JSX.Element;
+    complexInteractionTooltipDemo: () => React.JSX.Element;
+    complexContentTooltipDemo: () => React.JSX.Element;
+    offsetTooltipDemo: () => React.JSX.Element;
+    edgeCaseTooltipDemo: () => React.JSX.Element;
+};
+export default _default;

package/es/Tooltip/__tests__/fixtures/A11yDemos.js

@@ -0,0 +1,60 @@
+import React from "react";
+import Tooltip from "../../Tooltip";
+const basicTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement(Tooltip, { title: "\u8FD9\u662F\u4E00\u4E2A\u57FA\u7840\u7684\u63D0\u793A\u6587\u672C" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u57FA\u7840Tooltip")));
+};
+const placementTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px", flexWrap: "wrap" } }, /* @__PURE__ */ React.createElement(Tooltip, { title: "\u9876\u90E8\u63D0\u793A", placement: "top" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u9876\u90E8")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u53F3\u4FA7\u63D0\u793A", placement: "right" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u53F3\u4FA7")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u5E95\u90E8\u63D0\u793A", placement: "bottom" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u5E95\u90E8")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u5DE6\u4FA7\u63D0\u793A", placement: "left" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u5DE6\u4FA7")));
+};
+const triggerTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px" } }, /* @__PURE__ */ React.createElement(Tooltip, { title: "\u70B9\u51FB\u89E6\u53D1\u7684\u63D0\u793A", trigger: "click" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u70B9\u51FB\u89E6\u53D1")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u60AC\u505C\u89E6\u53D1\u7684\u63D0\u793A", trigger: "hover" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u60AC\u505C\u89E6\u53D1")));
+};
+const accessibilityTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px", flexDirection: "column" } }, /* @__PURE__ */ React.createElement(Tooltip, { title: "\u81EA\u5B9A\u4E49\u89D2\u8272\u7684\u63D0\u793A", role: "status", "aria-label": "\u72B6\u6001\u63D0\u793A" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u72B6\u6001\u63D0\u793A")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u652F\u6301Escape\u952E\u5173\u95ED", closeOnEscape: true, trigger: "click" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "Escape\u952E\u5173\u95ED")));
+};
+const complexInteractionTooltipDemo = () => {
+  const ComplexInteractionTooltipDemo = () => {
+    const [open, setOpen] = React.useState(false);
+    return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px", alignItems: "center" } }, /* @__PURE__ */ React.createElement(
+      Tooltip,
+      {
+        title: "\u53D7\u63A7\u6A21\u5F0F\u7684\u63D0\u793A",
+        open,
+        onOpenChange: (_, data) => setOpen(data.open)
+      },
+      /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u53D7\u63A7Tooltip")
+    ), /* @__PURE__ */ React.createElement("button", { type: "button", onClick: () => setOpen(!open) }, "\u5916\u90E8\u63A7\u5236: ", open ? "\u5173\u95ED" : "\u6253\u5F00"));
+  };
+  return /* @__PURE__ */ React.createElement(ComplexInteractionTooltipDemo, null);
+};
+const complexContentTooltipDemo = () => {
+  const ComplexContent = () => /* @__PURE__ */ React.createElement("div", { style: { maxWidth: "200px" } }, /* @__PURE__ */ React.createElement("h4", { style: { margin: "0 0 8px 0", fontSize: "14px" } }, "\u590D\u6742\u5185\u5BB9"), /* @__PURE__ */ React.createElement("p", { style: { margin: "0 0 8px 0", fontSize: "12px" } }, "\u8FD9\u662F\u4E00\u4E2A\u5305\u542B\u591A\u79CD\u5143\u7D20\u7684\u590D\u6742\u63D0\u793A\u5185\u5BB9\u3002"), /* @__PURE__ */ React.createElement("ul", { style: { margin: 0, fontSize: "12px", paddingLeft: "16px" } }, /* @__PURE__ */ React.createElement("li", null, "\u9879\u76EE\u4E00"), /* @__PURE__ */ React.createElement("li", null, "\u9879\u76EE\u4E8C")));
+  return /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement(Tooltip, { title: /* @__PURE__ */ React.createElement(ComplexContent, null) }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u590D\u6742\u5185\u5BB9Tooltip")));
+};
+const offsetTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px" } }, /* @__PURE__ */ React.createElement(Tooltip, { title: "\u65E0\u504F\u79FB", offset: 0 }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u65E0\u504F\u79FB")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u504F\u79FB10px", offset: 10 }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u504F\u79FB10px")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u504F\u79FB20px", offset: 20 }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u504F\u79FB20px")));
+};
+const edgeCaseTooltipDemo = () => {
+  return /* @__PURE__ */ React.createElement("div", { style: { display: "flex", gap: "10px", flexDirection: "column" } }, /* @__PURE__ */ React.createElement(Tooltip, { title: "" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u7A7A\u5185\u5BB9")), /* @__PURE__ */ React.createElement(Tooltip, { title: "\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u5F88\u957F\u7684\u63D0\u793A\u6587\u672C\u5185\u5BB9" }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u957F\u6587\u672C")), /* @__PURE__ */ React.createElement(Tooltip, { title: `\u7279\u6B8A\u5B57\u7B26 !@#$%^&*()_+-=[]{}|;':",./` }, /* @__PURE__ */ React.createElement("button", { type: "button" }, "\u7279\u6B8A\u5B57\u7B26")));
+};
+var A11yDemos_default = {
+  basicTooltipDemo,
+  placementTooltipDemo,
+  triggerTooltipDemo,
+  accessibilityTooltipDemo,
+  complexInteractionTooltipDemo,
+  complexContentTooltipDemo,
+  offsetTooltipDemo,
+  edgeCaseTooltipDemo
+};
+export {
+  accessibilityTooltipDemo,
+  basicTooltipDemo,
+  complexContentTooltipDemo,
+  complexInteractionTooltipDemo,
+  A11yDemos_default as default,
+  edgeCaseTooltipDemo,
+  offsetTooltipDemo,
+  placementTooltipDemo,
+  triggerTooltipDemo
+};

package/es/Tooltip/useTooltip.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import { TooltipProps } from './Tooltip.types';
+export interface UseTooltipParameters {
+    title?: React.ReactNode;
+    defaultOpen?: boolean;
+    open?: boolean;
+    offset?: number;
+    placement?: TooltipProps['placement'];
+    trigger?: TooltipProps['trigger'];
+    onOpenChange?: TooltipProps['onOpenChange'];
+    autoFocus?: boolean;
+    closeOnEscape?: boolean;
+    children: React.ReactElement;
+    rootRef?: React.Ref<HTMLElement>;
+}
+export interface UseTooltipReturnValue {
+    getTooltipProps: (otherProps?: Record<string, unknown>) => Record<string, unknown>;
+    getChildProps: () => Record<string, unknown>;
+    getPortalProps: () => {
+        onMounted: () => void;
+    };
+    tooltipRef: React.RefCallback<HTMLElement>;
+    isOpen: boolean;
+    toolStyles: React.CSSProperties;
+    arrowDirection: string;
+    arrowLocation: string;
+    tooltipId: string;
+}
+export declare function useTooltip(parameters: UseTooltipParameters): UseTooltipReturnValue;