From b710745e8811773bf4fd4e03db1d8291b60fe2a2 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 17 Sep 2026 20:58:21 +0800 Subject: [PATCH] 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 --- crates/marqdo-wasm/js/marqdo-bridge.js | 15 ++ doc/design/ext-web-spa.md | 24 ++++ doc/design/ext-web.md | 1 + examples/web-spa-app/README.md | 14 ++ examples/web-spa-app/index.mq.md | 23 +++ examples/web-spa-app/static/client.mq.md | 174 +++++++++++++++++++++++ lib/browser.mq.md | 44 ++++++ lib/浏览器.mq.md | 44 ++++++ tests/ext/web-spa-helpers-smoke.mq.md | 34 +++++ 9 files changed, 373 insertions(+) create mode 100644 doc/design/ext-web-spa.md create mode 100644 examples/web-spa-app/README.md create mode 100644 examples/web-spa-app/index.mq.md create mode 100644 examples/web-spa-app/static/client.mq.md create mode 100644 tests/ext/web-spa-helpers-smoke.mq.md 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