@choco-vanille/ui (英语)

个人项目通知: 该图书馆主要为个人使用而建. 它作为方便而公开发表,但不能保证稳定性、长期维护或后向兼容性。 冒险用吧.

使用 维特 (图书馆模式), 香草提取 (零运行时间,CSS-in-TS)和 基础UI 原始的 原始的 原始的 组成部分是: 预览用 故事书。 。 。 .

特征

• * 反应19+类型脚本,船舶无害环境管理+CJS+类型申报
• QQ 香草提取设计系统——一个已完全打入的符号主题 (颜色,间隔,半径,字体大小/重量,阴影,z-index)
• 以 Vanilla 提取为样式的基 UI 组件 recipe() (类型) 替换为 cva)),编为: clsx
• 用于交互式组件的文件目录
• + ESLint 平面配置( 类型script- eslint, 反应- hooks, jsx- a11y, 故事本) + Pretier

安装

# npm
npm install @choco-vanille/ui @iconify/react@^5.2.1 react react-dom

# yarn
yarn add @choco-vanille/ui @iconify/react@^5.2.1 react react-dom

# pnpm
pnpm add @choco-vanille/ui @iconify/react@^5.2.1 react react-dom

软件包条目自动加载其样式表。 然后使用组件 :

import { Typography } from '@choco-vanille/ui';

export function Example() {
  return (
    <>
      <Typography variant="h1">Hello world</Typography>
      <Typography variant="p">A typographic primitive.</Typography>
      <Typography variant="code">@choco-vanille/ui</Typography>
    </>
  );
}

对于需要明确CSS加载的集成,样式表仍保留 可用时间 @choco-vanille/ui/styles.css。 。 。 .

构成部分

图标

所有图标道具接受信任的本地 IconifyIcon SVG 数据并通过 @iconify/react/offline,无需网络请求或全球登记. 为您选中的收藏安装数据包 :

pnpm add @iconify-icons/lucide

// src/icons/index.ts
import type { IconifyIcon } from '@iconify/react/offline';
import searchIcon from '@iconify-icons/lucide/search';

export const IconRegistry = {
  searchIcon,
} as const satisfies Readonly<Record<string, IconifyIcon>>;

消费者项目应界定一个 IconRegistry 导出所有使用的图标 由项目。 仅在登记册中导入单个图标数据模块, 并将其条目用于组件。 密钥使用骆驼 Case with the Icon 后缀, 例如 searchIcon 或者说 warningIcon; 不导入全部收藏.

import { Button, Icon, IconButton } from '@choco-vanille/ui';
import { IconRegistry } from './icons';

const Example = () => (
  <>
    <Icon icon={IconRegistry.searchIcon} size="md" aria-label="Search" />
    <Button label="Search" startIcon={IconRegistry.searchIcon} />
    <IconButton icon={IconRegistry.searchIcon} aria-label="Search" />
  </>
);

图标默认为装饰. 提供 aria-label 或者说 aria-labelledby 页:1 信息图标;仅由图标控件拥有其可访问名称. 大小(xs 结束 2xl默认值 md, (中文(简体) ), spin,包装样式和CSS颜色不变. 参考文献指向SVG. 单色图标继承 currentColor; 多颜色图标 可以保持他们的固定颜色。 图书馆的登记册是内部的;每个消费者 拥有其登记册。 公约不需要运行时间提供者或图标 全球登记。 图标不需要 SVG 到反应构建插件 . 只使用可信任的数据, 因为 SVG 天体是作为标记插入的 . 内部的SVG识别器是用于SSR和水合的示例. 已应用 SVG ID必须是非空的,在用下划线取代连字符后是独一无二的.

中断更改 : 替换 SVG 反应组件和前者 IconComponent 类型为 IconifyIcon 数据,包括主要/跟踪和自定义变量 图标。 字符串图标名称不被接受 . SvgImage 保留其单独的 SVG 反应组件合同.

方框和打字法

Box 默认为 a div· ; Typography 默认为 a span都推断出本地人 属性、事件和来自 as,包括自定义反应组件. 对于打字, variant 也选择元素当 as 缺席; as 优先,同时 variant 保持视觉预设.

import { Box, Typography, vars, type BoxProps } from '@choco-vanille/ui';

const linkProps = {
  as: 'a',
  href: '/account',
  padding: 16,
} satisfies BoxProps<'a'>;

export function AccountSummary() {
  return (
    <Box display="grid" gridTemplateColumns="1fr auto" gap={16} padding={24}>
      <Typography variant="h2" fontSize={20} lineHeight={1.4}>
        Account
      </Typography>
      <Box {...linkProps}>Open account</Box>
      <Typography
        variant="p"
        maxLines={8}
        overflowWrap="anywhere"
        color={vars.color.text.secondary}
      >
        Account details and preferences.
      </Typography>
    </Box>
  );
}

框支持定位( E)inset,方向冲抵, zIndex),弹性和网格 安置、个人边界、, background, (中文(简体) ), boxSizing, (中文(简体) ), aspectRatio 财务报告和审定财务报表 opacity。类型学继承了 Box 的布局道具并添加了主题字体家族 (单位:千美元)sans, (中文(简体) ), serif, (中文(简体) ), mono, (中文(简体) ), fontStyle, (中文(简体) ), lineHeight, (中文(简体) ), letterSpacing, (中文(简体) ), verticalAlign包装和装饰 基于收件间隔,字体大小, 光度和阴影使用已公布的有限尺度;其他CSS道具接受CSS 数值. style 优先于样式道具并接受自定义属性.

