@newton-cloud/ui

Newton Cloud 受控 React UI 组件库，提供消息流、输入器、内容块、交互卡片、ComplexTable 及默认样式。 组件只接收 props，不自行请求 API，也不运行时依赖 @newton-cloud/sdk。

如何选择

| 需求 | 安装包 | | --- | --- | | 在 React 应用中开箱即用地接入完整 Agent | @newton-cloud/react | | 自行组合框架或界面，只使用任务状态与控制能力 | @newton-cloud/sdk | | 只使用受控 React 组件和默认样式 | @newton-cloud/ui | | 在自己的服务器上部署浏览器安全网关 | @newton-cloud/server |

包之间的关系

• npm 运行时依赖：@newton-cloud/react 精确依赖 @newton-cloud/sdk 和 @newton-cloud/ui，安装 React 集成时会自动安装这两个包。
• HTTPS 部署关系：@newton-cloud/sdk 通过 HTTPS 调用 @newton-cloud/server 或兼容的企业网关，再由网关访问 Newton Cloud Open API。
• 独立使用：@newton-cloud/ui 不依赖 SDK，可由应用直接传入 props 和处理交互意图。
• 独立部署：@newton-cloud/server 不会进入浏览器 bundle，也不会随 React 集成自动安装或部署。

安装

npm install --save-exact @newton-cloud/[email protected] react@19 react-dom@19

React 和 React DOM 是 peer dependencies。

使用入口

默认入口会自动引入默认 CSS：

import { AgentComposer, MessageFlow } from '@newton-cloud/ui';

高级消费者可以自行控制样式：

import { MessageFlow } from '@newton-cloud/ui/unstyled';
import '@newton-cloud/ui/style.css';

公开入口只有根入口、./unstyled 和 ./style.css。

ComplexTable

默认入口会同时提供组件、类型和样式：

import {
  ComplexTable,
  type ComplexTableIntent,
  type ComplexTableViewModel,
} from '@newton-cloud/ui';

const viewModel = {
  id: 'inventory',
  state: 'ready',
  columns: [{ key: 'name', title: '名称' }],
  body: {
    type: 'rows',
    rows: [{ id: 'row-1', cells: { name: { type: 'text', value: '示例' } } }],
  },
} as const satisfies ComplexTableViewModel;

function onIntent(intent: ComplexTableIntent) {
  // 在调用方解释 selection、pagination、stepper 或 action intent。
  console.log(intent);
}

export function Example() {
  return <ComplexTable viewModel={viewModel} onIntent={onIntent} />;
}

需要自行管理样式时使用 unstyled 入口，并显式引入唯一公开 CSS 子路径：

import { ComplexTable, type ComplexTableViewModel } from '@newton-cloud/ui/unstyled';
import '@newton-cloud/ui/style.css';

ComplexTableViewModel 是本 UI 包公开的只读、产品中立渲染契约。组件仅根据 props 渲染并通过 onIntent 上报声明式意图；它不会发起 fetch、不会导入 SDK runtime，也不会执行具体业务场景的 presenter、路由、埋点或外部跳转。local pagination 只切分调用方一次性提供的数据；remote pagination 完全受控，只上报翻页意图，不加载数据。

preview cell 是非交互的声明式展示 wrapper。trigger 和 content 只能组合公开的 display cells，组件统一处理 hover、键盘 focus、Escape、Portal 和视口边缘定位；preview 本身不会发出 业务 intent。presentFollowOrder() 则是一个纯 presenter，把 presentation-only 的 FollowOrderPresenterInput 映射为 ComplexTableViewModel，不会读取 SDK resource 或执行请求。

补货 presenter

presentReplenishment() 和 normalizeReplenishmentRows() 同时从 styled 与 unstyled 根入口导出。 输入只包含语义 mode、展示 phase、数据和数量覆盖，不包含 SDK descriptor 或请求参数：

import {
  ComplexTable,
  presentReplenishment,
  type ReplenishmentPresenterInput,
} from '@newton-cloud/ui';

