create-zleap-app 0.10.6 → 0.12.0

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 (36) hide show
  1. package/index.js +16 -14
  2. package/lib/scaffold.js +18 -5
  3. package/package.json +4 -4
  4. package/skills/zleap-cloud-app/SKILL.md +47 -11
  5. package/skills/zleap-cloud-app/references/cloud-functions.md +11 -6
  6. package/skills/zleap-cloud-app/references/limits.md +22 -19
  7. package/skills/zleap-cloud-app/references/sdk-database-files.md +4 -4
  8. package/skills/zleap-cloud-app/references/status-codes.md +24 -20
  9. package/skills/zleap-cloud-app/references/ui.md +304 -0
  10. package/skills/zleap-cloud-app-release/references/app-center-install.md +19 -11
  11. package/skills/zleap-cloud-app-release/references/app-center-publish.md +6 -6
  12. package/skills/zleap-cloud-app-release/references/console-release.md +1 -1
  13. package/skills/zleap-cloud-app-release/references/dev-to-production.md +67 -1
  14. package/skills/zleap-cloud-app-release/references/status-codes.md +24 -20
  15. package/templates/_shared/.cursor/mcp.json +14 -0
  16. package/templates/_shared/.mcp.json +14 -0
  17. package/templates/{react-ts → _shared}/scripts/zleap.mjs +138 -83
  18. package/templates/react-ts/AGENTS.md +9 -3
  19. package/templates/react-ts/package.json +4 -0
  20. package/templates/react-ts/src/App.tsx +227 -96
  21. package/templates/react-ts/src/cloud/client.ts +21 -6
  22. package/templates/react-ts/src/cloud/preview.ts +116 -0
  23. package/templates/react-ts/src/cloud/useCloudConnection.ts +2 -2
  24. package/templates/react-ts/src/index.css +5 -241
  25. package/templates/react-ts/src/main.tsx +3 -0
  26. package/templates/vanilla/AGENTS.md +37 -0
  27. package/templates/vanilla/CLAUDE.md +1 -0
  28. package/templates/vanilla/README.md +37 -0
  29. package/templates/vanilla/_gitignore +7 -0
  30. package/templates/vanilla/app/LICENSE +21 -0
  31. package/templates/vanilla/app/index.html +67 -0
  32. package/templates/vanilla/app/main.js +222 -0
  33. package/templates/vanilla/app/manifest.json +33 -0
  34. package/templates/vanilla/app/preview.js +114 -0
  35. package/templates/vanilla/app/style.css +5 -0
  36. package/templates/vanilla/package.json +32 -0
@@ -1,4 +1,6 @@
1
- import { useCallback, useEffect, useMemo, useState, type FormEvent, type ReactNode } from 'react';
1
+ // 界面统一用官方样式 zleap.css 的 zl- 类(与 zleapOS 桌面同色、自动跟随亮 / 暗),应用特有的样式写在 index.css。
2
+ // 每块数据都处理四种状态:加载中(骨架)、出错(说明 + 重试)、空(引导下一步)、有数据。
3
+ import { useCallback, useEffect, useMemo, useRef, useState, type FormEvent, type ReactNode } from 'react';
2
4
 
3
5
  import manifest from '../manifest.json';
4
6
  import { describeError, errorCode, hasProfile } from './cloud/client';
@@ -9,34 +11,44 @@ type Filter = 'all' | 'active' | 'done';
9
11
 
