@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/tooltip/Tooltip.svelte.d.ts

@@ -1,37 +1,107 @@
 import type { Snippet } from 'svelte';
-import { type Placement } from '@chenzy-design/core';
-type TriggerKind = 'hover' | 'focus' | 'click' | 'custom';
-type Theme = 'dark' | 'light';
-type Status = 'default' | 'warning' | 'error';
+import { type Position } from './placement.js';
+type TriggerKind = 'hover' | 'focus' | 'click' | 'custom' | 'contextMenu';
+type Spacing = number | {
+    x: number;
+    y: number;
+};
+type MarginObject = {
+    marginLeft?: number;
+    marginTop?: number;
+    marginRight?: number;
+    marginBottom?: number;
+};
 interface Props {
     content?: string | Snippet;
-    open?: boolean;
-    defaultOpen?: boolean;
+    /** 受控显隐（配合 trigger='custom'），对齐 Semi visible。undefined = 非受控 */
+    visible?: boolean | undefined;
+    /** 非受控初始显隐 */
+    defaultVisible?: boolean;
     trigger?: TriggerKind | Array<TriggerKind>;
-    placement?: Placement;
+    /** 弹出方位，Semi 12 方位命名（top/topLeft/leftTop…），默认 top */
+    position?: Position;
     /** 视口溢出时翻转到对侧 */
     autoAdjustOverflow?: boolean;
+    /** 浮层与触发器的距离（px）；{x,y} 时主轴取对应分量。默认 8 */
+    spacing?: Spacing | undefined;
+    /** 计算溢出翻转时增加的冗余安全边距（对齐 Semi margin），默认 0 */
+    margin?: number | MarginObject;
     mouseEnterDelay?: number;
     mouseLeaveDelay?: number;
-    showArrow?: boolean;
-    /** start/end 对齐时箭头指向触发器中心（默认 false：贴对齐边） */
+    /** 是否显示箭头，或传自定义箭头 Snippet（Popover 传双 path），默认 true */
+    showArrow?: boolean | Snippet;
+    /** 箭头是否指向触发元素中心（需 showArrow），默认 true */
     arrowPointAtCenter?: boolean;
-    theme?: Theme;
-    /** 语义态：非 default 时内容前渲染对应状态图标 */
-    status?: Status;
-    maxWidth?: number | string;
     disabled?: boolean;
-    /** 浮层 z-index（覆盖 CSS token --cd-tooltip-z） */
-    zIndex?: number;
-    /** 阻止浮层上的点击事件冒泡，默认 true */
+    /** 是否允许触发显示；false 时不响应 hover/click/focus/contextMenu（custom 不受影响），默认 true */
+    condition?: boolean;
+    /** hover 触发下，点击浮层内部即关闭，默认 false */
+    clickToHide?: boolean;
+    /** 关闭时保留浮层 DOM 不销毁（--hidden 隐藏），默认 false */
+    keepDOM?: boolean;
+    /** hover 触发时不响应键盘 focus 显隐，默认 false */
+    disableFocusListener?: boolean;
+    /** 是否展示进出场动画，默认 true */
+    motion?: boolean;
+    /**
+     * 是否从触发元素中心处变换（仅影响动效 transform-origin），默认 true。对齐 Semi transformFromCenter，
+     * 一般无需改动。false 时进出场缩放从浮层自身原点起。
+     */
+    transformFromCenter?: boolean;
+    /** 浮层 z-index（覆盖 CSS token --cd-z-tooltip），默认 undefined（走 token，=1060） */
+    zIndex?: number | undefined;
+    /** 浮层自定义类名（追加到浮层元素） */
+    class?: string;
+    /** 浮层自定义内联样式（追加到浮层元素） */
+    style?: string;
+    /** 阻止浮层上的点击事件冒泡，默认 false（对齐 Semi） */
     stopPropagation?: boolean;
+    /** Esc 关闭浮层，默认 true（WCAG 1.4.13：hover/focus 浮层也须可由 Esc 关闭） */
+    closeOnEsc?: boolean;
     /** 显示时阻止页面滚动 */
     preventScroll?: boolean;
-    /** 浮层完全关闭（动画结束）后的回调 */
-    afterClose?: () => void;
+    /** 更新该值手动触发浮层重新定位（对齐 Semi rePosKey） */
+    rePosKey?: string | number | undefined;
     /** 自定义浮层挂载容器（缺省回退 ConfigProvider 全局，再回退 body） */
-    getPopupContainer?: () => HTMLElement | null | undefined;
-    onOpenChange?: (open: boolean) => void;
+    getPopupContainer?: (() => HTMLElement | null | undefined) | undefined;
+    /** 显隐切换回调（对齐 Semi onVisibleChange） */
+    onVisibleChange?: ((visible: boolean) => void) | undefined;
+    /** 点击浮层与触发器外部区域的回调（仅 custom/click 有效，对齐 Semi onClickOutSide） */
+    onClickOutSide?: ((e: MouseEvent) => void) | undefined;
+    /** 浮层完全关闭后的回调 */
+    afterClose?: (() => void) | undefined;
+    /**
+     * 浮层 wrapper 的类名前缀（对齐 Semi prefixCls）：默认 'cd-tooltip'（深色 grey-7 浮层）。
+     * Popover/Popconfirm 传 'cd-popover' 切换整套类名前缀 + 浅色浮层视觉 + 双 path 箭头。
+     * 拼 {prefixCls}-wrapper / {prefixCls}-icon-arrow / {prefixCls}-with-arrow。
+     */
+    prefixCls?: string;
+    /**
+     * 当 children 为 disabled，或 children 为多个元素时，外层包裹 span 的类名（对齐 Semi wrapperClassName）。
+     * 此库始终以 span 包裹触发器，故该类名恒作用于包裹 span。
+     */
+    wrapperClassName?: string;
+    /**
+     * 外层包裹 span（rootEl，即定位参照的触发宿主）的内联样式。
+     * 用于让包裹 span 直接承载触发盒（如 UserGuide 的 fixed 定位空锚点），
+     * 避免子元素 position:fixed 使包裹 span 塌缩为 0 尺寸导致 floating 定位错位。
+     */
+    triggerStyle?: string;
+    /**
+     * 浮层 wrapper 节点的 id（对齐 Semi wrapperId）；trigger 的 aria 属性指向此 id，
+     * 不设则组件随机生成。
+     */
+    wrapperId?: string | undefined;
+    /** 浮层 role（对齐 Semi role），默认 'tooltip'。Popover 传 'dialog' 承载可交互富内容。 */
+    role?: string;
+    /** dialog 模式（role=dialog）：焦点陷入浮层（Tab 循环），默认随 role==='dialog' */
+    guardFocus?: boolean | undefined;
+    /** 关闭后焦点归还触发器（仅 guardFocus 时生效），默认 true */
+    returnFocusOnClose?: boolean;
+    /** dialog 模式无标题时的兜底 aria-label（Popover 传入） */
+    dialogLabel?: string | undefined;
+    /** dialog 模式浮层的 aria-labelledby（Popover 有标题时传入） */
+    ariaLabelledby?: string | undefined;
     children?: Snippet;
 }
 declare const Tooltip: import("svelte").Component<Props, {}, "">;

