Ordo UI
PatternsSemantic

GraphNode

@mox-hub/patterns 模式 · Semantic · canonical

graph-node@mox-hub/patternsSemanticcanonicalsrc/components/graph-node.tsx

变体轴

state
defaultfinal
density
defaultcompact
变体演示graph-node
需求澄清进行中

把原始需求拆成可执行任务

claude-sonnet-5-5
方案评审待评审

已选中:ring 表达画布焦点

2 个阻塞项
交付物定稿定稿

成功色描边 + 浅底;文字信号由徽标补齐

final · compact

Props API

Prop类型默认值说明
title*ReactNode——
icon*ReactNode——
badge*ReactNode——
description*ReactNode——
actions*ReactNode——
footer*ReactNode——
selected*booleanfalse—
state*GraphNodeState'default'—
density*GraphNodeDensity'default'—
disabled*booleanfalse—
className*string——
children*ReactNode——

源码

packages/patterns/src/components/graph-node.tsx
import type { ComponentProps, ReactNode } from 'react';

import { cn } from '@mox-hub/ui';
import { Card } from '@mox-hub/ui/components/card';

export type GraphNodeState = 'default' | 'final';
export type GraphNodeDensity = 'default' | 'compact';

export interface GraphNodeProps
  extends Omit<ComponentProps<'div'>, 'title' | 'children'> {
  /** 节点标题(必填,单行截断) */
  title: ReactNode;
  /** 标题行前导图标(已组装好的节点,如 lucide 图标或类型图标底框) */
  icon?: ReactNode;
  /** 标题右侧徽标槽(状态/版本等,可放 Badge / Chip) */
  badge?: ReactNode;
  /** 描述行,最多两行截断 */
  description?: ReactNode;
  /** 右上动作区(复制/禁用/删除等高频操作) */
  actions?: ReactNode;
  /** 底部元信息槽(配置摘要、模型名等) */
  footer?: ReactNode;
  /** 选中态;React Flow 自定义节点可直接透传 selected */
  selected?: boolean;
  /** 语义态:default 普通 / final 定稿(成功色描边与浅底) */
  state?: GraphNodeState;
  /** 密度:default 256px / compact 224px,只影响节点排版,不影响画布缩放 */
  density?: GraphNodeDensity;
  /** 禁用态:降透明度并禁用指针交互 */
  disabled?: boolean;
  /** 节点主体附加内容;根节点为 relative,可承载 React Flow Handle / 端口列 */
  children?: ReactNode;
}

/**
 * GraphNode —— 画布节点卡片骨架(DF-15,patterns 层,不绑定 React Flow)。
 *
 * 把任务图/拓扑里反复手写的节点卡收敛为同一形态:标题行(图标 + 标题 + 徽标 +
 * 动作)+ 描述 + 底部元信息,统一 hover / selected / final 三态与 density / disabled
 * 样式。组件只负责「节点长什么样」,画布机制(拖拽、连线、键盘移动、Handle 位置)
 * 仍由消费方或 React Flow 适配层承担;因此本件**不 import 任何画布依赖**。
 *
 * ## 状态约定
 * - hover:纯 CSS,禁用态自动失效。
 * - selected:`selected` prop(React Flow 的 `selected` 直接透传),用 ring 表达,
 *   不替代画布层的选中语义。
 * - final:`state="final"` 用成功色描边 + 浅底表达定稿;**颜色不是唯一信号**,
 *   调用方应在 `badge` 或 `footer` 中同时给出文字/图标。
 * - disabled:降透明 + `pointer-events-none`,不改变布局。
 *
 * ## React Flow 接入
 * - 在自定义节点组件里渲染 `<GraphNode selected={selected} …>`;
 * - 内部可交互元素(按钮/输入)加 `nodrag` 类,避免触发画布拖拽;
 * - Handle 作为 `children` 传入,自行用绝对定位贴到节点左右两侧。
 */
