diff --git a/crates/marqdo-wasm/js/marqdo-bridge.js b/crates/marqdo-wasm/js/marqdo-bridge.js index 631aa59..2c847d8 100644 --- a/crates/marqdo-wasm/js/marqdo-bridge.js +++ b/crates/marqdo-wasm/js/marqdo-bridge.js @@ -921,8 +921,23 @@ function runIntervalEffect(exports, spec, onError) { intervalHandles.set(id, handle); } +const memoryKV = new Map(); + function storageStore(scope) { if (scope === "cookie") return null; + if (scope === "memory" || scope === "mem" || scope === "内存") { + return { + getItem(key) { + return memoryKV.has(key) ? memoryKV.get(key) : null; + }, + setItem(key, value) { + memoryKV.set(key, String(value)); + }, + removeItem(key) { + memoryKV.delete(key); + }, + }; + } if (typeof localStorage === "undefined") return null; return scope === "session" ? sessionStorage : localStorage; } diff --git a/doc/design/ext-web-spa.md b/doc/design/ext-web-spa.md new file mode 100644 index 0000000..e0b97d0 --- /dev/null +++ b/doc/design/ext-web-spa.md @@ -0,0 +1,24 @@ +# Native SPA(Marqdo WASM 全页客户端) + +| | | +|---|---| +| 状态 | **Accepted · MVP** | +| 日期 | 2026-09-17 | +| 相关 | [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · route D/E | + +## 约定 + +| 表 | 列 | 用途 | +|----|-----|------| +| 客户端路由 | `路径` / `面板` / `标题` | 文档化视图;运行时用 `path` + `set_attr(hidden)` 切换 | +| 客户端状态 | `browser.store_set` / `store_get` `scope=memory` | 页内状态(列表 JSON、当前 id) | + +作者零业务 JS:`web.client_embed` + `static/client.mq.md` + `lib/browser`。 + +## Bridge + +`storage` effect 支持 `scope=memory`(进程内 `Map`),与 `local` / `session` / `cookie` 并列。 + +## Demo + +`examples/web-spa-app/` — 列表 → 详情 → 编辑,全客户端路由。 diff --git a/doc/design/ext-web.md b/doc/design/ext-web.md index ef63898..e693255 100644 --- a/doc/design/ext-web.md +++ b/doc/design/ext-web.md @@ -581,6 +581,7 @@ submit → action=insert → db.insert;action=update → db.update - Postgres / Redis / S3 驱动细节(SQLite 已落地); - ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`); +- ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory); - 子页路由糖的更多约定(`# 应用.route` 已够用)。 --- diff --git a/examples/web-spa-app/README.md b/examples/web-spa-app/README.md new file mode 100644 index 0000000..f1441db --- /dev/null +++ b/examples/web-spa-app/README.md @@ -0,0 +1,14 @@ +# web-spa-app + +Marqdo **native SPA**: list → detail → edit with client routes + `scope=memory` store. Zero author JS. + +## Run + +```bash +marqdo wasm build -o examples/web-spa-app/static +cd examples/web-spa-app +marqdo run index.mq.md +# http://127.0.0.1:18093 +``` + +Design: [ext-web-spa.md](../../doc/design/ext-web-spa.md). diff --git a/examples/web-spa-app/index.mq.md b/examples/web-spa-app/index.mq.md new file mode 100644 index 0000000..443f74f --- /dev/null +++ b/examples/web-spa-app/index.mq.md @@ -0,0 +1,23 @@ +--- +title: web-spa-app +description: Native Marqdo SPA — list/detail/edit via WASM client routes + memory store +import web:ext/web/web.mq.md +--- + +# main + +Full-page client app (zero author JS). Build assets first: + +``` +marqdo wasm build -o examples/web-spa-app/static +``` + +**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True** + +**`intro` = "

Items

Click an item for detail.

