@yoyaflow/yoya-ui 0.3.0 → 0.3.2

package/README.md

@@ -44,19 +44,22 @@ function HelloWorldExampleI18n() {
 
 ## Installation
 
-### Scaffold a new project
+### Quick experience
 
 ```bash
-npx create-yoya-ui@latest my-app                 # basic template (SPA)
-npx create-yoya-ui@latest my-app --template ssr  # SSR template (renderPage + hydrateOrMount)
-npx create-yoya-ui@latest my-app --template admin # admin console template (top nav + collapsible sidebar + RouterViews)
+# Install the scaffold
+npm install -g create-yoya-ui
+
+# Create a project with the admin template
+create-yoya-ui my-app --template admin
 cd my-app
 npm install
-npm run dev          # basic / admin: dev server
-# SSR: npm run build && npm start
+npm run dev
 ```
 
-`--template admin` scaffolds a standard admin console: top navigation, collapsible sidebar and a titled RouterViews content area, with feature examples for dashboard (data boards & charts), member / role / permission management, and dictionary management (type table with an item editor dialog).
+`--template admin` scaffolds a standard admin console: top navigation, sidebar and a titled RouterViews content area, with feature examples for dashboard (data boards & charts), member / role / permission management, and dictionary management (type table with an item editor dialog).
+
+yoya-ui has its own unique development paradigm — declarative node DSL, page composition, and feature-module organization. The admin template is the recommended way to get familiar with it: it demonstrates the full stack of a real admin console (shell, routing, tables / forms / dialogs, dashboard boards & charts) using the library's idiomatic patterns.
 
 ### Install into an existing project
 
@@ -82,24 +85,42 @@ The page only needs a `<div id="app"></div>` loaded with a module script.
 
 ## Server-Side Rendering (SSR)
 
-The same page factory switches between server rendering and client rendering:
+The same page factory switches between server rendering and client rendering. For a full page, use the high-level entry points — `renderPage` builds a complete HTML document (head/body in DSL) and `hydrateOrMount` bootstraps the client in one call:
 
 ```js
-// Server
-import { renderToString } from '@yoyaflow/yoya-ui/ssr';
-const { html, state } = renderToString(createPage, { state: { path: '/home' } });
-
-// Client
-import { hydrate, mount, parseState } from '@yoyaflow/yoya-ui/ssr';
-const data = parseState(document.getElementById('__YOYA_DATA__').textContent);
-const app = document.getElementById('app');
-if (app.firstElementChild) {
-  hydrate(createPage, app, data); // Server HTML exists: adopt DOM, bind events
-} else {
-  mount(createPage, app, data); // Empty shell: full client render
-}
+// Server — render a complete HTML document per request
+import { renderPage } from '@yoyaflow/yoya-ui/ssr';
+import { HomePage, messages } from './home-page.js';
+
+const html = renderPage(
+  {
+    page: (page, state) => {
+      page.head((head) => {
+        head.title('SSR Example'.s('title'));
+        head.meta({ charset: 'utf-8' });
+        head.link({ rel: 'stylesheet', href: '/assets/yoya.ui.css' });
+      });
+      page.body((body) => {
+        body.vBody((shell) => {
+          shell.child(HomePage(state)); // state = { lang, path, mode }
+        });
+      });
+    }
+  },
+  { lang, mode: 'history', path },
+  { messages } // per-request i18n; .s() is scoped automatically
+);
+
+// Client — reads __YOYA_DATA__; hydrates when server HTML exists, otherwise mounts
+import '@yoyaflow/yoya-ui/ui.css';
+import { hydrateOrMount } from '@yoyaflow/yoya-ui/ssr';
+import { HomePage, messages } from './home-page.js';
+
+hydrateOrMount(HomePage, { messages });
 ```
 
+Lower-level primitives (`renderToString` / `serializeState` / `parseState` / `mount` / `hydrate`) remain available for fine-grained control, e.g. embedding an HTML fragment into your own server template.
+
 Key points:
 
 - `vClientOnly(loader)`: non-SSR modules (e.g. ECharts) emit a placeholder on the server and load on the client after hydration
@@ -107,7 +128,7 @@ Key points:
 - Per-request i18n instance, render-context id allocator, auto-destroy after render — the server stays stateless
 - `maxNodes` falls back to client rendering automatically when exceeded
 
-Full integration guide: [docs/ssr.md](docs/ssr.md) (Chinese); runnable example:
+Full integration guide: [docs/ssr.md](docs/ssr.md) (Chinese). Or run the in-repo example:
 
 ```bash
 npm run build
@@ -120,7 +141,7 @@ node src/examples/ssr/server-http.mjs
 import { div, svg, createI18n } from '@yoyaflow/yoya-ui/core'; // core HTML/SVG/state
 import { vButton, vCard, vForm, vTable } from '@yoyaflow/yoya-ui/ui'; // official component library
 import { vEchart } from '@yoyaflow/yoya-ui/echart'; // ECharts component (bring your own echarts)
-import { renderToString, hydrate } from '@yoyaflow/yoya-ui/ssr'; // server-side rendering
+import { renderPage, hydrateOrMount } from '@yoyaflow/yoya-ui/ssr'; // server-side rendering
 import '@yoyaflow/yoya-ui/ui.css'; // default styles and theme variables
 ```
 
@@ -133,7 +154,7 @@ TypeScript projects get hints and type checking with no extra configuration:
 ```ts
 import { div, vButton, vCard, vTable, toast } from '@yoyaflow/yoya-ui';
 import { createI18n } from '@yoyaflow/yoya-ui/core';
-import { renderToString } from '@yoyaflow/yoya-ui/ssr';
+import { renderPage } from '@yoyaflow/yoya-ui/ssr';
 import '@yoyaflow/yoya-ui/ui.css';
 
 div((page) => {
@@ -189,7 +210,7 @@ npm run build
 
 - `yoya.core.js` / `yoya.ui.js` — core and component library ESM entries
 - `yoya.echart.js` — ECharts component entry (does not bundle echarts itself)
-- `yoya.ssr.js` — server rendering entry (`renderToString` / `hydrate` / `mount`)
+- `yoya.ssr.js` — server rendering entry (`renderPage` / `hydrateOrMount` / `renderToString` / `hydrate` / `mount`)
 - `echarts.min.js` — ECharts core (load globally via `<script>`)
 - `yoya.ui.css` — default styles and theme variables
 - `yoya-ui.umd.js` — UMD build (`window.YoyaUI`)

package/README.zh-CN.md

@@ -45,19 +45,22 @@ function HelloWorldExampleI18n() {
 
 ## 安装
 
-### 脚手架快速搭建
+### 快速体验
 
 ```bash
-npx create-yoya-ui@latest my-app                 # basic 模板（SPA）
-npx create-yoya-ui@latest my-app --template ssr  # SSR 模板（renderPage + hydrateOrMount）
-npx create-yoya-ui@latest my-app --template admin # admin 后台管理模板（顶部导航 + 可折叠侧栏 + RouterViews）
+# 安装脚手架
+npm install -g create-yoya-ui
+
+# 使用 admin 模板创建项目
+create-yoya-ui my-app --template admin
 cd my-app
 npm install
-npm run dev          # basic / admin：开发服务器
-# SSR：npm run build && npm start
+npm run dev
 ```
 
-`--template admin` 生成标准后台管理模板：顶部导航 + 可折叠侧栏 + 带标题的 RouterViews 内容区，内置数据概览看板与图表，以及成员 / 角色 / 权限 / 字典管理等业务域示例。
+`--template admin` 生成标准后台管理模板：顶部导航 + 左侧菜单 + 带标题的 RouterViews 内容区，内置数据概览看板与图表，以及成员 / 角色 / 权限 / 字典管理等业务域示例。
+
+yoya-ui 拥有自己独特的开发范式：声明式节点 DSL、页面编排与 feature 模块组织。推荐使用 admin 模板创建项目来了解这些范式——它用库的原生写法完整展示了一个真实后台（页面壳、路由、表格/表单/弹窗、数据看板与图表）。
 
 ### 已有项目引入
 
@@ -83,24 +86,42 @@ div((page) => {
 
 ## 服务端渲染（SSR）
 
-同一份页面工厂代码，服务端渲染与客户端渲染可切换：
+同一份页面工厂代码，服务端渲染与客户端渲染可切换。整页场景直接使用高层入口：`renderPage` 输出完整 HTML 文档（head/body 用 DSL 定义），`hydrateOrMount` 一行完成客户端接入：
 
 ```js
-// 服务端
-import { renderToString } from '@yoyaflow/yoya-ui/ssr';
-const { html, state } = renderToString(createPage, { state: { path: '/home' } });
-
-// 客户端
-import { hydrate, mount, parseState } from '@yoyaflow/yoya-ui/ssr';
-const data = parseState(document.getElementById('__YOYA_DATA__').textContent);
-const app = document.getElementById('app');
-if (app.firstElementChild) {
-  hydrate(createPage, app, data); // 有服务端 HTML：收养 DOM、绑定事件
-} else {
-  mount(createPage, app, data); // 空壳：全量客户端渲染
-}
+// 服务端：按请求渲染完整 HTML 文档
+import { renderPage } from '@yoyaflow/yoya-ui/ssr';
+import { HomePage, messages } from './home-page.js';
+
+const html = renderPage(
+  {
+    page: (page, state) => {
+      page.head((head) => {
+        head.title('SSR 示例'.s('title'));
+        head.meta({ charset: 'utf-8' });
+        head.link({ rel: 'stylesheet', href: '/assets/yoya.ui.css' });
+      });
+      page.body((body) => {
+        body.vBody((shell) => {
+          shell.child(HomePage(state)); // state = { lang, path, mode }
+        });
+      });
+    }
+  },
+  { lang, mode: 'history', path },
+  { messages } // 每请求 i18n，.s() 自动作用域
+);
+
+// 客户端：自动读取 __YOYA_DATA__，有服务端 HTML 走 hydrate，否则 mount
+import '@yoyaflow/yoya-ui/ui.css';
+import { hydrateOrMount } from '@yoyaflow/yoya-ui/ssr';
+import { HomePage, messages } from './home-page.js';
+
+hydrateOrMount(HomePage, { messages });
 ```
 
+底层原语（`renderToString` / `serializeState` / `parseState` / `mount` / `hydrate`）仍然可用，适合需要细粒度控制的场景，例如把 HTML 片段嵌入自有服务端模板。
+
 要点：
 
 - `vClientOnly(loader)`：非 SSR 模块（如 ECharts）服务端只出占位，hydration 后客户端加载
@@ -108,7 +129,7 @@ if (app.firstElementChild) {
 - 每请求 i18n 实例、渲染上下文 id 分配器、渲染后自动销毁——服务端保持无状态
 - `maxNodes` 超限自动回退客户端渲染
 
-完整集成指南见 [docs/ssr.md](docs/ssr.md)；可运行示例：
+完整集成指南见 [docs/ssr.md](docs/ssr.md)。或运行仓库内示例：
 
 ```bash
 npm run build
@@ -121,7 +142,7 @@ node src/examples/ssr/server-http.mjs
 import { div, svg, createI18n } from '@yoyaflow/yoya-ui/core'; // 核心 HTML/SVG/状态
 import { vButton, vCard, vForm, vTable } from '@yoyaflow/yoya-ui/ui'; // 官方组件库
 import { vEchart } from '@yoyaflow/yoya-ui/echart'; // ECharts 组件（需自行引入 echarts）
-import { renderToString, hydrate } from '@yoyaflow/yoya-ui/ssr'; // 服务端渲染
+import { renderPage, hydrateOrMount } from '@yoyaflow/yoya-ui/ssr'; // 服务端渲染
 import '@yoyaflow/yoya-ui/ui.css'; // 默认样式与主题变量
 ```
 
@@ -134,7 +155,7 @@ TypeScript 项目无需额外配置即可获得提示与类型检查：
 ```ts
 import { div, vButton, vCard, vTable, toast } from '@yoyaflow/yoya-ui';
 import { createI18n } from '@yoyaflow/yoya-ui/core';
-import { renderToString } from '@yoyaflow/yoya-ui/ssr';
+import { renderPage } from '@yoyaflow/yoya-ui/ssr';
 import '@yoyaflow/yoya-ui/ui.css';
 
 div((page) => {
@@ -190,7 +211,7 @@ npm run build
 
 - `yoya.core.js` / `yoya.ui.js` — 核心与组件库 ESM 入口
 - `yoya.echart.js` — ECharts 组件入口（不包含 echarts 本体）
-- `yoya.ssr.js` — 服务端渲染入口（`renderToString` / `hydrate` / `mount`）
+- `yoya.ssr.js` — 服务端渲染入口（`renderPage` / `hydrateOrMount` / `renderToString` / `hydrate` / `mount`）
 - `echarts.min.js` — ECharts 本体（用 `<script>` 标签全局引入）
 - `yoya.ui.css` — 默认样式与主题变量
 - `yoya-ui.umd.js` — UMD 版（`window.YoyaUI`）