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

.ua/backlog.json

@@ -1468,6 +1468,14 @@
       "acceptance": "datePicker 新增 range/end/onRangeChange：首点定起点不收弹层、次点定终点并排序，区间内部有底色；文档 props/steps 与演示同步；npm run check 全绿",
       "notes": "自补：既有组件可用性细节",
       "status": "done"
+    },
+    {
+      "id": "g139",
+      "title": "提示气泡支持左右方位",
+      "motivation": "tooltip 只有上下两向：竖排工具栏、贴右边的内容只能硬翻，left/right 全靠调用方自己补样式；position.ts 的 flip 也只认上下",
+      "acceptance": "position 新增 flipSide（四向判定，水平按宽度算左右空间），tooltip placement 支持 left/right 并复用自动翻转；CSS 四向定位 + 出场位移分离；文档 props/steps 与演示同步；npm run check 全绿",
+      "notes": "自补：既有组件可用性细节",
+      "status": "open"
     }
   ]
 }

.ua/index.json

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

apps/demo/main.ts

@@ -464,13 +464,15 @@ const content = h(
   section(
     'sec-tooltip',
     '悬浮提示',
-    'tooltip 包裹触发器：hover / 聚焦延迟 150ms 出场，移出、失焦或 Esc 收起，气泡不抢指针；视口一侧空间不足时气泡自动翻到另一侧。',
+    'tooltip 包裹触发器：hover / 聚焦延迟 150ms 出场，移出、失焦或 Esc 收起，气泡不抢指针；方位支持上下左右四向，视口该侧空间不足时自动翻到对侧。',
     h(
       'div',
       { class: 'row' },
       tooltip({ content: '保存后立即生效' }, button({ label: '保存' })),
       tooltip({ content: '该操作不可撤销', placement: 'bottom' }, button({ label: '删除', variant: 'danger' })),
       tooltip({ content: '聚焦输入框同样会显示' }, textField({ placeholder: '聚焦我…' })),
+      tooltip({ content: '左侧方位：竖排工具栏常用', placement: 'left' }, button({ label: '左侧气泡', variant: 'ghost' })),
+      tooltip({ content: '右侧方位，贴右边时自动翻回左侧', placement: 'right' }, button({ label: '右侧气泡', variant: 'ghost' })),
     ),
   ),
   section(

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T07:31:10.742Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T07:32:30.909Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -588,7 +588,7 @@ toast.success('保存成功'); toast.error('网络请求失败', 5000)
 参数：
 
 - content（必填）：string —— 提示文案（纯文本）
-- placement（默认 top）：'top' | 'bottom' —— 气泡方位；缺省 top（触发器上方）
+- placement（默认 top）：'top' | 'bottom' | 'left' | 'right' —— 气泡方位；缺省 top，出场时按视口剩余空间自动翻到对侧（水平方位按宽度判左右）
 - delay（默认 150）：number —— 出场延迟毫秒；缺省 150，传 0 立即显示
 - trigger（必填）：HTMLElement —— 第二个参数：被包裹的触发器元素（按钮 / 输入框等任意 DOM）
 
@@ -604,6 +604,7 @@ tooltip({ content: '保存后立即生效' }, button({ label: '保存', onClick:
 2. 鼠标悬停或键盘聚焦后延迟 delay 毫秒出场，移出 / 失焦 / Esc 收起；空间不足时自动翻到另一侧
 3. 触摸屏没有 hover：手指按下即出场，抬手后停留 1.2 秒再收起，免得手指正挡着就消失
 4. 气泡设了 pointer-events: none，不会挡住下面的点击；aria-describedby 已关联，读屏能念出提示文案
+5. 方位支持上下左右四向：贴边或工具栏竖排时用 left / right，出场时按该方向剩余空间自动翻到对侧
 
 现场演示：apps/docs/demo.html#sec-tooltip
 

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'",
+            "t": "'top' | 'bottom' | 'left' | 'right'",
-            "d": "气泡方位；缺省 top（触发器上方）",
+            "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%);
 }
 
 /* —— 通用禁用态：置灰 + 禁用光标 —— */