export function GraphNode({
  title,
  icon,
  badge,
  description,
  actions,
  footer,
  selected = false,
  state = 'default',
  density = 'default',
  disabled = false,
  className,
  children,
  ...props
}: GraphNodeProps) {
  return (
    <Card
      data-slot="graph-node"
      data-selected={selected || undefined}
      data-state={state}
      data-density={density}
      data-disabled={disabled || undefined}
      variant="outline"
      size="sm"
      className={cn(
        'group/graph-node relative w-64 gap-2 overflow-visible rounded-lg border-border bg-card text-sm transition-[background-color,border-color,box-shadow] duration-normal',
        // hover:仅提示可交互,不改变选中/定稿语义
        'hover:border-ring/50 hover:bg-muted/30',
        // selected:ring 是主信号,描边同步提亮
        'data-[selected=true]:border-ring data-[selected=true]:ring-2 data-[selected=true]:ring-ring/40',
        // final:成功色描边 + 浅底;文字/图标由 badge/footer 补齐
        'data-[state=final]:border-accent-green/40 data-[state=final]:bg-accent-green-light/30',
        // disabled:不响应指针,视觉降级
        'data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50',
        // 紧凑档:更窄的节点宽度与行距
        'data-[density=compact]:w-56 data-[density=compact]:gap-1.5',
        className
      )}
      {...props}
    >
      <div className="flex items-start gap-2 px-(--card-spacing)">
        {icon ? (
          <span className="flex size-control-2xs shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground group-data-[density=compact]/graph-node:size-control-xs">
            {icon}
          </span>
        ) : null}
        <div className="min-w-0 flex-1">
          <div className="flex min-w-0 items-center gap-1.5">
            <span className="truncate font-medium text-foreground">{title}</span>
            {badge ? <span className="shrink-0">{badge}</span> : null}
          </div>
          {description !== undefined && description !== null ? (
            <p className="line-clamp-2 text-xs text-muted-foreground">{description}</p>
          ) : null}
        </div>
        {actions ? (
          <div className="flex shrink-0 items-center gap-0.5">{actions}</div>
        ) : null}
      </div>
      {footer !== undefined && footer !== null ? (
        <div className="border-t border-border/60 px-(--card-spacing) pt-2 text-xs text-muted-foreground">
          {footer}
        </div>
      ) : null}
      {children}
    </Card>
  );
}

可访问性与 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。

用法说明

画布节点卡片骨架(不绑定 React Flow):标题/图标/徽标/描述/动作/页脚槽,统一 hover/selected/final 三态与 density/disabled 样式。React Flow 自定义节点直接透传 selected;交互元素加 nodrag,Handle 作为 children 绝对定位。

React Flow 接入

GraphNode 不依赖 React Flow,也不注册节点类型;在自定义节点组件里把它当普通卡片渲染即可。 画布机制仍由 React Flow 负责:

  • selected 直接透传 React Flow 的节点选中态;
  • 节点内按钮/输入加 nodrag,避免点击时触发画布拖拽;
  • Handle 作为 children 传入,自行用绝对定位贴到左右两侧;
  • 拖拽、连线、键盘移动与 aria 语义保持在 React Flow 适配层。
import {
  Handle,
  Position,
  type Node,
  type NodeProps,
} from '@xyflow/react'
import { Badge } from '@mox-hub/ui'
import { GraphNode } from '@mox-hub/patterns/components/graph-node'

type TaskNodeData = {
  title: string
  description?: string
  status: string
  final?: boolean
}

type TaskNode = Node<TaskNodeData, 'task'>

function TaskNode({ data, selected }: NodeProps<TaskNode>) {
  return (
    <GraphNode
      selected={selected}
      state={data.final ? 'final' : 'default'}
      title={data.title}
      description={data.description}
      badge={<Badge variant="secondary">{data.status}</Badge>}
      actions={
        <button type="button" className="nodrag" aria-label="更多操作">
          ⋯
        </button>
      }
      footer="claude-sonnet-5-5"
    >
      <Handle type="target" position={Position.Left} />
      <Handle type="source" position={Position.Right} />
    </GraphNode>
  )
}

如需禁用某个节点,传 disabled;紧凑画布用 density="compact"(224px),常规节点为 256px。 state="final" 只负责描边与浅底,定稿文字或图标请同时放进 badge / footer,不要只靠颜色传达。