soma-ui

SOMA 开放世界低代码组件库：契约驱动、令牌换装、容器优先自适应、目录一源双出（人与 AI 共用同一份组件目录）。

用法

import { composeComponentPacks } from 'soma-core';
import { createSomaUiPack } from 'soma-ui';

// 宿主 bootstrap/soma-bootstrap.ts
const composed = composeComponentPacks([createSomaUiPack(), businessPack]);
await bootstrap.mount(container, { ...assets, components: composed.components });

页面 DSL 侧(四件套,不新增文件类型):

<div data-soma-component="QtyStepper" data-soma-id="qty"></div>

# _ui.yaml
qty:
  props: { value: item.quantity, max: item.stock }

# _event.yaml
qty.change: UI_REFRESH | page.changeQty

2.0.0 发布说明（2026-09-22）

2.0 固定 Node.js 24.21.0 / Next.js 16.3.5 的运行时基线，并与 [email protected] 配套。既有页面 DSL 与组件契约保持不变；本轮补强了导航滚动容器识别、 键盘与触控可达性、浮层定位及窄容器降级，目录与 Chromium 双视口审查继续作为发布门禁。

1.5.0 发布说明（2026-09-15）

本版本发布 REQ-016 结构层能力，并与 [email protected] 的组件树运行时配套：

• 新增 Box、Region、Text、Heading、Fragment、List 六个结构组件，提供插槽、集合行与主题化结构 props；
• 组件定义、目录与准备摘要接入结构适配器和示例契约，支持组件树嵌套与确定性降级；
• 新增结构原语单测、组件树视觉夹具与真实 Chromium 验收，保持既有业务组件和事件契约兼容。

1.4.0 发布说明（2026-09-13）

本版本保持现有 props、emit 与页面 DSL 兼容，重点补齐运行时一致性与跨领域复用：

• 业务卡动作在派发前复核当前动作、禁用态、隐藏态与实体身份，避免旧渲染快照误触发；
• QueryConsole、DetailConsole、FormConsole 增加请求生命周期与异步归属保护，切换记录或卸载后不污染新状态；
• KpiBoard 增加加载/错误/空/部分失败反馈、retry 意图与 extra / footer 插槽，并补齐图表读屏名称与实例隔离；
• 键盘、typeahead、弹层与按压交互统一处理 IME、动态禁用、过期游标和卸载边界。

发布前已通过 npm run test:all：页面 Playwright、真实 Chromium 视觉矩阵及全部 325 个组件双视口审查均无 findings。

当前能力（以代码为准，2026-09-13）

五层体系 token / atom / composite / solution / page，库内 331 个注册组件 (atom 20 / composite 128 / solution 183)；token 层由 soma-core 主题引擎承载， page 层 = 顶层声明资产(文件态四件套或声明态入声明仓库)。 轻量选型见 catalog/组件索引.md,逐组件详情见 catalog/components/,完整机器真值见 catalog/catalog.json;catalog/组件目录.md 保留为兼容入口(全部自动生成,禁止手改)。

