ranui 0.1.10-alpha.9 → 0.2.0-alpha.0

package/README.md

@@ -0,0 +1,397 @@
+# ranui
+
+An experimental UI component library based on Web Components. Components use Shadow DOM encapsulation, CSS Token theming, and SSR / Declarative Shadow DOM support.
+
+---
+
+<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/github/actions/workflow/status/chaxus/ran/ci.yml" alt="Build Status"></a>
+<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/v/ranui.svg" alt="npm-v"></a>
+<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/dt/ranui.svg" alt="npm-d"></a>
+<a href="https://github.com/chaxus/ran"><img src="https://img.badgesize.io/https:/unpkg.com/ranui/dist/umd/shadowless/shadowless.umd.cjs?label=brotli&compression=brotli" alt="brotli"></a>
+<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/badge/module%20formats-umd%2C%20esm-green.svg" alt="module formats: umd, esm"></a>
+
+[中文](./README.zh-CN.md) | **English**
+
+## Important Notice
+
+This is an **experimental UI library** in early development. It is usable, but primarily intended for learning and experimentation.
+
+Key points:
+
+- **Early development**: features are still being developed and refined.
+- **Experimental**: APIs may change frequently.
+- **Learning-oriented**: mainly intended for learning Web Components and UI development.
+
+## Features
+
+1. **Cross-framework compatibility:** works with React, Vue, Preact, SolidJS, Svelte, and any JavaScript project that follows W3C standards.
+2. **Native experience:** use custom elements such as `<r-button>` and `<r-modal>` like native HTML elements.
+3. **Modular design:** supports both full imports and per-component imports for better maintainability and bundle control.
+4. **Shadow DOM encapsulation:** component internals are isolated by default, while CSS Tokens, `::part()`, and the `sheet` attribute provide controlled styling hooks.
+5. **TypeScript support:** built with TypeScript and type definitions.
+6. **SSR friendly:** supports server rendering through `defineSSR`, `renderToString`, and Declarative Shadow DOM.
+7. **Accessible:** ARIA roles/states, full keyboard navigation, form-associated inputs (`<r-checkbox>`/`<r-input>`/`<r-select>` participate in native `FormData`), live-region toasts, and `prefers-reduced-motion` support.
+
+## Installation
+
+Using npm:
+
+```console
+npm install ranui --save
+```
+
+## Documentation and Examples
+
+[See components and use examples](https://chaxus.github.io/ran/src/ranui/)
+
+### Components & API reference
+
+Every element's attributes, properties, **events (with `detail` shapes)**, slots, and `::part()` names are generated from source — no need to grep the exports:
+
+- Per-element API: [docs/COMPONENTS.md](./docs/COMPONENTS.md)
+- Design standard (color/spacing/typography/motion/a11y): [docs/DESIGN.md](./docs/DESIGN.md)
+
+Regenerate after changing a component's API with:
+
+```bash
+pnpm doc:api
+```
+
+### AI / Claude Code skill
+
+A ready-to-use skill lets AI assistants (Claude Code) read and use ranui without
+spelunking the source. It's published from the `ran` plugin marketplace:
+
+```bash
+/plugin marketplace add chaxus/ran
+/plugin install ranui@ran
+```
+
+Once installed, Claude uses it automatically when you work with ranui (or invoke it
+explicitly as `/ranui:ranui`). The skill covers the import map, element inventory, the
+builder/reactivity API, accessibility, and usage examples, and points to the API
+reference shipped in the package ([docs/COMPONENTS.md](./docs/COMPONENTS.md)).
+
+### Styling Documentation
+
+The styling system is unified around CSS Tokens and `::part()`.
+
+- Style override guide: [docs/style-override.md](./docs/style-override.md)
+- Complete Token/Part list, generated automatically: [docs/style-tokens-parts.md](./docs/style-tokens-parts.md)
+- Public styling API for consumers, generated automatically: [docs/style-tokens-public.md](./docs/style-tokens-public.md)
+- Public token filter config: [docs/style-token-filter.json](./docs/style-token-filter.json)
+
+Refresh the styling docs with:
+
+```bash
+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):
+
+```ts
+import { initTheme, setTheme, setThemeToken, setThemeTokens } from 'ranui';
+import 'ranui/style';
+
+initTheme(); // restore the persisted choice on load
+setTheme('system'); // 'light' | 'dark' | 'system'
+setThemeToken('--ran-color-primary', '#6c47ff');
+setThemeTokens({ '--ran-radius-md': '10px' });
+```
+
+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).
+
+## Imports
+
+Use per-component imports to reduce bundle size:
+
+```js
+import 'ranui/button';
+```
+
+If styles are missing, import the stylesheet manually:
+
+```js
+import 'ranui/style';
+```
+
+If type resolution fails, import one of the type entry points manually:
+
+```ts
+import 'ranui/typings';
+// or
+import 'ranui/dist/index.d.ts';
+// or
+import 'ranui/type';
+// or
+import 'ranui/dist/typings';
+```
+
+Only one working type entry is needed.
+
+Full import is also supported:
+
+```ts
+import 'ranui';
+```
+
+ES module:
+
+```js
+import 'ranui';
+```
+
+or:
+
+```js
+import 'ranui/button';
+```
+
+UMD, IIFE, CJS:
+
+```html
+<script src="./ranui/dist/umd/index.umd.cjs"></script>
+```
+
+## Usage
+
+RanUI components are Web Components, so they can be used without framework-specific wrappers.
+
+In most cases, use them like native HTML elements.
+
+Examples:
+
+- html
+- js
+- jsx
+- vue
+- tsx
+
+### html
+
+```html
+<script src="./ranui/dist/umd/index.umd.cjs"></script>
+
+<body>
+  <r-button>Button</r-button>
+</body>
+```
+
+### js
+
+```js
+import 'ranui';
+
+const Button = document.createElement('r-button');
+Button.textContent = 'this is button text';
+document.body.appendChild(Button);
+```
+
+### jsx
+
+```jsx
+import 'ranui';
+
+const App = () => {
+  return (
+    <>
+      <r-button>Button</r-button>
+    </>
+  );
+};
+```
+
+### vue
+
+```vue
+<template>
+  <r-button></r-button>
+</template>
+<script>
+import 'ranui';
+</script>
+```
+
+### tsx
+
+```tsx
+import 'ranui/button';
+
+const Button = () => {
+  return (
+    <div>
+      <r-button type="primary">button</r-button>
+    </div>
+  );
+};
+```
+
+### Message Position and Container
+
+`window.message` supports custom top offset, z-index, and mount container:
+
+```ts
+import 'ranui/message';
+
+const customRoot = document.getElementById('custom-message-root');
+
+window.message?.success({
+  content: 'Saved',
+  duration: 2000,
+  top: 24,
+  zIndex: 3000,
+  getContainer: () => customRoot,
+});
+```
+
+`top` supports `number | string`; `24` becomes `24px`, while `'2rem'` keeps its unit.
+
+`zIndex` supports `number | string`.
+
+`getContainer` must return an `HTMLElement`; when omitted, messages mount to `document.body`.
+
+### Reactive Primitives
+
+`signal`, `createEffect`, `computed`, and `batch` ship alongside the DOM builder for building reactive page sections without a framework. The design mirrors SwiftUI's `@Observable` with two correctness improvements from Solid.js: effects automatically clean up stale subscriptions before each re-run, and `batch()` coalesces multiple signal writes into a single effect flush — the same guarantee SwiftUI gives for free.
+
+```ts
+import { signal, createEffect, computed, batch, EventManager, Div, ButtonBuilder } from 'ranui/builder';
+
+function initCounter(container: HTMLElement) {
+  const [count, setCount] = signal(0);
+  const [step, setStep] = signal(1);
+  const doubled = computed(() => count() * 2);
+  const scope = new EventManager();
+
+  const label = Div().build();
+  const view = Div()
+    .children(
+      label,
+      ButtonBuilder()
+        .text('+')
+        .listen(scope, 'click', () => setCount((n) => n + step())),
+      ButtonBuilder()
+        .text('reset')
+        .listen(
+          scope,
+          'click',
+          () =>
+            batch(() => {
+              setCount(0);
+              setStep(1);
+            }), // two writes → one effect flush
+        ),
+    )
+    .build();
+
+  const dispose = createEffect(() => {
+    label.textContent = `${count()} (×2 = ${doubled()})`;
+  });
+
+  container.appendChild(view);
+  return () => {
+    dispose();
+    scope.abort();
+  }; // teardown
+}
+```
+
+See [Utility Documentation](./utils/README.md) for the full API.
+
+### Routing
+
+RanUI includes client-side routing via declarative components and a JavaScript API.
+
+**Declarative components:**
+
+```html
+<r-router>
+  <nav>
+    <r-link href="/">Home</r-link>
+    <r-link href="/about">About</r-link>
+  </nav>
+
+  <r-route path="/" exact><h2>Home</h2></r-route>
+  <r-route path="/about"><h2>About</h2></r-route>
+  <r-route path="/users/:id"><h2>User detail</h2></r-route>
+</r-router>
+```
+
+**JavaScript API with navigation guard:**
+
+```ts
+import { createRouter } from 'ranui';
+
+const router = createRouter({
+  mode: 'history',
+  routes: [
+    { path: '/', exact: true, meta: { title: 'Home' } },
+    { path: '/users/:id', meta: { requiresAuth: true } },
+  ],
+  viewTransition: 'spa', // 'spa' | 'mpa' | 'both'
+});
+
+router.beforeEach((to, from, next) => {
+  if (to.meta?.requiresAuth && !isLoggedIn()) next('/login');
+  else next();
+});
+
+router.push('/users/42');
+```
+
+For pure MPA sites (no JS router needed), use `enableMpaViewTransitions()` to inject `@view-transition { navigation: auto }`. Shared-element morph animations are supported via the standard `view-transition-name` CSS property.
+
+```ts
+import { enableMpaViewTransitions } from 'ranui';
+enableMpaViewTransitions();
+```
+
+See the [Router documentation](https://chaxus.github.io/ran/src/ranui/router/) for the full API including guards, `onPageSwap`/`onPageReveal`, and per-element transition names.
+
+### SSR & Builder
+
+For SSR or declarative UI construction, RanUI internally uses `builder`, the SSR registry, and Declarative Shadow DOM. Components reuse existing Shadow Roots through `ensureShadowRoot` and keep initialization idempotent through `ensureShadowElement`.
+
+Source-level SSR rendering example:
+
+```ts
+import { Button } from '@/components/button';
+import { renderToString } from '@/utils/ssr';
+
+const button = new Button();
+button.setAttribute('effect', 'true');
+
+// Outputs an HTML string containing Declarative Shadow DOM.
+const html = renderToString(button);
+```
+
+See [Utility Documentation](./utils/README.md) for details.
+
+## Component Development Conventions
+
+When adding or maintaining components, follow the package conventions:
+
+- Extend `RanElement`; do not directly extend the browser `HTMLElement`.
+- Use `ensureShadowRoot` to create or reuse Shadow Roots; do not call `attachShadow` directly.
+- Use `ensureShadowElement` to build Shadow DOM subtrees idempotently.
+- Include `sheet` in `observedAttributes` and sync component-level style overrides through `syncSheetAttribute`.
+- Guard `attributeChangedCallback` with `if (old === next) return;`.
+- Register components with `defineSSR('r-name', Component)`, not direct `customElements.define`.
+- Add both type exports and side-effect imports in `index.ts`; also add standalone entries in `vite.config.ts` and `package.json`.
+- Use `EventManager` from `@/utils/builder` for lifecycle-bound listeners in `connectedCallback`; call `manager.abort()` in `disconnectedCallback` instead of tracking individual `removeEventListener` calls.
+
+## Contributing
+
+Contributions from learners and developers are welcome. This is an experimental project, so please expect active iteration.
+
+## Contributors
+
+<a href="https://github.com/chaxus/ran/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=chaxus/ran" />
+</a>
+
+## Meta
+
+[LICENSE (MIT)](/LICENSE)

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # ranui
 
-基于 `Web Components` 组件方案
+基于 `Web Components` 的实验性组件库。组件使用 Shadow DOM 封装、CSS Token 主题体系，并提供 SSR / Declarative Shadow DOM 支持。
 
 ---
 
@@ -12,14 +12,25 @@
 
 **中文** | [English](./README.md)
 
+## ⚠️ 重要说明
+
+这是一个**实验性 UI 库**，处于早期开发阶段。虽然功能可用，但主要用于学习和实验。
+
+**关键要点：**
+
+- 🚧 **早期开发**: 功能仍在开发和完善中
+- 🧪 **实验性**: API 可能会频繁变化
+- 📚 **学习导向**: 主要用于学习 Web Components 和 UI 开发
+
 ## 特点
 
 1. **跨框架兼容：** 与 React, Vue, Preact, SolidJS, Svelte 等兼容。可以和遵循 W3C 标准的任何 JavaScript 项目集成。
-2. **原生体验：** 易于入门，像使用本地 div 标签，简化项目大小和减少学习成本。
+2. **原生体验：** 易于入门，像使用原生 HTML 标签一样使用 `<r-button>`、`<r-modal>` 等自定义元素。
 3. **模块化设计：** 可选导入和全量导入，以增强可维护性和可伸缩性。
-4. **交互式丰富文档：** 提供详细的交互式文档，并附有有效的示例子。
+4. **Shadow DOM 封装：** 组件内部样式默认隔离，并通过 CSS Token、`::part()` 和 `sheet` 属性开放可控的样式覆盖能力。
 5. **支持类型校验：** 基于 TypeScript 构建，具有类型支持，确保代码的健壮性和可维护性。
-6. **持久和稳定：** 与框架 (React/vue) 无关，避免破坏性的更新，并确保持续的项目运行。
+6. **SSR 友好：** 通过 `defineSSR`、`renderToString` 和 Declarative Shadow DOM 支持服务端渲染场景。
+7. **无障碍：** ARIA 角色/状态、完整键盘导航、表单参与控件（`<r-checkbox>`/`<r-input>`/`<r-select>` 可被原生 `FormData` 收集）、live-region 提示，并尊重 `prefers-reduced-motion`。
 
 ## 安装
 
@@ -33,6 +44,37 @@ npm install ranui --save
 
 [See components and use examples](https://chaxus.github.io/ran/cn/src/ranui/)
 
+### 样式定制文档
+
+当前样式系统已统一为 CSS Token 与 `::part()` 规范。
+
+- 样式覆盖规范：[docs/style-override.md](./docs/style-override.md)
+- 完整 Token/Part 清单（自动生成）: [docs/style-tokens-parts.md](./docs/style-tokens-parts.md)
+- 面向使用方的公开样式 API（自动生成）: [docs/style-tokens-public.md](./docs/style-tokens-public.md)
+- 公开 Token 过滤配置：[docs/style-token-filter.json](./docs/style-token-filter.json)
+
+可通过以下命令刷新样式文档：
+
+```bash
+pnpm doc:style
+```
+
+### 主题与主题包
+
+RanUI 支持亮色、暗色与系统主题，并提供多个 CSS-only 主题包。
+
+```ts
+import { initTheme, setTheme, setThemePack, setThemeToken } from 'ranui';
+import 'ranui/theme-packs/pixel-retro';
+
+initTheme();
+setTheme('system');
+setThemePack('pixel-retro');
+setThemeToken('--ran-color-primary', '#2563eb');
+```
+
+可用主题包包括 `windows-98`、`windows-xp`、`system-6`、`wired`、`paper`、`pixel-retro`、`neo-brutalism`。使用 `setThemePack('default')` 可恢复默认主题包。
+
 ## 引入方式
 
 支持按需导入，以显著减少包体积大小
@@ -50,15 +92,17 @@ import 'ranui/style';
 如果遇到类型问题，可以选择手动导入类型文件
 
 ```ts
-import 'ranui/types';
-```
-
-或者
-
-```ts
+import 'ranui/typings';
+// 或者
+import 'ranui/dist/index.d.ts';
+// 或者
+import 'ranui/type';
+// 或者
 import 'ranui/dist/typings';
 ```
 
+并不是都要，选一个能生效的就行
+
 也支持全量导入
 
 ```ts
@@ -113,7 +157,7 @@ import 'ranui/button';
 import 'ranui';
 
 const Button = document.createElement('r-button');
-Button.appendChild('this is button text');
+Button.textContent = 'this is button text';
 document.body.appendChild(Button);
 ```
 
@@ -145,40 +189,175 @@ import 'ranui';
 ### tsx
 
 ```tsx
-// react 18
-import type { SyntheticEvent } from 'react';
-import React, { useRef } from 'react';
-import 'ranui';
+import 'ranui/button';
 
-const FilePreview = () => {
-  const ref = useRef<HTMLDivElement | null>(null);
-  const uploadFile = (e: SyntheticEvent<HTMLDivElement>) => {
-    if (ref.current) {
-      const uploadFile = document.createElement('input');
-      uploadFile.setAttribute('type', 'file');
-      uploadFile.click();
-      uploadFile.onchange = (e) => {
-        const { files = [] } = uploadFile;
-        if (files && files?.length > 0 && ref.current) {
-          ref.current.setAttribute('src', '');
-          const file = files[0];
-          const url = URL.createObjectURL(file);
-          ref.current.setAttribute('src', url);
-        }
-      };
-    }
-  };
+const Button = () => {
   return (
     <div>
-      <r-preview ref={ref}></r-preview>
-      <r-button type="primary" onClick={uploadFile}>
-        choose file to preview
-      </r-button>
+      <r-button type="primary">button</r-button>
     </div>
   );
 };
 ```
 
+### Message 位置与容器配置
+
+`window.message` 现已支持自定义顶部偏移、层级和挂载容器：
+
+```ts
+import 'ranui/message';
+
+const customRoot = document.getElementById('custom-message-root');
+
+window.message?.success({
+  content: '保存成功',
+  duration: 2000,
+  top: 24,
+  zIndex: 3000,
+  getContainer: () => customRoot,
+});
+```
+
+`top` 支持 `number | string`（`24` 会转成 `24px`，`'2rem'` 会保留原单位）。
+
+`zIndex` 支持 `number | string`。
+
+`getContainer` 需要返回 `HTMLElement`；未传时默认挂载到 `document.body`。
+
+### 响应式原语
+
+`signal`、`createEffect`、`computed`、`batch` 与 DOM builder 一起提供，用于在无框架依赖的情况下构建响应式页面区块。设计参考 SwiftUI 的 `@Observable`，并借鉴 Solid.js 补充了两个正确性改进：effect 重新执行前自动清理过期订阅；`batch()` 将多次 signal 写入合并为一次 effect flush，与 SwiftUI 自动合并变更的行为对齐。
+
+```ts
+import { signal, createEffect, computed, batch, EventManager, Div, ButtonBuilder } from 'ranui/builder';
+
+function initCounter(container: HTMLElement) {
+  const [count, setCount] = signal(0);
+  const [step, setStep] = signal(1);
+  const doubled = computed(() => count() * 2);
+  const scope = new EventManager();
+
+  const label = Div().build();
+  const view = Div()
+    .children(
+      label,
+      ButtonBuilder()
+        .text('+')
+        .listen(scope, 'click', () => setCount((n) => n + step())),
+      ButtonBuilder()
+        .text('重置')
+        .listen(
+          scope,
+          'click',
+          () =>
+            batch(() => {
+              setCount(0);
+              setStep(1);
+            }), // 两次写入 → 一次 flush
+        ),
+    )
+    .build();
+
+  const dispose = createEffect(() => {
+    label.textContent = `${count()} (×2 = ${doubled()})`;
+  });
+
+  container.appendChild(view);
+  return () => {
+    dispose();
+    scope.abort();
+  }; // 区块销毁时清理
+}
+```
+
+详细 API 请参考 [工具文档](./utils/README.zh-CN.md)。
+
+### 路由
+
+RanUI 内置客户端路由，提供声明式组件和 JavaScript API 两种方式。
+
+**声明式组件：**
+
+```html
+<r-router>
+  <nav>
+    <r-link href="/">首页</r-link>
+    <r-link href="/about">关于</r-link>
+  </nav>
+
+  <r-route path="/" exact><h2>首页</h2></r-route>
+  <r-route path="/about"><h2>关于</h2></r-route>
+  <r-route path="/users/:id"><h2>用户详情</h2></r-route>
+</r-router>
+```
+
+**JavaScript API，含导航守卫：**
+
+```ts
+import { createRouter } from 'ranui';
+
+const router = createRouter({
+  mode: 'history',
+  routes: [
+    { path: '/', exact: true, meta: { title: '首页' } },
+    { path: '/users/:id', meta: { requiresAuth: true } },
+  ],
+  viewTransition: 'spa', // 'spa' | 'mpa' | 'both'
+});
+
+router.beforeEach((to, from, next) => {
+  if (to.meta?.requiresAuth && !isLoggedIn()) next('/login');
+  else next();
+});
+
+router.push('/users/42');
+```
+
+纯 MPA 站点（无需 JS router）可使用 `enableMpaViewTransitions()` 注入 `@view-transition { navigation: auto }`。共享元素过渡动画通过标准 `view-transition-name` CSS 属性实现。
+
+```ts
+import { enableMpaViewTransitions } from 'ranui';
+enableMpaViewTransitions();
+```
+
+完整 API（守卫、`onPageSwap`/`onPageReveal`、元素级动画命名）请参考 [路由文档](https://chaxus.github.io/ran/cn/src/ranui/router/)。
+
+### SSR & Builder (推荐)
+
+对于需要服务端渲染 (SSR) 或更声明式构建 UI 的场景，RanUI 内部使用 `builder`、SSR registry 与 Declarative Shadow DOM。组件会通过 `ensureShadowRoot` 复用已有 Shadow Root，并通过 `ensureShadowElement` 保持初始化幂等。
+
+源码内的 SSR 渲染示例：
+
+```ts
+import { Button } from '@/components/button';
+import { renderToString } from '@/utils/ssr';
+
+const button = new Button();
+button.setAttribute('effect', 'true');
+
+// 输出包含 Declarative Shadow DOM 的 HTML 字符串
+const html = renderToString(button);
+```
+
+更多细节请查看 [Utility Documentation](./utils/README.md)。
+
+## 组件开发约定
+
+新增或维护组件时请遵循当前包内约定：
+
+- 组件继承 `RanElement`，不要直接继承浏览器环境下的 `HTMLElement`。
+- 使用 `ensureShadowRoot` 创建或复用 Shadow Root，不要直接调用 `attachShadow`。
+- 使用 `ensureShadowElement` 构建 Shadow DOM 子树，保证重复构造时幂等。
+- `observedAttributes` 包含 `sheet`，并通过 `syncSheetAttribute` 同步组件级样式覆盖。
+- `attributeChangedCallback` 首行使用 `if (old === next) return;` 避免重复同步。
+- 使用 `defineSSR('r-name', Component)` 注册组件，而不是直接调用 `customElements.define`。
+- 在 `index.ts` 中同时添加类型导出和副作用导入；在 `vite.config.ts`、`package.json` 中补齐独立入口与导出。
+- 在 `connectedCallback` 中使用 `@/utils/builder` 导出的 `EventManager` 管理生命周期事件；在 `disconnectedCallback` 中调用 `manager.abort()` 一次清理所有监听器，不要逐个调用 `removeEventListener`。
+
+## 贡献
+
+我们欢迎学习者和开发者的贡献！这是一个实验性项目，请对开发过程保持耐心。
+
 ## 贡献者
 
 <a href="https://github.com/chaxus/ran/graphs/contributors">