dsh-calendar 0.10.4 → 0.11.1

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.11.1（2026-10-20）
+
+- 修复 calendar_update 传入空字符串时无法清空说明、地点或重复规则的问题；省略字段仍保留原值。
+- 首次使用引导跟随宿主中文 / English，按当前连接、视图和写入行为说明操作，不再承诺所有改删都有额外确认。
+
+## 0.11.0（2026-10-17）
+
+- 设置面板顶部新增「首次使用」分步引导：一次只讲一步，支持上一步/下一步/跳过，看完记在本机不再出现。
+- 引导内容与该插件的实际用法一致；可在开发者工具里清掉 `dsh-first-run:dsh-calendar:v1` 重新查看。
 ## 0.10.4 (2026-10-17)
 
 - 日程与连接表单采用每个实例独立的字段标识，点击标签可聚焦输入框，并提供正确的可访问名称。

package/docs/USAGE.md

@@ -187,7 +187,7 @@ Nextcloud / 自定义 Basic 服务：检查账号、密码或服务要求的应
 - `calendar_health`：离线检查服务商、日历集合地址与 Basic/OAuth 凭据完整性，不回显密钥、不发起网络连接。
 - `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`。结果按开始时间稳定排序
 - `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay/rrule 可选）。严格校验真实日历日期与 `end >= start`
-- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值；ATTENDEE、ORGANIZER、VALARM 等原始属性一并保留，重复规则不再丢失）
+- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值；description、location、rrule 显式传空字符串可清空说明、地点或停止重复；ATTENDEE、ORGANIZER、VALARM 等原始属性一并保留）
 - `calendar_delete`：按 uid 删事件
 - `calendar_search`：按关键词搜事件（只查询 start~end 窗口内的事件，缺省为当前时间前后各 1 年；客户端过滤标题/描述/地点/UID，不区分大小写；`limit` 默认 50、clamp 1-200，结果按开始时间排序）
 

package/lib/client.js

@@ -10,6 +10,84 @@ var module = { exports: {} }; var exports = module.exports;
 "use strict";
 
 const React = require("react");
+var __FR_KEY = "dsh-first-run:dsh-calendar:v1";
+var __FR_TITLE = "日历 · 首次使用（4 步）";
+var __FR_STEPS = [{title:"先测试日历连接",body:"选择 Google、iCloud、Nextcloud 或自建 CalDAV，填写对应登录信息，先测试再保存。"},{title:"查看实际日程",body:"在月、周或议程视图查看日程；重复事件可展开成每次发生的实例。"},{title:"把时间说清楚",body:"新建时说明标题、开始和结束时间；跨时区请带上时区。",tryIt:"下周三下午三点创建一小时的产品评审，地点会议室 A，使用北京时间"},{title:"保存前核对",body:"更改会写入已连接的日历。保存前核对日期和重复规则；删除后无法在插件里撤销。"}];
+var __FR_TITLE_EN = "Calendar · First steps";
+var __FR_STEPS_EN = [{title:"Test the calendar connection",body:"Choose Google, iCloud, Nextcloud or a custom CalDAV service. Fill in its sign-in details, then test before saving."},{title:"View your events",body:"Use the month, week or agenda view. Recurring events can be expanded into individual occurrences."},{title:"Specify the time",body:"Include a title, start and end time. Add a time zone when working across regions.",tryIt:"Create a one-hour product review next Wednesday at 3 pm Beijing time in Meeting Room A."},{title:"Review before saving",body:"Changes are written to the connected calendar. Check dates and recurrence rules before saving; deleted events cannot be undone in this plugin."}];
+
+// ---- first-run guide (shared snippet; keep in sync across plugins) ----
+var __FR_STYLE_ID = 'dsh-first-run-css';
+var __FR_CSS = [
+  '.fr-card{border:1px solid var(--dsw-border,rgba(0,0,0,.10));border-radius:12px;padding:14px 16px;margin:0 0 14px;background:linear-gradient(180deg,rgba(59,130,246,.06),rgba(59,130,246,.02))}',
+  '.fr-head{display:flex;align-items:center;gap:8px;margin-bottom:6px}',
+  '.fr-dot{width:6px;height:6px;border-radius:50%;background:var(--dsw-accent,#3b82f6)}',
+  '.fr-title{font-weight:650;font-size:13.5px}',
+  '.fr-count{margin-left:auto;font-size:11px;color:var(--dsw-text-weak,#6b7280);font-variant-numeric:tabular-nums}',
+  '.fr-step{font-weight:600;font-size:13px;margin:2px 0 4px}',
+  '.fr-body{color:var(--dsw-text-weak,#4b5563);font-size:12.5px;line-height:1.65}',
+  '.fr-try{margin-top:8px;padding:7px 9px;border-radius:8px;background:rgba(59,130,246,.09);font-size:12px;display:flex;gap:8px}',
+  '.fr-try code{font-family:ui-monospace,monospace;white-space:pre-wrap;word-break:break-word}',
+  '.fr-bar{display:flex;gap:8px;align-items:center;margin-top:12px}',
+  '.fr-progress{display:flex;gap:4px;margin-right:auto}',
+  '.fr-seg{width:16px;height:3px;border-radius:2px;background:var(--dsw-border,rgba(0,0,0,.12))}',
+  '.fr-seg.on{background:var(--dsw-accent,#3b82f6)}',
+  '.fr-btn{border:1px solid var(--dsw-border,rgba(0,0,0,.14));background:transparent;color:inherit;border-radius:8px;padding:4px 10px;font-size:12px;cursor:pointer}',
+  '.fr-btn:hover{background:rgba(0,0,0,.04)}',
+  '.fr-btn.primary{background:var(--dsw-accent,#3b82f6);border-color:transparent;color:#fff}',
+  '.fr-btn.ghost{border-color:transparent;color:var(--dsw-text-weak,#6b7280)}',
+].join('\n');
+function __frEnsureCss() {
+  if (typeof document === 'undefined' || document.getElementById(__FR_STYLE_ID)) return;
+  var el = document.createElement('style');
+  el.id = __FR_STYLE_ID;
+  el.textContent = __FR_CSS;
+  document.head.appendChild(el);
+}
+function __frRead() { try { return localStorage.getItem(__FR_KEY) === 'done'; } catch (e) { return false; } }
+function __frWrite() { try { localStorage.setItem(__FR_KEY, 'done'); } catch (e) {} }
+function __FirstRunCard() {
+  useUILanguage();
+  var english = UI_LANG === 'en';
+  try { if (activeLocaleService?.getSnapshot) english = localeToLang(activeLocaleService.getSnapshot().active) === 'en'; } catch {}
+  var steps = english ? __FR_STEPS_EN : __FR_STEPS;
+  var text = (zh, en) => english ? en : zh;
+  var doneState = React.useState(__frRead);
+  var done = doneState[0], setDone = doneState[1];
+  var idxState = React.useState(0);
+  var index = idxState[0], setIndex = idxState[1];
+  React.useEffect(function () { __frEnsureCss(); }, []);
+  if (done) return null;
+  var step = steps[index];
+  var last = index >= steps.length - 1;
+  var close = function () { __frWrite(); setDone(true); };
+  var kids = [
+    React.createElement('div', { className: 'fr-head', key: 'h' },
+      React.createElement('span', { className: 'fr-dot' }),
+      React.createElement('span', { className: 'fr-title' }, english ? __FR_TITLE_EN : __FR_TITLE),
+      React.createElement('span', { className: 'fr-count' }, (index + 1) + ' / ' + steps.length)),
+    React.createElement('div', { className: 'fr-step', key: 't' }, step.title),
+    React.createElement('div', { className: 'fr-body', key: 'b' }, step.body),
+  ];
+  if (step.tryIt) kids.push(React.createElement('div', { className: 'fr-try', key: 'y' },
+    React.createElement('span', null, text('可以直接说', 'Try saying')),
+    React.createElement('code', null, text('「', '“') + step.tryIt + text('」', '”'))));
+  var buttons = [React.createElement('div', { className: 'fr-progress', key: 'p' }, steps.map(function (_, i) {
+    return React.createElement('span', { key: i, className: 'fr-seg' + (i <= index ? ' on' : '') });
+  }))];
+  buttons.push(React.createElement('button', { className: 'fr-btn ghost', type: 'button', onClick: close, key: 's' }, text('跳过', 'Skip')));
+  if (index > 0) buttons.push(React.createElement('button', { className: 'fr-btn', type: 'button', key: 'prev', onClick: function () { setIndex(index - 1); } }, text('上一步', 'Back')));
+  buttons.push(React.createElement('button', { className: 'fr-btn primary', type: 'button', key: 'next', onClick: function () { if (last) close(); else setIndex(index + 1); } }, last ? text('开始使用', 'Start') : text('下一步', 'Next')));
+  kids.push(React.createElement('div', { className: 'fr-bar', key: 'bar' }, buttons));
+  return React.createElement('div', { className: 'fr-card' }, kids);
+}
+function __withFirstRun(Component) {
+  return function FirstRunWrapped(props) {
+    return React.createElement(React.Fragment, null, React.createElement(__FirstRunCard, null), React.createElement(Component, props));
+  };
+}
+// ---- end first-run guide ----
+
 const { useState, useEffect, useMemo, useRef, useCallback, useId } = React;
 const h = React.createElement;
 
@@ -2195,7 +2273,7 @@ function apply(ctx) {
         return UI[lang]["nav.title"];
       },
       inject: () => ({})
-    }, CalendarSection));
+    }, __withFirstRun(CalendarSection)));
   } catch (e) { /* 没有 slots 服务：仍是合法的插件，只是没有设置页 */ }
 
   try {

package/lib/tools.js

@@ -24,6 +24,11 @@ export function optionalString(args, key) {
     const value = args[key];
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 }
+/** An omitted patch preserves the field; an explicit empty string clears it. */
+function optionalPatchString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' ? value.trim() : undefined;
+}
 function requiredString(args, key, label) {
     const value = optionalString(args, key);
     if (value === undefined) {
@@ -198,16 +203,16 @@ export function buildCalendarTools(config, env = process.env) {
     };
     const update = {
         name: 'calendar_update',
-        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay、rrule 均可选，未提供的字段保留原值。',
+        description: '按 uid 修改日历事件。uid 必填（来自 calendar_list / calendar_search 返回的 uid）。summary、start、end、description、location、allDay、rrule 均可选，未提供的字段保留原值。description、location、rrule 显式传空字符串可分别清空说明、地点或停止重复。',
         parameters: compileParameters({
             uid: { type: 'string', required: true, description: '事件稳定标识（来自 calendar_list / calendar_search 的 uid，必填）。' },
             summary: { type: 'string', description: '新标题（可选）。' },
             start: { type: 'string', description: '新开始时间（ISO 8601，可选）。' },
             end: { type: 'string', description: '新结束时间（ISO 8601，可选）。' },
-            description: { type: 'string', description: '新描述（可选）。' },
-            location: { type: 'string', description: '新地点（可选）。' },
+            description: { type: 'string', description: '新描述（可选）；空字符串清空说明，省略则保留。' },
+            location: { type: 'string', description: '新地点（可选）；空字符串清空地点，省略则保留。' },
             allDay: { type: 'boolean', description: '是否全天事件（可选）。' },
-            rrule: { type: 'string', description: '新的重复规则（可选）。' },
+            rrule: { type: 'string', description: '新的重复规则（可选）；空字符串停止重复，省略则保留。' },
         }),
         output: {
             schema: {
@@ -238,16 +243,16 @@ export function buildCalendarTools(config, env = process.env) {
                 assertIsoTime(end, 'end');
                 changes.end = end;
             }
-            const description = optionalString(input, 'description');
+            const description = optionalPatchString(input, 'description');
             if (description !== undefined)
                 changes.description = description;
-            const location = optionalString(input, 'location');
+            const location = optionalPatchString(input, 'location');
             if (location !== undefined)
                 changes.location = location;
             const allDay = optionalBoolean(input, 'allDay');
             if (allDay !== undefined)
                 changes.allDay = allDay;
-            const rrule = optionalString(input, 'rrule');
+            const rrule = optionalPatchString(input, 'rrule');
             if (rrule !== undefined)
                 changes.rrule = rrule;
             const updated = await service().update(uid, changes, executionSignal(exec));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "description": "连接 CalDAV 日历，在 DSH 中查看、创建和调整日程。",
   "type": "module",
   "main": "lib/index.js",