限制宽度 ellipsis。 。 。 . maxLines 接受任何正整数,并 优先于 ellipsis; 明确 style 能够覆盖断线. 提供另一种读取被剪切的基本内容的方法.

中断合同变更: 参考文献和本地属性必须匹配 已变造元素; 明确的非违约通用要求 as 或匹配 类型 variant 在呼叫现场。 使用 satisfies 当编译道具到 保留这些文字选择器,或者在 展开。 无效的令牌、 非无限 CSS 数字和无效行限制 TypeError。公开的打字方法使用 clamp: true 多线 结构而不是编号 maxLines 变体;行数为动态. 边际造型现在为 Box 所拥有, 而非复制于 Typography 食谱。 仍保留构成部分名称 Box 财务报告和审定财务报表 Typography。 。 。 .

通知

NotificationCard 是独立的视觉复合体: Header 包含 Icon, (中文(简体) ), Title 财务报告和审定财务报表 Close, (中文(简体) ), Body 包含 Description 或自定义内容,以及 Footer 包含 Actions区域是可选的 NotificationCard.Icon 在使用复合内容时明确. Header 供给根 onClose 按钮,除非 Close 插槽已存在 。 方便道具仍然包括 变相图标. ToasterProvider 用同一张牌挂载两个频道 暂时的吐司和持续的通知。 一次包装应用程序 在所希望的主题范围内,外部转换或剪接容器:

import { Button, ThemeProvider, ToasterProvider, useNotification, useToast } from '@choco-vanille/ui';

const Actions = () => {
  const { showSuccess } = useToast();
  const { show } = useNotification();

  return (
    <>
      <Button label="Save" onClick={() => showSuccess({ title: 'Changes saved' })} />
      <Button label="Notify" onClick={() => show({ title: 'Update available' })} />
    </>
  );
};

const Example = () => (
  <ThemeProvider>
    <ToasterProvider>
      <Actions />
    </ToasterProvider>
  </ThemeProvider>
);

ToasterProviderProps 接受 children 和视图端口配置 : toastPosition, (中文(简体) ), notificationPosition, (中文(简体) ), toastLabel, (中文(简体) ), notificationLabel, (中文(简体) ), className,以及 style。它没有添加 DOM 包装并保留了视图 地方主题范围. Toaster 仍可供手工安装; 不为同一应用程序挂载两者。 钩子不需要反应 上下文,但信息需要挂载的提供者或手动的 Toaster 显示.

吐司出现在右下方,默认为5000ms,支持刷取解雇 没有关闭按钮。 通知出现在右上方, 默认为持久性 (单位:千美元)duration: 0并有一个关闭按钮。 每个频道显示最多 三堆 消息,在 Sonner 的队列中保留额外消息。 动作与 弹性端. 两个钩子都接受 actions; 只接受通知 closeLabel。 。 。 . 通知 children 接受 自定义 NotificationCard 节; 包含 Header 以保留默认关闭 按钮,或提供自己的 Close 插槽 。 原先的平面化合物含量应 归入 Header, (中文(简体) ), Body,以及 Footer。 。 。 .

中断 API 更改 : 替换 Toast 财务报告和审定财务报表 Toast.* 与 NotificationCard 财务报告和审定财务报表 NotificationCard.*,包括其相应的道具类型和样式 地图。 替换 <ToastProvider>{children}</ToastProvider> 与 <ToasterProvider>{children}</ToasterProvider>;钩名不变.

他们

设计系统是信使真实的单一来源. 调色板, 语义颜色和其他符号类别 src/theme/tokens/。 。 。 . 完整的光和暗主题组装在 src/theme/themes/,其CSS变量由 src/theme/styles/contract/contract.css.ts。 。 。 .