" + embed**
+
+**page = > web.page title="Marqdo SPA" intro=intro layout="bare"**
+**app = > web.app page=page host="127.0.0.1" port=18093**
+**app = > app.static dir="static" mount="/static"**
+**app = > app.redirect from="/item" to="/" permanent=False**
+> `app`.listen
diff --git a/examples/web-spa-app/static/client.mq.md b/examples/web-spa-app/static/client.mq.md
new file mode 100644
index 0000000..4697f8f
--- /dev/null
+++ b/examples/web-spa-app/static/client.mq.md
@@ -0,0 +1,174 @@
+---
+title: spa client
+description: routes table + memory store; list / detail / edit
+import browser:lib/browser.mq.md
+import table:lib/table.mq.md
+import text:lib/text.mq.md
+---
+
+# main
+
+Routes (documentation + titles). Runtime switches panels by `path`.
+
+`routes` =
+
+| @ | 路径 | 面板 | 标题 |
+|---|------|------|------|
+| 1 | / | #view-list | Items |
+| 2 | /item | #view-detail | Detail |
+| 3 | /edit | #view-edit | Edit |
+
+**`path` = "/"**
+**`cur_id` = ""**
+**`items` = "Alpha\nBeta"**
+
+`wire` =
+
+| @ | 选择器 | 事件 | 调用 | 委托 | 值选择器 |
+|---|--------|------|------|------|----------|
+| 1 | "#nav-list" | click | go_list | | |
+| 2 | "#nav-new" | click | go_new | | |
+| 3 | "#items" | click | open_item | "li[data-id]" | |
+| 4 | "#btn-edit" | click | go_edit | | |
+| 5 | "#btn-back" | click | go_list | | |
+| 6 | "#btn-save" | click | save_item | | "#edit-title" |
+| 7 | "#btn-cancel" | click | go_list | | |
+| 8 | "window" | popstate | on_pop | | |
+
+`seed` =
+
+| op | key | value | scope |
+|----|-----|-------|-------|
+| set | spa-items | `items` | memory |
+
+**`w` = > table.put in=None at="wire" value=wire**
+**`s` = > browser.storage spec=seed**
+**`boot` = > browser.merge a=w b=s**
+**`ready` = > browser.set_text sel="#log" text="spa ready — click Items"**
+*> browser.merge a=boot b=ready*
+
+## on_pop
+    + `path`=""
+
+1. `path` != ""
+    **`path` = path**
+2. *
+    ****
+*> spa_render*
+
+## go_list
+**`path` = "/"**
+**`cur_id` = ""**
+*> spa_render*
+
+## go_new
+**`path` = "/edit"**
+**`cur_id` = ""**
+*> spa_render*
+
+## go_edit
+**`path` = "/edit"**
+*> spa_render*
+
+## open_item
+    + `data_id`=""
+
+1. `data_id` != ""
+    **`cur_id` = data_id**
+    **`path` = "/item"**
+    *> spa_render*
+2. *
+    ****
+
+## save_item
+    + `value`=""
+
+1. `value` != ""
+    1. `cur_id` != ""
+        **`parts` = > text.str_split s=items sep="\n"**
+        **`next` = ""**
+        - [item](parts)
+            1. `item` != ""
+                1. `item` == `cur_id`
+                    1. `next` == ""
+                        **`next` = value**
+                    2. *
+                        **`next` = next + "\n" + value**
+                2. *
+                    1. `next` == ""
+                        **`next` = item**
+                    2. *
+                        **`next` = next + "\n" + item**
+        **`items` = next**
+        **`cur_id` = value**
+    2. *
+        1. `items` == ""
+            **`items` = value**
+        2. *
+            **`items` = items + "\n" + value**
+        **`cur_id` = value**
+    **`path` = "/item"**
+    *> spa_render*
+2. *
+    *> browser.set_text sel="#log" text="title required"*
+
+## spa_render
+*> spa_paint*
+
+## spa_paint
+**`hide` = > table.put in=None at="hidden" value=""**
+**`show` = > table.put in=None at="hidden" value=False**
+1. `path` == "/item"
+    `attrs` =
+
+    | #view-detail | #view-list | #view-edit |
+    |--------------|------------|------------|
+    | `show` | `hide` | `hide` |
+    **`title` = "Detail"**
+    **`body` = cur_id**
+2. *
+    1. `path` == "/edit"
+        `attrs` =
+
+        | #view-edit | #view-list | #view-detail |
+        |------------|------------|--------------|
+        | `show` | `hide` | `hide` |
+        **`title` = "Edit"**
+        **`body` = cur_id**
+    2. *
+        `attrs` =
+
+        | #view-list | #view-detail | #view-edit |
+        |------------|--------------|------------|
+        | `show` | `hide` | `hide` |
+        **`title` = "Items"**
+        **`body` = ""**
+**`parts` = > text.str_split s=items sep="\n"**
+**`html` = ""**
+- [item](parts)
+    1. `item` != ""
+        **`html` = html + "
  • " + item + "
  • "** +`persist` = + +| op | key | value | scope | +|----|-----|-------|-------| +| set | spa-items | `items` | memory | + +**`t` = > browser.set_text sel="#title" text=title** +**`a` = > browser.wrap key="set_attr" value=attrs** +**`ret` = > browser.merge a=t b=a** +**`list` = > browser.set_html sel="#items" html=html** +**`ret` = > browser.merge a=ret b=list** +**`d` = > browser.set_text sel="#detail-body" text=body** +**`ret` = > browser.merge a=ret b=d** +1. `path` == "/edit" + **`v` = > browser.set_value sel="#edit-title" value=cur_id** + **`ret` = > browser.merge a=ret b=v** +2. * + **** +**`nav` = > browser.spa_goto url=path** +**`ret` = > browser.merge a=ret b=nav** +**`log` = > browser.set_text sel="#log" text=path** +**`ret` = > browser.merge a=ret b=log** +**`sav` = > browser.storage spec=persist** +*> browser.merge a=ret b=sav* diff --git a/lib/browser.mq.md b/lib/browser.mq.md index 35cba82..525d858 100644 --- a/lib/browser.mq.md +++ b/lib/browser.mq.md @@ -154,6 +154,50 @@ focus. *> table.put in=None at="navigate" value=spec* +## store_set + + `key` + + `value` + + `scope`="memory" + +In-memory (or local/session) key write for SPA client state. Prefer `scope=memory` for tab-local app state. + +`spec` = + +| op | key | value | scope | +|----|-----|-------|-------| +| set | `key` | `value` | `scope` | + +*> table.put in=None at="storage" value=spec* + +## store_get + + `key` + + `then` + + `scope`="memory" + +Read a key then call `then` with `{ok, value, found, key, scope}`. + +`spec` = + +| op | key | then | scope | +|----|-----|------|-------| +| get | `key` | `then` | `scope` | + +*> table.put in=None at="storage" value=spec* + +## spa_goto + + `url` + + `replace`=False + +SPA navigation: `history.pushState` / `replaceState` via bridge `navigate` effect. + +`spec` = + +| url | replace | +|-----|---------| +| `url` | `replace` | + +*> table.put in=None at="navigate" value=spec* + ## storage + `spec` diff --git a/lib/浏览器.mq.md b/lib/浏览器.mq.md index 3de7c25..6a86fa2 100644 --- a/lib/浏览器.mq.md +++ b/lib/浏览器.mq.md @@ -153,6 +153,50 @@ import table:lib/table.mq.md *> table.put in=None at="navigate" value=spec* +## 存设 + + `键` + + `值` + + `作用域`="memory" + +SPA 客户端状态写入。优先 `作用域=memory`(页内内存)。 + +`spec` = + +| op | key | value | scope | +|----|-----|-------|-------| +| set | `键` | `值` | `作用域` | + +*> table.put in=None at="storage" value=spec* + +## 存取 + + `键` + + `然后` + + `作用域`="memory" + +读取键并回调 `然后`,参数含 `{ok, value, found, key, scope}`。 + +`spec` = + +| op | key | then | scope | +|----|-----|------|-------| +| get | `键` | `然后` | `作用域` | + +*> table.put in=None at="storage" value=spec* + +## 页跳 + + `url` + + `替换`=False + +SPA 导航(bridge `navigate`)。 + +`spec` = + +| url | replace | +|-----|---------| +| `url` | `替换` | + +*> table.put in=None at="navigate" value=spec* + ## 存储 + `规格` diff --git a/tests/ext/web-spa-helpers-smoke.mq.md b/tests/ext/web-spa-helpers-smoke.mq.md new file mode 100644 index 0000000..ce2ec0c --- /dev/null +++ b/tests/ext/web-spa-helpers-smoke.mq.md @@ -0,0 +1,34 @@ +--- +title: browser spa helpers smoke +description: store_set / spa_goto effect bags +import browser:lib/browser.mq.md +import json:lib/json.mq.md +import sys:lib/sys.mq.md +--- + +# main + +**set = > browser.store_set key="k" value="v" scope="memory"** +**op = > json.get value=`set` key="storage"** +**op_name = > json.get value=`op` key="op"** +**scope = > json.get value=`op` key="scope"** +1. `op_name` == "set" + 1. `scope` == "memory" + > print text=store-set-ok + 2. * + > print text=scope-fail + > sys.exit code=1 +2. * + > print text=op-fail + > sys.exit code=1 + +**nav = > browser.spa_goto url="/item" replace=False** +**n = > json.get value=`nav` key="navigate"** +**url = > json.get value=`n` key="url"** +1. `url` == "/item" + > print text=spa-goto-ok +2. * + > print text=spa-goto-fail + > sys.exit code=1 + +> print text=spa-helpers-ok