dsh-matrix-todo 1.0.1 → 1.1.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.1.0
4
+
5
+ - First-run guide: when the panel opens on an empty store, the client sends
6
+ seven localized onboarding to-dos (one per interaction: add, drag, edit,
7
+ quadrant split, settings, overdue coloring, date picker). The Host writes
8
+ them once behind a new `seeded` flag, so deleting the guide never brings it
9
+ back; an existing list is treated as already seeded (no duplicates for
10
+ upgrades).
11
+ - New `seed` API action: idempotent, accepts localized titles from the client,
12
+ validates them like any other create, and stamps their own creation order.
13
+
3
14
  ## 1.0.1
4
15
 
5
16
  - Drop the module-level window guard so the client bundle re-registers after
package/README.md CHANGED
@@ -3,6 +3,7 @@
3
3
  DeepSeek Harness 的侧栏待办插件:主界面是艾森豪威尔矩阵(重要 × 紧急四个象限),可一键切换到「已完成」;数据与界面设置写入本机 profile 下的一个 JSON 文件。
4
4
 
5
5
  - 侧边栏新增入口「四象限待办」,排在自带「待办」之后
6
+ - 首次打开且清单为空时,自动写入一组本地化引导条目(覆盖四个象限、逾期变色与日期面板);删掉后不会再出现
6
7
  - 矩阵视图:立即做 / 计划做 / 委托做 / 别做,四个象限自动撑满面板、各自计数
7
8
  - 拖动四象限中心的圆点即可调整行/列比例,双击圆点恢复均分
8
9
  - 每个象限都能直接点击空白处或底部「+ 添加」就地新增,可为该条设置截止日期
@@ -149,12 +150,15 @@ plugin_manager install_bundle target: <本目录绝对路径>
149
150
  "rowRatio": 0.5,
150
151
  "navLabel": ""
151
152
  },
152
- "reordered": false
153
+ "reordered": false,
154
+ "seeded": true
153
155
  }
