@teamix-evo/ui

v1.4.0

Published

4 hours ago

Source-injected UI components for Teamix Evo (shadcn-based, antd capabilities)

0High
0Medium
0Low

ifblooms

@teamix-evo/ui

变体无关、基于 shadcn v4 工程模式的源码注入式 UI 资源包。

组件以 .tsx 源码交付，不作为黑盒 runtime library 使用。安装后源码归消费项目所有，默认 updateStrategy: frozen；上游升级通过 staging + AI semantic merge，不由普通 update 静默覆盖。

修改组件前必须先读 AGENTS.md。架构理由见 ADR 0036，公共行为契约见 ADR 0049。

国际化

组件库不持有应用级国际化 runtime，也不要求消费项目为每个实例重复传文案。每个含 chrome、状态或可访问文案的 entry 会连同一份三语言纯 JSON catalog 一起落地；普通浏览器应用只需在首次 render 前配置一次语言，组件便按该环境自行读取文案。

import { configureTeamixEvoG11n } from "@/lib/teamix-evo-g11n";

const g11n = configureTeamixEvoG11n({ language: "zh-TW" });
document.documentElement.lang = g11n.language;
document.documentElement.dir = g11n.dir;

<Pagination total={total} />;

language 只选择 Teamix Evo catalog；locale 控制数字/日期格式，dir 控制方向。省略 timeZone 时浏览器使用宿主时区，绝不从语言推断；业务要求固定时区时传 IANA 名称，例如 Asia/Shanghai。语言变化通过浏览器刷新生效，不支持同一页面生命周期内热切换。

Teamix Evo 不会修改宿主 <html>。浏览器应用必须同步 lang / dir，SSR 应在根 HTML 输出相同属性。DatePicker/TimePicker 的默认输入格式保持稳定，不会仅因 locale 自动改成美式日期或 12 小时制；需要时显式传组件 format 配置。

catalog 会安装到例如 src/lib/teamix-evo-g11n/locales/ui/pagination.json。该文件是 frozen 源码，归消费工程所有；修改一次即可影响项目内所有 Pagination 实例。业务数据、产品文案和消费项目自己的 i18n framework 仍由应用负责，不放进 Teamix Evo catalog。

SSR/RSC 使用 createTeamixEvoG11n 创建 request-scoped 环境；只在跨 Client Component 边界共享该环境时使用窄范围 TeamixEvoG11nProvider。不要为普通浏览器应用增加全局 Provider。完整契约见 ADR 0055。

子应用 Portal 边界

嵌入到平台、微应用、Shadow DOM 或 iframe 时，可在应用 shell 用 TeamixEvoPortalProvider 为 Teamix UI 浮层提供统一默认 target。Provider 只传递应用已经拥有的 HTMLElement，不创建 DOM，也不改变 Radix 的焦点、dismiss、定位、滚动锁定和无障碍行为。

import * as React from "react";
import { TeamixEvoPortalProvider } from "@/lib/teamix-evo-portal/react";

function EmbeddedAppShell() {
  const [portalTarget, setPortalTarget] =
    React.useState<HTMLDivElement | null>(null);

  return (
    <TeamixEvoPortalProvider container={portalTarget}>
      <App />
      <div ref={setPortalTarget} data-teamix-evo-portal-root />
    </TeamixEvoPortalProvider>
  );
}

container={null} 是 pending：组件暂不创建 Portal，不会先投放到 body；callback ref 就绪后才首次挂载到正确 target。没有 Provider 时保持 shadcn/Radix 的 body 默认。最近的 Provider 生效，内层 pending 不回退外层；组件显式非 null container 仍可局部覆盖。 Provider 不解决宿主 overflow/contain 裁切、stacking context 或“只阻断子应用”的 Modal Scope，这些需要分别诊断。完整决策见 ADR 0065。

当前清单

manifest.json 当前包含 82 个 entries：

75 个 component；
5 个 util；
2 个 hook。

准确 id、文件、依赖和 entry type 以 manifest.json 为机器真值，不要在 README 中维护第二份组件矩阵。

工程模式

每个组件目录使用 index.tsx、meta.md、stories.tsx；
公开组件遵守 data-slot、cva、Radix/shadcn anatomy 和 React 18 ref 契约；
源码使用 @/components/...、@/lib/... 假路径，CLI 安装时按消费项目 alias 改写；
样式只使用语义 token；品牌差异由 @teamix-evo/tokens 吸收；
组件 TSDoc 是说明源，meta.md 由生成器同步；
metadata 由 CLI 安装到消费工程 .teamix-evo/meta/ui/，不通过已移除的 MCP 读取。

packages/ui/
├── manifest.json
├── _data.json
├── .storybook/
├── scripts/
│   ├── generate-meta.ts
│   └── validate-entries.ts
├── tests/
│   └── non-components.test.tsx
└── src/
    ├── _design-system/
    ├── components/<id>/
    │   ├── index.tsx
    │   ├── meta.md
    │   └── stories.tsx
    ├── hooks/
    └── lib/

验证

从仓库根执行：

pnpm --filter @teamix-evo/ui validate
pnpm --filter @teamix-evo/ui gen:check
pnpm --filter @teamix-evo/ui typecheck
pnpm --filter @teamix-evo/ui lint
pnpm --filter @teamix-evo/ui test

Storybook：

pnpm --filter @teamix-evo/ui storybook
pnpm --filter @teamix-evo/ui build-storybook

根 pnpm validate:all 会组合包级测试、manifest/meta 校验与仓库级同步检查。完整研发动作、视觉核验和 token 合规协议只以 AGENTS.md 为准。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@teamix-evo/ui

国际化

子应用 Portal 边界

当前清单

工程模式

验证