@guandata/guanvis 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guanvis 0.1.20 - 2026-05-28
+
+- 新增普通图表卡片点击联动能力，支持通过 `card.linkTo(...)` 配置卡片之间的字段映射联动。
+- 构建阶段会校验同页联动、字段映射、日期粒度和联动环，提前发现无法发布的联动配置。
+- 补充图表卡片联动文档和测试覆盖，提升联动页面生成稳定性。
+
+## @guandata/guanvis 0.1.19 - 2026-05-26
+
+- 筛选器默认值校验增强，日历筛选器会校验绑定字段类型，避免非日期字段误配日期默认值。
+- 增强来源动态字段、联动筛选器和默认值映射的校验，提前发现无法可靠发布的配置。
+- 补充相关测试覆盖和 builder 参考文档说明，提升复杂筛选器配置的可诊断性。
+
 ## @guandata/guanvis 0.1.18 - 2026-05-25
 
 - 新增 Tab 布局能力，支持通过 `createTab()` / `addPanel()` 组织同页多组可切换内容。

package/README.md

@@ -36,6 +36,18 @@ guanvis publish ./my_dashboard/
 
 ## 版本更新
 
+### 0.1.20
+
+- 新增普通图表卡片点击联动能力，支持通过 `card.linkTo(...)` 配置卡片之间的字段映射联动。
+- 构建阶段会校验同页联动、字段映射、日期粒度和联动环，提前发现无法发布的联动配置。
+- 补充图表卡片联动文档和测试覆盖，提升联动页面生成稳定性。
+
+### 0.1.19
+
+- 增强日历筛选器默认值校验，固定默认值会校验日期格式、区间端点数量、起止顺序和粒度一致性。
+- 日历筛选器会校验绑定字段类型，避免非日期字段误配日期默认值。
+- 新增 `setDefaultDateRange(start, end)` 辅助方法，配置日期区间默认值更直接。
+
 ### 0.1.18
 
 - 新增 Tab 布局能力，支持通过 `createTab()` / `addPanel()` 组织同页多组可切换内容。

package/package.json

@@ -1,17 +1,10 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"
   },
-  "scripts": {
-    "build": "node scripts/build.js && node scripts/sync-skill.js",
-    "test:build-script": "node scripts/build.test.js",
-    "changelog": "node ../../scripts/generate-release-changelog.js .",
-    "check-changelog": "node ../../scripts/check-release-changelog.js .",
-    "prepublishOnly": "npm run test:build-script && npm run check-changelog && npm run build && node scripts/preflight.js"
-  },
   "files": [
     "bin/",
     "binaries/",
@@ -37,7 +30,6 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   }
 }

package/skills/guanvis/SKILL.md

@@ -36,7 +36,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 7. **calcField 命名**：不能与数据集物理字段同名，否则 BI 默认取数据集字段
 8. **calcField 类型**：`aggregation`（默认）公式必须含聚合函数；纯算术用 `{ calculationType: "normal" }`；窗口函数用 `{ calculationType: "window" }`
 9. **明细/滚动表 calcField**：`DETAIL_TABLE` / `SCROLL_TABLE` 只做逐行展示；如需行级计算，必须写 `{ calculationType: "normal" }`，且不要写任何 SQL 聚合函数或窗口函数。汇总需求改用非明细图表 `aggrType` / aggregation calcField，或 ETL 预计算
-10. **selector 联动**：必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`
+10. **联动**：筛选器联动必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`；普通图表卡片联动普通图表用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；详细规则见 `references/builder-reference.md`
 11. **selector 类型选择**：离散值（区域/类别）→ `DS_ELEMENTS`（默认）；连续数值（利润率/金额）→ `.setSelectorType(SelectorType.DS_INTERVAL)`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setTimeMacroOptions(options)`
 12. **同环比默认**：用户说同比/环比/同环比/年同比/月环比且未指定输出值时，默认用增长率；未指定模式时默认按日期筛选模式（`ComparativeMode.FILTER_BASED`），普通模式需显式指定 `ComparativeMode.NORMAL`
 13. **placeCard 索引**：按 registerCard → registerTextCard 调用顺序累加，文件按文件名排序加载。**registerSelector 不参与 card index 计数**

package/skills/guanvis/references/builder-reference.md

@@ -24,6 +24,7 @@
 | `.setThemeColor(tcId, colors)` | 主题颜色 |
 | `.setLimit(count)` | 数据行数限制 |
 | `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式/辅助线 |
+| `.linkTo(cardIndex, config)` | 普通图表卡片点击联动普通图表卡片，详细规则见本节 Card Linkage |
 | `.setRawSettings(key, value)` | 原始设置 |
 | `.build()` | 构建（触发验证） |
 
@@ -111,6 +112,64 @@
 
 > **迁移建议**：Tableau 的 Reference Line 对应 `setAuxiliaryLine`，Reference Band 暂无直接等价，可用辅助线近似。条件格式主要用于表格类图表的单元格着色。
 