154
156
  ```
155
157
 
156
158
  `todos` 的数组顺序就是同象限内的显示顺序。`reordered` 为 `false` 时顺序按创建时间倒序派生(新条目在前);一旦手动拖拽排序,它就变成 `true`,此后数组顺序即你的顺序。`dueDate` 为 `YYYY-MM-DD` 或 `null`。
157
159
 
160
+ `seeded` 表示首次使用引导只写过一次:面板首次打开且清单为空时,会按当前界面语言向 Host 提交 7 条引导待办,Host 写入后把 `seeded` 置为 `true`。之后即使把引导全部删掉,也不会再自动生成。
161
+
158
162
  写盘是「临时文件 + rename」的原子替换,写操作串行排队;文件损坏时会先备份为 `todos.corrupt-<时间戳>.json`,再以空清单 + 默认设置启动。手改文件里的 `settings` 非法值会被忽略并回落到默认值。
159
163
 
160
164
  可在 `cordis.patch.yml` 的插件行里覆盖路径:
@@ -172,6 +176,7 @@ Host 半在 `/matrix-todo/api` 注册 prefix 路由,只接受 POST,并做同
172
176
  | 方法 | body | 说明 |
173
177
  | --- | --- | --- |
174
178
  | `list` | `{}` | 取全部待办与设置 |
179
+ | `seed` | `{ items: [{ title, important, urgent, dueDate? }] }` | 首次使用引导:仅在 `seeded` 为 `false` 时写入,幂等 |
175
180
  | `create` | `{ title, important, urgent, dueDate? }` | 新建 |
176
181
  | `update` | `{ id, title?, important?, urgent?, dueDate? }` | 改字段(含象限标记、截止日期;`dueDate: null` 清除) |
177
182
  | `toggle` | `{ id }` | 完成 / 恢复 |
@@ -180,7 +185,7 @@ Host 半在 `/matrix-todo/api` 注册 prefix 路由,只接受 POST,并做同
180
185
  | `clearCompleted` | `{}` | 清空已完成 |
181
186
  | `saveSettings` | `{ urgentSide?, frame?, radius?, tint?, fontSize?, dueFormat?, titleStyle?, colRatio?, rowRatio?, navLabel? }` | 合并保存界面设置 |
182
187
 
183
- 成功返回 `{ ok: true, result: { todos, settings } }`;失败返回 `{ ok: false, error: { code, message } }`,状态码 `invalid-input` 400 / `not-found` 404 / `io-error` 500。标题去空白后 1–200 字符,清单上限 500 条,圆角 0–24 整数,字号 11–17 整数,`dueDate` 必须是真实存在的 `YYYY-MM-DD` 日期。
188
+ 成功返回 `{ ok: true, result: { todos, settings, seeded } }`;失败返回 `{ ok: false, error: { code, message } }`,状态码 `invalid-input` 400 / `not-found` 404 / `io-error` 500。标题去空白后 1–200 字符,清单上限 500 条,圆角 0–24 整数,字号 11–17 整数,`dueDate` 必须是真实存在的 `YYYY-MM-DD` 日期。
184
189
 
185
190
  ## 文件结构
186
191
 
package/client.js CHANGED
@@ -83,6 +83,13 @@ window.__ModuleLoader__.load({
83
83
  'item.due.overdue': 'Overdue',
84
84
  'item.drag': 'Drag to reorder or move to another quadrant',
85
85
  'item.edit': 'Double-click to edit',
86
+ 'seed.add': 'Click an empty spot or "+ Add" to create a to-do',
87
+ 'seed.drag': 'Drag a to-do to reorder it or move it to another quadrant',
88
+ 'seed.edit': 'Double-click the text to edit it',
89
+ 'seed.split': 'Drag the center dot to resize quadrants; double-click resets',
90
+ 'seed.settings': 'Use the gear to change border, tint, font size, urgent side',
91
+ 'seed.overdue': 'Overdue items turn red',
92
+ 'seed.date': 'Date panel: single-click to preview, double-click to confirm',
86
93
  'quickAdd.due': 'Due date',
87
94
  'toast.praise.1': 'Well done! Right on time.',
88
95
  'toast.praise.2': 'Nice — done before the deadline.',
@@ -167,6 +174,13 @@ window.__ModuleLoader__.load({
167
174
  'item.due.overdue': '已逾期',
168
175
  'item.drag': '拖动可排序,或移到其他象限',
169
176
  'item.edit': '双击编辑',
177
+ 'seed.add': '点空白处或「+ 添加」新增待办',
178
+ 'seed.drag': '拖拽待办可在象限内排序,或移到别的象限',
179
+ 'seed.edit': '双击待办文字即可编辑',
180
+ 'seed.split': '拖动中心圆点调整象限大小,双击复位',
181
+ 'seed.settings': '右上角齿轮可改边框、底色、字号、紧急方向',
182
+ 'seed.overdue': '未按期完成的待办会变红',
183
+ 'seed.date': '日期面板:单击选择,双击确定',
170
184
  'quickAdd.due': '截止日期',
171
185
  'toast.praise.1': 'Well done! 按期完成',
172
186
  'toast.praise.2': '漂亮,正好赶上',
@@ -320,6 +334,30 @@ window.__ModuleLoader__.load({
320
334
  return year === new Date().getFullYear() ? parts[1] + '-' + parts[2] : key;
321
335
  }
322
336
 
337
+ /** Day key `offset` days from today (negative = past). */
338
+ function dayKeyOffset(offset) {
339
+ const date = new Date();
340
+ date.setDate(date.getDate() + offset);
341
+ return dayKeyOf(date);
342
+ }
343
+
344
+ /**
345
+ * First-run guide rows, sent once to the Host with localized titles. They
346
+ * demonstrate all four quadrants, including an overdue row and a date-picker
347
+ * row; the Host flag makes them one-shot, so deleting them sticks.
348
+ */
349
+ function seedItems(t) {
350
+ return [
351
+ { title: t('seed.add'), important: true, urgent: true },
352
+ { title: t('seed.drag'), important: true, urgent: false },
353
+ { title: t('seed.edit'), important: true, urgent: false },
354
+ { title: t('seed.split'), important: true, urgent: false },
355
+ { title: t('seed.settings'), important: false, urgent: true },
356
+ { title: t('seed.overdue'), important: false, urgent: true, dueDate: dayKeyOffset(-3) },
357
+ { title: t('seed.date'), important: false, urgent: false, dueDate: dayKeyOffset(30) },
358
+ ];
359
+ }
360
+
323
361
  /** `overdue` / `today` / `future` for an open todo's due date. */
324
362
  function dueStateOf(dueDate) {
325
363
  if (typeof dueDate !== 'string' || dueDate === '') return null;
@@ -1413,14 +1451,19 @@ window.__ModuleLoader__.load({
1413
1451
 
1414
1452
  const load = useCallback(async () => {
1415
1453
  try {
1416
- applyResult(await fetchApi('list'));
1454
+ let result = await fetchApi('list');
1455
+ // Brand-new store: ask the Host to write the localized guide rows once.
1456
+ if (result.seeded === false && Array.isArray(result.todos) && result.todos.length === 0) {
1457
+ result = await fetchApi('seed', { items: seedItems(t) });
1458
+ }
1459
+ applyResult(result);
1417
1460
  } catch (err) {
1418
1461
  setError(messageOf(err));
1419
1462
  setTodos((current) => (current === null ? [] : current));
1420
1463
  } finally {
1421
1464
  setLoaded(true);
1422
1465
  }
1423
- }, [applyResult, messageOf]);
1466
+ }, [applyResult, messageOf, t]);
1424
1467
 
1425
1468
  useEffect(() => {
1426
1469
  void load();
package/index.js CHANGED
@@ -63,6 +63,7 @@ function refusalOf(ctx, req) {
63
63
 
64
64
  const ACTIONS = {
65
65
  list: (store) => store.list(),
66
+ seed: (store, body) => store.seed(body),
66
67
  create: (store, body) => store.create(body),
67
68
  update: (store, body) => store.update(body),
68
69
  toggle: (store, body) => store.toggle(body),
@@ -73,7 +74,7 @@ const ACTIONS = {
73
74
 
74
75
  /** Every response carries the full list plus the layout preferences. */
75
76
  function resultOf(store) {
76
- return { todos: store.list(), settings: store.settings() }
77
+ return { todos: store.list(), settings: store.settings(), seeded: store.seeded() }
77
78
  }
78
79
 
79
80
  export function apply(ctx, config = {}) {
package/lib/store.js CHANGED
@@ -57,7 +57,7 @@ export class StoreError extends Error {
57
57
  }
58
58
 
59
59
  function emptyDoc() {
60
- return { version: VERSION, todos: [], settings: { ...DEFAULT_SETTINGS }, reordered: false }
60
+ return { version: VERSION, todos: [], settings: { ...DEFAULT_SETTINGS }, reordered: false, seeded: false }
61
61
  }
62
62
 
63
63
  const DAY_RE = /^\d{4}-\d{2}-\d{2}$/
@@ -197,7 +197,7 @@ function corruptBackupPath(file) {
197
197
  export function createStore({ file } = {}) {
198
198
  if (typeof file !== 'string' || file === '') throw new StoreError('invalid-input', '数据文件路径必填')
199
199
  const dataFile = file
200
- const state = { todos: [], settings: { ...DEFAULT_SETTINGS }, reordered: false, corrupt: false, sealed: false }
200
+ const state = { todos: [], settings: { ...DEFAULT_SETTINGS }, reordered: false, seeded: false, corrupt: false, sealed: false }
201
201
  let queue = Promise.resolve()
202
202
  let closed = false
203
203
 
@@ -209,7 +209,7 @@ export function createStore({ file } = {}) {
209
209
  async function persist() {
210
210
  if (state.sealed) throw new StoreError('io-error', CORRUPT_UNBACKUPED)
211
211
  const snapshotText = JSON.stringify(
212
- { version: VERSION, todos: state.todos, settings: state.settings, reordered: state.reordered },
212
+ { version: VERSION, todos: state.todos, settings: state.settings, reordered: state.reordered, seeded: state.seeded },
213
213
  null,
214
214
  2,
215
215
  )
@@ -243,6 +243,9 @@ export function createStore({ file } = {}) {
243
243
  state.todos = sanitizeTodos(doc.todos)
244
244
  state.settings = sanitizeSettings(doc.settings)
245
245
  state.reordered = doc.reordered === true
246
+ // A store that already holds rows, or one that was seeded before, never
247
+ // gets onboarding rows again — deleting the guide must stick.
248
+ state.seeded = corrupt || doc.seeded === true || state.todos.length > 0
246
249
  // Until someone drags a row, the list order is derived: newest first. Once
247
250
  // a drag is saved, the stored array order is the user's own order.
248
251
  if (!state.reordered) state.todos.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
@@ -270,6 +273,45 @@ export function createStore({ file } = {}) {
270
273
  return snapshot()
271
274
  },
272
275
 
276
+ /** True once onboarding rows were written, or when the store was never empty. */
277
+ seeded() {
278
+ return state.seeded
279
+ },
280
+
281
+ /**
282
+ * One-time onboarding rows for a brand-new store. The client sends localized
283
+ * titles; the flag makes the call idempotent and stops the guide from coming
284
+ * back after the user deletes it.
285
+ */
286
+ async seed(input = {}) {
287
+ if (state.seeded) return { added: 0 }
288
+ const source = asRecord(input)
289
+ const rows = Array.isArray(source.items) ? source.items.slice(0, 32) : []
290
+ const now = Date.now()
291
+ const added = []
292
+ rows.forEach((raw, index) => {
293
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return
294
+ const title = typeof raw.title === 'string' ? raw.title.trim() : ''
295
+ if (title === '' || title.length > TITLE_MAX) return
296
+ const createdAt = new Date(now - index * 1000).toISOString()
297
+ added.push({
298
+ id: newId(),
299
+ title,
300
+ important: raw.important === true,
301
+ urgent: raw.urgent === true,
302
+ done: false,
303
+ dueDate: sanitizeDueDate(raw.dueDate),
304
+ createdAt,
305
+ updatedAt: createdAt,
306
+ completedAt: null,
307
+ })
308
+ })
309
+ state.seeded = true
310
+ if (added.length > 0) state.todos = [...added, ...state.todos]
311
+ await guard(persist)
312
+ return { added: added.length }
313
+ },
314
+
273
315
  /** Current layout preferences (a copy; callers cannot mutate the source of truth). */
274
316
  settings() {
275
317
  return { ...state.settings }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-matrix-todo",
3
- "version": "1.0.1",
3
+ "version": "1.1.0",
4
4
  "type": "module",
5
5
  "description": "Eisenhower-matrix to-do list for DeepSeek Harness: four importance/urgency quadrants, drag sorting, due dates, completed view and minimal theme-aware styling.",
6
6
  "license": "MIT",