From 54b1d2f698622923c2c3af489b78965126771274 Mon Sep 17 00:00:00 2001 From: tiye Date: Thu, 29 Oct 2026 05:51:01 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E8=BF=81=E7=A7=BB=20Respo=20Guidebook=20?= =?UTF-8?q?=E5=88=B0=20Calcit=200.32.0=20=E5=B9=B6=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 14 +++++------ calcit.cirru | 54 +++++++++++++++--------------------------- deps.cirru | 16 ++++++------- docs/beginner-guide.md | 2 +- docs/guide.md | 21 ++++++++-------- docs/home.md | 2 +- package.json | 2 +- yarn.lock | 10 ++++---- 8 files changed, 52 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index bbf4c7e..b39ce4c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # Respo Guidebook -配对正式 Calcit CLI / `@calcit/procs` 0.31.0，以及已发布的 Docs Workflow 0.0.38、 -Respo 0.17.0-alpha.2、Reel 0.7.0-alpha.2、UI 0.9.0-alpha.2 和 JS-FFI 0.2.5。 -工具链为正式版本，模块图仍有预发布版本；不把两者统称为全图稳定。升级后重新安装依赖并完整 -刷新页面，不混用旧 CLI/alpha runtime。UI 0.9 基础样式可能影响外观。源码仅使用 -`calcit.cirru` 与 `deps.cirru`，不生成 compact/package.cirru。 +本轮候选配对正式 Calcit CLI / `@calcit/procs` **0.32.0**，目标模块为 Docs Workflow +0.0.40、Respo 0.17.0、Reel 0.7.0、UI/Router 0.9.0、Markdown 0.5.0 和 JS-FFI 0.2.8。 +当前通过本地候选模块链接验证，尚未证明已发布依赖图的 Caps strict 安装；上游 tag +发布后仍需干净安装和 PR CI。升级后重新安装依赖并完整刷新页面，UI 样式可能影响外观。 +源码仅使用 `calcit.cirru` 与 `deps.cirru`，不生成 compact/package.cirru。 Guide 说明当前 Ref/watch、Option、event handler/app dispatch、名义 Store 和宿主边界。 旧 Beginner Guide、部分 Guide 实现说明和 API 仍有历史片段，尚未全部迁移或独立执行；站点构建通过不代表 @@ -13,7 +13,7 @@ Guide 说明当前 Ref/watch、Option、event handler/app dispatch、名义 Stor ## 开发与验收 -Node 24、Yarn 4.18.0、正式 0.31.0 CLI： +Node 24、Yarn 4.18.0、正式 0.32.0 CLI： ```bash corepack enable @@ -32,7 +32,7 @@ yarn dev 默认 entry 的 dispatch-op 显式绑定原有 renderer 的 Dynamic 宿主入口； 非 Enum 输入仍被拒绝，业务 payload 仍受检后构造 Docs Workflow 的具名 Op。 -Store/Op、全部定义 schema 与处理函数未改，不以关闭证明审计或增加断言绕过 strict。 +14 个定义的 schema 与 Store/Op 合同保持；官方 formatter 转换 renderer 的一处类型提示，业务表达式不变，不以关闭证明审计或增加断言绕过 strict。 ## 部署边界 diff --git a/calcit.cirru b/calcit.cirru index 3997aac..35f423b 100644 --- a/calcit.cirru +++ b/calcit.cirru @@ -13,16 +13,16 @@ 'Site $ %{} 'CodeEntry (:doc |) :code $ quote $ defstruct Site (:storage-key 'String) :examples $ [] - :schema $ :: 'StructDef + :schema $ quote StructDef 'dev? $ %{} 'CodeEntry (:doc |) :code $ quote $ def dev? = |dev $ .unwrap-or (get-env |mode) |release :examples $ [] - :schema $ :: 'Bool + :schema $ quote Bool 'site $ %{} 'CodeEntry (:doc |) :code $ quote $ def site (Site :storage-key |workflow) :examples $ [] - :schema $ :: 'app.config/Site + :schema $ quote app.config/Site :ns $ %{} 'NsEntry (:doc |) :code $ quote $ ns app.config 'app.main $ %{} 'FileEntry @@ -30,7 +30,7 @@ '*reel $ %{} 'CodeEntry (:doc |) :code $ quote $ defref *reel (typed/new-reel schema/store) :examples $ [] - :schema $ :: 'Ref $ :: 'reel.typed/State 'docs-workflow.schema/Op 'docs-workflow.schema/Store + :schema $ quote $ Ref (reel.typed/State docs-workflow.schema/Op docs-workflow.schema/Store) 'dispatch! $ %{} 'CodeEntry (:doc |) :code $ quote $ defn dispatch! (op) when config/dev? $ println |Dispatch: op @@ -55,9 +55,7 @@ _ $ eprintln |Unknown-operation: op , &unit :examples $ [] - :schema $ :: 'Fn $ {} (:return 'Unit) - :args $ [] 'Enum - :features $ #{} :js-ffi + :schema $ quote $ Fn Enum (-> Unit) (:features :js-ffi) 'main! $ %{} 'CodeEntry (:doc |) :code $ quote $ defn main! () (register-languages!) println "|Running mode:" $ if config/dev? |dev |release @@ -69,25 +67,20 @@ browser/set-interval! persist-storage! 60000 println "|App started." :examples $ [] - :schema $ :: 'Fn $ {} (:return 'Unit) - :args $ [] - :features $ #{} :js-ffi + :schema $ quote $ Fn (-> Unit) (:features :js-ffi) 'mount-target $ %{} 'CodeEntry (:doc |) :code $ quote $ defn mount-target () .query-selector (js-cast js/document dom/DomDocument) |.app :examples $ [] - :schema $ :: 'Fn $ {} - :args $ [] - :features $ #{} :js-ffi - :return $ :: 'JsNullish 'respo.dom/DomElement + :schema $ quote $ Fn + -> $ JsNullish respo.dom/DomElement + :features :js-ffi 'persist-storage! $ %{} 'CodeEntry (:doc |) :code $ quote $ defn persist-storage! () (js/console.log |persist) browser/storage-set! (:storage-key config/site) format-cirru-edn $ :store @*reel :examples $ [] - :schema $ :: 'Fn $ {} (:return 'Unit) - :args $ [] - :features $ #{} :js-ffi + :schema $ quote $ Fn (-> Unit) (:features :js-ffi) 'reload! $ %{} 'CodeEntry (:doc |) :code $ quote $ defn reload! () if (nil? build-errors) @@ -98,23 +91,16 @@ hud! |error build-errors , &unit :examples $ [] - :schema $ :: 'Fn $ {} (:return 'Unit) - :args $ [] - :features $ #{} :js-ffi + :schema $ quote $ Fn (-> Unit) (:features :js-ffi) 'render-app! $ %{} 'CodeEntry (:doc |) :code $ quote $ defn render-app! () render! (mount-target) (comp-container @*reel schema/docs) fn (op) - hint-fn $ {} - :args $ [] 'Dynamic - :return 'Unit - :features $ #{} :js-ffi + hint-fn $ Fn Dynamic (-> Unit) (:features :js-ffi) if (enum? op) (dispatch! op) (raise "|Expected an Enum render action") , &unit :examples $ [] - :schema $ :: 'Fn $ {} (:return 'Unit) - :args $ [] - :features $ #{} :js-ffi + :schema $ quote $ Fn (-> Unit) (:features :js-ffi) :ns $ %{} 'NsEntry (:doc |) :code $ quote $ ns app.main :require @@ -177,20 +163,19 @@ DocNode :title |patch-instance! :key :patch-instance :content (load-doc |apis/patch-instance.md) :children $ [] DocNode :title |Community :key :community :content (load-doc |community.md) :children $ [] :examples $ [] - :schema $ :: 'List 'docs-workflow.schema/DocNode + :schema $ quote $ List docs-workflow.schema/DocNode 'load-doc $ %{} 'CodeEntry (:doc |) :code $ quote $ defmacro load-doc (filename) read-file $ str |docs/ filename :examples $ [] - :schema $ :: 'Macro $ {} - :capabilities $ #{} :fs-read - :expansion $ :: 'Expr 'String - :required $ [] 'Syntax + :schema $ quote $ Macro Syntax + -> $ Expr String + :capabilities :fs-read 'store $ %{} 'CodeEntry (:doc |) :code $ quote $ def store Store :states $ {} $ :cursor ([]) :examples $ [] - :schema $ :: 'docs-workflow.schema/Store + :schema $ quote docs-workflow.schema/Store :ns $ %{} 'NsEntry (:doc |) :code $ quote $ ns app.schema :require $ docs-workflow.schema :refer $ DocNode Store @@ -199,8 +184,7 @@ %{} 'CodeEntry (:doc |) :code $ quote $ defn updater (store op op-id op-time) (docs-updater/updater store op op-id op-time) :examples $ [] - :schema $ :: 'Fn $ {} (:return 'docs-workflow.schema/Store) - :args $ [] 'docs-workflow.schema/Store 'docs-workflow.schema/Op 'String 'Number + :schema $ quote $ Fn docs-workflow.schema/Store docs-workflow.schema/Op String Number (-> docs-workflow.schema/Store) :ns $ %{} 'NsEntry (:doc |) :code $ quote $ ns app.updater :require $ docs-workflow.updater :as docs-updater diff --git a/deps.cirru b/deps.cirru index 9a8658d..f33ced4 100644 --- a/deps.cirru +++ b/deps.cirru @@ -1,10 +1,10 @@ -{} (:calcit-version |0.31.0) +{} (:calcit-version |0.32.0) :version |0.0.4 - :dependencies $ {} (|Respo/reel.calcit |0.7.0-alpha.2) - |Respo/respo-markdown.calcit |0.5.0-alpha.3 - |Respo/respo-router.calcit |0.9.0-alpha.1 - |Respo/respo-ui.calcit |0.9.0-alpha.2 - |Respo/respo.calcit |0.17.0-alpha.2 - |calcit-lang/docs-workflow |0.0.38 - |calcit-lang/js-ffi |0.2.5 + :dependencies $ {} (|Respo/reel.calcit |0.7.0) + |Respo/respo-markdown.calcit |0.5.0 + |Respo/respo-router.calcit |0.9.0 + |Respo/respo-ui.calcit |0.9.0 + |Respo/respo.calcit |0.17.0 + |calcit-lang/docs-workflow |0.0.40 + |calcit-lang/js-ffi |0.2.8 diff --git a/docs/beginner-guide.md b/docs/beginner-guide.md index fa16247..4c00029 100644 --- a/docs/beginner-guide.md +++ b/docs/beginner-guide.md @@ -1,6 +1,6 @@ > Historical tutorial: the old macro expansions, JavaScript access and dispatch > examples below predate current typed APIs. Start with **Guide** in the sidebar -> for formal 0.31.0 contracts. This is not a standalone checked current app. +> for formal 0.32.0 contracts. This is not a standalone checked current app. Want to explore by yourself? diff --git a/docs/guide.md b/docs/guide.md index 7d8dbbf..008673a 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,10 +1,11 @@ -# Guide: Calcit 0.31.0 +# Guide: Calcit 0.32.0 -This site pairs formal Calcit CLI / `@calcit/procs` **0.31.0**, Respo -**0.17.0-alpha.2**, Reel **0.7.0-alpha.2** and Docs Workflow **0.0.38**. -The CLI/runtime are formal releases; the module graph still includes prereleases. Use `calcit.cirru` -for source and `deps.cirru` for published module versions; do not restore -`compact.cirru` or `package.cirru`, or mix this runtime with an alpha CLI. +This site targets formal Calcit CLI / `@calcit/procs` **0.32.0**, Respo +**0.17.0**, Reel **0.7.0** and Docs Workflow **0.0.40** candidates. +Local candidate validation does not establish a released dependency graph; +clean Caps installation and PR CI must follow upstream publication. Use +`calcit.cirru` for source and `deps.cirru` for module versions; do not restore +`compact.cirru` or `package.cirru`, or mix runtime and CLI versions. For a new application, start with the maintained [Respo template](https://github.com/Respo/respo-calcit-workflow). Check its own @@ -25,9 +26,7 @@ ns example.counter defref *count 0 defn increment! () - hint-fn $ {} - :args $ [] - :return 'Unit + hint-fn $ Fn $ -> Unit reset! *count $ inc @*count , &unit ``` @@ -52,7 +51,7 @@ handle `typed/decode-control` separately, and use `typed/record-op` for domain operations. `Date.now` is a host call, not a numeric constant; JS-FFI's `date-now-snapshot` exposes a checked `:timestamp` value. -This app uses Docs Workflow's published **DocNode, Store and Op**, plus its +This app uses Docs Workflow's **DocNode, Store and Op**, plus its updater. A second nominally distinct Store with identical fields is not interchangeable with that module's Store. @@ -74,6 +73,6 @@ fragment or certify browser/WebSocket application behavior. The Beginner Guide, older implementation discussions under Guide, and several API chapters retain historical design notes. Their old macro expansions, direct JavaScript access and operation syntax are not -copy-ready 0.31.0 code. Consult the paired published module's `calcit query def` +copy-ready 0.32.0 code. Consult the paired published module's `calcit query def` and `query schema` views and the maintained template. Historical examples need section-by-section migration, not mechanical renaming without contract checks. diff --git a/docs/home.md b/docs/home.md index 4586b36..2715c9d 100644 --- a/docs/home.md +++ b/docs/home.md @@ -4,7 +4,7 @@ Inspired by React and Reagent. -This site targets formal Calcit/procs **0.31.0**. Choose **Guide** in the sidebar +This site targets formal Calcit/procs **0.32.0**. Choose **Guide** in the sidebar for current migration notes. Beginner Guide and older API chapters retain historical material; not every snippet is ported or independently type-checked. diff --git a/package.json b/package.json index d4e70c9..00afb5d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "packageManager": "yarn@4.18.0", "dependencies": { - "@calcit/procs": "0.31.0" + "@calcit/procs": "0.32.0" }, "devDependencies": { "bottom-tip": "^0.1.5", diff --git a/yarn.lock b/yarn.lock index 9302bcc..398dfe6 100644 --- a/yarn.lock +++ b/yarn.lock @@ -12,15 +12,15 @@ __metadata: languageName: node linkType: hard -"@calcit/procs@npm:0.31.0": - version: 0.31.0 - resolution: "@calcit/procs@npm:0.31.0" +"@calcit/procs@npm:0.32.0": + version: 0.32.0 + resolution: "@calcit/procs@npm:0.32.0" dependencies: "@calcit/finger-vec": "npm:0.1.1" "@calcit/ternary-tree": "npm:0.0.26" "@cirru/parser.ts": "npm:0.0.10" "@cirru/writer.ts": "npm:^0.1.9" - checksum: 10c0/daa73d722acd302be00f5f83eb91f742025a5323fac01b84222bed0fffef688761c1285637f9d672b74c2b1bb4513b170d4b5dfcc51bd65f1396390bd526ac77 + checksum: 10c0/99e58a7b15f2e8216df8e15240a5661b65ae03e5206f01504ca738221fec89077dfceeb94372606bf47c30275f98971a9719377299b7576abd2778f350f47b9a languageName: node linkType: hard @@ -688,7 +688,7 @@ __metadata: version: 0.0.0-use.local resolution: "root-workspace-0b6124@workspace:." dependencies: - "@calcit/procs": "npm:0.31.0" + "@calcit/procs": "npm:0.32.0" bottom-tip: "npm:^0.1.5" cirru-color: "npm:^0.2.3" github-markdown-css: "npm:^5.3.0" From 9dba38a8ffe3197b41b86005ab51cd96193bfded Mon Sep 17 00:00:00 2001 From: tiye Date: Sat, 31 Oct 2026 17:18:07 +0800 Subject: [PATCH 2/2] chore: migrate Respo Guidebook to Calcit 0.32.1 --- .github/workflows/upload.yaml | 5 ++- README.md | 17 +++++----- deps.cirru | 12 ++++---- docs/beginner-guide.md | 2 +- docs/guide.md | 11 ++----- docs/guide/dom-events.md | 58 ++++++++++++----------------------- docs/home.md | 2 +- package.json | 2 +- yarn.lock | 10 +++--- 9 files changed, 49 insertions(+), 70 deletions(-) diff --git a/.github/workflows/upload.yaml b/.github/workflows/upload.yaml index 2511f85..8055bf8 100644 --- a/.github/workflows/upload.yaml +++ b/.github/workflows/upload.yaml @@ -44,13 +44,16 @@ jobs: - name: Validate Calcit snapshot run: | + set -euo pipefail calcit calcit.cirru edit format - git diff --exit-code -- calcit.cirru + git diff --exit-code --quiet -- calcit.cirru calcit --check-only --all-defs --format json calcit --check-only --ns app.main --ns app.config --ns app.schema --ns app.updater --format json calcit fix --workflow strict --verify --format json | jq -e '.data.workflow.status == "passed" and .diagnostics == []' calcit analyze weak-types --only dynamic-method --summary-only --format json | jq -e '.data.summary.findings == 0' calcit analyze weak-types --only deprecated-call --summary-only --format json | jq -e '.data.summary.calls == 0' + calcit docs check-md docs/guide.md --failures-only + calcit docs check-md docs/guide/dom-events.md --failures-only - name: Compile and build web app env: diff --git a/README.md b/README.md index b39ce4c..82e651f 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,7 @@ # Respo Guidebook -本轮候选配对正式 Calcit CLI / `@calcit/procs` **0.32.0**，目标模块为 Docs Workflow -0.0.40、Respo 0.17.0、Reel 0.7.0、UI/Router 0.9.0、Markdown 0.5.0 和 JS-FFI 0.2.8。 -当前通过本地候选模块链接验证，尚未证明已发布依赖图的 Caps strict 安装；上游 tag -发布后仍需干净安装和 PR CI。升级后重新安装依赖并完整刷新页面，UI 样式可能影响外观。 -源码仅使用 `calcit.cirru` 与 `deps.cirru`，不生成 compact/package.cirru。 +使用者注意：本轮将站点 Calcit CLI / `@calcit/procs` 从 **0.31.0** 配对正式 **0.32.1**，采用已发布 Docs Workflow **0.0.40**、Respo **0.17.1**、UI **0.9.0** 和 JS-FFI **0.2.9**。Reel **0.7.0-alpha.5**、Markdown **0.5.0-alpha.5**、Router **0.9.0-alpha.4** 仍为已发布 alpha，不声称完整依赖图均为正式版。升级后重新安装完整精确依赖图并刷新页面，UI 样式可能变化。源码仍仅使用 `calcit.cirru`，依赖以 `deps.cirru` 为准，不恢复 compact/package.cirru。 Guide 说明当前 Ref/watch、Option、event handler/app dispatch、名义 Store 和宿主边界。 旧 Beginner Guide、部分 Guide 实现说明和 API 仍有历史片段，尚未全部迁移或独立执行；站点构建通过不代表 @@ -13,7 +9,7 @@ Guide 说明当前 Ref/watch、Option、event handler/app dispatch、名义 Stor ## 开发与验收 -Node 24、Yarn 4.18.0、正式 0.32.0 CLI： +Node 24、Yarn 4.18.0、正式 0.32.1 CLI： ```bash corepack enable @@ -27,7 +23,7 @@ yarn dev `yarn build` 默认使用相对资源路径，`VITE_BASE_URL` 可指定前端 CDN 根路径。CI 检查所有定义、公开 namespace、完整 strict、旧调用与动态方法，构建 SPA/mdBook -并保存 PR 预览。原项目没有定义附带测试，零个测试不等于业务覆盖；浏览器导航、 +并保存 PR 预览。当前 Guide 计数器与 DOM Events 数据解码示例由官方代码块检查覆盖；原项目没有定义附带测试，零个测试不等于业务覆盖；浏览器导航、 搜索与刷新需另行验收。页面 `hud!` 错误展示保留。 默认 entry 的 dispatch-op 显式绑定原有 renderer 的 Dynamic 宿主入口； @@ -41,13 +37,16 @@ action 内置校验，不新增脚本。原 SPA/mdBook 的 rsync 目录均保持 `/web-assets/repo/Respo/guidebook`，无服务端部署。本 PR 不自动合并或发版。 组织级 COS secrets 需要授权本仓库；PR 不读取部署凭据、不运行 COS 或 rsync。 原 SHA256 校验的 rsync/mdBook 安装、SSH 主机校验和 main 部署条件保留。 +CI 的类型步骤显式启用 pipefail，保留上游 Calcit 失败退出码；canonical diff 仅静默输出。 +npm 新版本解析使用统一一小时包龄，无包级豁免；已有 lock 的 immutable 重放不重新检查包龄。 ```bash -cargo install mdbook -cargo install mdbook-linkcheck +# 与 CI 对齐 mdbook 0.4.14 / mdbook-linkcheck 0.7.6 mdbook build ``` +已知 mdBook Cirru 高亮回退为纯文本，见 [Docs Workflow #95](https://github.com/calcit-lang/docs-workflow/issues/95)；当前构建不声称修复该限制。 + ## License MIT diff --git a/deps.cirru b/deps.cirru index f33ced4..8301edb 100644 --- a/deps.cirru +++ b/deps.cirru @@ -1,10 +1,10 @@ -{} (:calcit-version |0.32.0) +{} (:calcit-version |0.32.1) :version |0.0.4 - :dependencies $ {} (|Respo/reel.calcit |0.7.0) - |Respo/respo-markdown.calcit |0.5.0 - |Respo/respo-router.calcit |0.9.0 + :dependencies $ {} (|Respo/reel.calcit |0.7.0-alpha.5) + |Respo/respo-markdown.calcit |0.5.0-alpha.5 + |Respo/respo-router.calcit |0.9.0-alpha.4 |Respo/respo-ui.calcit |0.9.0 - |Respo/respo.calcit |0.17.0 + |Respo/respo.calcit |0.17.1 |calcit-lang/docs-workflow |0.0.40 - |calcit-lang/js-ffi |0.2.8 + |calcit-lang/js-ffi |0.2.9 diff --git a/docs/beginner-guide.md b/docs/beginner-guide.md index 4c00029..f9b17cc 100644 --- a/docs/beginner-guide.md +++ b/docs/beginner-guide.md @@ -1,6 +1,6 @@ > Historical tutorial: the old macro expansions, JavaScript access and dispatch > examples below predate current typed APIs. Start with **Guide** in the sidebar -> for formal 0.32.0 contracts. This is not a standalone checked current app. +> for formal 0.32.1 contracts. This is not a standalone checked current app. Want to explore by yourself? diff --git a/docs/guide.md b/docs/guide.md index 008673a..544d513 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,11 +1,6 @@ -# Guide: Calcit 0.32.0 +# Guide: Calcit 0.32.1 -This site targets formal Calcit CLI / `@calcit/procs` **0.32.0**, Respo -**0.17.0**, Reel **0.7.0** and Docs Workflow **0.0.40** candidates. -Local candidate validation does not establish a released dependency graph; -clean Caps installation and PR CI must follow upstream publication. Use -`calcit.cirru` for source and `deps.cirru` for module versions; do not restore -`compact.cirru` or `package.cirru`, or mix runtime and CLI versions. +This site pairs formal Calcit CLI / `@calcit/procs` **0.32.1** with released Docs Workflow **0.0.40**, Respo **0.17.1** and JS-FFI **0.2.9**. The published UI graph still includes Reel **0.7.0-alpha.5**, Markdown **0.5.0-alpha.5** and Router **0.9.0-alpha.4**; it is not an entirely stable-release graph. Install it using Caps strict and keep runtime and CLI paired. Use `calcit.cirru` for source and `deps.cirru` for module versions; do not restore `compact.cirru` or `package.cirru`. For a new application, start with the maintained [Respo template](https://github.com/Respo/respo-calcit-workflow). Check its own @@ -73,6 +68,6 @@ fragment or certify browser/WebSocket application behavior. The Beginner Guide, older implementation discussions under Guide, and several API chapters retain historical design notes. Their old macro expansions, direct JavaScript access and operation syntax are not -copy-ready 0.32.0 code. Consult the paired published module's `calcit query def` +copy-ready 0.32.1 code. Consult the paired published module's `calcit query def` and `query schema` views and the maintained template. Historical examples need section-by-section migration, not mechanical renaming without contract checks. diff --git a/docs/guide/dom-events.md b/docs/guide/dom-events.md index eef0fd5..9efa775 100644 --- a/docs/guide/dom-events.md +++ b/docs/guide/dom-events.md @@ -1,48 +1,30 @@ ## DOM events -Here is a simple demo handling `input` events: +当前 Respo `respo.schema/EventHandler` 接收两个参数：不可变的 `Map` 事件数据与应用的 dispatch 函数。dispatch 只接收一个 entry `dispatch-op` 类型的值并返回 Unit；不要沿用旧 `(op, op-data)` 两参数调用方式。 -```cirru -input $ {} - :on-input $ fn (e dispatch!) - println (:value e) -``` +事件转换以已发布 `respo.util.format/event->edn` 为准，不要复制旧版 `case-default` 与直接 JavaScript 属性读取的实现。常见 click、input/change、键盘事件的 `:type` 为对应 Tag；不认识的事件类型仍可能是 String。input/change 提供 `:value`、`:checked`，键盘字段由当前库填充，不能假定所有事件都有相同字段。 -`e` is a HashMap with several entries: +Map 读取返回 Option。输入框应用预期文本时，可在这个真实开放边界收敛为 `Option`： ```cirru -def e $ {} - :type "|input" - :original-event event +let + input-text $ fn (event) + hint-fn $ Fn (Map Tag Dynamic) + -> $ Option String + decode-map-as (get event :value) + quote $ Option String + assert= |hello $ .unwrap $ input-text + {} $ :value |hello + assert= true $ .none? $ input-text ({}) ``` -The details: +缺失 `:value` 返回 none；已有空字符串仍是 some，已有非 String 值会被 decoder 拒绝，不以任意空字符串隐藏错误。此原生示例验证事件数据读取，不模拟或证明浏览器事件的完整绑定与传播行为。 -```cirru -defn event->edn (event) - ; js/console.log "|simplify event:" event - -> - case-default (.-type event) - {} - :msg (str "|Unhandled event: " (.-type event)) - :type (.-type event) - |click $ {} - :type :click - |keydown $ {} - :key-code (.-keyCode event) - :type :keydown - |keyup $ {} - :key-code (.-keyCode event) - :type :keyup - |input $ {} - :value (aget (.-target event) "|value") - :type :input - |change $ {} - :value (aget (.-target event) "|value") - :type :change - |focus $ {} - :type :focus - assoc :original-event event -``` +原始 DOM event 位于 `:event`，兼容字段 `:original-event` 也保留。它是宿主对象，整个事件 Map 不是 DOM event；浏览器属性读取应沿用 Respo/JS-FFI 的实际宿主合同，不能把 Map 强转为另一类型。事件绑定与传播策略也应查看实际库实现，不从这段数据示例推断。 + +在项目中核对当前版本的 source of truth： -Events are bound directly on the elements for simplicity and consistency. And it stops propagation when event is triggered. +```bash +calcit query def respo.schema/EventHandler +calcit query def 'respo.util.format/event->edn' +``` diff --git a/docs/home.md b/docs/home.md index 2715c9d..de830ae 100644 --- a/docs/home.md +++ b/docs/home.md @@ -4,7 +4,7 @@ Inspired by React and Reagent. -This site targets formal Calcit/procs **0.32.0**. Choose **Guide** in the sidebar +This site targets formal Calcit/procs **0.32.1**. Choose **Guide** in the sidebar for current migration notes. Beginner Guide and older API chapters retain historical material; not every snippet is ported or independently type-checked. diff --git a/package.json b/package.json index 00afb5d..8e04084 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "packageManager": "yarn@4.18.0", "dependencies": { - "@calcit/procs": "0.32.0" + "@calcit/procs": "0.32.1" }, "devDependencies": { "bottom-tip": "^0.1.5", diff --git a/yarn.lock b/yarn.lock index 398dfe6..c65faeb 100644 --- a/yarn.lock +++ b/yarn.lock @@ -12,15 +12,15 @@ __metadata: languageName: node linkType: hard -"@calcit/procs@npm:0.32.0": - version: 0.32.0 - resolution: "@calcit/procs@npm:0.32.0" +"@calcit/procs@npm:0.32.1": + version: 0.32.1 + resolution: "@calcit/procs@npm:0.32.1" dependencies: "@calcit/finger-vec": "npm:0.1.1" "@calcit/ternary-tree": "npm:0.0.26" "@cirru/parser.ts": "npm:0.0.10" "@cirru/writer.ts": "npm:^0.1.9" - checksum: 10c0/99e58a7b15f2e8216df8e15240a5661b65ae03e5206f01504ca738221fec89077dfceeb94372606bf47c30275f98971a9719377299b7576abd2778f350f47b9a + checksum: 10c0/54c505396a4653e643d24eaa71bf9a029b48034cabcd68ce47b2b40b565cf04a4693ac47c7feb34b8e84936621a397802743bffd3134ddeb37b08d23ef113923 languageName: node linkType: hard @@ -688,7 +688,7 @@ __metadata: version: 0.0.0-use.local resolution: "root-workspace-0b6124@workspace:." dependencies: - "@calcit/procs": "npm:0.32.0" + "@calcit/procs": "npm:0.32.1" bottom-tip: "npm:^0.1.5" cirru-color: "npm:^0.2.3" github-markdown-css: "npm:^5.3.0"