weifuwu 0.85.0 → 0.87.0

package/examples/apps/auth/server.ts

@@ -0,0 +1,37 @@
+/**
+ * auth 独立 server——内存用户 + 会话（契约层：生产换 postgres() + userSystem）
+ *   cd examples/apps/auth && node server.ts → http://localhost:3301
+ */
+import { serve, Router, ui, createMemorySql } from 'weifuwu'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerAuthApi, ensureAuthTables } from './api.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const sql = createMemorySql()
+await ensureAuthTables(sql)
+
+const app = new Router()
+app.use(ui())
+app.get('/app.js', (req, ctx) => ctx.ui.js(resolve(__dirname, 'main.tsx')))
+registerAuthApi(app, sql)
+
+app.get('/*', async (req, ctx) => ctx.ui.html`
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="/components.css">
+  <title>auth 应用模板</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="/app.js"></script>
+</body>
+</html>
+`)
+app.get('/components.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+serve(app, { port: 3301 })
+console.log('auth 模板 → http://localhost:3301')

package/examples/apps/multi/README.md

@@ -0,0 +1,23 @@
+# multi 应用模板（复制即用）
+
+```bash
+# 1. 安装依赖（weifuwu 包——含 content/ 离线文档 + examples/ 模板源码）
+npm i weifuwu
+
+# 2. 复制本目录到你的项目（或直接在 examples/apps/multi 内开发）
+# 3. 启动
+node server.ts    # → http://localhost:multi/3300 3301 3302 3303
+```
+
+## 改造指南
+
+见 `node_modules/weifuwu/content/apps/multi.md`（目录结构 + 逐步改造步骤）。
+
+## 结构
+
+| 文件 | 职责 |
+|------|------|
+| app.tsx | 前端：路由表 + 页面组件 + 状态 |
+| api.ts | 后端：API 注册函数（独立/嵌入共享） |
+| server.ts | 独立入口（MemorySql——生产换 postgres() 一行） |
+| main.tsx | 独立前端入口 |

package/examples/apps/multi/app.tsx

@@ -0,0 +1,83 @@
+/**
+ * multi 应用模板——应用编排（父应用嵌子应用：registerApp/hApp + 独立状态）
+ *
+ * 演示能力（design/vdom3-app-node.md）：
+ *   - registerApp 注册子应用（工厂闭包持有实例状态——appId 复用不重跑）
+ *   - hApp（<App appId />）在父树渲染子应用——app:mount/update 边界事件
+ *   - 子应用独立状态：各自 let + render()，互不干扰
+ * 纯前端编排——无后端（模板结构最简形态：app.tsx + server.ts + main.tsx）
+ */
+import { UIRouter, uiServe, h, createClientBrowser } from 'weifuwu/vdom'
+import type { Component } from 'weifuwu/vdom'
+import { Button, Input, Tag, PageHeader, Space } from 'weifuwu/components'
+
+// ── 子应用 1：计数器（独立状态） ──
+const Counter = async (_init: any, ctx: any) => {
+    let count = 0
+    let step = 1
+    return async (_p: any) => (
+      <div class="wf-stack wf-gap-sm">
+        <Space align="center"><Tag variant="primary">子应用 1</Tag><b>{count}</b></Space>
+        <div class="wf-row wf-gap-xs">
+          <Button size="sm" onClick={() => { count -= step; ctx.render() }}>-{step}</Button>
+          <Button size="sm" variant="primary" onClick={() => { count += step; ctx.render() }}>+{step}</Button>
+          <Button size="sm" variant="ghost" onClick={() => { step = step === 1 ? 5 : 1; ctx.render() }}>步长 {step}→{step === 1 ? 5 : 1}</Button>
+        </div>
+      </div>
+    )
+  }
+
+// ── 子应用 2：迷你任务（独立状态——与计数器互不干扰） ──
+const MiniTodo = async (_init: any, ctx: any) => {
+    let items: string[] = ['子应用任务 A', '子应用任务 B']
+    let input = ''
+    return async (_p: any) => (
+      <div class="wf-stack wf-gap-sm">
+        <Tag variant="success">子应用 2</Tag>
+        <div class="wf-row wf-gap-xs">
+          <input class="wf-input" style="flex:1" value={input}
+            onInput={(e: any) => { input = (e.target as HTMLInputElement).value; ctx.render() }}
+            placeholder="新任务…" />
+          <Button size="sm" onClick={() => { if (input.trim()) { items.push(input.trim()); input = ''; ctx.render() } }}>添加</Button>
+        </div>
+        <ul style="margin:0;padding-left:16px">
+          {items.map((it, i) => <li key={it + i} class="wf-text-sm">{it}</li>)}
+        </ul>
+      </div>
+    )
+  }
+
+// ── 父应用：工作台（嵌入子应用 + 边界事件观测） ──
+export const WorkbenchPage: Component = async (_init: any, ctx: any) => {
+  return async (_p: any) => (
+    <div class="wf-stack wf-gap-md">
+      <PageHeader title="应用编排工作台" sub="父应用嵌入子应用——registerApp 注册 · <App appId /> 渲染 · 独立状态" />
+      <div class="wf-grid" style="--wf-cols:repeat(auto-fit,minmax(240px,1fr));--wf-gap:12px">
+        <div class="wf-surface wf-border wf-rounded-md wf-p-md wf-stack wf-gap-sm">
+          <b class="wf-text-sm">计数器（子应用 1）</b>
+          {h(Counter, {})}
+        </div>
+        <div class="wf-surface wf-border wf-rounded-md wf-p-md wf-stack wf-gap-sm">
+          <b class="wf-text-sm">迷你任务（子应用 2）</b>
+          {h(MiniTodo, {})}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export const multiRoutes = [
+  { path: '/', render: () => h(WorkbenchPage, {}) },
+]
+
+export const pathFromHash = (): string => location.hash.replace(/^#/, '') || '/'
+
+export function createMultiApp(root: HTMLElement, _options?: { history?: boolean }): ReturnType<typeof uiServe> {
+  // vdom 规范面：UIRouter + uiServe——布局共享精准路由
+  const router = new UIRouter()
+  for (const r of multiRoutes) {
+    router.get(r.path, (req: Request, ctx: any) =>
+      (ctx as { stream: (v: unknown) => Response }).stream(r.render()))
+  }
+  return uiServe(router, { root, browser: createClientBrowser()! })
+}

package/examples/apps/multi/main.tsx

@@ -0,0 +1,8 @@
+/**
+ * multi 独立入口——复制本目录即可运行：
+ *   cd examples/apps/multi && node server.ts → http://localhost:3303
+ */
+import { createMultiApp, pathFromHash } from './app.tsx'
+
+const sub = createMultiApp(document.querySelector('#root') as HTMLElement)
+window.addEventListener('hashchange', () => sub.navigate(pathFromHash()))

package/examples/apps/multi/server.ts

@@ -0,0 +1,33 @@
+/**
+ * multi 独立 server——纯前端编排（无后端 API）
+ *   cd examples/apps/multi && node server.ts → http://localhost:3303
+ */
+import { serve, Router, ui } from 'weifuwu'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const app = new Router()
+app.use(ui())
+app.get('/app.js', (req, ctx) => ctx.ui.js(resolve(__dirname, 'main.tsx')))
+
+app.get('/*', async (req, ctx) => ctx.ui.html`
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="/components.css">
+  <title>multi 应用模板</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="/app.js"></script>
+</body>
+</html>
+`)
+app.get('/components.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+serve(app, { port: 3303 })
+console.log('multi 模板 → http://localhost:3303')

package/examples/apps/todo/README.md

@@ -0,0 +1,23 @@
+# todo 应用模板（复制即用）
+
+```bash
+# 1. 安装依赖（weifuwu 包——含 content/ 离线文档 + examples/ 模板源码）
+npm i weifuwu
+
+# 2. 复制本目录到你的项目（或直接在 examples/apps/todo 内开发）
+# 3. 启动
+node server.ts    # → http://localhost:todo/3300 3301 3302 3303
+```
+
+## 改造指南
+
+见 `node_modules/weifuwu/content/apps/todo.md`（目录结构 + 逐步改造步骤）。
+
+## 结构
+
+| 文件 | 职责 |
+|------|------|
+| app.tsx | 前端：路由表 + 页面组件 + 状态 |
+| api.ts | 后端：API 注册函数（独立/嵌入共享） |
+| server.ts | 独立入口（MemorySql——生产换 postgres() 一行） |
+| main.tsx | 独立前端入口 |

package/examples/apps/todo/api.ts

@@ -0,0 +1,26 @@
+/**
+ * todo 后端 API——可复用注册函数（独立 server 与 showcase 嵌入共享同一实现）
+ * 契约：registerTodoApi(app, sql)——sql 为 Sql 契约（MemorySql/postgres 均可）
+ */
+import type { Router } from 'weifuwu'
+
+export function registerTodoApi(app: Router, sql: any): void {
+  app.get('/api/todos', async () => {
+    const rows = await sql`SELECT * FROM todos ORDER BY id DESC`
+    return Response.json({ rows })
+  })
+  app.post('/api/todos', async (req: Request) => {
+    const { name } = await req.json()
+    const rows = await sql`INSERT INTO todos (name) VALUES (${String(name)}) RETURNING id, name, done`
+    return Response.json({ row: rows[0] }, { status: 201 })
+  })
+  app.patch('/api/todos/:id', async (req: Request, ctx: any) => {
+    const { done } = await req.json()
+    await sql`UPDATE todos SET done = ${!!done} WHERE id = ${Number((ctx as any).params.id)}`
+    return Response.json({ ok: true })
+  })
+  app.delete('/api/todos/:id', async (req: Request, ctx: any) => {
+    await sql`DELETE FROM todos WHERE id = ${Number((ctx as any).params.id)}`
+    return Response.json({ ok: true })
+  })
+}

package/examples/apps/todo/app.tsx

@@ -0,0 +1,128 @@
+/**
+ * todo 应用模板——完整全栈（复制即用，随 npm 包发布 examples/apps/todo/）
+ *
+ * 演示（design/showcase-plan.md §P2）：
+ *   - 多页路由（/ 列表 + /new 新建）+ createStore 跨页状态
+ *   - 后端：MemorySql 持久化（契约层——生产换 postgres() 一行）
+ *   - 嵌入方式：createRouter(routes, root, { history: false })——showcase 页面内嵌
+ */
+import { UIRouter, uiServe, h, createStore, createClientBrowser } from 'weifuwu/vdom'
+import type { Component } from 'weifuwu/vdom'
+import { Button, Input, Checkbox, Tag, EmptyState, PageHeader, Form, Field, Alert } from 'weifuwu/components'
+
+export interface Todo {
+  id: string
+  name: string
+  done: boolean
+}
+
+export const todoStore = createStore<{ todos: Todo[]; loading: boolean; error: string | null }>({
+  todos: [],
+  loading: true,
+  error: null,
+})
+
+export async function loadTodos(): Promise<void> {
+  todoStore.update((s) => { s.loading = true; s.error = null })
+  try {
+    const res = await fetch('/api/todos')
+    const data = await res.json()
+    todoStore.update((s) => { s.todos = data.rows; s.loading = false })
+  } catch (e) {
+    todoStore.update((s) => { s.error = (e as Error).message; s.loading = false })
+  }
+}
+
+/** 列表页 */
+export const TodoList: Component = async (_init: any, ctx: any) => {
+  void loadTodos()
+  const state = ctx.ui.useExternal(todoStore)
+  const toggle = async (t: Todo) => {
+    await fetch(`/api/todos/${t.id}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ done: !t.done }) })
+    await loadTodos()
+  }
+  const del = async (t: Todo) => {
+    await fetch(`/api/todos/${t.id}`, { method: 'DELETE' })
+    await loadTodos()
+  }
+  return async (_p: any) => (
+    <div class="wf-stack wf-gap-md">
+      <PageHeader title="任务列表" sub={`${state.todos.filter((t: Todo) => !t.done).length} 个未完成`}>
+        <Button variant="primary" onClick={() => location.hash = '#/new'}>新建任务</Button>
+      </PageHeader>
+      {state.error && <Alert variant="error">{state.error}</Alert>}
+      {state.loading && <div class="wf-text-secondary">加载中…</div>}
+      {!state.loading && state.todos.length === 0 && <EmptyState text="暂无任务——点击「新建任务」开始" />}
+      <div class="wf-stack wf-gap-xs">
+        {state.todos.map((t: Todo) => (
+          <div key={t.id} class="wf-surface wf-border wf-rounded-sm wf-p-sm wf-row wf-between">
+            <div class="wf-row wf-gap-sm">
+              <Checkbox checked={t.done} onChange={() => void toggle(t)} />
+              <span class={t.done ? 'wf-text-tertiary' : ''} style={t.done ? 'text-decoration:line-through' : ''}>{t.name}</span>
+            </div>
+            <div class="wf-row wf-gap-xs">
+              {t.done && <Tag variant="success">完成</Tag>}
+              <Button size="sm" variant="ghost" onClick={() => void del(t)}>删除</Button>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+/** 新建页 */
+export const TodoNew: Component = async (_init: any, ctx: any) => {
+  let name = ''
+  let error = ''
+  let saving = false
+  const submit = async () => {
+    if (!name.trim()) { error = '任务名不能为空'; ctx.render(); return }
+    saving = true; error = ''; ctx.render()
+    try {
+      await fetch('/api/todos', {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: name.trim() }),
+      })
+      await loadTodos()
+      location.hash = '#/'
+    } catch (e) {
+      error = (e as Error).message; saving = false; ctx.render()
+    }
+  }
+  return async (_p: any) => (
+    <div class="wf-stack wf-gap-md" style="max-width:480px">
+      <PageHeader title="新建任务" sub="填写任务名称——提交后写入 MemorySql" />
+      <Form onSubmit={() => void submit()}>
+        <Field label="任务名称" error={error}>
+          <Input value={name} onInput={(e: any) => { name = (e.target as HTMLInputElement).value; ctx.render() }}
+            placeholder="例如：完成 showcase Phase 2" autoFocus />
+        </Field>
+        <div class="wf-row wf-gap-sm">
+          <Button variant="primary" loading={saving} onClick={() => void submit()}>保存</Button>
+          <Button variant="ghost" onClick={() => location.hash = '#/'}>取消</Button>
+        </div>
+      </Form>
+    </div>
+  )
+}
+
+// ── 路由表（layout 包裹 + 参数——模板可复制部分） ──
+export const todoRoutes = [
+  { path: '/', render: () => h(TodoList, {}) },
+  { path: '/new', render: () => h(TodoNew, {}) },
+]
+
+/** hash → 内部路径（模板导航约定：location.hash = '#/new'——独立运行可深链/嵌入不污染宿主 pathname） */
+export const pathFromHash = (): string => location.hash.replace(/^#/, '') || '/'
+
+/** 应用入口：createTodoApp(root)——独立运行（main.tsx）与嵌入（showcase）复用 */
+export function createTodoApp(root: HTMLElement, _options?: { history?: boolean }): ReturnType<typeof uiServe> {
+  // vdom 规范面：UIRouter + uiServe——布局共享精准路由
+  const router = new UIRouter()
+  for (const r of todoRoutes) {
+    router.get(r.path, (req: Request, ctx: any) =>
+      (ctx as { stream: (v: unknown) => Response }).stream(r.render()))
+  }
+  return uiServe(router, { root, browser: createClientBrowser()! })
+}

package/examples/apps/todo/main.tsx

@@ -0,0 +1,9 @@
+/**
+ * todo 应用模板独立入口——复制本目录即可运行：
+ *   cd examples/apps/todo && node server.ts → http://localhost:3300
+ * hash 桥接：hashchange → 内部路由（独立运行可深链 #/new）
+ */
+import { createTodoApp, pathFromHash } from './app.tsx'
+
+const sub = createTodoApp(document.querySelector('#root') as HTMLElement)
+window.addEventListener('hashchange', () => sub.navigate(pathFromHash()))

package/examples/apps/todo/server.ts

@@ -0,0 +1,39 @@
+/**
+ * todo 后端——MemorySql CRUD（契约层：演示用内存实现——生产换 postgres() 一行）
+ * 独立运行：node server.ts → http://localhost:3300
+ */
+import { serve, Router, ui, createMemorySql } from 'weifuwu'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerTodoApi } from './api.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const sql = createMemorySql()
+
+await sql.unsafe('CREATE TABLE IF NOT EXISTS todos (id serial PRIMARY KEY, name text, done boolean DEFAULT false)')
+
+const app = new Router()
+app.use(ui())
+app.get('/app.js', (req, ctx) => ctx.ui.js(resolve(__dirname, 'main.tsx')))
+
+registerTodoApi(app, sql)
+
+app.get('/*', async (req, ctx) => ctx.ui.html`
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="/components.css">
+  <title>todo 应用模板</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="/app.js"></script>
+</body>
+</html>
+`)
+app.get('/components.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+serve(app, { port: 3300 })
+console.log('todo 模板 → http://localhost:3300')

package/examples/hello-world/README.md

@@ -0,0 +1,9 @@
+# hello-world 最小起步项目
+
+```bash
+npm i weifuwu
+node server.ts    # → http://localhost:3400
+```
+
+三文件：server.ts（后端）+ routes.tsx（路由/组件）+ client.ts（前端入口）。
+改造：加页面 → routes.tsx 路由表加一行；加数据 → server.ts 加 /api 端点（组件用 ctx.data 读取）。

package/examples/hello-world/client.ts

@@ -0,0 +1,14 @@
+/**
+ * client.ts——客户端入口（纯 SPA 渲染：vdom3 事件流引擎）
+ * createRouter(routes, root) —— 监听 location → 匹配 → 事件流渲染
+ */
+import { UIRouter, uiServe } from 'weifuwu/vdom'
+import { routes } from './routes.tsx'
+
+// 路由声明 → UIRouter（get 挂载）→ uiServe 渲染（vdom 规范面）
+const router = new UIRouter()
+for (const r of routes) {
+  router.get(r.path, (req: Request, ctx: any) =>
+    (ctx as { stream: (v: unknown) => Response }).stream(r.render()))
+}
+uiServe(router, { root: document.querySelector('#root') as HTMLElement })

package/examples/hello-world/routes.tsx

@@ -0,0 +1,26 @@
+/**
+ * routes.tsx——路由声明（两阶段异步组件）
+ *
+ * 新手必读（概念见 content/guides/component-model.md）：
+ * - 外层 async 工厂 = mount（只一次）：await 数据 / 初始化状态
+ * - 内层 async renderFn = 每次渲染：读最新 props / 输出视图
+ * - 状态 = 普通对象 let + 改后 ctx.render()（render-only）
+ */
+import { h } from 'weifuwu/vdom'
+
+// 两阶段异步组件：工厂层 await 数据（ctx.data——缓存 + 并发合并）
+const Home = async (_init: any, ctx: any) => {
+  const data = await ctx.data.get('/api/hello')
+  let count = 0 // 组件状态（render-only）
+  return async (_props: any) =>
+    h('div', { class: 'wf-container wf-stack', style: '--wf-max:640px;--wf-gap:16px;padding:40px 16px;text-align:center' },
+      h('h1', { class: 'wf-text-3xl wf-m-0' }, 'weifuwu hello-world'),
+      h('p', { class: 'wf-text-secondary' }, `数据管道：${(data as any).msg}`),
+      h('button', {
+        class: 'wf-btn wf-btn--primary',
+        onClick: () => { count++; ctx.render() }, // 改状态 → 显式 render()
+      }, `点击 ${count} 次`),
+    )
+}
+
+export const routes = [{ path: '/', render: () => h(Home, {}) }]

package/examples/hello-world/server.ts

@@ -0,0 +1,46 @@
+/**
+ * hello-world——最小可运行起步项目（新手第一步，复制本目录即跑）
+ *
+ * 与 README「快速开始」模式 A 对应——三文件落地版：
+ *   server.ts   后端：SPA 外壳 + /api/hello 数据端点
+ *   routes.tsx  路由声明：两阶段异步组件（await ctx.data → 返回视图）
+ *   client.ts   客户端入口：createRouter 接管渲染
+ *
+ * 跑起来：node server.ts → http://localhost:3400
+ */
+import { serve, Router, ui, cors } from 'weifuwu'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const router = new Router()
+router.use(cors())
+router.use(ui()) // 注入 ctx.ui.html / ctx.ui.js / ctx.ui.css
+
+// SPA 外壳（空 root + 前端 bundle）
+router.get('/', (req, ctx) => ctx.ui.html`
+  <!doctype html>
+  <html>
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="/components.css">
+    <title>weifuwu hello-world</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="/static/app.js"></script>
+  </body>
+  </html>
+`)
+router.get('/static/app.js', (req, ctx) => ctx.ui.js(resolve(__dirname, 'client.ts')))
+
+// 样式自托管（node_modules/weifuwu/components/style.css——包内 CSS，零外部依赖/CDN）
+router.get('/components.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+// 数据端点（ctx.data 消费——SPA 下真 fetch，SSR 下服务端直取）
+router.get('/api/hello', () => Response.json({ msg: '你好，weifuwu！' }))
+
+serve(router, { port: 3400 })
+console.log('hello-world → http://localhost:3400')