+#### Card Linkage（图表卡片点击联动）
+
+`CardBuilder.linkTo(cardIndex, config)` 用于让一个普通图表卡片在点击维度值后过滤同一页面内的目标普通图表卡片。
+通过 `settings.asFilter` 配置联动关系，通过 `settings.interaction`配置默认交互，不是 selector 联动。
+
+```javascript
+// card_00_region_sales.js
+var card = createCard(ChartType.GROUPED_COLUMN, "区域销售")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetric(f("销售额", { aggrType: AggrType.SUM }))
+    .linkTo(1, {
+        fields: [
+            { source: "区域", target: "区域" }
+        ]
+    });
+
+registerCard(card.build());
+```
+
+`cardIndex` 和页面布局中的 `card: n` 含义一致，按 `registerCard` / `registerTextCard` / `registerImageCard` / `registerCustomChart` 等可布局资源的注册顺序解析；`registerSelector` 不参与该 index。注意它和 `SelectorBuilder.linkTo(cardIndex)` 不同，selector 的 index 仍是历史普通图表注册顺序。
+
+构建阶段会按当前点击动作重算 `interaction`：只有联动一个动作时默认直接联动；如果已有跳转、下钻等其它点击动作，会切换为菜单选择。
+
+限制：
+
+- 仅支持同一页面内普通图表卡片互相联动；source 卡片不能跨 page 复用，也不能已有 `settings.asFilter`。
+- source 只能用 `.addRow(...)` / `.addColumn(...)` 添加的维度；target 使用目标卡片绑定的数据集字段。
+- 一次 `.linkTo(...)` 声明一组 `{ source, target }`；多个目标多次调用。
+- 日期联动会按 source 日期粒度对齐目标日期字段；source 使用月/季度/年等粒度时，用 `field(..., { granularity })` 表达该粒度。
+- 构建阶段会校验字段、同页关系和联动环。
+
+```javascript
+var month = field(DS, "日期", { granularity: Granularity.MONTH });
+
+var trend = createCard(ChartType.BASIC_LINE, "月度趋势")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindDataset(DS)
+    .addRow(month)
+    .addMetric(f("订单数", { aggrType: AggrType.SUM }));
+
+var source = createCard(ChartType.GROUPED_COLUMN, "月度区域销售")
+    .setId("cccccccccccccccccccccccc")
+    .bindDataset(DS)
+    .addRow(month)
+    .addMetric(f("销售额", { aggrType: AggrType.SUM }))
+    .linkTo(0, {
+        fields: [
+            // target 写原始日期字段名时，会按 source 的 MONTH 粒度自动对齐
+            { source: month, target: "日期" }
+        ]
+    });
+
+registerCard(trend.build());  // layout card index 0
+registerCard(source.build()); // source linkTo(0) targets trend
+```
+
 ### PageBuilder
 
 **布局单位**：
@@ -223,6 +282,7 @@ registerPage(page.build());
 | `.setDefaultType(type)` | 默认值类型：`SelectorDefaultType.FIRST_PICK`（默认）、`FIXED_VALUE` 或 `ALL` |
 | `.setDefaultAll()` | 设置默认"全部"（不筛选），等价于 `setDefaultType(SelectorDefaultType.ALL)` |
 | `.setDefaultValue(values, displayValues?)` | 设置固定默认值，自动切换为 FIXED_VALUE 类型 |
+| `.setDefaultDateRange(start, end, displayValues?)` | 设置 `CALENDAR` 日期区间默认值，自动切换为 FIXED_VALUE；比手写数组更不容易漏填区间端点 |
 | `.setFirstPickLink(bool)` | FIRST_PICK 模式下是否联动刷新（默认 false） |
 | `.setDisplayType(type)` | 展示类型（仅 `DS_ELEMENTS` 使用）：`SelectorDisplay.SEARCH_LIST`（单选下拉）、`SEARCH_BOX`（多选下拉）、`CHECKBOX`（复选框）、`RADIO`（单选框）、`BUTTON_GROUP`（按钮组）。不设置时根据 multiSelect 自动选择。`DS_INTERVAL` 类型不需要此设置 |
 | `.setShowSelectAll(bool)` | 是否显示"全选"（默认 true） |
@@ -257,6 +317,21 @@ registerSelector(sel);
 // 也可设置 .setFilterType("EQ") 单值等于，或 "GT"/"LT" 等比较
 ```
 
+```javascript
+// selector_03_date.js — 日期范围（CALENDAR）
+var sel = createSelector("日期筛选")
+    .setId("abc123def456abc123def456")
+    .setSelectorType(SelectorType.CALENDAR)
+    .bindField(f("订单日期"))
+    .setDefaultDateRange("2026-01-01", "2026-01-31")
+    .linkToAll()
+    .build();
+registerSelector(sel);
+// CALENDAR 默认 filterType="BT"（区间），固定默认值必须是 2 个日期值。
+// 支持 "2026-01-15"、"2026-01"、"2026-Q1"、"2026-W03"、"2026" 等格式。
+// 同一个默认值数组必须使用同一粒度；未显式 setGranularity 时会从默认值格式推断粒度。
+```
+
 ```javascript
 // selector_03_timemacro.js — 快捷日期（TIME_MACRO）
 var sel = createSelector("快捷日期")