@orbit-work/ui 0.1.0

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

@@ -0,0 +1,48 @@
+"use client"
+
+import type { ButtonHTMLAttributes } from "react"
+import { cn } from "../../../lib/utils"
+import { Button, type ButtonSize } from "../../primitives"
+import { ChevLeft } from "../Icons"
+
+/**
+ * BackButton — 返回（DS 2.0 模式层，全站唯一形）
+ *
+ * 归口口径：ghost 变体 + chevron-left 字形。
+ * - 只有图标时即 icon-only 按钮（≥28×28，命中区 ≥24，§7）；带 label 时图标在左。
+ * - 图标度量落 §7 档位 {16,20,24}：sm/md=16、lg=20。
+ * - 状态由 Button 原语统一承担：hover/press/focus-visible(2px 环 +2px 缝)/disabled 逐 token。
+ * - 中性件（R3）：不着色、不引信标；旧 `.ch-ic--back` 蓝底方块形已废止。
+ */
+export interface BackButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  /** 可见文案。省略时为 icon-only，无障碍名走 label */
+  children?: React.ReactNode
+  /** 无障碍名与 title，默认「返回」 */
+  label?: string
+  size?: ButtonSize
+  className?: string
+}
+
+/* §7 图标档只有 {16,20,24}：原 sm:14 / lg:18 不在档上（R2 终扫）。
+   sm/md 同取 16（28/32 控件里 16 仍留足内缝），lg(40) 取 20。 */
+const ICON_PX: Record<ButtonSize, number> = { sm: 16, md: 16, lg: 20 }
+
+export function BackButton({ children, label = "返回", size = "md", className, ...rest }: BackButtonProps) {
+  const px = ICON_PX[size]
+  const iconOnly = children == null
+  return (
+    <Button
+      variant="ghost"
+      size={size}
+      data-slot="back-button"
+      /* 有可见文案时不再覆盖无障碍名（避免读屏与视觉不一致），只留 title 作悬停提示。 */
+      aria-label={iconOnly ? label : undefined}
+      title={label}
+      className={cn(className)}
+      icon={<ChevLeft width={px} height={px} aria-hidden="true" />}
+      {...rest}
+    >
+      {children}
+    </Button>
+  )
+}

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

