mosaic-ui-sdk

Data-driven UI runtime SDK — render template JSON into React UI.

Upstream systems only need to produce a JSON template. The SDK renders it as a complete interactive UI with tables, forms, charts, and custom views.

Install

npm install mosaic-ui-sdk react react-dom lucide-react

Quick Start

import { MosaicRenderer } from 'mosaic-ui-sdk';
import type { Template } from 'mosaic-ui-sdk';

const template: Template = {
  name: 'Demo',
  version: '1.0.0',
  uuid: 'tpl-demo',
  slots: [
    {
      layout: 'CONTENT',
      config: {
        type: 'table',
        columns: [
          { title: 'Name', dataIndex: 'name', sortable: true },
          { title: 'Status', dataIndex: 'status' },
        ],
        searchable: true,
        pagination: { pageSize: 10 },
      },
      dataSource: 'users',
    },
  ],
};

const data = {
  users: [
    { name: 'Alice', status: 'active' },
    { name: 'Bob', status: 'inactive' },
  ],
};

function App() {
  return <MosaicRenderer template={template} data={data} />;
}

Layout System

SDK 使用类 antd Layout 的布局模型，通过 slot.layout 字段控制位置：

┌─────────────────────────────────┐
│            HEADER               │
├────────┬────────────────────────┤
│        │                        │
│ SIDER  │       CONTENT          │
│        │                        │
├────────┴────────────────────────┤
│            FOOTER               │
└─────────────────────────────────┘

渲染容器自动填满宿主 div 的 100% 宽高，不预设固定尺寸。

Slot Types

Table

{
  "type": "table",
  "columns": [
    { "title": "名称", "dataIndex": "name", "sortable": true },
    { "title": "状态", "dataIndex": "status", "render": "tag" }
  ],
  "searchable": true,
  "pagination": { "pageSize": 10 },
  "bordered": true
}

支持排序、搜索、分页，基于 @tanstack/react-table 实现。

Form

{
  "type": "form",
  "items": [
    { "type": "input", "label": "标题", "field": "title", "rules": [{ "required": true }] },
    { "type": "select", "label": "类型", "field": "type", "options": [...] }
  ],
  "layout": "vertical",
  "columns": 2,
  "submitAction": { "type": "request", "target": "/api/submit" },
  "resetable": true
}

支持 input / textarea / select / switch / number 等控件，基于 react-hook-form + zod 校验。

Chart

{
  "type": "chart",
  "chartType": "bar",
  "yAxis": { "unit": "ms" }
}

数据格式：{ title, description, points: [{ label, value }] }

View

通用视图节点，支持 card / metric / badge / text / row / stack 等 nodeType，可通过 DSL 树构建任意自定义 UI。

Template Schema

interface Template {
  name: string;
  version: string;
  uuid: string;
  description?: string;
  tags?: string[];
  slots: Slot[];
}

interface Slot {
  id?: string;
  layout: 'HEADER' | 'SIDER' | 'CONTENT' | 'FOOTER';
  config: TableSlot | FormSlot | ChartSlot | ViewSlot;
  slotStyle?: { className?: string; style?: CSSProperties };
  dataSource?: string | { field: string; transform?: string };
  visible?: boolean;
  children?: Slot[];
}

Styling

SDK 内置基础样式。可通过 slotStyle 对单个 Slot 追加样式：

• className — 附加 CSS 类名
• style — 内联 React CSSProperties

HitlForm — HITL 动态表单

独立于 MosaicRenderer 的表单渲染器，用于渲染 HITL（human-in-the-loop）事件驱动的动态表单。只关心 fields 输入和 onSubmit 输出，不绑定任何上下文管理。

基本用法

import { HitlForm } from 'mosaic-ui-sdk';
import type { HitlField } from 'mosaic-ui-sdk';

const fields: HitlField[] = [
  { field_name: 'host', label: '服务器地址', type: 'text', required: true, placeholder: '192.168.1.100' },
  { field_name: 'port', label: '端口号', type: 'number', required: false, placeholder: '22' },
  { field_name: 'password', label: '密码', type: 'password', required: true, sensitive: true },
  { field_name: 'env', label: '环境', type: 'select', required: true, options: ['生产', '测试', '开发'] },
];

function App() {
  return (
    <HitlForm
      fields={fields}
      title="需要补充信息"
      description="请提供服务器连接信息"
      theme="dark"
      onSubmit={(values) => console.log(values)}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | fields | HitlField[] | — | 表单字段定义（必填） | | onSubmit | (values: Record<string, string>) => void | — | 提交回调，返回所有字段值（必填） | | title | string | — | 表单标题 | | description | string | — | 表单描述文字 | | theme | 'dark' \| 'light' | 'dark' | 主题 | | columns | number | 1 | 栅格列数 | | className | string | — | 自定义根容器类名 | | submitButton | ReactNode \| { text?: string; className?: string } | '提交' | 自定义提交按钮 |

HitlField

interface HitlField {
  field_name: string;       // 字段标识
  label: string;            // 显示标签
  type: 'text' | 'password' | 'select' | 'number' | 'textarea';
  required?: boolean;       // 是否必填
  placeholder?: string;     // 占位文本
  sensitive?: boolean;      // 敏感字段（自动使用 password 输入）
  options?: string[];       // select 类型的选项列表
  default_value?: string;   // 默认值
}

自定义提交按钮

// 自定义文案和样式
<HitlForm fields={fields} onSubmit={handleSubmit} submitButton={{ text: '确认部署', className: 'my-btn' }} />

// 完全自定义 ReactNode
<HitlForm fields={fields} onSubmit={handleSubmit} submitButton={<MyButton />} />

主题

组件默认使用暗色主题（深色背景、浅色文字），设置 theme="light" 切换为亮色。也可通过 className 叠加自定义样式覆盖。

Peer Dependencies

| Package | Version | |---------|---------| | react | >= 18 | | react-dom | >= 18 | | lucide-react | >= 0.400.0 |

License

MIT