• atom(20):Avatar、Badge、Button、Divider、PriceText、ProgressBar、Skeleton、Switch、 Icon、TextInput、Checkbox、Loading、Kbd、Status、RadialProgress、Link、ValidationMessage、Toggle、Text、Heading
• composite(128):数据展示(DataTable/DescriptionList/CardWaterfall/VirtualList/Timeline/ ActivityFeed/CommentList/StatCard/TagList/TaskProgress/Tree…)、表单(FormField/Select/Combobox/Cascader/TagInput/ NumberInput/DatePicker/DateRangePicker/TimePicker/SegmentedControl/FilterBar/RuleBuilder…)、反馈(Alert/ Toast/Tooltip/Modal/AlertDialog/Drawer/Popover/StatePanel)、导航与效率(Tabs/Breadcrumb/Steps/Pagination/Dropdown/ SearchBar/CommandPalette/ContextMenu)、布局与主题(Collapsible/ResponsiveGrid/StackLayout/AdaptiveSurface/ThemeScope/PageFrame/AppShell)、 结构(Box/Region/Fragment/List)、SVG 图表族(DonutChart/BarChart/LineChart/PieChart/HeatMap…)
• solution(183):控制台/流程组件 + 可独立组合的业务颗粒,覆盖电商、运营、CRM、财务、 AI 智能、市场分析、供应链、营销增长、项目交付、内容社区、组织人事、教育、医疗、 合规风控、旅行酒店、设施运营、制造、法务、保险、公共服务、能源、工程建设、网络安全、 采购、农业、公益社会影响、电信、社交图谱、媒体流、云成本、末端配送与轻娱乐等领域
• 39 个领域模块 / 42 个能力包:createSomaUiDomainComponents() 可按领域选取; 领域轻量包之外另含 foundation、adaptive-layout 与跨领域 workflow 包; soma-ui/packs/* 只携带目标组件及其 CSS,不会静态拉入全库入口
• 主题配方：46 套风格预设（11 套产品气质 + 35 套 daisyUI 对标主题），正交组合 density/shape/elevation/typography/motion/dataDensity 六轴,并支持 ThemeScope 子树换肤
• 容器自适应(默认开启):组件按所在容器而非视口宽度自适应,不写参数即生效。ResponsiveGrid、StackLayout 与 stack/cluster/auto-grid/switcher/sidebar/cover 原语纯 CSS 按最近容器响应,业务卡在 Drawer、侧栏和弹层中也能独立降列; MasterDetail、KpiBoard、QueryConsole、WizardFlow、SettingsConsole 五个版式组件默认按各自版式接自适应引擎与降级阶梯, 写 adaptive_profile: off 关闭。ResponsiveGrid / StackLayout / AdaptiveSurface 的 adaptive_profile 默认 off, 写版式画像才接引擎
• 自适应算法体系:CSS container query 负责内在重排;planSomaLayout() 以容器尺寸、 最小项宽、内容复杂度、操作数和显式迟滞状态生成稳定布局计划;浏览器侧由 attachAdaptiveScope() 经 soma-core 观察者池与调度器将模式、密度和操作形态投射为 data 属性/CSS 变量。算法不含业务领域、不读取 window、不改变组件事件语义
• 数据自适应:shape-infer 形状推断、字段别名容错、DataTable 无 columns 推断、 autoDeclare 数据直渲、速记列("order.id|3" / "@action")、异构列表 role_by

质量闸门(测试强制)

• 目录新鲜度:提交的 catalog/ 必须与契约实时生成一致;契约变更后 npm run catalog:build -w soma-ui;
• 令牌纪律(C3):组件零裸色值,样式颜色只允许出现在 var(--soma-*, 回退) 回退位;
• 主题：--soma-* 令牌由 soma-core 主题引擎注入；theme 除 brand 外可用 palette: { harmony, semantics, chroma, contrast, accents } 与 scene: { field, intensity, material } 表达完整气质，省略新轴仍保持兼容默认与亮暗 AA 配对保障。

文件态组件包(AI 自产通道)

无控制器逻辑的声明式组件可用纯文件交付（contract.yaml + template.html + ui.yaml + event.yaml）， 在构建期或服务端经 soma-core 的 loadComponentPackFromDir(dir, { name, version }) 生成完整组件包； loadComponentPackages 仅保留给明确需要无样式定义表的兼容工具。

颗粒化装配

import { createAiIntelligenceUiComponents } from 'soma-ui/packs/ai-intelligence';
import { createFoundationUiComponents } from 'soma-ui/packs/foundation';

const components = {
  ...createFoundationUiComponents(),
  ...createAiIntelligenceUiComponents(),
};

也可用 soma-ui/components/* 直接导入单个组件工厂和 CSS。领域包通过轻量样式运行时 登记自己的分片、共享依赖和 CSP nonce,不依赖根 styles.ts。

行为底座（headless 层）

自己写组件、或把官方组件 soma component eject 出去自行维护时,焦点陷阱、层栈、方向键漫游 这些东西不要重写——它们从包根直接取,值和类型都在:

import {
  createFocusScope,        // 焦点陷阱 + inert + 引用计数滚动锁
  createDismissableLayer,  // Escape 与外点的单一层栈
  createOverlayHost,       // 原生 popover 顶层，不搬家不建 portal
  createOverlayPositioner, // 翻转 / 避让 / RTL 逻辑边
  createKeyboardWiring,    // 契约 keyboard: 段的接线
  createFormSemantics,     // aria-describedby 合并与 aria-invalid
  isCommitAfterLeave,      // 输入法上屏落在焦点离开之后的判断
  toneSurfaceCss,          // 整块强色底的语境翻转
  type FocusScopeOptions,
} from 'soma-ui';

共十四个模块按 semver 承诺：focus-scope dismissable-layer overlay-host overlay-positioner keyboard-nav keyboard-wiring popup-select popup-dismiss form-semantics list-states windowing dom-id commit-after-leave tone-surface。

必须用官方这一份、而不是各抄一遍：滚动锁是引用计数的,弹层层栈和 dom-id 计数器各只有一个—— 抄一份出去,两边各记各的数,结果是先关的那层把还开着的弹层解锁、Escape 关错层、aria-describedby 指到别人身上。

soma-ui/shared/<模块> 子路径取到的是同一份实现,soma component eject 产物里的 import … from 'soma-ui/shared/x' 照旧可用。别名（acquireScrollLock、computePosition、 applyOverlayPosition、createPositioner）只在子路径保留,包根只留规范名。shared/ 下其余模块 是内部实现,通配子路径能 import 到,但随时可变——不要依赖。

自适应使用与业界对齐

页面里直接用组件即可，自适应默认生效（见上文“容器自适应”）；ResponsiveGrid 的 gap / min_item 与 StackLayout 的 gap 默认 auto，跟随版式与密度默认，写了档位就按该档。下面两个 API 只在 SSR、预览、测试或宿主手写 HTML 时需要：

// 纯函数规划器可用于 SSR、预览和测试；它不读 DOM，也不写像素坐标。
import { planSomaLayout } from 'soma-ui/adaptive';

const plan = planSomaLayout({
  inlineSize: 960, blockSize: 360, itemCount: 8, minItem: 224, maxColumns: 4,
  actionCount: 3, contentComplexity: 'medium',
});

浏览器侧需要把测得的容器档位投射到 CSS 时，使用 soma-ui/adaptive-engine 的唯一接线入口：

import { attachAdaptiveScope } from 'soma-ui/adaptive-engine';

const scope = attachAdaptiveScope(surface, {
  profile: 'dashboard', itemMin: 'sm', maxColumns: 4, itemCount: 8,
  densityPref: 'auto',
  onPlan: (plan) => console.debug('SOMA adaptive plan', plan),
});
// 卸载页面或移除容器时：scope.detach();

itemMin 与 gap（间距六档）都可选：不传即按组件 CSS 的版式/密度默认档解算列数；宿主自带 CSS 时应显式传档，让解算与实际轨道同口径。

引擎只写 --soma-ui-adaptive-* 与 data-soma-*，不写宽高/坐标，也不自建观察者循环； 未接线时仍由纯 CSS 默认档完整渲染。

这套边界吸收并对齐了 Material Adaptive、 Adobe Spectrum Responsive、 Every Layout、MDN Container Queries 与 MDN ResizeObserver 的共同实践：

• 按真实容器可用空间而非设备名/窗口宽度决策；视口 media 仅用于页面壳等全局结构。
• 组件先用 auto-fit/minmax、Stack、Cluster、Sidebar 等内在布局；运行时只处理 CSS 不能可靠推断的密度、操作折叠和主从信息。
• 窄空间优先重排、堆叠或局部滚动，保留主任务与交互契约，绝不因断点改变业务事件。
• 主题和密度通过语义 token 及局部 ThemeScope 传递；领域组件不得写色板值或业务断点。
• ResizeObserver 回调只采样，rAF 合并写入；纯决策、迟滞和签名去重共同避免容器反馈循环。

文档索引

接入 soma-ui 看仓库 external-docs/，不在本目录：

• external-docs/soma-UI组件接入指南.md — 安装、包合成、按需样式、CSP、主题、容器自适应、SSR、卸载与验收
• external-docs/soma-UI组件接入指南.md 第二部分 — 主题、空间令牌、容器查询与自适应接入
• external-docs/soma-UI组件接入指南.md 第三部分 — 八个布局原语的用法与选型
• external-docs/soma-UI组件接入指南.md 第四部分 — 页面骨架与降级阶梯声明
• external-docs/soma-声明语法手册.md §7 — _style.yaml 配置语法

本目录 doc/ 是 soma-ui 的模块详设，面向组件作者与维护者：

• soma 组件体系与契约.md — 五层架构、每层准入标准、contract 字段级规范与 ai 段写作标准
• soma 组件体系概念定义.md — 组件体系各概念的标准称谓、定义、归属与现行载体，收敛散落别名，附标准术语表
• soma 组件体系-变更日志.md — 组件体系逐批变更记录
• soma 业务组件商用级写作规范.md — solution 组件的组合优先设计法、四维判据、状态域、配色角色（§10）、登记点与硬闸门
• soma 视觉与空间规范.md — 视觉几何的概念真源：尺度、几何族、排版、配色规格（§11）、组合版面规格（§12）
• soma 空间体系落地.md — 组件层空间能力的实现：几何令牌、断点、原语、测量算法与性能账
• soma 空间质量闸门.md — G1–G8 静态门、V1–V20 真实浏览器门（44 档，含结构树）、棘轮与登记表
• soma 自适应布局引擎.md — 四层架构、迟滞算法、虚拟化与性能预算
• soma 图表几何与上游移植.md — 零依赖 SVG 图表的几何资产与上游算法移植边界
• shadcn-ui借鉴与许可边界.md — 借鉴落点与合规边界

catalog/ 全部由 npm run catalog:build -w soma-ui 生成，禁止手改。组件能力以自动生成的 catalog/、单元/集成测试和 npm run visual -w soma-ui 的真实 Chromium 矩阵为准。

测试

npm test -w soma-ui            # Vitest(含目录新鲜度 / token-lint / 响应式 / 领域模拟)
npm run typecheck -w soma-ui
npm run catalog:build -w soma-ui   # 契约 → catalog/ 重建