@@ -0,0 +1,180 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { Button } from "../../primitives"
+import { Banner } from "./index"
+
+const meta = {
+  title: "Primitives/Banner",
+  component: Banner,
+  parameters: { layout: "padded" },
+  tags: ["autodocs"],
+  argTypes: {
+    variant: { control: "inline-radio", options: ["info", "warning", "error"] },
+  },
+} satisfies Meta<typeof Banner>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** 页首横幅骨架：图标＋一句人话。三态形状不同、颜色只作第二编码。 */
+export const Info: Story = {
+  args: {
+    variant: "info",
+    children: "工作区已切到只读模式，改动不会写回。",
+  },
+}
+
+export const Warning: Story = {
+  args: {
+    variant: "warning",
+    children: "有 3 个连接器超过 30 天没同步了。",
+  },
+}
+
+export const Error: Story = {
+  args: {
+    variant: "error",
+    children: "连接已断开，正在重试。",
+  },
+}
+
+export const WithTitle: Story = {
+  args: {
+    variant: "warning",
+    title: "连接器需要更新",
+    children: "飞书连接器有新版本，更新后才能继续同步群消息。",
+  },
+}
+
+export const WithAction: Story = {
+  args: {
+    variant: "info",
+    title: "有新版本",
+    children: "更新到 2.4.0 后可用新的定时任务。",
+    action: (
+      <Button variant="secondary" size="sm">
+        立即更新
+      </Button>
+    ),
+  },
+}
+
+export const Closable: Story = {
+  args: {
+    variant: "info",
+    children: "这条横幅可以关掉。",
+    closable: true,
+    onClose: () => console.log("banner closed"),
+  },
+}
+
+export const ActionAndClose: Story = {
+  args: {
+    variant: "error",
+    title: "同步失败",
+    children: "上一次同步在 14:02 中断，本地改动还留着。",
+    action: (
+      <Button variant="secondary" size="sm">
+        重试
+      </Button>
+    ),
+    closable: true,
+    onClose: () => console.log("banner closed"),
+  },
+}
+
+export const WithoutIcon: Story = {
+  args: {
+    variant: "info",
+    icon: null,
+    children: "不带图标的窄横幅。",
+  },
+}
+
+export const LongText: Story = {
+  args: {
+    variant: "warning",
+    title: "存储空间快满了",
+    children:
+      "当前工作区已用 9.4 GB，配额 10 GB。超出后新的附件会上传失败，历史记录不受影响。你可以先清理回收站里 14 天前的文件，或者升级套餐。",
+    action: (
+      <Button variant="secondary" size="sm">
+        去清理
+      </Button>
+    ),
+    closable: true,
+  },
+}
+
+/** 三态并排：形状（图标）与色一起读，颜色不是唯一编码（R1）。 */
+export const AllVariants: Story = {
+  args: { children: "" },
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <Banner variant="info" title="只读模式">
+        工作区已切到只读模式，改动不会写回。
+      </Banner>
+      <Banner variant="warning" title="连接器需要更新">
+        飞书连接器有新版本，更新后才能继续同步群消息。
+      </Banner>
+      <Banner variant="error" title="同步失败">
+        上一次同步在 14:02 中断，本地改动还留着。
+      </Banner>
+    </div>
+  ),
+}
+
+/** 状态完整性：关闭钮 default / hover / press / focus-visible 请在此故事里逐个试。 */
+export const CloseButtonStates: Story = {
+  args: { children: "" },
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <Banner variant="info" closable onClose={() => {}}>
+        Tab 到关闭钮看 focus-visible 环（2px 环＋2px 缝）。
+      </Banner>
+      <Banner variant="warning" closable onClose={() => {}}>
+        hover / 按住看 tint 族内的两档递进。
+      </Banner>
+      <Banner variant="error" closable onClose={() => {}}>
+        错误态 role=alert，会被读屏立即播报。
+      </Banner>
+    </div>
+  ),
+}
+
+/** 双主题并排；不写死主题，靠 data-theme 属性驱动。 */
+export const BothThemes: Story = {
+  args: { children: "" },
+  render: () => (
+    <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 16 }}>
+      {(["light", "dark"] as const).map((theme) => (
+        <div
+          key={theme}
+          data-theme={theme}
+          style={{
+            background: "var(--ow-bg)",
+            padding: 16,
+            borderRadius: 12,
+            display: "flex",
+            flexDirection: "column",
+            gap: 10,
+          }}
+        >
+          <Banner variant="info" closable onClose={() => {}}>
+            只读模式已开启。
+          </Banner>
+          <Banner
+            variant="warning"
+            action={
+              <Button variant="secondary" size="sm">
+                更新
+              </Button>
+            }
+          >
+            飞书连接器有新版本。
+          </Banner>
+          <Banner variant="error">连接已断开，正在重试。</Banner>
+        </div>
+      ))}
+    </div>
+  ),
+}

package/src/components/composite/Banner/BannerSource.test.mjs