package/dist/tooltip/Tooltip.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.svelte.d.ts","sourceRoot":"","sources":["../../src/tooltip/Tooltip.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAOrF,KAAK,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC1D,KAAK,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAC9B,KAAK,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9C,UAAU,KAAK;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACzD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAwPH,QAAA,MAAM,OAAO,2CAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Tooltip.svelte.d.ts","sourceRoot":"","sources":["../../src/tooltip/Tooltip.svelte.ts"],"names":[],"mappings":"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"}

package/dist/tooltip/index.d.ts

@@ -1,3 +1,4 @@
 export { default as Tooltip } from './Tooltip.svelte';
 export { meta as tooltipMeta } from './meta.js';
+export { type Position, POSITION_SET, positionToPlacement, placementToPosition, } from './placement.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tooltip/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tooltip/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tooltip/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,KAAK,QAAQ,EACb,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/tooltip/index.js

@@ -1,2 +1,3 @@
 export { default as Tooltip } from './Tooltip.svelte';
 export { meta as tooltipMeta } from './meta.js';
+export { POSITION_SET, positionToPlacement, placementToPosition, } from './placement.js';

package/dist/tooltip/meta.d.ts

@@ -1,80 +1,177 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * See specs/00-foundation/ai-friendly.spec.md.
+ * 严格对齐 Semi Design semi-ui/tooltip 的 API 表。
  */
 export declare const meta: {
     readonly name: "Tooltip";
     readonly category: "show";
-    readonly description: "文字提示，鼠标悬停/聚焦/点击触发元素时展示简短说明。支持常用 placement、箭头、延迟、dark/light 主题、status 语义图标与 custom 完全受控触发，浮层命令式定位。";
+    readonly description: "文字提示，鼠标悬停/聚焦/点击/右键触发元素时展示简短说明。固定深色浮层（grey-7），DOM 严格对齐 Semi：.cd-tooltip-wrapper[x-placement] > .cd-tooltip-content + 单 path 箭头 .cd-tooltip-icon-arrow（fill=currentColor）。支持 12 方位 position、hover/focus/click/custom/contextMenu 触发、延迟、custom 完全受控、condition 条件触发，浮层命令式定位（对齐 Semi）。prefixCls 机制供 Popover/Popconfirm 复用切换前缀。";
     readonly props: readonly [{
         readonly name: "content";
         readonly type: "string | Snippet";
         readonly default: "undefined";
         readonly desc: "提示内容，为空不显示";
     }, {
-        readonly name: "open";
+        readonly name: "visible";
         readonly type: "boolean";
         readonly default: "undefined";
-        readonly desc: "受控显隐";
+        readonly desc: "受控显隐（配合 trigger=custom）";
     }, {
-        readonly name: "defaultOpen";
+        readonly name: "defaultVisible";
         readonly type: "boolean";
         readonly default: "false";
         readonly desc: "非受控初始显隐";
     }, {
         readonly name: "trigger";
-        readonly type: "'hover'|'focus'|'click'|'custom'|Array<'hover'|'focus'|'click'|'custom'>";
-        readonly default: "['hover','focus']";
-        readonly desc: "触发方式，可组合；'custom' 完全受控（仅 open + onOpenChange，不自动 hover/click/focus）";
+        readonly type: "'hover'|'focus'|'click'|'custom'|'contextMenu'|Array<...>";
+        readonly default: "'hover'";
+        readonly desc: "触发方式，可组合；'custom' 完全受控（仅 visible + onVisibleChange）；'contextMenu' 右键触发";
     }, {
-        readonly name: "placement";
-        readonly type: "'top'|'topLeft'|'topRight'|'bottom'|'bottomLeft'|'bottomRight'|'left'|'right'";
-        readonly default: "top";
-        readonly desc: "浮层方位";
+        readonly name: "position";
+        readonly type: "'top'|'topLeft'|'topRight'|'left'|'leftTop'|'leftBottom'|'right'|'rightTop'|'rightBottom'|'bottom'|'bottomLeft'|'bottomRight'|'leftTopOver'|'rightTopOver'";
+        readonly default: "'top'";
+        readonly desc: "弹出方位（Semi 12 方位命名 + 2 Over）";
+    }, {
+        readonly name: "autoAdjustOverflow";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "视口溢出时翻转到对侧";
+    }, {
+        readonly name: "spacing";
+        readonly type: "number | { x: number; y: number }";
+        readonly default: "8";
+        readonly desc: "浮层与触发器距离(px)";
+    }, {
+        readonly name: "margin";
+        readonly type: "number | { marginLeft; marginTop; marginRight; marginBottom }";
+        readonly default: "0";
+        readonly desc: "计算溢出翻转时增加的冗余安全边距";
     }, {
         readonly name: "mouseEnterDelay";
         readonly type: "number";
-        readonly default: "100";
+        readonly default: "50";
         readonly desc: "hover 进入延迟(ms)";
     }, {
         readonly name: "mouseLeaveDelay";
         readonly type: "number";
-        readonly default: "100";
+        readonly default: "50";
         readonly desc: "hover 离开延迟(ms)";
     }, {
         readonly name: "showArrow";
-        readonly type: "boolean";
+        readonly type: "boolean | Snippet";
         readonly default: "true";
-        readonly desc: "是否显示箭头";
+        readonly desc: "是否显示箭头，或传自定义箭头 Snippet";
     }, {
         readonly name: "arrowPointAtCenter";
         readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "箭头是否指向触发元素中心（需 showArrow）";
+    }, {
+        readonly name: "disabled";
+        readonly type: "boolean";
         readonly default: "false";
-        readonly desc: "start/end 对齐时箭头指向触发器中心";
+        readonly desc: "禁用触发";
     }, {
-        readonly name: "theme";
-        readonly type: "'dark'|'light'";
-        readonly default: "dark";
-        readonly desc: "主题";
+        readonly name: "condition";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "false 时不响应 hover/click/focus 触发（custom 不受影响）";
     }, {
-        readonly name: "status";
-        readonly type: "'default'|'warning'|'error'";
-        readonly default: "default";
-        readonly desc: "语义态：非 default 时内容前渲染对应状态图标（图标 aria-label 经 locale）";
+        readonly name: "clickToHide";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "hover 触发下点击浮层内部即关闭";
     }, {
-        readonly name: "maxWidth";
-        readonly type: "number | string";
-        readonly default: "300";
-        readonly desc: "浮层最大宽度";
+        readonly name: "keepDOM";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "关闭时保留浮层 DOM 不销毁（--hidden 隐藏）";
     }, {
-        readonly name: "disabled";
+        readonly name: "disableFocusListener";
         readonly type: "boolean";
         readonly default: "false";
-        readonly desc: "禁用触发";
+        readonly desc: "hover 触发时不响应键盘 focus 显隐";
+    }, {
+        readonly name: "motion";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "是否展示进出场动画，reduced-motion 退化";
+    }, {
+        readonly name: "transformFromCenter";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "是否从触发元素中心处变换（仅影响动效 transform-origin，一般无需改动）";
+    }, {
+        readonly name: "zIndex";
+        readonly type: "number";
+        readonly default: "undefined";
+        readonly desc: "浮层 z-index（覆盖 token --cd-z-tooltip，=1060）";
+    }, {
+        readonly name: "prefixCls";
+        readonly type: "string";
+        readonly default: "'cd-tooltip'";
+        readonly desc: "浮层 wrapper 类名前缀（对齐 Semi prefixCls）；Popover 传 cd-popover 切换整套前缀与视觉";
+    }, {
+        readonly name: "wrapperClassName";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "触发器包裹 span 的类名（对齐 Semi wrapperClassName）";
+    }, {
+        readonly name: "wrapperId";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "浮层 wrapper 节点 id（对齐 Semi wrapperId）；不设则自动生成，trigger 的 aria 指向它";
+    }, {
+        readonly name: "class";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "浮层自定义类名";
+    }, {
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "浮层自定义内联样式（如覆盖 max-width）";
+    }, {
+        readonly name: "stopPropagation";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "阻止浮层上的点击事件冒泡";
+    }, {
+        readonly name: "closeOnEsc";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "Esc 关闭浮层（WCAG 1.4.13）";
+    }, {
+        readonly name: "preventScroll";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "显示时阻止页面滚动";
+    }, {
+        readonly name: "rePosKey";
+        readonly type: "string | number";
+        readonly default: "undefined";
+        readonly desc: "更新该值手动触发浮层重新定位";
+    }, {
+        readonly name: "getPopupContainer";
+        readonly type: "() => HTMLElement | null | undefined";
+        readonly default: "undefined";
+        readonly desc: "自定义浮层挂载容器（缺省回退 ConfigProvider 全局，再回退 body）";
+    }, {
+        readonly name: "onVisibleChange";
+        readonly type: "(visible: boolean) => void";
+        readonly default: "undefined";
+        readonly desc: "显隐切换回调";
+    }, {
+        readonly name: "onClickOutSide";
+        readonly type: "(e: MouseEvent) => void";
+        readonly default: "undefined";
+        readonly desc: "点击浮层与触发器外部的回调（仅 custom/click）";
     }, {
-        readonly name: "onOpenChange";
-        readonly type: "(open: boolean) => void";
+        readonly name: "afterClose";
+        readonly type: "() => void";
         readonly default: "undefined";
+        readonly desc: "浮层完全关闭后的回调";
     }, {
         readonly name: "children";
         readonly type: "Snippet";
@@ -84,8 +181,8 @@ export declare const meta: {
     readonly a11y: {
         readonly role: "tooltip";
         readonly keyboard: readonly ["Escape"];
-        readonly notes: readonly ["浮层 role=tooltip，使用 useId 生成唯一 id", "触发元素 open 时加 aria-describedby 指向浮层", "focus 触发支持键盘聚焦展示，click 触发用 useDismiss 处理 Escape 与外部点击", "custom 触发不绑定 hover/click/focus，显隐完全由受控 open + onOpenChange 控制", "status 非 default 时状态图标用 role=img + aria-label（经 locale）"];
+        readonly notes: readonly ["浮层 role=tooltip，使用 useId 生成唯一 id", "触发元素 visible 时加 aria-describedby 指向浮层", "focus 触发支持键盘聚焦展示；closeOnEsc 时 click/custom 触发用 useDismiss 处理 Escape 与外部点击", "custom 触发不绑定 hover/click/focus，显隐完全由受控 visible + onVisibleChange 控制", "condition=false 时禁止一切自动触发（custom 不受影响）"];
     };
-    readonly tokens: readonly ["--cd-tooltip-*", "--cd-focus-ring", "--cd-motion-*"];
+    readonly tokens: readonly ["--cd-color-tooltip-bg-default", "--cd-color-tooltip-text-default", "--cd-color-tooltip-icon-default", "--cd-color-tooltip-arrow-icon-default", "--cd-radius-tooltip", "--cd-font-tooltip-fontsize", "--cd-width-tooltip", "--cd-width-tooltip-arrow", "--cd-height-tooltip-arrow", "--cd-width-tooltip-arrow-vertical", "--cd-height-tooltip-arrow-vertical", "--cd-spacing-tooltip-content-paddingtop", "--cd-spacing-tooltip-content-paddingright", "--cd-spacing-tooltip-content-paddingbottom", "--cd-spacing-tooltip-content-paddingleft", "--cd-spacing-tooltip-arrow-offset-x", "--cd-spacing-tooltip-arrow-offset-y", "--cd-spacing-tooltip-arrow-adjusted-offset-x", "--cd-spacing-tooltip-arrow-adjusted-offset-y", "--cd-filter-tooltip-bg", "--cd-z-tooltip", "--cd-animation-duration-tooltip-in", "--cd-animation-duration-tooltip-out", "--cd-animation-function-tooltip-in", "--cd-animation-function-tooltip-out", "--cd-tooltip-motion-zoom-scale-from", "--cd-tooltip-motion-zoom-opacity-from", "--cd-tooltip-motion-zoom-opacity-to", "--cd-tooltip-horizontal-rate", "--cd-tooltip-vertical-rate"];
 };
 //# sourceMappingURL=meta.d.ts.map

package/dist/tooltip/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/tooltip/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDP,CAAC"}
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/tooltip/meta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqHP,CAAC"}

package/dist/tooltip/meta.js

@@ -1,46 +1,76 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * See specs/00-foundation/ai-friendly.spec.md.
+ * 严格对齐 Semi Design semi-ui/tooltip 的 API 表。
  */
 export const meta = {
     name: 'Tooltip',
     category: 'show',
-    description: '文字提示，鼠标悬停/聚焦/点击触发元素时展示简短说明。支持常用 placement、箭头、延迟、dark/light 主题、status 语义图标与 custom 完全受控触发，浮层命令式定位。',
+    description: '文字提示，鼠标悬停/聚焦/点击/右键触发元素时展示简短说明。固定深色浮层（grey-7），DOM 严格对齐 Semi：.cd-tooltip-wrapper[x-placement] > .cd-tooltip-content + 单 path 箭头 .cd-tooltip-icon-arrow（fill=currentColor）。支持 12 方位 position、hover/focus/click/custom/contextMenu 触发、延迟、custom 完全受控、condition 条件触发，浮层命令式定位（对齐 Semi）。prefixCls 机制供 Popover/Popconfirm 复用切换前缀。',
     props: [
         { name: 'content', type: 'string | Snippet', default: 'undefined', desc: '提示内容，为空不显示' },
-        { name: 'open', type: 'boolean', default: 'undefined', desc: '受控显隐' },
-        { name: 'defaultOpen', type: 'boolean', default: 'false', desc: '非受控初始显隐' },
+        { name: 'visible', type: 'boolean', default: 'undefined', desc: '受控显隐（配合 trigger=custom）' },
+        { name: 'defaultVisible', type: 'boolean', default: 'false', desc: '非受控初始显隐' },
         {
             name: 'trigger',
-            type: "'hover'|'focus'|'click'|'custom'|Array<'hover'|'focus'|'click'|'custom'>",
-            default: "['hover','focus']",
-            desc: "触发方式，可组合；'custom' 完全受控（仅 open + onOpenChange，不自动 hover/click/focus）",
+            type: "'hover'|'focus'|'click'|'custom'|'contextMenu'|Array<...>",
+            default: "'hover'",
+            desc: "触发方式，可组合；'custom' 完全受控（仅 visible + onVisibleChange）；'contextMenu' 右键触发",
         },
         {
-            name: 'placement',
-            type: "'top'|'topLeft'|'topRight'|'bottom'|'bottomLeft'|'bottomRight'|'left'|'right'",
-            default: 'top',
-            desc: '浮层方位',
+            name: 'position',
+            type: "'top'|'topLeft'|'topRight'|'left'|'leftTop'|'leftBottom'|'right'|'rightTop'|'rightBottom'|'bottom'|'bottomLeft'|'bottomRight'|'leftTopOver'|'rightTopOver'",
+            default: "'top'",
+            desc: '弹出方位（Semi 12 方位命名 + 2 Over）',
         },
-        { name: 'mouseEnterDelay', type: 'number', default: '100', desc: 'hover 进入延迟(ms)' },
-        { name: 'mouseLeaveDelay', type: 'number', default: '100', desc: 'hover 离开延迟(ms)' },
-        { name: 'showArrow', type: 'boolean', default: 'true', desc: '是否显示箭头' },
+        { name: 'autoAdjustOverflow', type: 'boolean', default: 'true', desc: '视口溢出时翻转到对侧' },
+        { name: 'spacing', type: 'number | { x: number; y: number }', default: '8', desc: '浮层与触发器距离(px)' },
+        {
+            name: 'margin',
+            type: 'number | { marginLeft; marginTop; marginRight; marginBottom }',
+            default: '0',
+            desc: '计算溢出翻转时增加的冗余安全边距',
+        },
+        { name: 'mouseEnterDelay', type: 'number', default: '50', desc: 'hover 进入延迟(ms)' },
+        { name: 'mouseLeaveDelay', type: 'number', default: '50', desc: 'hover 离开延迟(ms)' },
+        { name: 'showArrow', type: 'boolean | Snippet', default: 'true', desc: '是否显示箭头，或传自定义箭头 Snippet' },
         {
             name: 'arrowPointAtCenter',
             type: 'boolean',
-            default: 'false',
-            desc: 'start/end 对齐时箭头指向触发器中心',
+            default: 'true',
+            desc: '箭头是否指向触发元素中心（需 showArrow）',
+        },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '禁用触发' },
+        {
+            name: 'condition',
+            type: 'boolean',
+            default: 'true',
+            desc: 'false 时不响应 hover/click/focus 触发（custom 不受影响）',
         },
-        { name: 'theme', type: "'dark'|'light'", default: 'dark', desc: '主题' },
+        { name: 'clickToHide', type: 'boolean', default: 'false', desc: 'hover 触发下点击浮层内部即关闭' },
+        { name: 'keepDOM', type: 'boolean', default: 'false', desc: '关闭时保留浮层 DOM 不销毁（--hidden 隐藏）' },
+        { name: 'disableFocusListener', type: 'boolean', default: 'false', desc: 'hover 触发时不响应键盘 focus 显隐' },
+        { name: 'motion', type: 'boolean', default: 'true', desc: '是否展示进出场动画，reduced-motion 退化' },
+        { name: 'transformFromCenter', type: 'boolean', default: 'true', desc: '是否从触发元素中心处变换（仅影响动效 transform-origin，一般无需改动）' },
+        { name: 'zIndex', type: 'number', default: 'undefined', desc: '浮层 z-index（覆盖 token --cd-z-tooltip，=1060）' },
+        { name: 'prefixCls', type: 'string', default: "'cd-tooltip'", desc: '浮层 wrapper 类名前缀（对齐 Semi prefixCls）；Popover 传 cd-popover 切换整套前缀与视觉' },
+        { name: 'wrapperClassName', type: 'string', default: "''", desc: '触发器包裹 span 的类名（对齐 Semi wrapperClassName）' },
+        { name: 'wrapperId', type: 'string', default: 'undefined', desc: '浮层 wrapper 节点 id（对齐 Semi wrapperId）；不设则自动生成，trigger 的 aria 指向它' },
+        { name: 'class', type: 'string', default: "''", desc: '浮层自定义类名' },
+        { name: 'style', type: 'string', default: "''", desc: '浮层自定义内联样式（如覆盖 max-width）' },
+        { name: 'stopPropagation', type: 'boolean', default: 'false', desc: '阻止浮层上的点击事件冒泡' },
+        { name: 'closeOnEsc', type: 'boolean', default: 'true', desc: 'Esc 关闭浮层（WCAG 1.4.13）' },
+        { name: 'preventScroll', type: 'boolean', default: 'false', desc: '显示时阻止页面滚动' },
+        { name: 'rePosKey', type: 'string | number', default: 'undefined', desc: '更新该值手动触发浮层重新定位' },
         {
-            name: 'status',
-            type: "'default'|'warning'|'error'",
-            default: 'default',
-            desc: '语义态：非 default 时内容前渲染对应状态图标（图标 aria-label 经 locale）',
+            name: 'getPopupContainer',
+            type: '() => HTMLElement | null | undefined',
+            default: 'undefined',
+            desc: '自定义浮层挂载容器（缺省回退 ConfigProvider 全局，再回退 body）',
         },
-        { name: 'maxWidth', type: 'number | string', default: '300', desc: '浮层最大宽度' },
-        { name: 'disabled', type: 'boolean', default: 'false', desc: '禁用触发' },
-        { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
+        { name: 'onVisibleChange', type: '(visible: boolean) => void', default: 'undefined', desc: '显隐切换回调' },
+        { name: 'onClickOutSide', type: '(e: MouseEvent) => void', default: 'undefined', desc: '点击浮层与触发器外部的回调（仅 custom/click）' },
+        { name: 'afterClose', type: '() => void', default: 'undefined', desc: '浮层完全关闭后的回调' },
         { name: 'children', type: 'Snippet', default: 'undefined', desc: '触发元素（必填）' },
     ],
     a11y: {
@@ -48,11 +78,45 @@ export const meta = {
         keyboard: ['Escape'],
         notes: [
             '浮层 role=tooltip，使用 useId 生成唯一 id',
-            '触发元素 open 时加 aria-describedby 指向浮层',
-            'focus 触发支持键盘聚焦展示，click 触发用 useDismiss 处理 Escape 与外部点击',
-            'custom 触发不绑定 hover/click/focus，显隐完全由受控 open + onOpenChange 控制',
-            'status 非 default 时状态图标用 role=img + aria-label（经 locale）',
+            '触发元素 visible 时加 aria-describedby 指向浮层',
+            'focus 触发支持键盘聚焦展示；closeOnEsc 时 click/custom 触发用 useDismiss 处理 Escape 与外部点击',
+            'custom 触发不绑定 hover/click/focus，显隐完全由受控 visible + onVisibleChange 控制',
+            'condition=false 时禁止一切自动触发（custom 不受影响）',
         ],
     },
-    tokens: ['--cd-tooltip-*', '--cd-focus-ring', '--cd-motion-*'],
+    tokens: [
+        // 严格对齐 Semi（semi-foundation/tooltip/variables.scss + animation.scss），
+        // 组件 CSS 直接消费，无中间变量层（已移除 tooltip-bg/color/radius/padding… 中间变量）。
+        '--cd-color-tooltip-bg-default',
+        '--cd-color-tooltip-text-default',
+        '--cd-color-tooltip-icon-default',
+        '--cd-color-tooltip-arrow-icon-default',
+        '--cd-radius-tooltip',
+        '--cd-font-tooltip-fontsize',
+        '--cd-width-tooltip',
+        '--cd-width-tooltip-arrow',
+        '--cd-height-tooltip-arrow',
+        '--cd-width-tooltip-arrow-vertical',
+        '--cd-height-tooltip-arrow-vertical',
+        '--cd-spacing-tooltip-content-paddingtop',
+        '--cd-spacing-tooltip-content-paddingright',
+        '--cd-spacing-tooltip-content-paddingbottom',
+        '--cd-spacing-tooltip-content-paddingleft',
+        '--cd-spacing-tooltip-arrow-offset-x',
+        '--cd-spacing-tooltip-arrow-offset-y',
+        '--cd-spacing-tooltip-arrow-adjusted-offset-x',
+        '--cd-spacing-tooltip-arrow-adjusted-offset-y',
+        '--cd-filter-tooltip-bg',
+        '--cd-z-tooltip',
+        // 进出场动画（Semi animation.scss，100ms + cubic-bezier）+ zoom 关键帧参数
+        '--cd-animation-duration-tooltip-in',
+        '--cd-animation-duration-tooltip-out',
+        '--cd-animation-function-tooltip-in',
+        '--cd-animation-function-tooltip-out',
+        '--cd-tooltip-motion-zoom-scale-from',
+        '--cd-tooltip-motion-zoom-opacity-from',
+        '--cd-tooltip-motion-zoom-opacity-to',
+        '--cd-tooltip-horizontal-rate',
+        '--cd-tooltip-vertical-rate',
+    ],
 };

package/dist/tooltip/placement.d.ts

@@ -1,4 +1,24 @@
-import { type Placement, type Side } from '@chenzy-design/core';
+import { parsePlacement, makePlacement, type Placement, type Side } from '@chenzy-design/core';
+/**
+ * Semi Design 的 12 方位 position 命名（top/topLeft/leftTop…）↔ core 的 side+align Placement。
+ * Tooltip/Popover/Popconfirm 三者共享此映射（对齐 Semi 的继承链）。
+ *
+ * Semi 命名语义（见 semi-foundation/tooltip/arrow.scss）：
+ *  - top/bottom 系：主轴纵向、交叉轴横向。Left=浮层左边缘对齐触发器左（align start）、
+ *    Right=右边缘对齐（align end）、无后缀=居中。
+ *  - left/right 系：主轴横向、交叉轴纵向。Top=浮层顶边缘对齐（align start）、
+ *    Bottom=底边缘对齐（align end）、无后缀=居中。
+ *  - leftTopOver/rightTopOver：Semi 特殊，浮层顶部与触发器顶部对齐并允许覆盖到触发器上方，
+ *    定位语义等同 leftStart/rightStart（我们不做 over 覆盖，退化为 start 对齐）。
+ */
+export type Position = 'top' | 'topLeft' | 'topRight' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom' | 'bottom' | 'bottomLeft' | 'bottomRight' | 'leftTopOver' | 'rightTopOver';
+/** Semi 12 方位可选值集合（对齐 semi-foundation/popover/constants POSITION_SET）。 */
+export declare const POSITION_SET: readonly Position[];
+/** Semi position（如 topLeft）→ core Placement（如 topStart）。 */
+export declare function positionToPlacement(position: Position): Placement;
+/** core Placement（flip 后，如 bottomStart）→ Semi position（如 bottomLeft）。 */
+export declare function placementToPosition(placement: Placement): Position;
 /** 取 placement 的主方向 side（驱动箭头朝向的 class）。 */
 export declare function resolveSide(placement: Placement): Side;
+export { makePlacement, parsePlacement };
 //# sourceMappingURL=placement.d.ts.map

package/dist/tooltip/placement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/tooltip/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhF,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAEtD"}
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/tooltip/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAChB,KAAK,GACL,SAAS,GACT,UAAU,GACV,MAAM,GACN,SAAS,GACT,YAAY,GACZ,OAAO,GACP,UAAU,GACV,aAAa,GACb,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,aAAa,GACb,cAAc,CAAC;AAEnB,0EAA0E;AAC1E,eAAO,MAAM,YAAY,EAAE,SAAS,QAAQ,EAelC,CAAC;AAkCX,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAElE;AAED,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAEtD;AAED,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}