ranui 0.2.0-alpha.5 → 0.2.0-alpha.7

package/README.md

@@ -89,10 +89,10 @@ pnpm doc:style
 
 ### Theming
 
-ranui ships a single token system based on the [Geist design system](https://vercel.com/design), with `light`, `dark`, and `system` modes — there are no theme packs. Switch the mode or override any token at runtime (SSR-safe):
+ranui ships a single token system based on the [Geist design system](https://vercel.com/geist) — Vercel's open-source design language, where color is a **state ladder** (each scale runs 100→1000, one job per step: background → hover → border → solid fill → text). ranui adopts that ladder plus **Geist Sans / Geist Mono**, so dark mode just redefines the base scale and every semantic token flips automatically. Three modes — `light`, `dark`, `system` — and no theme packs. Switch the mode or override any token at runtime (SSR-safe):
 
 ```ts
-import { initTheme, setTheme, setThemeToken, setThemeTokens } from 'ranui';
+import { initTheme, setTheme, setThemeToken, setThemeTokens } from 'ranui/theme';
 import 'ranui/style';
 
 initTheme(); // restore the persisted choice on load
@@ -101,8 +101,35 @@ setThemeToken('--ran-color-primary', '#6c47ff');
 setThemeTokens({ '--ran-radius-md': '10px' });
 ```
 
+The `ranui/theme` entry ships only the theming engine — no custom elements are
+registered, so it stays out of your bundle if you just want tokens/dark mode.
+The same APIs are also re-exported from the `ranui` barrel.
+
 Dark mode redefines only the base color scale; semantic tokens (`--ran-color-*`) reference it and flip automatically. See [docs/THEME_STYLE_SYSTEM_DESIGN.md](./docs/THEME_STYLE_SYSTEM_DESIGN.md) and [docs/DESIGN.md](./docs/DESIGN.md).
 
+### Internationalization
+
+A framework-agnostic i18n engine ships as its own `ranui/i18n` entry — like
+`ranui/theme`, it registers no custom elements:
+
+```ts
+import { createI18n, useI18n } from 'ranui/i18n';
+
+createI18n({
+  // each locale is a flat dictionary — keys are used verbatim (no nesting)
+  messages: { en: { 'hero.title': 'Hi {name}' }, zh: { 'hero.title': '你好 {name}' } },
+  fallbackLocale: 'en',
+  persist: true, // remember the choice in localStorage
+  detectNavigator: true, // pick the initial locale from the browser
+});
+
+useI18n()!.t('hero.title', { name: 'Ada' }); // → "Hi Ada"
+useI18n()!.setLocale('zh'); // persists and notifies subscribers
+```
+
+`t()` falls back to the fallback locale, then to the key itself; `{param}`
+placeholders are interpolated. The core is SSR-safe.
+
 ## Imports
 
 Use per-component imports to reduce bundle size:
@@ -111,6 +138,14 @@ Use per-component imports to reduce bundle size:
 import 'ranui/button';
 ```
 
+Non-component subpaths ship the utilities on their own, so you can pull in just
+the engine you need without registering every element:
+
+```js
+import { initTheme } from 'ranui/theme'; // theming only
+import { createI18n } from 'ranui/i18n'; // i18n only
+```
+
 If styles are missing, import the stylesheet manually:
 
 ```js

package/README.zh-CN.md

@@ -59,21 +59,44 @@ npm install ranui --save
 pnpm doc:style
 ```
 
-### 主题与主题包
+### 主题
 
-RanUI 支持亮色、暗色与系统主题，并提供多个 CSS-only 主题包。
+RanUI 基于 [Geist 设计体系](https://vercel.com/geist) 提供统一的 CSS Token 主题体系——Geist 是 Vercel 的开源设计语言，其核心是把颜色组织成一条**状态阶梯**（每条色阶 100→1000，每档一个固定职责：背景 → 悬停 → 边框 → 实心填充 → 文字）。RanUI 采用这套阶梯并搭配 **Geist Sans / Geist Mono**，因此暗色模式只需重定义基础色阶，所有语义 Token 自动翻转。支持 `light`、`dark`、`system` 三种模式（已不再提供主题包）。可在运行时切换模式或覆盖任意 Token（SSR 安全）：
 
 ```ts
-import { initTheme, setTheme, setThemePack, setThemeToken } from 'ranui';
-import 'ranui/theme-packs/pixel-retro';
+import { initTheme, setTheme, setThemeToken, setThemeTokens } from 'ranui/theme';
+import 'ranui/style';
+
+initTheme(); // 页面加载时恢复上次的选择
+setTheme('system'); // 'light' | 'dark' | 'system'
+setThemeToken('--ran-color-primary', '#6c47ff');
+setThemeTokens({ '--ran-radius-md': '10px' });
+```
+
+`ranui/theme` 入口只包含主题引擎，不会注册任何自定义元素——只需要 Token / 暗色模式时它不会把组件带进你的包体。这些 API 同样从 `ranui` 主入口重新导出。
+
+暗色模式只重定义基础色阶，语义 Token（`--ran-color-*`）引用色阶后自动翻转。详见 [docs/THEME_STYLE_SYSTEM_DESIGN.md](./docs/THEME_STYLE_SYSTEM_DESIGN.md) 与 [docs/DESIGN.md](./docs/DESIGN.md)。
+
+### 国际化
+
+框架无关的 i18n 引擎作为独立的 `ranui/i18n` 入口提供，与 `ranui/theme` 一样不注册任何自定义元素：
 
-initTheme();
-setTheme('system');
-setThemePack('pixel-retro');
-setThemeToken('--ran-color-primary', '#2563eb');
+```ts
+import { createI18n, useI18n } from 'ranui/i18n';
+
+createI18n({
+  // 每种语言是扁平字典——key 原样使用（不做嵌套）
+  messages: { en: { 'hero.title': 'Hi {name}' }, zh: { 'hero.title': '你好 {name}' } },
+  fallbackLocale: 'en',
+  persist: true, // 记住选择（localStorage）
+  detectNavigator: true, // 按浏览器语言初始化
+});
+
+useI18n()!.t('hero.title', { name: 'Ada' }); // → "Hi Ada"
+useI18n()!.setLocale('zh'); // 持久化并通知订阅者
 ```
 
-可用主题包包括 `windows-98`、`windows-xp`、`system-6`、`wired`、`paper`、`pixel-retro`、`neo-brutalism`。使用 `setThemePack('default')` 可恢复默认主题包。
+`t()` 依次回退到 fallback locale、再到 key 本身；`{param}` 占位符会被插值。核心逻辑 SSR 安全。
 
 ## 引入方式
 
@@ -83,6 +106,13 @@ setThemeToken('--ran-color-primary', '#2563eb');
 import 'ranui/button';
 ```
 
+非组件入口单独打包对应的工具引擎，可以只引入需要的部分，而不注册全部元素：
+
+```js
+import { initTheme } from 'ranui/theme'; // 仅主题
+import { createI18n } from 'ranui/i18n'; // 仅 i18n
+```
+
 如果遇到样式问题，可以选择手动导入样式文件
 
 ```js

package/dist/i18n.d.ts

@@ -0,0 +1,2 @@
+export { I18nCore, createI18n, useI18n } from '@/utils/i18n';
+export type { I18nConfig, MessageDict, LocaleMessages, TranslateParams, LocaleChangeHandler } from '@/utils/i18n';

package/dist/i18n.js

@@ -0,0 +1,6 @@
+import { I18nCore as r, createI18n as o, useI18n as n } from "./utils/i18n.js";
+export {
+  r as I18nCore,
+  o as createI18n,
+  n as useI18n
+};