const input = {
  id: 'replenishment-1',
  selectionScope: '["task-1","replenishment-1",1]',
  mode: 'prediction',
  phase: 'ready',
  result: [{
    rowKey: 'row-1',
    offerId: '10001',
    title: '示例商品',
    suggestedRestockQuantity: 2,
  }],
} as const satisfies ReplenishmentPresenterInput;

export function ReplenishmentExample() {
  return <ComplexTable viewModel={presentReplenishment(input)} />;
}

prediction 生成商品、下游商品、建议补货量、补货推理四列；history-order 生成商品和建议 补货量两列。Stepper 只发出 stepper.change，数量状态与请求由调用方 controller 管理，产品动作由宿主或 React 集成执行。

订单场景 presenter

presentMyOrders() / presentRiskOrder() 与 normalizeMyOrdersRows() / normalizeRiskOrderRows() 同样从两个根入口导出。myOrders 生成 rowGroups（每订单一组、组级 selection、组头声明「查看订单 / 立即支付」动作）；RiskOrder 生成 3 列扁平行与表底「催促商家 处理」动作（不声明 selectionEffect，空选择也会发出 intent）。两者共享纯选择器 extractOrderNo()（orderNo → idStr → id）与谓词 isOrderPayable()，它们是订单号与可支付 判定的唯一推导来源，调用方进行产品动作映射时必须复用。

配套的通用能力变更：remote pagination 不再 clamp 受控当前页——当 page 超出由 total 派生的页数时控件仍展示该页并允许导航到合法页；text cell 新增可选 copyValue，声明后渲染 相邻复制按钮，仅写剪贴板、不发 intent。

afterSale presenter

presentAfterSale()、normalizeAfterSaleRows()、buildAfterSaleCascadeFilter()、 collectLeaves()、CascadeFilter 与 ComplexTableSuggestions 均从 styled/unstyled 根入口导出。 presenter 先按 phase 分流，再按 runtimeState.filter 判断 canonical data 是级联树还是列表； 输出售后单、商品、申请时间、操作四列，保持不可勾选。退款 id 重复时按当前 response occurrence 生成唯一行 id，interaction scope 变化会令全部行 id 失效。

CascadeFilter 只产生选择/清除 action intent；followUps 只做容错降级（字符串数组原样、JSON 字符串数组解包一次、其他形状丢弃）并产生 after-sale.insert-prompt intent。本 UI 包不执行 fetch、 外部跳转或 Composer 写入。

ConversationWorkspace

ConversationWorkspace 是本 UI 包提供的受控桌面对话扩展：左侧组合 conversation、资源入口和 composer，右侧最多展示一个由调用方提供的 active panel。

import { ConversationWorkspace } from '@newton-cloud/ui';

export function Workspace() {
  return (
    <ConversationWorkspace
      conversation={<div>Conversation</div>}
      composer={<form>Composer</form>}
      entries={[
        { id: 'entry-1', label: '跟单进展' },
        { id: 'entry-2', label: '另一业务资源' },
      ]}
      activeEntryId="entry-1"
      panel={<div>Active panel</div>}
      onEntrySelect={id => console.log('select', id)}
      onPanelClose={() => console.log('close')}
    />
  );
}

entry id 对组件而言是 opaque presentation id；组件不解释 resource、task、session 或 live/replay 语义。选择和关闭只通过 callback 上报，open/active 状态仍由调用方控制。当前契约不持久化 open state、active entry 或 panel width，也不支持同时展示多个 panel；当前产品没有移动端 workspace 形态，因此本组件只承诺桌面默认分栏。

默认根入口自动加载 workspace、ComplexTable 和 preview 样式。若使用 @newton-cloud/ui/unstyled，需要由消费方自行引入 @newton-cloud/ui/style.css 或提供完整 样式。

第三方依赖

• react-markdown：Markdown 渲染
• remark-gfm：GFM 扩展
• react、react-dom：由消费项目提供的 peer dependencies

License

Apache-2.0。Copyright 2026 Newton Cloud Open Contributors.