内建的彩色坡道使用 sRGB 十六进制值, 有蓝色初级和紫色二级 颜色 语义路径包括: surface.main, (中文(简体) ), surface.elevated, (中文(简体) ), surface.muted, (中文(简体) ), text.primary, (中文(简体) ), text.secondary, (中文(简体) ), text.tertiary, (中文(简体) ), neutral.main, (中文(简体) ), danger.main, (中文(简体) ), accent*,以及 focusRing。这些替换以前的颜色符号和CSS变量名称; 更新消费者主题对象并相应覆盖。 组件颜色意图 使用情况 neutral 财务报告和审定财务报表 danger;反馈变量也使用 danger编辑 purple 其他口音意向使用相应的 accent* 标志. ThemeColors, (中文(简体) ), ThemeEditorColors,以及 Theme 接受自定义的字符串 数值; ThemeColorOverrides 类型提供者的部分语义颜色 超载 全部从 @choco-vanille/ui。 。 。 .

装满了装备的船 浅而暗 主题。 暗模式遵循 操作系统默认( O)prefers-color-scheme),并且可以强制每个子树:

<html data-theme="dark"> ...   <!-- force dark -->
<html data-theme="light"> ...  <!-- force light -->
<html> ...                     <!-- auto: follow the OS -->

全球主题标识符使用 choco-vanille 名称空间 : .choco-vanille-theme-light, (中文(简体) ), .choco-vanille-theme-dark,则 choco-vanille.theme 财务报告和审定财务报表 choco-vanille.reset 级联层,和 --choco-vanille-theme-transition-duration。此前缀更改正在打破 : 更新自定义选择器、 层顺序和过渡覆盖到这些 名称。 上一个前缀的别名不释放 。 这个 data-theme 属性和符号变量,例如 --color-primary-main 不变.

有两种方法:

1. 类型 vars (内部) *.css.ts,完全自动完成 :

import { style } from '@vanilla-extract/css';
import { vars } from '@choco-vanille/ui';

export const card = style({
  backgroundColor: vars.color.surface.main,
  color: vars.color.surface.foreground,
  padding: vars.space[16],
  borderRadius: vars.radius[8],
  boxShadow: vars.shadow.sm,
});

2. 基本CSS变量 - 每一个符号都发出在 :root 与一个稳定, 人类可读名称来源于其路径( :--color-primary-main, (中文(简体) ), --space-12, (中文(简体) ), --radius-6(中文(简体) ). 在任意样式表中使用它们,或覆盖它们以重取主题 :

:root {
  --color-primary-main: oklch(0.55 0.2 250); /* override this token */
  --radius-8: 0.25rem;
}

两者自动保持同步 – 压倒 CSS 变量同时更新每个 内容,通过 vars。 。 。 .

间距、字体大小和半径使用数字键参考像素 16px根 (英语). 除间距外,值仍为对数 0 并固定 1px。 。 。 . 使用 padding={16}, (中文(简体) ), fontSize={14} 财务报告和审定财务报表 borderRadius={8}; 没有名称 别名或隐相乘. 支持中只接受数字 缩放,而不是任意值. radius.full 和类型 通过 72。 。 。 .

主题不再暴露 lineHeight 或者说 letterSpacing: 保留组件 他们的CSS打字机和打字机 letterSpacing 接受 CSS 值. 两者 shadow 财务报告和审定财务报表 dropShadow 曝光 none, (中文(简体) ), xs, (中文(简体) ), sm, (中文(简体) ), md, (中文(简体) ), lg, (中文(简体) ), xl。 。 。 . 字体家庭、重量、期限、放松和堆放保持不变. 独立组件大小轴, 如按钮 size="md" 不受影响. 这些符号名称和CSS变量正在打破没有遗留别名的更改.

覆盖接受任何有效的 CSS 颜色 。 重塑意图还要求其 盘旋、按住、前景和微妙的象征物 填满 请检查两个主题的每个受影响状态的对比度.

框、打字和图标直接接受 CSS 颜色,包括外部自定义 属性。 传出参考文献而不是符号名称 :

import { Box, Typography, vars } from '@choco-vanille/ui';

<Box backgroundColor={vars.color.surface.main} borderColor="var(--app-border)">
  <Typography color={vars.color.primary.main}>Brand text</Typography>
</Box>;

例如,提供方对嵌入形状的覆盖 tokens={{ primary: { main: '#0f766e' } }}。只提供叶片改变. 这是对颜色对象、基于符号的道具路径、 覆盖的破解更改 并重新命名 CSS 变量; 没有释放出遗留的别名 .

许可证

麻省理工学院