@@ -0,0 +1,67 @@
+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("banner exposes the three page-level semantic states", () => {
+  assert.match(source, /export type BannerVariant = "info" \| "warning" \| "error"/)
+  assert.match(source, /data-slot="banner"/)
+  assert.match(source, /data-ow-role=\{variant\}/)
+  assert.match(source, /role=\{variant === "error" \? "alert" : "status"\}/)
+})
+
+test("banner surfaces use the tint family: tint bg, tint-border, on-tint text", () => {
+  for (const v of ["info", "warning", "error"]) {
+    assert.match(source, new RegExp(`bg-\\[var\\(--ow-${v}-tint\\)\\]`))
+    assert.match(source, new RegExp(`border-\\[color:var\\(--ow-${v}-tint-border\\)\\]`))
+    assert.match(source, new RegExp(`text-\\[color:var\\(--ow-${v}-on-tint\\)\\]`))
+  }
+  // 任意值 var() 必须带类型标注，否则 tailwind-merge 会按错误分组吞类
+  assert.doesNotMatch(source, /(?:text|border)-\[var\(--ow-/)
+})
+
+test("banner sits flush on the surface: 1px border, radius 12, no shadow", () => {
+  assert.match(source, /\[border-radius:var\(--ow-radius-card\)\]/)
+  assert.match(source, /gap-2\.5 px-3\.5 py-2\.5 border /)
+  assert.doesNotMatch(source, /shadow-\[var\(--ow-shadow-(pop|modal|1|2|3)\)\]|shadow-ow-shadow/)
+})
+
+test("banner colour is only the second coding — each state ships its own icon shape (R1)", () => {
+  assert.match(source, /info: <InfoCircle \/>/)
+  assert.match(source, /warning: <WarningTriangle \/>/)
+  assert.match(source, /error: <ErrorCircle \/>/)
+  assert.match(source, /icon \?\? defaultIcons\[variant\]/)
+  assert.match(source, /icon !== null && \(/)
+})
+
+test("banner is a neutral component — no beacon / highlighter yellow (R3)", () => {
+  assert.doesNotMatch(source, /--ow-beacon|--ow-accent-dot|--ow-data-today|--ow-highlighter/)
+  // 零裸 hex（§2）
+  assert.doesNotMatch(source, /#[0-9a-fA-F]{3,8}\b/)
+})
+
+// R2：关闭钮原是手搓 <button>，20×20 出 §7 控件高表 {28,32,40}，焦点还走
+// --ow-focus-shadow（内圈 2px 缝画的是 --ow-surface，落在 tint 面上会现出中性白缝）。
+// 同簇同角色的 Toast 关闭钮早已是 Button ghost·sm——同一角色只留一套实现。
+test("banner close button is a real button with full state coverage", () => {
+  assert.match(source, /import \{ Button \} from "\.\.\/\.\.\/primitives\/Button"/)
+  assert.match(source, /<Button\s+variant="ghost"\s+size="sm"\s+type="button"\s+data-ow-part="close"/)
+  assert.match(source, /aria-label="关闭横幅"/)
+  assert.match(source, /icon=\{<Close className="w-3\.5 h-3\.5" aria-hidden="true" \/>\}/)
+  // 手搓的 20 方尺寸与 --ow-focus-shadow 焦点写法整套退场（焦点环由原语的 ow-focus-ring 给）
+  assert.doesNotMatch(source, /w-5 h-5/)
+  assert.doesNotMatch(source, /focus-visible:shadow-\[var\(--ow-focus-shadow\)\]/)
+  // 每态的 hover/press 底仍逐 token 跟着所在 tint 面走
+  for (const v of ["info", "warning", "error"]) {
+    assert.match(
+      source,
+      new RegExp(`hover:bg-\\[var\\(--ow-${v}-tint-hover\\)\\] active:bg-\\[var\\(--ow-${v}-tint-border\\)\\]`),
+    )
+  }
+})
+
+test("banner supports an inline action slot", () => {
+  assert.match(source, /action\?: ReactNode/)
+  assert.match(source, /data-ow-part="action"/)
+})

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

@@ -0,0 +1,125 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { cn } from "../../../lib/utils"
+import { Button } from "../../primitives/Button"
+import { Close, ErrorCircle, InfoCircle, WarningTriangle } from "../Icons"
+
+export type BannerVariant = "info" | "warning" | "error"
+
+export interface BannerProps {
+  /** 三语义态，决定 tint 族配色与默认图标 */
+  variant?: BannerVariant
+  /** 可选短标题（500 字重一行） */
+  title?: ReactNode
+  /** 人话一句：横幅正文 */
+  children?: ReactNode
+  /** 覆盖默认图标；传 null 隐藏图标 */
+  icon?: ReactNode | null
+  /** 行内操作钮（传 Button；放在正文右侧、关闭钮左侧） */
+  action?: ReactNode
+  /** 显示右侧关闭按钮 */
+  closable?: boolean
+  onClose?: () => void
+  className?: string
+}
+
+const defaultIcons: Record<BannerVariant, ReactNode> = {
+  info: <InfoCircle />,
+  warning: <WarningTriangle />,
+  error: <ErrorCircle />,
+}
+
+/** 表面：tint 底 + tint-border 1px 边 + on-tint 字色（§2 语义配对 · §5 贴地 0 影） */
+const surfaceMap: Record<BannerVariant, string> = {
+  info: "bg-[var(--ow-info-tint)] border-[color:var(--ow-info-tint-border)] text-[color:var(--ow-info-on-tint)]",
+  warning:
+    "bg-[var(--ow-warning-tint)] border-[color:var(--ow-warning-tint-border)] text-[color:var(--ow-warning-on-tint)]",
+  error: "bg-[var(--ow-error-tint)] border-[color:var(--ow-error-tint-border)] text-[color:var(--ow-error-on-tint)]",
+}
+
+/** 关闭钮 hover/press：留在 tint 族内递进（tint-hover → tint-border） */
+const closeStateMap: Record<BannerVariant, string> = {
+  info: "hover:bg-[var(--ow-info-tint-hover)] active:bg-[var(--ow-info-tint-border)]",
+  warning: "hover:bg-[var(--ow-warning-tint-hover)] active:bg-[var(--ow-warning-tint-border)]",
+  error: "hover:bg-[var(--ow-error-tint-hover)] active:bg-[var(--ow-error-tint-border)]",
+}
+
+/**
+ * Banner — DS2 页首横幅（BLUEPRINT 02：合并 TopBanner / ConnectorAlert / ConnectorUpdateBanner）。
+ *
+ * 页面顶部的持久告知条：info / warning / error 三态 tint 族表面，
+ * 图标（形状各异，颜色只作第二编码 R1）＋可选标题＋人话一句＋可选行内操作钮＋可选关闭。
+ * 立面按 §5 贴地：0 影＋1px `--ow-*-tint-border`；圆角 card(12)（§7）。
+ * 中性件，禁信标荧黄（R3）。关闭钮走 `primitives/Button`（ghost·sm ＝ §7 图标钮 28 方，
+ * 状态全集与 focus-visible 环由原语给），口径与同簇 Toast 的关闭钮一致——原来是手搓
+ * `<button>` 的 20×20，既出 §7 控件高表 {28,32,40}，焦点也走 `--ow-focus-shadow`
+ * （内圈 2px 缝画的是 `--ow-surface`，落在 tint 面上会出现一圈中性白缝）。
+ *
+ * 与 InlineMessage 的分工：InlineMessage 贴在表单/卡片内说明「这一处」的状态（带 mono 详情折叠），
+ * Banner 横跨页首说明「整页/整个连接」的状态，带行内操作钮。
+ */
+export function Banner({
+  variant = "info",
+  title,
+  children,
+  icon,
+  action,
+  closable = false,
+  onClose,
+  className,
+}: BannerProps) {
+  return (
+    <div
+      data-slot="banner"
+      data-variant={variant}
+      data-ow-part="surface"
+      data-ow-role={variant}
+      role={variant === "error" ? "alert" : "status"}
+      className={cn(
+        "flex w-full items-start gap-2.5 px-3.5 py-2.5 border [border-radius:var(--ow-radius-card)] text-ow-fs-ui leading-[1.4]",
+        surfaceMap[variant],
+        className,
+      )}
+    >
+      {icon !== null && (
+        <span
+          data-ow-part="icon"
+          className="inline-flex shrink-0 items-center justify-center w-4 h-4 mt-px [&>svg]:w-4 [&>svg]:h-4"
+          aria-hidden="true"
+        >
+          {icon ?? defaultIcons[variant]}
+        </span>
+      )}
+      <div data-ow-part="body" className="flex-1 min-w-0">
+        {title && (
+          <div data-ow-part="title" className="font-medium">
+            {title}
+          </div>
+        )}
+        {children && (
+          <div data-ow-part="text" className={cn(title && "mt-0.5")}>
+            {children}
+          </div>
+        )}
+      </div>
+      {action && (
+        <span data-ow-part="action" className="shrink-0 self-center">
+          {action}
+        </span>
+      )}
+      {closable && (
+        <Button
+          variant="ghost"
+          size="sm"
+          type="button"
+          data-ow-part="close"
+          aria-label="关闭横幅"
+          onClick={onClose}
+          className={cn("shrink-0 self-center -mr-1 text-current", closeStateMap[variant])}
+          icon={<Close className="w-3.5 h-3.5" aria-hidden="true" />}
+        />
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,153 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { CSSProperties } from "react"
+import { BEACON_ICON_NAMES, BeaconIcon } from "./index"
+import type { BeaconIconName } from "./index"
+
+const meta = {
+  title: "Composite/BeaconIcons",
+  component: BeaconIcon,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof BeaconIcon>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const SIZES = [24, 20, 16] as const
+const DOTS = [
+  { dot: "off", label: "常态" },
+  { dot: "pre", label: "预亮 40%" },
+  { dot: "lit", label: "点亮" },
+] as const
+
+const cellStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: 44,
+  height: 36,
+  color: "var(--ow-text)",
+}
+const monoLabel: CSSProperties = {
+  fontFamily: "var(--ow-font-mono)",
+  fontVariantNumeric: "tabular-nums",
+  fontSize: 11,
+  color: "var(--ow-text-2)",
+}
+
+export const Default: Story = {
+  args: {
+    name: "tasks",
+    size: 24,
+    dot: "off",
+  },
+}
+
+/** 三档 × 三态全矩阵：每行一枚图标，列＝尺寸档（24/20/16）×点状态（常态/预亮/点亮）。 */
+export const Matrix: Story = {
+  render: () => (
+    <div
+      style={{
+        background: "var(--ow-surface)",
+        border: "1px solid var(--ow-border)",
+        borderRadius: 10,
+        padding: "8px 16px",
+        display: "inline-block",
+        color: "var(--ow-text)",
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: 4, padding: "6px 0" }}>
+        <span style={{ ...monoLabel, width: 96 }}>icon</span>
+        {SIZES.map((size) =>
+          DOTS.map(({ dot, label }) => (
+            <span key={`${size}-${dot}`} style={{ ...monoLabel, width: 44, textAlign: "center" }}>
+              {size}
+              <br />
+              {label}
+            </span>
+          )),
+        )}
+      </div>
+      {BEACON_ICON_NAMES.map((name) => (
+        <div
+          key={name}
+          style={{ display: "flex", alignItems: "center", gap: 4, borderTop: "1px solid var(--ow-border)" }}
+        >
+          <span style={{ ...monoLabel, width: 96, fontSize: 12, color: "var(--ow-text)" }}>{name}</span>
+          {SIZES.map((size) =>
+            DOTS.map(({ dot }) => (
+              <span key={`${size}-${dot}`} style={cellStyle}>
+                <BeaconIcon name={name} size={size} dot={dot} />
+              </span>
+            )),
+          )}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** 点亮（lit）＝位置极陈列：点色 var(--ow-accent-dot)，浅主题深黄／暗主题荧黄随 token 翻转。 */
+export const DotStates: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+      {DOTS.map(({ dot, label }) => (
+        <div key={dot} style={{ display: "flex", alignItems: "center", gap: 16 }}>
+          <span style={{ ...monoLabel, width: 88 }}>{label}</span>
+          {BEACON_ICON_NAMES.map((name: BeaconIconName) => (
+            <span key={name} style={{ color: "var(--ow-text)", display: "inline-flex" }}>
+              <BeaconIcon name={name} size={24} dot={dot} label={name} />
+            </span>
+          ))}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** 祖先挂类点亮：不经 dot prop，由外层 .ow-dot-lit / .ow-dot-pre 点亮（侧栏当前项用法）。 */
+export const AncestorLighting: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 8, width: 220 }}>
+      <div
+        className="ow-dot-lit"
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          height: 28,
+          padding: "0 8px",
+          borderRadius: 6,
+          background: "var(--ow-current-bg)",
+          fontWeight: 500,
+          fontSize: 12,
+          color: "var(--ow-text)",
+        }}
+      >
+        <BeaconIcon name="tasks" size={16} />
+        <span>任务</span>
+        <span style={{ ...monoLabel, marginLeft: "auto" }}>位置极</span>
+      </div>
+      <div
+        className="ow-dot-pre"
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          height: 28,
+          padding: "0 8px",
+          borderRadius: 6,
+          background: "var(--ow-hover)",
+          fontSize: 12,
+          color: "var(--ow-text)",
+        }}
+      >
+        <BeaconIcon name="schedule" size={16} />
+        <span>定时任务</span>
+        <span style={{ ...monoLabel, marginLeft: "auto" }}>hover 预亮</span>
+      </div>
+    </div>
+  ),
+}