feat(web): native SPA helpers, memory store, and demo

Add bridge scope=memory, lib/browser store_set/spa_goto, web-spa-app
list/detail/edit client routes demo, and helper smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-17 20:58:21 +08:00
1 parent 5cf84fe9b7
commit b710745e88
9 files changed
+373

No files matched your search

+15
View File
@@ -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;
}
+24
View File
@@ -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/` — 列表 → 详情 → 编辑,全客户端路由。
+1
View File
@@ -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` 已够用)。
---
+14
View File
@@ -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).
+23
View File
@@ -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` = "<nav class='spa-nav'><button type='button' id='nav-list'>Items</button> <button type='button' id='nav-new'>New</button></nav><p id='title' class='spa-title'>Items</p><section id='view-list'><ul id='items'></ul><p class='hint'>Click an item for detail.</p></section><section id='view-detail' hidden><p id='detail-body'></p><p><button type='button' id='btn-edit'>Edit</button> <button type='button' id='btn-back'>Back</button></p></section><section id='view-edit' hidden><label>Title <input id='edit-title' /></label><p><button type='button' id='btn-save'>Save</button> <button type='button' id='btn-cancel'>Cancel</button></p></section><pre id='log'></pre>" + 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
+174
View File
@@ -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 + "<li data-id=\"" + item + "\">" + item + "</li>"**
`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*
+44
View File
@@ -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`
+44
View File
@@ -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*
## 存储
+ `规格`
+34
View File
@@ -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