@hy-bricks/canvas 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +2 -0
  3. package/package.json +4 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,108 @@
1
+ # @hy-bricks/canvas
2
+
3
+ ## [0.4.1] - 2026-05-27
4
+
5
+ 文档补完 — 0.4.0 的发版说明现在 npm 包页面可见。代码无变更。
6
+ 从 0.4.0 升上来可跳过。
7
+
8
+ ---
9
+
10
+ ## [0.4.0] - 2026-05-27 · 组件 mounted 里立即可订阅
11
+
12
+ ### ✨ 新特性
13
+
14
+ 组件作者可在 `mounted` 里**直接调** `__HYPERCARD__.runtime.on(this.hcInstanceId, ...)` 立即生效,不再需要 nextTick / microtask 等一拍。
15
+
16
+ 每个组件实例可读 3 个 SDK 注入 prop:
17
+
18
+ | Prop | 含义 |
19
+ |---|---|
20
+ | `this.hcInstanceId` | 实例 ID |
21
+ | `this.hcCanvasId` | 所属画布 ID |
22
+ | `this.hcComponentId` | 组件源 ID |
23
+
24
+ ```js
25
+ // 组件源码 component.js
26
+ export default {
27
+ mounted() {
28
+ console.log('我是谁', this.hcInstanceId, this.hcCanvasId)
29
+
30
+ // ✅ 立即订阅,不再要等
31
+ __HYPERCARD__.runtime.on(this.hcInstanceId, 'click', (payload) => {
32
+ // ...
33
+ })
34
+
35
+ // ✅ 立即拿到 handle
36
+ const handle = __HYPERCARD__.canvases
37
+ .get(this.hcCanvasId)
38
+ ?.getInstance(this.hcInstanceId)
39
+ },
40
+ }
41
+ ```
42
+
43
+ ### ⚠ BREAKING — host 升级前 audit
44
+
45
+ `onInstanceLifecycle('instance:ready')` / `handle.on('instance:ready')` 回调被调时,**子组件 DOM 还没渲染**,`vm.$el` 是 `null`。
46
+
47
+ **修法**(回调内访问 DOM 的话):
48
+
49
+ ```js
50
+ // ❌ 不能直接访问 $el
51
+ onInstanceLifecycle('instance:ready', ({ instance }) => {
52
+ instance.$el.querySelector(...) // null,报错
53
+ })
54
+
55
+ // ✅ 等下一帧 DOM 渲染完
56
+ onInstanceLifecycle('instance:ready', ({ instance }) => {
57
+ nextTick(() => {
58
+ instance.$el.querySelector(...)
59
+ })
60
+ })
61
+ ```
62
+
63
+ ### 升级 checklist
64
+
65
+ ```bash
66
+ grep -rn "instance:ready\|onInstanceLifecycle\|getInstanceReady" src/
67
+ ```
68
+
69
+ 每处看回调内是否访问 `vm.$el` / DOM。
70
+ - 没访问 → `npm install @hy-bricks/{core,canvas,editor,devtools}@^0.4.0` 透明升
71
+ - 访问了 → 改 `nextTick`
72
+
73
+ ### 命名保留
74
+
75
+ 组件作者**不要**用这 3 个名字声明你自己的 prop(同名会被 SDK 注入覆盖):
76
+ `hcInstanceId` / `hcCanvasId` / `hcComponentId`。
77
+
78
+ 之前的保留 prop `hcCustomValues` 不变。
79
+
80
+ ---
81
+
82
+ ## 0.3.0
83
+
84
+ ### Minor Changes
85
+
86
+ - 0.3.0 渲染核心 · mount-ready 信号 + cache 精确读 API
87
+
88
+ **主题**:`RenderScheduler` 渐进 mount 下,SDK 第一次给出"组件挂好"信号(per-canvas 隔离的 event + Promise + cache 精确读 API)。host 替掉 `setTimeout(300)` / `mountConcurrency:50` / `replayFromCache` 全表遍历兜底。
89
+
90
+ **新 API**:
91
+ - `@hy-bricks/core`:`onInstanceLifecycle("instance:ready" | "instance:unmounted", cb)` — 模块级 lifecycle emitter,跨 canvas 共享,payload `{ canvasId, instanceId }`
92
+ - `@hy-bricks/canvas · CanvasHandle`:
93
+ - `handle.on("instance:ready" | "instance:unmounted", cb)` — per-canvas 自动过滤,payload 只透 `instanceId`
94
+ - `handle.getInstanceReady(instanceId): Promise<void>` — 已挂立即 resolved / 未挂等 emit / `handle.dispose()` 时 reject `HandleDisposedError`
95
+ - `handle.getInstanceRuntime(instanceId)` — 返**运行时 vm handle**(`ComponentInstanceHandle`),给 host 调 `setDataInput / call / emit` 用;跟 `getInstance(id)` 返 PageInstance snapshot 区分
96
+ - `handle.getCachedBySourceId(sourceId, params?)` — cache 精确读快照,plain object(不返 reactive)
97
+ - `HandleDisposedError` 具名 error class(host 可 `instanceof` 判)
98
+ - `handle.dispose()` 终态 guard:dispose 后所有入口 no-op / reject / null,防 listener 泄漏 + pending 永挂
99
+ - `@hy-bricks/canvas · HyperCardPageRendererExpose.data.getCachedBySourceId(sourceId, params?)` 同款
100
+
101
+ **边界**(摸底备忘 §1):SDK 只补"信号 + 暴露 API",**不**替 host 自动 push / replay / 重拉 — 数据治理仍归 host。D5.4 §R6 "cache 保留 + 不自动 replay,host 手动 invalidate" 合约**不变**。
102
+
103
+ **host 升级(不强制)**:
104
+ - 0.2.0 → 0.3.0 **不破坏现有代码**;不用 ready 信号当 0.3.0 没加
105
+ - 用了就简化:`handle.on("instance:ready", id => { const c = handle.getCachedBySourceId(src); if (c?.status === "success") handle.getInstanceRuntime(id)?.setDataInput?.(key, c.value) })`
106
+ - workaround(`replayFromCache` / `mountConcurrency:50` / 首屏 reload)**可保留**,SDK 不强制删
107
+
108
+ 详见 `docs/v1/frontend-sdk/20260523-1648-claude-渲染核心-挂载就绪信号-实施稿-rev1.md`。
package/README.md CHANGED
@@ -6,6 +6,8 @@
6
6
  [![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
7
7
  [![vue](https://img.shields.io/badge/vue-%5E3.5-42b883)](https://vuejs.org/)
8
8
 
9
+ > ⚠️ **0.4.0 BREAKING** ── `handle.on('instance:ready')` / `onInstanceLifecycle('instance:ready')` 回调被调时,子组件 DOM 还没渲染。回调内访问 `vm.$el` 会拿 `null`,需改 `nextTick(() => vm.$el...)`。详 [CHANGELOG](./CHANGELOG.md)。
10
+
9
11
  ---
10
12
 
11
13
  ## 简介
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hy-bricks/canvas",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "HyperCard 画布 — 多组件实例编排 / 自由布局 / 拖拽 / 连线 / 属性面板。受控组件,SDK 边界守住:不 fetch / 不知后端 / 不开 Drawer。",
5
5
  "keywords": [
6
6
  "hypercard",
@@ -26,14 +26,15 @@
26
26
  "files": [
27
27
  "dist",
28
28
  "README.md",
29
- "LICENSE"
29
+ "LICENSE",
30
+ "CHANGELOG.md"
30
31
  ],
31
32
  "publishConfig": {
32
33
  "access": "public"
33
34
  },
34
35
  "peerDependencies": {
35
36
  "vue": "^3.5.0",
36
- "@hy-bricks/core": "^0.3.0"
37
+ "@hy-bricks/core": "^0.4.1"
37
38
  },
38
39
  "devDependencies": {
39
40
  "@vitejs/plugin-vue": "^5.2.1",