iter(g139): 提示气泡支持左右方位

packages/skin/ui/src/position.ts

@@ -9,3 +9,16 @@ export function flip(trigger: HTMLElement, panel: HTMLElement, preferred: 'top'
   if (preferred === 'top') return up >= h + GAP || up >= down ? 'top' : 'bottom'; // 首选上方：放得下、或不比下方更局促就保持
   return down >= h + GAP || down >= up ? 'bottom' : 'top'; // 首选下方：对称判定
 }
+
+/*** 浮层方位判定（四向）：水平方向按宽度判左右空间，垂直方向复用 flip 的上下一套逻辑 ***/
+export function flipSide(trigger: HTMLElement, panel: HTMLElement, preferred: 'top' | 'bottom' | 'left' | 'right'): 'top' | 'bottom' | 'left' | 'right' {
+  const GAP = 8;  // 与样式表预留的间距一致
+  const MIN = 24; // 兜底：面板尚未量出宽度时按最小可读宽度估算
+  if (preferred === 'top' || preferred === 'bottom') return flip(trigger, panel, preferred); // 垂直交回原判定
+  const t = trigger.getBoundingClientRect();
+  const w = panel.offsetWidth || MIN;
+  const left = t.left;                          // 触发器左侧可用空间
+  const right = window.innerWidth - t.right;    // 触发器右侧可用空间
+  if (preferred === 'left') return left >= w + GAP || left >= right ? 'left' : 'right'; // 对称判定
+  return right >= w + GAP || right >= left ? 'right' : 'left';
+}

packages/skin/ui/src/tooltip.ts

@@ -1,6 +1,6 @@
 import { effect, h, signal } from '@ui-arch/frame';
 import type { TooltipProps } from './types.js';
-import { flip } from './position.js';
+import { flipSide } from './position.js';
 
 let seq = 0; // 全局自增序号：保证每个气泡 id 唯一，供 aria-describedby 关联
 
@@ -8,7 +8,7 @@ let seq = 0; // 全局自增序号：保证每个气泡 id 唯一，供 aria-des
 export function tooltip(props: TooltipProps, trigger: HTMLElement): HTMLElement {
   // —— 状态集中声明 ——
   const open = signal(false);       // 气泡显隐
-  const place = signal(props.placement ?? 'top'); // 实际生效方位：出场时按视口空间自动翻转
+  const place = signal<'top' | 'bottom' | 'left' | 'right'>(props.placement ?? 'top'); // 实际生效方位：出场时按视口空间自动翻转
   const id = `ua-tip-${++seq}`;     // 气泡唯一 id
   const delay = props.delay ?? 150; // 出场延迟毫秒；<=0 视为立即显示
   let timer: number | null = null;  // 出场延迟计时器句柄
@@ -64,7 +64,7 @@ export function tooltip(props: TooltipProps, trigger: HTMLElement): HTMLElement
   // —— 触摸屏：没有 hover，改点按。按下即出（不等 150ms），抬手留 1.2s 再收，否则手指正挡着气泡就没了 ——
   root.addEventListener('pointerdown', (e: PointerEvent) => { if (e.pointerType === 'touch') show(); });
   root.addEventListener('pointerup', (e: PointerEvent) => { if (e.pointerType === 'touch') hideLater(); });
-  effect(() => { if (open()) place(flip(trigger, bubble, props.placement ?? 'top')); }); // 每次出场重算方位：空间不足自动翻转
+  effect(() => { if (open()) place(flipSide(trigger, bubble, props.placement ?? 'top')); }); // 每次出场重算方位：空间不足自动翻转
   root.addEventListener('keydown', (e: KeyboardEvent) => {
     if (e.key === 'Escape') { e.stopPropagation(); hide(); } // Esc 立即收起且不影响外层弹层
   });

packages/skin/ui/src/types.ts

@@ -4,7 +4,7 @@ import type { Signal } from '@ui-arch/frame';
 /*** 悬浮提示入参 ***/
 export interface TooltipProps {
   content: string;             // 提示文案（纯文本）
-  placement?: 'top' | 'bottom'; // 气泡方位；缺省 top（触发器上方）
+  placement?: 'top' | 'bottom' | 'left' | 'right'; // 气泡方位；缺省 top，空间不足自动翻到对侧
   delay?: number;              // 出场延迟毫秒；缺省 150，传 0 立即显示
 }
 

packages/skin/ui/ua.manifest.json

@@ -1082,8 +1082,8 @@
           },
           {
             "n": "placement",
-            "t": "'top' | 'bottom'",
-            "d": "气泡方位；缺省 top（触发器上方）",
+            "t": "'top' | 'bottom' | 'left' | 'right'",
+            "d": "气泡方位；缺省 top，出场时按视口剩余空间自动翻到对侧（水平方位按宽度判左右）",
             "df": "top"
           },
           {
@@ -1104,7 +1104,8 @@
           "把提示要挂在的元素作为第二个参数传入，返回的包裹节点替换原位置（气泡绝对定位，不占布局）",
           "鼠标悬停或键盘聚焦后延迟 delay 毫秒出场，移出 / 失焦 / Esc 收起；空间不足时自动翻到另一侧",
           "触摸屏没有 hover：手指按下即出场，抬手后停留 1.2 秒再收起，免得手指正挡着就消失",
-          "气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案"
+          "气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案",
+          "方位支持上下左右四向：贴边或工具栏竖排时用 left / right，出场时按该方向剩余空间自动翻到对侧"
         ]
       },
       {

packages/skin/ui/ui.css

@@ -1790,7 +1790,6 @@ button.ua-step-dot:hover {
 }
 .ua-tip {
   position: absolute;
-  left: 50%;
   z-index: 30;
   max-width: 220px;
   padding: var(--ua-space-1) var(--ua-space-2);
@@ -1804,16 +1803,35 @@ button.ua-step-dot:hover {
   transition: opacity 0.16s ease-out, transform 0.16s ease-out;
 }
 .ua-tip-top {
+  left: 50%;
   bottom: calc(100% + 6px);
-  transform: translateX(-50%) translateY(3px);
+  transform: translate(-50%, 3px);
 }
 .ua-tip-bottom {
+  left: 50%;
   top: calc(100% + 6px);
-  transform: translateX(-50%) translateY(-3px);
+  transform: translate(-50%, -3px);
+}
+.ua-tip-left {
+  right: calc(100% + 6px);
+  top: 50%;
+  transform: translate(3px, -50%);
+}
+.ua-tip-right {
+  left: calc(100% + 6px);
+  top: 50%;
+  transform: translate(-3px, -50%);
 }
 .ua-tip.ua-open {
   opacity: 1;
-  transform: translateX(-50%) translateY(0);
+}
+.ua-tip-top.ua-open,
+.ua-tip-bottom.ua-open {
+  transform: translate(-50%, 0);
+}
+.ua-tip-left.ua-open,
+.ua-tip-right.ua-open {
+  transform: translate(0, -50%);
 }
 
 /* —— 通用禁用态：置灰 + 禁用光标 —— */