@jike-js/ui

这是 jike 统一前端组件的参考实现，组件契约见 frontend/UI_COMPONENT_CATALOG.md。

安装

pnpm add @jike-js/[email protected]

当前已发布推荐版本：0.5.1。本地工作区正在准备 0.5.2 补丁，包含公共组件状态语义修正；发布前业务项目继续安装 0.5.1。业务项目安装后锁定明确版本，不使用 Git、本地 file: 或未发布版本。

业务项目只需引入 @jike-js/ui/styles.css 一个样式入口；该入口在构建时包含 Token、基础层和组件层，避免漏引或形成第二份 reset。Token 的唯一源文件仍是 frontend/tokens/design-tokens.json，CSS 是其运行时输出。

当前工作区提供：Button、BrandLogo、LoginShell、可选的 SliderCaptcha（从 @jike-js/ui/captcha 引入）、PageLayout、PageHeader、Notice、ToastProvider、useToast、EmptyState、LoadingState、Modal、Drawer。包构建会同时检查 TypeScript，并输出单一 styles.css 和品牌资源。标签页目前属于页面模式候选，尚未作为公共入口发布。

弹层使用受控接口：

<Modal open={open} title="编辑任务" size="md" onClose={() => setOpen(false)} footer={actions}>
  {content}
</Modal>
<Drawer open={open} title="筛选条件" side="right" onClose={() => setOpen(false)}>
  {content}
</Drawer>

Modal 支持 sm、md、lg；Drawer 支持 left、right。默认支持遮罩点击、Escape 关闭和背景滚动锁定，必要时通过 closeOnOverlay、closeOnEscape 显式关闭。

当前推荐的 0.5.1 已包含完整的 LoginShell、可选验证码和弹层组件；0.5.0 作为上一版兼容版本保留，存量业务项目按迁移计划升级。

本包不包含业务请求、路由和权限。业务项目通过 BrandLogo 使用统一 Logo，通过 LoginShell 参数接入品牌文案和登录逻辑。登录文案使用 brandTitle、brandSubtitle、formTitle、formSubtitle 四个明确层级；formSubtitle 默认为空，需要时再显式传入。

顶部导航的 Logo 区可使用公共 .jike-brand-region 样式包裹 BrandLogo size="md"；该区域与登录品牌区共用品牌区域 Token，不承载页面布局或平台业务色。

品牌差异通过 LoginBrandConfig 传入：

<LoginShell
  brand={{
    primary: "var(--color-primary)",
    primaryHover: "var(--color-primary-hover)",
    brandSurface: "var(--color-brand-area-surface)",
    brandOnSurface: "var(--color-brand-area-on-surface)",
  }}
  {...props}
/>

primary、primaryHover 和 focusRing 只影响按钮、链接和表单焦点等系统区域；brandSurface 和 brandOnSurface 只影响 Logo 品牌区。平台专属颜色不传入这些字段。不得通过全局 CSS 或任意 Token 覆盖登录结构。

公共包只提供配置入口和默认值，不包含具体业务项目的品牌决策；项目颜色、字体和装饰选择应由各业务项目自行传入。

登录品牌区可选使用 brandDecoration="waves" 原型，颜色通过 brand.brandDecorationColor 传入；不传时默认为 none，不会改变存量页面。

Toast 使用方式：

import { ToastProvider, useToast } from "@jike-js/ui";

function App() {
  const toast = useToast();
  return <button onClick={() => toast.info("正在处理")}>开始</button>;
}

<ToastProvider><App /></ToastProvider>

Toast 的位置、堆叠数量、状态颜色和自动消失规则由公共样式统一维护；业务项目只传入安全中文内容。

验证码的接口、启用方式和后端边界唯一见 frontend/CAPTCHA_SPEC.md；组件从 @jike-js/ui/captcha 独立入口加载。