@orbit-work/ui 0.1.0

package/src/components/composite/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,304 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { Button } from "../../primitives/Button"
+import { Tooltip } from "./index"
+
+const meta = {
+  title: "Composite/Tooltip",
+  component: Tooltip,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    side: {
+      control: "select",
+      options: ["top", "bottom", "left", "right"],
+      description: "Tooltip position relative to trigger",
+    },
+    align: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Tooltip alignment on the side",
+    },
+    delay: {
+      control: "number",
+      description: "Delay before showing (ms)",
+    },
+    offset: {
+      control: "number",
+      description: "Distance from trigger (px)",
+    },
+    showArrow: {
+      control: "boolean",
+      description: "Show arrow indicator",
+    },
+    followCursor: {
+      control: "boolean",
+      description: "Follow mouse cursor",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Disable tooltip",
+    },
+    maxWidth: {
+      control: "number",
+      description: "Maximum width (px)",
+    },
+  },
+} satisfies Meta<typeof Tooltip>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    content: "This is a helpful tooltip",
+    children: <Button variant="secondary">Hover me</Button>,
+    side: "top",
+  },
+}
+
+export const AllSides: Story = {
+  render: () => (
+    <div className="flex gap-16 items-center">
+      <Tooltip content="Top tooltip" side="top">
+        <Button variant="secondary">Top</Button>
+      </Tooltip>
+      <Tooltip content="Right tooltip" side="right">
+        <Button variant="secondary">Right</Button>
+      </Tooltip>
+      <Tooltip content="Bottom tooltip" side="bottom">
+        <Button variant="secondary">Bottom</Button>
+      </Tooltip>
+      <Tooltip content="Left tooltip" side="left">
+        <Button variant="secondary">Left</Button>
+      </Tooltip>
+    </div>
+  ),
+}
+
+export const AllAlignments: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="text-sm text-ow-text-2 mb-2">Top side, different alignments:</div>
+      <div className="flex gap-8 items-center">
+        <Tooltip content="Start aligned" side="top" align="start">
+          <Button variant="secondary">Align Start</Button>
+        </Tooltip>
+        <Tooltip content="Center aligned" side="top" align="center">
+          <Button variant="secondary">Align Center</Button>
+        </Tooltip>
+        <Tooltip content="End aligned" side="top" align="end">
+          <Button variant="secondary">Align End</Button>
+        </Tooltip>
+      </div>
+    </div>
+  ),
+}
+
+export const WithArrow: Story = {
+  args: {
+    content: "Tooltip with arrow indicator",
+    children: <Button variant="secondary">With Arrow</Button>,
+    showArrow: true,
+    side: "top",
+  },
+}
+
+export const WithoutArrow: Story = {
+  args: {
+    content: "Tooltip without arrow",
+    children: <Button variant="secondary">No Arrow</Button>,
+    showArrow: false,
+    side: "top",
+  },
+}
+
+export const LongContent: Story = {
+  args: {
+    content:
+      "This is a much longer tooltip text that demonstrates how the tooltip handles multi-line content with a maximum width constraint.",
+    children: <Button variant="secondary">Long Text</Button>,
+    side: "top",
+    maxWidth: 240,
+  },
+}
+
+export const CustomMaxWidth: Story = {
+  render: () => (
+    <div className="flex gap-8 items-center">
+      <Tooltip content="This tooltip has a small max width of 150px and will wrap sooner" maxWidth={150}>
+        <Button variant="secondary">Max 150px</Button>
+      </Tooltip>
+      <Tooltip
+        content="This tooltip has a larger max width of 400px so it can display more text in a single line before wrapping"
+        maxWidth={400}
+      >
+        <Button variant="secondary">Max 400px</Button>
+      </Tooltip>
+    </div>
+  ),
+}
+
+export const ShortDelay: Story = {
+  args: {
+    content: "Appears quickly (100ms delay)",
+    children: <Button variant="secondary">Short Delay</Button>,
+    delay: 100,
+    side: "top",
+  },
+}
+
+export const LongDelay: Story = {
+  args: {
+    content: "Takes longer to appear (800ms delay)",
+    children: <Button variant="secondary">Long Delay</Button>,
+    delay: 800,
+    side: "top",
+  },
+}
+
+export const FollowCursor: Story = {
+  args: {
+    content: "I follow your cursor!",
+    children: (
+      <div className="px-8 py-4 border border-ow-border [border-radius:var(--ow-radius-lg)] bg-ow-surface">
+        Move your mouse over this area
+      </div>
+    ),
+    followCursor: true,
+    showArrow: false,
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    content: "You won't see this",
+    children: <Button variant="secondary">Disabled Tooltip</Button>,
+    disabled: true,
+    side: "top",
+  },
+}
+
+export const Controlled: Story = {
+  render: () => {
+    const [open, setOpen] = useState(false)
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <Tooltip
+          content="This tooltip is controlled by the buttons below"
+          open={open}
+          onOpenChange={setOpen}
+          side="top"
+        >
+          <Button variant="secondary">Controlled Target</Button>
+        </Tooltip>
+        <div className="flex gap-2">
+          <Button variant="primary" size="sm" onClick={() => setOpen(true)}>
+            Show
+          </Button>
+          <Button variant="secondary" size="sm" onClick={() => setOpen(false)}>
+            Hide
+          </Button>
+          <Button variant="ghost" size="sm" onClick={() => setOpen(!open)}>
+            Toggle
+          </Button>
+        </div>
+        <div className="text-sm text-ow-text-2">State: {open ? "Open" : "Closed"}</div>
+      </div>
+    )
+  },
+}
+
+export const OnTextContent: Story = {
+  render: () => (
+    <div className="max-w-md text-ow-text">
+      <p>
+        You can use tooltips on{" "}
+        <Tooltip content="This is an inline tooltip">
+          <span className="underline decoration-dotted cursor-help">inline text</span>
+        </Tooltip>{" "}
+        to provide additional context without cluttering the interface.
+      </p>
+    </div>
+  ),
+}
+
+export const OnIcon: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Tooltip content="Settings">
+        <button className="w-8 h-8 flex items-center justify-center rounded hover:bg-ow-surface-2">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M8 10a2 2 0 100-4 2 2 0 000 4z" />
+            <path
+              fillRule="evenodd"
+              clipRule="evenodd"
+              d="M6.5 2a.5.5 0 00-.5.5v1.1a4.5 4.5 0 00-1.5.9l-.95-.55a.5.5 0 00-.68.18l-1.5 2.6a.5.5 0 00.18.68l.95.55a4.5 4.5 0 000 1.8l-.95.55a.5.5 0 00-.18.68l1.5 2.6a.5.5 0 00.68.18l.95-.55a4.5 4.5 0 001.5.9v1.1a.5.5 0 00.5.5h3a.5.5 0 00.5-.5v-1.1a4.5 4.5 0 001.5-.9l.95.55a.5.5 0 00.68-.18l1.5-2.6a.5.5 0 00-.18-.68l-.95-.55a4.5 4.5 0 000-1.8l.95-.55a.5.5 0 00.18-.68l-1.5-2.6a.5.5 0 00-.68-.18l-.95.55a4.5 4.5 0 00-1.5-.9V2.5a.5.5 0 00-.5-.5h-3z"
+            />
+          </svg>
+        </button>
+      </Tooltip>
+      <Tooltip content="Help">
+        <button className="w-8 h-8 flex items-center justify-center rounded hover:bg-ow-surface-2">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+            <path
+              fillRule="evenodd"
+              clipRule="evenodd"
+              d="M8 14A6 6 0 108 2a6 6 0 000 12zm0-9a1 1 0 00-1 1v.5a.5.5 0 01-1 0V6a2 2 0 113 1.732V8a.5.5 0 01-1 0V7a1 1 0 00-1-1zm.5 5.5a.5.5 0 11-1 0 .5.5 0 011 0z"
+            />
+          </svg>
+        </button>
+      </Tooltip>
+      <Tooltip content="Notifications">
+        <button className="w-8 h-8 flex items-center justify-center rounded hover:bg-ow-surface-2">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M8 14a2 2 0 002-2H6a2 2 0 002 2zm4-6V6a4 4 0 10-8 0v2L3 9v1h10V9l-1-1z" />
+          </svg>
+        </button>
+      </Tooltip>
+    </div>
+  ),
+}
+
+export const ComplexExample: Story = {
+  render: () => (
+    <div className="p-8 bg-ow-bg [border-radius:var(--ow-radius-lg)] border border-ow-border">
+      <div className="flex items-center gap-3 mb-4">
+        <h3 className="text-lg font-semibold text-ow-text">User Profile</h3>
+        <Tooltip content="Edit profile settings">
+          <button className="text-ow-text-3 hover:text-ow-text">
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+              <path d="M11.5 2a1.5 1.5 0 011.5 1.5v.5a.5.5 0 01-1 0v-.5a.5.5 0 00-.5-.5h-8a.5.5 0 00-.5.5v8a.5.5 0 00.5.5h.5a.5.5 0 010 1h-.5A1.5 1.5 0 012 11.5v-8A1.5 1.5 0 013.5 2h8zM14.854 6.146a.5.5 0 010 .708l-7 7a.5.5 0 01-.708 0l-3-3a.5.5 0 11.708-.708L7 12.293l6.646-6.647a.5.5 0 01.708 0z" />
+            </svg>
+          </button>
+        </Tooltip>
+      </div>
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-ow-text-2">Name:</span>
+          <span className="text-sm text-ow-text">张三</span>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="text-sm text-ow-text-2">Status:</span>
+          <Tooltip content="User is currently active and available">
+            <span className="inline-flex items-center gap-1 text-sm text-ow-success">
+              <span className="w-2 h-2 rounded-full bg-ow-success" />
+              Active
+            </span>
+          </Tooltip>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+/** Keyboard focus shows the tooltip immediately; press Escape to dismiss it. */
+export const FocusAndEscape: Story = {
+  args: {
+    content: "Shown on focus — press Escape to close",
+    children: <Button variant="secondary">Tab to me</Button>,
+    side: "bottom",
+  },
+}

package/src/components/composite/Tooltip/TooltipSource.test.mjs

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+test("Tooltip is the DS2 inverse surface with pop shadow, radius 8 and tooltip z-layer", () => {
+  assert.match(source, /bg-ow-tooltip-bg/)
+  assert.match(source, /text-ow-tooltip-text/)
+  assert.match(source, /\[box-shadow:var\(--ow-shadow-pop\)\]/)
+  assert.match(source, /\[border-radius:var\(--ow-radius-sm\)\]/)
+  assert.match(source, /z-\[var\(--ow-z-tooltip\)\]/)
+  assert.match(source, /maxWidth = 320/)
+})
+
+test("Tooltip enters in 120ms with ease-beacon, opacity only (no translation)", () => {
+  // R2 复审：时长由裸 120ms 换 var(--ow-dur-1)（同文件的缓动/圆角早已 token 化）
+  assert.match(source, /animate-\[ow-tooltip-in_var\(--ow-dur-1\)_var\(--ow-ease-beacon\)\]/)
+  assert.doesNotMatch(source, /animate-[^"]*translate/)
+})
+
+test("箭头是转 45° 的方块，不是圆疙瘩（§7 8px 档不适用于 8px 见方元素）", () => {
+  // W5 把 Tailwind rounded-sm(2px) 直换成 --ow-radius-sm(8px)，8×8 方块套 8px 圆角＝正圆，
+  // 转 45° 无形变。R2 复审改 --ow-radius-2xs(4px)。
+  // 8×8 的盒子上任何 ≥4px 圆角都等于正圆，所以箭头一律尖角（rounded-none）。
+  assert.match(source, /w-2 h-2 rounded-none bg-ow-tooltip-bg/)
+  assert.doesNotMatch(source, /w-2 h-2 \[border-radius:/)
+})
+
+test("focus shows immediately and Escape dismisses", () => {
+  assert.match(source, /onFocus=\{showNow\}/)
+  assert.match(source, /event\.key === "Escape"/)
+  assert.match(source, /onBlur=\{hide\}/)
+})

package/src/components/composite/Tooltip/index.tsx

@@ -0,0 +1,204 @@
+"use client"
+
+import { cva } from "class-variance-authority"
+import { type CSSProperties, type PointerEvent, type ReactNode, useEffect, useId, useRef, useState } from "react"
+import { cn } from "../../../lib/utils"
+
+const tooltipTriggerVariants = cva("relative inline-flex")
+
+const tooltipBubbleVariants = cva(
+  "absolute z-[var(--ow-z-tooltip)] w-max px-2 py-[5px] box-border [border-radius:var(--ow-radius-sm)] bg-ow-tooltip-bg text-ow-tooltip-text [box-shadow:var(--ow-shadow-pop)] text-ow-fs-caption leading-[18px] font-normal text-left whitespace-normal pointer-events-none animate-[ow-tooltip-in_var(--ow-dur-1)_var(--ow-ease-beacon)]",
+)
+
+export type TooltipSide = "top" | "bottom" | "left" | "right"
+export type TooltipAlign = "start" | "center" | "end"
+
+export type TooltipProps = {
+  content: ReactNode
+  children: ReactNode
+  side?: TooltipSide
+  align?: TooltipAlign
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  delay?: number
+  offset?: number
+  showArrow?: boolean
+  followCursor?: boolean
+  disabled?: boolean
+  maxWidth?: number | string
+  className?: string
+}
+
+/**
+ * Tooltip — the DS2 inverse surface (navy bubble / off-white text; inverted in dark).
+ * Radius 8, max-width 320, `--ow-shadow-pop`, `--ow-z-tooltip`.
+ * Appears in 120ms with `--ow-ease-beacon` (opacity only, no entry translation).
+ * Shows on hover (delayed) and on keyboard focus (immediate); Escape dismisses.
+ */
+export function Tooltip({
+  content,
+  children,
+  side = "top",
+  align = "center",
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  delay = 300,
+  offset = 8,
+  showArrow = true,
+  followCursor = false,
+  disabled = false,
+  maxWidth = 320,
+  className = "",
+}: TooltipProps) {
+  const id = useId()
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [internalOpen, setInternalOpen] = useState(defaultOpen)
+  const [cursor, setCursor] = useState({ x: 0, y: 0 })
+  const isOpen = open ?? internalOpen
+
+  const updateOpen = (next: boolean) => {
+    if (open === undefined) setInternalOpen(next)
+    onOpenChange?.(next)
+  }
+
+  const clearTimer = () => {
+    if (timer.current) clearTimeout(timer.current)
+    timer.current = null
+  }
+
+  const show = () => {
+    if (disabled) return
+    clearTimer()
+    timer.current = setTimeout(() => updateOpen(true), delay)
+  }
+
+  /** Keyboard focus shows immediately — no hover-intent delay for focus triggers. */
+  const showNow = () => {
+    if (disabled) return
+    clearTimer()
+    updateOpen(true)
+  }
+
+  const hide = () => {
+    clearTimer()
+    updateOpen(false)
+  }
+
+  useEffect(() => () => clearTimer(), [])
+
+  // Escape dismisses the tooltip while it is visible (WAI-ARIA tooltip pattern).
+  useEffect(() => {
+    if (!isOpen) return
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") hide()
+    }
+    document.addEventListener("keydown", onKeyDown, true)
+    return () => document.removeEventListener("keydown", onKeyDown, true)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen])
+
+  const handlePointerMove = (event: PointerEvent<HTMLSpanElement>) => {
+    if (followCursor) setCursor({ x: event.clientX, y: event.clientY })
+  }
+
+  return (
+    <span
+      data-slot="tooltip-trigger"
+      className={cn(tooltipTriggerVariants(), className)}
+      aria-describedby={isOpen ? id : undefined}
+      onPointerEnter={show}
+      onPointerMove={handlePointerMove}
+      onPointerLeave={hide}
+      onFocus={showNow}
+      onBlur={hide}
+    >
+      {children}
+      {isOpen && !disabled && (
+        <span
+          id={id}
+          role="tooltip"
+          data-slot="tooltip"
+          className={tooltipBubbleVariants()}
+          style={{
+            ...getPositionStyle(side, align, offset, followCursor, cursor),
+            maxWidth,
+          }}
+        >
+          {content}
+          {showArrow && !followCursor && (
+            <span
+              aria-hidden="true"
+              // 箭头＝转 45° 的方块，必须保持尖角：8×8 的盒子上任何 ≥4px 的圆角都等于正圆
+              // （W5 把 Tailwind rounded-sm(2px) 直换成 --ow-radius-sm(8px)，就把箭头渲成了圆疙瘩）。
+              // 形状表管的是面/控件的圆角档，这里的尖角是几何构造的一部分，不占档。
+              className="absolute w-2 h-2 rounded-none bg-ow-tooltip-bg"
+              style={getArrowStyle(side, align)}
+            />
+          )}
+        </span>
+      )}
+    </span>
+  )
+}
+
+function getPositionStyle(
+  side: TooltipSide,
+  align: TooltipAlign,
+  offset: number,
+  followCursor: boolean,
+  cursor: { x: number; y: number },
+): CSSProperties {
+  if (followCursor) return { position: "fixed", left: cursor.x + 12, top: cursor.y + 14 }
+
+  const vertical = side === "top" || side === "bottom"
+  const crossAxis = vertical
+    ? align === "start"
+      ? { left: 0 }
+      : align === "end"
+        ? { right: 0 }
+        : { left: "50%", transform: "translateX(-50%)" }
+    : align === "start"
+      ? { top: 0 }
+      : align === "end"
+        ? { bottom: 0 }
+        : { top: "50%", transform: "translateY(-50%)" }
+
+  if (side === "top") return { bottom: `calc(100% + ${offset}px)`, ...crossAxis }
+  if (side === "bottom") return { top: `calc(100% + ${offset}px)`, ...crossAxis }
+  if (side === "left") return { right: `calc(100% + ${offset}px)`, ...crossAxis }
+  return { left: `calc(100% + ${offset}px)`, ...crossAxis }
+}
+
+function getArrowStyle(side: TooltipSide, align: TooltipAlign): CSSProperties {
+  const aligned = align === "start" ? 12 : align === "end" ? undefined : "50%"
+  const trailing = align === "end" ? 12 : undefined
+  if (side === "top")
+    return {
+      bottom: -3,
+      left: aligned,
+      right: trailing,
+      transform: align === "center" ? "translateX(-50%) rotate(45deg)" : "rotate(45deg)",
+    }
+  if (side === "bottom")
+    return {
+      top: -3,
+      left: aligned,
+      right: trailing,
+      transform: align === "center" ? "translateX(-50%) rotate(45deg)" : "rotate(45deg)",
+    }
+  if (side === "left")
+    return {
+      right: -3,
+      top: aligned,
+      bottom: trailing,
+      transform: align === "center" ? "translateY(-50%) rotate(45deg)" : "rotate(45deg)",
+    }
+  return {
+    left: -3,
+    top: aligned,
+    bottom: trailing,
+    transform: align === "center" ? "translateY(-50%) rotate(45deg)" : "rotate(45deg)",
+  }
+}