10
12
  export function App() {
11
13
  const { state, retry } = useCloudConnection();
14
+ const ready =
15
+ state.status === 'preview' || (state.status === 'ready' && hasProfile(state.capabilities, 'document-core/1'));
12
16
 
13
17
  return (
14
- <main className="app">
15
- <header className="app-header">
18
+ <main className="zl-page">
19
+ <header className="zl-header">
16
20
  <div>
17
- <p className="eyebrow">zleapOS App Cloud</p>
18
- <h1>{manifest.name}</h1>
21
+ <h1 className="zl-title">{manifest.name}</h1>
22
+ <p className="zl-subtitle">记下要做的事,完成后勾掉。</p>
19
23
  </div>
20
- <ConnectionBadge status={state.status} />
24
+ <ConnectionStatus status={state.status} />
21
25
  </header>
22
26
 
23
- {state.status === 'standalone' ? (
24
- <Notice tone="info" title="当前是浏览器独立预览">
25
- Cloud SDK 只能在 zleapOS 的应用窗口里连接宿主。运行 <code>npm run deploy</code> 部署后从启动台打开;
26
- 这里只用于调样式,不会展示任何数据。
27
- </Notice>
27
+ {state.status === 'preview' ? (
28
+ <Alert tone="info" title="预览模式 · 示例数据">
29
+ 没有连接 zleapOS,改动不会保存。部署(<code>npm run deploy</code>)后从启动台打开才是真实数据。
30
+ </Alert>
28
31
  ) : null}
29
32
  {state.status === 'error' ? (
30
- <Notice tone="bad" title="连接 zleapOS 失败" action={<button onClick={retry}>重试</button>}>
33
+ <Alert
34
+ tone="danger"
35
+ title="连接 zleapOS 失败"
36
+ action={
37
+ <button className="zl-btn zl-btn--sm" onClick={retry}>
38
+ 重试
39
+ </button>
40
+ }
41
+ >
31
42
  {describeError({ errCode: state.code })}
32
- </Notice>
43
+ </Alert>
33
44
  ) : null}
34
- {state.status === 'ready' && !hasProfile(state.capabilities, 'document-core/1') ? (
35
- <Notice tone="warn" title="数据库能力未就绪">
36
- 宿主没有协商到 document-core/1:通常是开发环境或数据库尚未开通,或窗口顶部「权限」里没有勾选数据读写。
37
- </Notice>
45
+ {state.status === 'ready' && !ready ? (
46
+ <Alert tone="warning" title="数据库能力未就绪">
47
+ 通常是开发环境或数据库还在开通,或窗口顶部「权限」里没有勾选数据读写。
48
+ </Alert>
38
49
  ) : null}
39
- {state.status === 'ready' && hasProfile(state.capabilities, 'document-core/1') ? <TodoBoard /> : null}
50
+ {state.status === 'connecting' ? <ListSkeleton /> : null}
51
+ {ready ? <TodoBoard /> : null}
40
52
  </main>
41
53
  );
42
54
  }
@@ -44,16 +56,19 @@ export function App() {
44
56
  function TodoBoard() {
45
57
  const [todos, setTodos] = useState<Todo[]>([]);
46
58
  const [loading, setLoading] = useState(true);
59
+ const [loadError, setLoadError] = useState('');
47
60
  const [busy, setBusy] = useState(false);
48
- const [message, setMessage] = useState<{ tone: 'ok' | 'bad' | 'warn'; text: string } | null>(null);
61
+ const [message, setMessage] = useState<{ tone: 'warning' | 'danger'; text: string } | null>(null);
49
62
  const [filter, setFilter] = useState<Filter>('all');
50
63
  const [title, setTitle] = useState('');
64
+ const toast = useToast();
51
65
 
52
66
  const reload = useCallback(async () => {
53
67
  try {
54
68
  setTodos(await listTodos());
69
+ setLoadError('');
55
70
  } catch (error) {
56
- setMessage({ tone: 'bad', text: `读取失败:${describeError(error)}` });
71
+ setLoadError(describeError(error));
57
72
  } finally {
58
73
  setLoading(false);
59
74
  }
@@ -70,11 +85,11 @@ function TodoBoard() {
70
85
  setMessage(null);
71
86
  try {
72
87
  await action();
73
- setMessage({ tone: 'ok', text: success });
88
+ toast.show(success);
74
89
  } catch (error) {
75
90
  // 结果未知时不自动重试:先重读,让用户看到真实状态再决定。
76
91
  const unknown = errorCode(error) === 'COMMIT_UNKNOWN';
77
- setMessage({ tone: unknown ? 'warn' : 'bad', text: describeError(error) });
92
+ setMessage({ tone: unknown ? 'warning' : 'danger', text: describeError(error) });
78
93
  } finally {
79
94
  await reload();
80
95
  setBusy(false);
@@ -88,7 +103,7 @@ function TodoBoard() {
88
103
  void mutate(async () => {
89
104
  await addTodo(value);
90
105
  setTitle('');
91
- }, '已保存');
106
+ }, '已添加');
92
107
  };
93
108
 
94
109
  const visible = useMemo(
@@ -98,9 +113,10 @@ function TodoBoard() {
98
113
  const doneCount = todos.filter((todo) => todo.done).length;
99
114
 
100
115
  return (
101
- <section className="board">
102
- <form className="composer" onSubmit={submit}>
116
+ <>
117
+ <form className="zl-composer" onSubmit={submit}>
103
118
  <input
119
+ className="zl-input"
104
120
  value={title}
105
121
  onChange={(event) => setTitle(event.target.value)}
106
122
  placeholder="下一件想完成的事…"
@@ -108,48 +124,74 @@ function TodoBoard() {
108
124
  aria-label="新待办"
109
125
  disabled={busy}
110
126
  />
111
- <button type="submit" disabled={busy || !title.trim()}>
127
+ <button className="zl-btn zl-btn--primary" type="submit" disabled={!title.trim()} aria-busy={busy}>
112
128
  添加
113
129
  </button>
114
130
  </form>
115
131
 
116
- <div className="toolbar">
117
- <div className="filters" role="group" aria-label="筛选">
118
- {(['all', 'active', 'done'] as const).map((value) => (
119
- <button key={value} aria-pressed={filter === value} onClick={() => setFilter(value)}>
120
- {{ all: '全部', active: '未完成', done: '已完成' }[value]}
121
- </button>
122
- ))}
132
+ {message ? <Alert tone={message.tone} title={message.tone === 'warning' ? '请先核对' : '操作失败'}>{message.text}</Alert> : null}
133
+
134
+ <section className="zl-section">
135
+ <div className="zl-section-title">
136
+ <div className="zl-segmented" role="group" aria-label="筛选">
137
+ {(['all', 'active', 'done'] as const).map((value) => (
138
+ <button key={value} type="button" aria-pressed={filter === value} onClick={() => setFilter(value)}>
139
+ {{ all: '全部', active: '未完成', done: '已完成' }[value]}
140
+ </button>
141
+ ))}
142
+ </div>
143
+ <span className="zl-num zl-text-sm">
144
+ {doneCount} / {todos.length} 已完成
145
+ </span>
123
146
  </div>
124
- <span className="summary">
125
- {doneCount} 完成 · {todos.length - doneCount} 待办
126
- </span>
127
- <button className="ghost" onClick={() => void reload()} disabled={busy}>
128
- 刷新
129
- </button>
130
- </div>
131
147
 
132
- {message ? <p className={`message is-${message.tone}`}>{message.text}</p> : null}
148
+ {todos.length > 0 ? (
149
+ <div className="zl-progress" aria-hidden>
150
+ <span style={{ width: `${Math.round((doneCount / todos.length) * 100)}%` }} />
151
+ </div>
152
+ ) : null}
133
153
 
134
- {loading ? (
135
- <p className="empty">正在读取…</p>
136
- ) : visible.length === 0 ? (
137
- <p className="empty">这里还很安静。写下第一件小事吧。</p>
138
- ) : (
139
- <ul className="list">
140
- {visible.map((todo) => (
141
- <TodoRow
142
- key={todo.id}
143
- todo={todo}
144
- busy={busy}
145
- onToggle={() => void mutate(() => updateTodo(todo, { done: !todo.done }), '已更新')}
146
- onRename={(next) => void mutate(() => updateTodo(todo, { title: next }), '已更新')}
147
- onRemove={() => void mutate(() => removeTodo(todo), '已删除')}
148
- />
149
- ))}
150
- </ul>
151
- )}
152
- </section>
154
+ {loading ? (
155
+ <ListSkeleton />
156
+ ) : loadError ? (
157
+ <Alert
158
+ tone="danger"
159
+ title="读取失败"
160
+ action={
161
+ <button className="zl-btn zl-btn--sm" onClick={() => void reload()}>
162
+ 重试
163
+ </button>
164
+ }
165
+ >
166
+ {loadError}
167
+ </Alert>
168
+ ) : visible.length === 0 ? (
169
+ <div className="zl-empty">
170
+ <div className="zl-empty-icon" aria-hidden>
171
+ ✓
172
+ </div>
173
+ <p className="zl-empty-title">{todos.length === 0 ? '还没有待办' : '这里没有内容'}</p>
174
+ <p className="zl-empty-text">
175
+ {todos.length === 0 ? '在上面写下第一件想完成的事。' : '换个筛选条件看看。'}
176
+ </p>
177
+ </div>
178
+ ) : (
179
+ <ul className="zl-list">
180
+ {visible.map((todo) => (
181
+ <TodoRow
182
+ key={todo.id}
183
+ todo={todo}
184
+ busy={busy}
185
+ onToggle={() => void mutate(() => updateTodo(todo, { done: !todo.done }), todo.done ? '已恢复' : '已完成')}
186
+ onRename={(next) => void mutate(() => updateTodo(todo, { title: next }), '已保存')}
187
+ onRemove={() => void mutate(() => removeTodo(todo), '已删除')}
188
+ />
189
+ ))}
190
+ </ul>
191
+ )}
192
+ </section>
193
+ {toast.node}
194
+ </>
153
195
  );
154
196
  }
155
197
 
@@ -167,71 +209,160 @@ function TodoRow({
167
209
  onRemove: () => void;
168
210
  }) {
169
211
  const [editing, setEditing] = useState(false);
212
+ const [confirming, setConfirming] = useState(false);
170
213
  const [draft, setDraft] = useState(todo.title);
171
214
 
172
215
  if (editing) {
173
216
  return (
174
- <li className="row">
175
- <input value={draft} maxLength={200} onChange={(event) => setDraft(event.target.value)} aria-label="编辑待办" />
176
- <button
177
- disabled={busy || !draft.trim()}
178
- onClick={() => {
179
- onRename(draft.trim());
180
- setEditing(false);
181
- }}
182
- >
183
- 保存
184
- </button>
185
- <button className="ghost" onClick={() => setEditing(false)}>
186
- 取消
187
- </button>
217
+ <li className="zl-list-item">
218
+ <input
219
+ className="zl-input"
220
+ value={draft}
221
+ maxLength={200}
222
+ autoFocus
223
+ onChange={(event) => setDraft(event.target.value)}
224
+ aria-label="编辑待办"
225
+ />
226
+ <div className="zl-item-actions">
227
+ <button
228
+ className="zl-btn zl-btn--primary zl-btn--sm"
229
+ disabled={busy || !draft.trim()}
230
+ onClick={() => {
231
+ onRename(draft.trim());
232
+ setEditing(false);
233
+ }}
234
+ >
235
+ 保存
236
+ </button>
237
+ <button className="zl-btn zl-btn--ghost zl-btn--sm" onClick={() => setEditing(false)}>
238
+ 取消
239
+ </button>
240
+ </div>
188
241
  </li>
189
242
  );
190
243
  }
191
244
  return (
192
- <li className={`row${todo.done ? ' is-done' : ''}`}>
193
- <input type="checkbox" checked={todo.done} disabled={busy} onChange={onToggle} aria-label={`完成:${todo.title}`} />
194
- <span className="title">{todo.title}</span>
195
- <button
196
- className="ghost"
245
+ <li className={`zl-list-item${todo.done ? ' is-done' : ''}`}>
246
+ <input
247
+ className="zl-check"
248
+ type="checkbox"
249
+ checked={todo.done}
197
250
  disabled={busy}
198
- onClick={() => {
199
- setDraft(todo.title);
200
- setEditing(true);
201
- }}
202
- >
203
- 编辑
204
- </button>
205
- <button className="ghost danger" disabled={busy} onClick={onRemove}>
206
- 删除
207
- </button>
251
+ onChange={onToggle}
252
+ aria-label={`完成:${todo.title}`}
253
+ />
254
+ <div className="zl-item-main">
255
+ <span className="zl-item-title">{todo.title}</span>
256
+ <span className="zl-item-meta">{formatTime(todo.createdAt)}</span>
257
+ </div>
258
+ {/* 沙箱里不能用 confirm():危险操作用行内二次确认。 */}
259
+ {confirming ? (
260
+ <div className="zl-item-actions">
261
+ <button
262
+ className="zl-btn zl-btn--danger zl-btn--sm"
263
+ disabled={busy}
264
+ onClick={() => {
265
+ setConfirming(false);
266
+ onRemove();
267
+ }}
268
+ >
269
+ 确认删除
270
+ </button>
271
+ <button className="zl-btn zl-btn--ghost zl-btn--sm" onClick={() => setConfirming(false)}>
272
+ 取消
273
+ </button>
274
+ </div>
275
+ ) : (
276
+ <div className="zl-item-actions zl-item-actions--hover">
277
+ <button
278
+ className="zl-btn zl-btn--ghost zl-btn--sm"
279
+ disabled={busy}
280
+ onClick={() => {
281
+ setDraft(todo.title);
282
+ setEditing(true);
283
+ }}
284
+ >
285
+ 编辑
286
+ </button>
287
+ <button className="zl-btn zl-btn--ghost zl-btn--sm" disabled={busy} onClick={() => setConfirming(true)}>
288
+ 删除
289
+ </button>
290
+ </div>
291
+ )}
208
292
  </li>
209
293
  );
210
294
  }
211
295
 
212
- function ConnectionBadge({ status }: { status: string }) {
213
- const label = { connecting: '正在连接 OS', ready: '● OS 已连接', standalone: '独立预览', error: '连接需要处理' }[status];
214
- return <span className={`badge is-${status}`}>{label}</span>;
296
+ function ConnectionStatus({ status }: { status: string }) {
297
+ const state = status === 'ready' ? 'ready' : status === 'error' ? 'error' : status === 'preview' ? 'preview' : 'connecting';
298
+ const label = { connecting: '正在连接', ready: '已连接 zleapOS', error: '连接失败', preview: '预览模式' }[state];
299
+ return (
300
+ <span className="zl-status" data-state={state}>
301
+ {label}
302
+ </span>
303
+ );
215
304
  }
216
305
 
217
- function Notice({
306
+ function Alert({
218
307
  tone,
219
308
  title,
220
309
  children,
221
310
  action,
222
311
  }: {
223
- tone: 'info' | 'warn' | 'bad';
312
+ tone: 'info' | 'warning' | 'danger';
224
313
  title: string;
225
314
  children: ReactNode;
226
315
  action?: ReactNode;
227
316
  }) {
228
317
  return (
229
- <div className={`notice is-${tone}`} role={tone === 'bad' ? 'alert' : 'status'}>
318
+ <div className={`zl-alert zl-alert--${tone}`} role={tone === 'danger' ? 'alert' : 'status'}>
230
319
  <div>
231
320
  <strong>{title}</strong>
232
- <p>{children}</p>
321
+ {children}
233
322
  </div>
234
323
  {action}
235
324
  </div>
236
325
  );
237
326
  }
327
+
328
+ function ListSkeleton() {
329
+ return (
330
+ <ul className="zl-list" aria-busy="true" aria-label="正在读取">
331
+ {[68, 45, 56].map((width) => (
332
+ <li key={width} className="zl-list-item">
333
+ <span className="zl-skeleton" style={{ width: 18, height: 18 }} />
334
+ <span className="zl-skeleton" style={{ width: `${width}%` }} />
335
+ </li>
336
+ ))}
337
+ </ul>
338
+ );
339
+ }
340
+
341
+ /** 操作成功的轻提示:2 秒后自动消失(沙箱里不能用 alert)。 */
342
+ function useToast() {
343
+ const [text, setText] = useState('');
344
+ const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
345
+ useEffect(() => () => clearTimeout(timer.current), []);
346
+ return {
347
+ show(next: string) {
348
+ clearTimeout(timer.current);
349
+ setText(next);
350
+ timer.current = setTimeout(() => setText(''), 2000);
351
+ },
352
+ node: text ? (
353
+ <div className="zl-toast" role="status">
354
+ {text}
355
+ </div>
356
+ ) : null,
357
+ };
358
+ }
359
+
360
+ function formatTime(ms: number) {
361
+ if (!ms) return '';
362
+ const date = new Date(ms);
363
+ const today = new Date();
364
+ const sameDay = date.toDateString() === today.toDateString();
365
+ return sameDay
366
+ ? `今天 ${date.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' })}`
367
+ : date.toLocaleDateString('zh-CN', { month: 'numeric', day: 'numeric' });
368
+ }
@@ -8,6 +8,8 @@
8
8
  */
9
9
  import { CloudError, zl, type Capabilities } from '@zleap-ai/app-sdk';
10
10
 
11
+ import { previewApiFetch, previewDatabase } from './preview';
12
+
11
13
  export { CloudError };
12
14
  export type { Capabilities };
13
15
  export type { Document } from '@zleap-ai/app-sdk';
@@ -15,12 +17,12 @@ export type { Document } from '@zleap-ai/app-sdk';
15
17
  export type ConnectionState =
16
18
  | { status: 'connecting' }
17
19
  | { status: 'ready'; capabilities: Capabilities }
18
- | { status: 'standalone' }
20
+ | { status: 'preview' }
19
21
  | { status: 'error'; code: string };
20
22
 
21
23
  let connection: Promise<Capabilities> | null = null;
22
24
 
23
- /** 浏览器直接打开(npm run dev)时没有宿主窗口,SDK 握手只会超时。 */
25
+ /** 浏览器直接打开(npm run preview / dev)时没有宿主窗口:进入预览模式,用 ./preview.ts 的示例数据。 */
24
26
  export function isStandalone(): boolean {
25
27
  try {
26
28
  return window.parent === window;
@@ -29,7 +31,11 @@ export function isStandalone(): boolean {
29
31
  }
30
32
  }
31
33
 
32
- /** 与宿主握手一次;失败后允许重新尝试。 */
34
+ /**
35
+ * 与宿主握手一次;失败后允许重新尝试。
36
+ * 只给云数据库、云函数、云文件用:应用只调 OS 接口(zl.cloud.os.api.fetch)时不要调用它,
37
+ * 平台没为这类应用准备云环境,ready() 会报 ENV_FORBIDDEN。
38
+ */
33
39
  export function connect(): Promise<Capabilities> {
34
40
  if (!connection) {
35
41
  zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV });
@@ -41,10 +47,18 @@ export function connect(): Promise<Capabilities> {
41
47
  return connection;
42
48
  }
43
49
 
44
- export function database() {
50
+ export function database(): ReturnType<typeof zl.cloud.database> {
51
+ // 预览模式只在没有宿主时启用;在 zleapOS 窗口里永远是真实数据。
52
+ if (isStandalone()) return previewDatabase as unknown as ReturnType<typeof zl.cloud.database>;
45
53
  return zl.cloud.database();
46
54
  }
47
55
 
56
+ /** 调 OS 已有接口(路径相对 /api/v1)。不依赖云环境,只调 OS 接口的应用不需要 connect()。 */
57
+ export function osFetch(path: string, init?: RequestInit): Promise<Response> {
58
+ if (isStandalone()) return previewApiFetch(path, init);
59
+ return zl.cloud.os.api.fetch(path, init);
60
+ }
61
+
48
62
  /** 是否协商到了某个能力档(如 document-core/1、storage-object/1、app-execution/1)。 */
49
63
  export function hasProfile(capabilities: Capabilities, profile: string): boolean {
50
64
  return capabilities.profiles.includes(profile);
@@ -57,9 +71,10 @@ export function errorCode(error: unknown): string {
57
71
  }
58
72
 
59
73
  /**
60
- * 面向用户的中文说明。未知错误码原样展示,方便对照文档「状态与错误码」。
74
+ * 面向用户的中文说明,只返回文案、不拼英文错误码;错误码另用 errorCode() 取(埋点、按码分支)。
61
75
  *
62
76
  * 宿主只把错误码(errCode)交给应用,不传服务端的中文说明,所以文案在这里按码维护。
77
+ * 没列出的码给通用提示;对照文档「状态与错误码」排查时看 errorCode() 或 npm run logs。
63
78
  */
64
79
  export function describeError(error: unknown): string {
65
80
  const code = errorCode(error);
@@ -80,5 +95,5 @@ export function describeError(error: unknown): string {
80
95
  RUNTIME_UNAVAILABLE: '云服务暂时不可用,请稍后重试。',
81
96
  RELEASE_UNAVAILABLE: '应用版本已切换,请重新加载应用。',
82
97
  };
83
- return hints[code] ? `${hints[code]}(${code})` : code;
98
+ return hints[code] ?? '操作没有完成,请稍后重试。';
84
99
  }
@@ -0,0 +1,116 @@
1
+ /**
2
+ * 预览模式(npm run preview):浏览器直接打开页面、没有 zleapOS 宿主时,用内存数据把界面渲染出来,
3
+ * 方便调样式、截图自查。只在独立打开时启用;在 zleapOS 窗口里永远连真实数据,出错就如实显示。
4
+ *
5
+ * 示例数据写在下面的 SAMPLE / OS_SAMPLE:新增集合或调用新的 OS 接口时,顺手补一份样例,预览才看得到内容。
6
+ */
7
+ type Row = Record<string, unknown> & { _id: string; _version: string };
8
+ type Query = { field?: string; dir?: 'asc' | 'desc'; skip: number; limit: number; where: Record<string, unknown> };
9
+
10
+ const now = Date.now();
11
+ const SAMPLE: Record<string, Record<string, unknown>[]> = {
12
+ todos: [
13
+ { title: '整理本周会议纪要', done: false, created_at: now - 60_000 },
14
+ { title: '给设计稿补暗色截图', done: false, created_at: now - 3_600_000 },
15
+ { title: '确认上线时间', done: true, created_at: now - 86_400_000 },
16
+ ],
17
+ };
18
+
19
+ /** OS 接口样例:键是「方法 路径(不含查询串)」,值是接口 data 字段。未列出的接口返回空列表。 */
20
+ const OS_SAMPLE: Record<string, unknown> = {
21
+ 'GET /todos': { list: [], total: 0 },
22
+ };
23
+
24
+ const wait = () => new Promise((done) => setTimeout(done, 200));
25
+ let serial = 0;
26
+ const stores = new Map<string, Row[]>();
27
+ const listeners = new Map<string, Set<() => void>>();
28
+
29
+ function store(name: string): Row[] {
30
+ if (!stores.has(name)) {
31
+ stores.set(
32
+ name,
33
+ (SAMPLE[name] ?? []).map((row) => ({ ...row, _id: `preview-${++serial}`, _version: '1' })),
34
+ );
35
+ }
36
+ return stores.get(name)!;
37
+ }
38
+
39
+ function changed(name: string) {
40
+ listeners.get(name)?.forEach((handler) => handler());
41
+ }
42
+
43
+ function builder(name: string, query: Query) {
44
+ const next = (patch: Partial<Query>) => builder(name, { ...query, ...patch });
45
+ return {
46
+ where: (where: Record<string, unknown>) => next({ where: { ...query.where, ...where } }),
47
+ orderBy: (field: string, dir: 'asc' | 'desc' = 'asc') => next({ field, dir }),
48
+ skip: (skip: number) => next({ skip }),
49
+ limit: (limit: number) => next({ limit }),
50
+ async get() {
51
+ await wait();
52
+ let rows = store(name).filter((row) => Object.entries(query.where).every(([key, value]) => row[key] === value));
53
+ if (query.field) {
54
+ const field = query.field;
55
+ const sign = query.dir === 'desc' ? -1 : 1;
56
+ rows = [...rows].sort((a, b) => (a[field]! > b[field]! ? sign : a[field]! < b[field]! ? -sign : 0));
57
+ }
58
+ return { data: rows.slice(query.skip, query.skip + query.limit).map((row) => ({ ...row })) };
59
+ },
60
+ };
61
+ }
62
+
63
+ function collection(name: string) {
64
+ return {
65
+ ...builder(name, { skip: 0, limit: 100, where: {} }),
66
+ async add({ data }: { data: Record<string, unknown> }) {
67
+ await wait();
68
+ const row: Row = { ...data, _id: `preview-${++serial}`, _version: '1' };
69
+ store(name).unshift(row);
70
+ changed(name);
71
+ return { _id: row._id };
72
+ },
73
+ doc(id: string) {
74
+ const find = () => store(name).find((row) => row._id === id);
75
+ return {
76
+ async get() {
77
+ await wait();
78
+ const row = find();
79
+ return { data: row ? { ...row } : null };
80
+ },
81
+ async update({ data }: { data: Record<string, unknown> }) {
82
+ await wait();
83
+ const row = find();
84
+ if (row) Object.assign(row, data, { _version: String(Number(row._version) + 1) });
85
+ changed(name);
86
+ },
87
+ async remove() {
88
+ await wait();
89
+ stores.set(
90
+ name,
91
+ store(name).filter((row) => row._id !== id),
92
+ );
93
+ changed(name);
94
+ },
95
+ };
96
+ },
97
+ onChange(handler: () => void) {
98
+ if (!listeners.has(name)) listeners.set(name, new Set());
99
+ listeners.get(name)!.add(handler);
100
+ return () => listeners.get(name)!.delete(handler);
101
+ },
102
+ };
103
+ }
104
+
105
+ export const previewDatabase = { collection };
106
+
107
+ /** zl.cloud.os.api.fetch 的预览版:返回 { code: 0, data } 形状的 Response。 */
108
+ export async function previewApiFetch(path: string, init: RequestInit = {}): Promise<Response> {
109
+ await wait();
110
+ const key = `${(init.method ?? 'GET').toUpperCase()} ${path.split('?')[0]}`;
111
+ const data = key in OS_SAMPLE ? OS_SAMPLE[key] : { list: [], total: 0 };
112
+ return new Response(JSON.stringify({ code: 0, message: 'preview', data }), {
113
+ status: 200,
114
+ headers: { 'Content-Type': 'application/json' },
115
+ });
116
+ }
@@ -2,10 +2,10 @@ import { useCallback, useEffect, useState } from 'react';
2
2
 
3
3
  import { connect, errorCode, isStandalone, type ConnectionState } from './client';
4
4
 
5
- /** 连接宿主的状态机:standalone(浏览器独立预览)/ connecting / ready / error。 */
5
+ /** 连接宿主的状态机:preview(浏览器独立打开,示例数据)/ connecting / ready / error。 */
6
6
  export function useCloudConnection() {
7
7
  const [state, setState] = useState<ConnectionState>(() =>
8
- isStandalone() ? { status: 'standalone' } : { status: 'connecting' },
8
+ isStandalone() ? { status: 'preview' } : { status: 'connecting' },
9
9
  );
10
10
 
11
11
  const retry = useCallback(() => {