Ordo UI
组件Semantic

NavStatusDot

@mox-hub/ui 组件 · Semantic · canonical

nav-status-dot@mox-hub/uiSemanticcanonicalsrc/components/nav-status-dot.tsx
变体演示nav-status-dot
在线 不可用 检查中

Props API

Prop类型默认值说明
tone*Tone——
label*string——
loading*booleanfalse—

源码

packages/ui/src/components/nav-status-dot.tsx
import { TONE_CLASS, type Tone } from './tone';
import { cn } from '../lib/utils';

/**
 * NavStatusDot —— 导航条目右侧的状态点(语义组件层,批 G1 第二件)。
 *
 * 侧边栏条目「能不能用 / 有没有人在线」用一个小色点表达。全库**导航态状态点**
 * 从此只有一个实现(原 `modules/settings/pages/settings-page.tsx` 内的同名局部件,
 * 2026-09-29 提取到本层,G 类「新增组件默认落点」)。
 *
 * **状态色链路遵 §19.5**:本组件只做**视觉层映射**(tone → class,走 `components/ui/tone.ts`
 * 唯一词表),不做业务映射。故 props 收的是 `tone` 而非 `available` / `online` 之类业务词——
 * status → tone 由调用方(业务层,知道业务语义)负责。本文件**不得出现颜色字面量**。
 *
 * **§8.5#4 不得只靠颜色传达状态**:`label` 必填,同时作为 `aria-label`(屏幕阅读器)
 * 与 `title`(悬停提示),是颜色之外的第二信号。缺了它组件在类型层就不成立——
 * 这是刻意的:一个说不出自己是什么状态的点,不该被渲染出来。
 *
 * **props 面封闭(裁决 G8)**:显式声明 props,不接 `className`、不透传 `variant`、
 * 不 `extends HTMLAttributes`(口径见 `semantic/README.md`)。
 *
 * **语义边界(刻意不做通用 StatusDot)**:本件以「导航 / 菜单条目右侧的小点」为界,
 * 尺寸固定 8px(`h-2 w-2`),`shrink-0` 防被相邻 `flex-1 truncate` 文案挤扁。
 * 仓内其他状态点形态与口径不同、不在本件内,等首个真实合并诉求出现再议:
 * - `modules/assistant/components/assistant-status-dot.tsx`:面板内状态点,6px、
 *   `aria-hidden`(状态由同区文案承载)、允许 `className` 透传——是另一套口径;
 * - 列表行 / 徽章内的 6px 色点(多处),尺寸与语境均不同。
 */
function NavStatusDot({
  tone,
  label,
  loading = false,
}: {
  /** 语义色档(§19.4 五档封闭词表):就绪 = success / 不可用·需处理 = danger / 中性 = default */
  tone: Tone;
  /** 可访问名兼悬停提示(同一文案)——颜色之外的第二信号,必填 */
  label: string;
  /** 检查中:叠加 ping 动画(与静态灰点的区分信号,不是唯一信号),通常配 tone="default" */
  loading?: boolean;
}) {
  const dot = TONE_CLASS[tone].dot;

  if (loading) {
    return (
      <span
        data-slot="nav-status-dot"
        role="img"
        aria-label={label}
        title={label}
        className="relative flex h-2 w-2 shrink-0"
      >
        <span
          className={cn('absolute inline-flex h-2 w-2 animate-ping rounded-full opacity-75', dot)}
        />
        <span className={cn('relative inline-flex h-2 w-2 rounded-full', dot)} />
      </span>
    );
  }

  return (
    <span
      data-slot="nav-status-dot"
      role="img"
      aria-label={label}
      title={label}
      className={cn('h-2 w-2 shrink-0 rounded-full', dot)}
    />
  );
}

export { NavStatusDot };

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

导航状态点,表达 git 或 runtime 等状态;颜色需配文字或 aria-label,不单独承载语义。