@icen.ai/ui 0.8.0 → 0.8.1

package/dist/behaviors/back-top.mjs

@@ -1,3 +1,10 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/back-top.ts
 function numOr(value, fallback) {
   if (value === void 0 || value === "") return fallback;
@@ -51,7 +58,10 @@ function setup(btn, opts = {}) {
   const scrollHost = !isWindow && targetEl ? targetEl : window;
   scrollHost.addEventListener("scroll", onScroll, { passive: true });
   window.addEventListener("resize", onScroll, { passive: true });
-  const onClick = () => scrollToTop(target, offset);
+  const onClick = () => {
+    scrollToTop(target, offset);
+    emitIcen(btn, "icen:back-top", {});
+  };
   btn.addEventListener("click", onClick);
   apply();
   return () => {
@@ -67,6 +77,7 @@ function initBackTop(opts = {}) {
     const root = opts.root ?? document;
     if (opts.autoCreate) {
       let btn = document.body.querySelector(".back-top[data-back-top-auto]");
+      let created = false;
       if (!btn) {
         btn = document.createElement("button");
         btn.type = "button";
@@ -77,9 +88,13 @@ function initBackTop(opts = {}) {
         const svg = new DOMParser().parseFromString(AUTO_BTN_SVG, "image/svg+xml").documentElement;
         btn.appendChild(document.importNode(svg, true));
         document.body.appendChild(btn);
+        created = true;
       }
       const cleanup = setup(btn, opts);
       if (cleanup) cleanups.push(cleanup);
+      if (created) cleanups.push(() => {
+        btn?.remove();
+      });
     }
     const candidates = [];
     if (root instanceof Element && root.matches(".back-top[data-back-top]")) candidates.push(root);

package/dist/behaviors/carousel.d.mts

@@ -1,4 +1,7 @@
-/** 为 root 下每个 .carousel 初始化（root 自身是 .carousel 也算）。 */
-declare function initCarousel(root?: ParentNode): void;
+/**
+ * 为 root 下每个 .carousel 初始化（root 自身是 .carousel 也算）。
+ * 返回销毁函数：移除本次挂上的全部监听并复位幂等标记（销毁后可重新 init）。SSR 下返回 no-op。
+ */
+declare function initCarousel(root?: ParentNode): () => void;
 
 export { initCarousel };

package/dist/behaviors/carousel.mjs

@@ -1,23 +1,30 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/carousel.ts
 function setup(carousel) {
   const el = carousel;
-  if (el.__icenCarouselInit) return;
-  el.__icenCarouselInit = true;
-  const trackQ = carousel.querySelector(":scope > .carousel-track");
-  if (!trackQ) return;
-  const track = trackQ;
+  if (el.__icenCarouselInit) return void 0;
+  const track = carousel.querySelector(":scope > .carousel-track");
+  if (!track) return void 0;
   const prev = carousel.querySelector(".carousel-arrow--prev");
   const next = carousel.querySelector(".carousel-arrow--next");
   const dotsBox = carousel.querySelector(".carousel-dots");
+  const querySlides = () => Array.from(track.querySelectorAll(":scope > .carousel-slide"));
   let index = 0;
   let slides = querySlides();
   let count = slides.length;
-  if (count === 0) return;
+  if (count === 0) return void 0;
+  el.__icenCarouselInit = true;
   let dots = [];
-  function querySlides() {
-    return Array.from(track.querySelectorAll(":scope > .carousel-slide"));
-  }
+  let dotOffs = [];
   function buildDots() {
+    for (const off of dotOffs) off();
+    dotOffs = [];
     if (!dotsBox) return;
     while (dotsBox.firstChild) dotsBox.removeChild(dotsBox.firstChild);
     dots = [];
@@ -27,7 +34,9 @@ function setup(carousel) {
       dot.type = "button";
       dot.className = "carousel-dot";
       dot.setAttribute("aria-label", `\u7B2C ${i + 1} \u5F20`);
-      dot.addEventListener("click", () => go(i));
+      const onDotClick = () => go(i);
+      dot.addEventListener("click", onDotClick);
+      dotOffs.push(() => dot.removeEventListener("click", onDotClick));
       dotsBox.appendChild(dot);
       dots.push(dot);
     }
@@ -39,7 +48,7 @@ function setup(carousel) {
     if (index >= count) index = Math.max(0, count - 1);
     buildDots();
   }
-  function render() {
+  const render = () => {
     track.style.transform = `translateX(${-index * 100}%)`;
     slides.forEach((s, i) => s.setAttribute("aria-hidden", String(i !== index)));
     dots.forEach((d, i) => {
@@ -47,20 +56,19 @@ function setup(carousel) {
       if (i === index) d.setAttribute("aria-current", "true");
       else d.removeAttribute("aria-current");
     });
-  }
+  };
   function go(i) {
     syncSlides();
     if (count === 0) return;
     index = (i % count + count) % count;
     render();
-    carousel.dispatchEvent(new CustomEvent("icen:carousel-change", {
-      bubbles: true,
-      detail: { index, count }
-    }));
+    emitIcen(carousel, "icen:carousel-change", { index, count });
   }
-  prev?.addEventListener("click", () => go(index - 1));
-  next?.addEventListener("click", () => go(index + 1));
-  carousel.addEventListener("keydown", (ev) => {
+  const onPrev = () => go(index - 1);
+  const onNext = () => go(index + 1);
+  prev?.addEventListener("click", onPrev);
+  next?.addEventListener("click", onNext);
+  const onKeyDown = (ev) => {
     const kev = ev;
     switch (kev.key) {
       case "ArrowLeft":
@@ -80,17 +88,36 @@ function setup(carousel) {
         go(count - 1);
         break;
     }
-  });
+  };
+  carousel.addEventListener("keydown", onKeyDown);
   buildDots();
   render();
+  return () => {
+    prev?.removeEventListener("click", onPrev);
+    next?.removeEventListener("click", onNext);
+    carousel.removeEventListener("keydown", onKeyDown);
+    for (const off of dotOffs) off();
+    dotOffs = [];
+    dotsBox?.replaceChildren();
+    el.__icenCarouselInit = false;
+  };
 }
 function initCarousel(root) {
-  if (typeof document === "undefined") return;
-  const scope = root ?? document;
-  const containers = [];
-  if (scope instanceof Element && scope.matches(".carousel")) containers.push(scope);
-  containers.push(...Array.from(scope.querySelectorAll(".carousel")));
-  for (const c of containers) setup(c);
+  const cleanups = [];
+  if (typeof document !== "undefined") {
+    const scope = root ?? document;
+    const containers = [];
+    if (scope instanceof Element && scope.matches(".carousel")) containers.push(scope);
+    containers.push(...Array.from(scope.querySelectorAll(".carousel")));
+    for (const c of containers) {
+      const cleanup = setup(c);
+      if (cleanup) cleanups.push(cleanup);
+    }
+  }
+  return () => {
+    for (const fn of cleanups) fn();
+    cleanups.length = 0;
+  };
 }
 export {
   initCarousel

package/dist/behaviors/charts.d.mts

@@ -1,4 +1,5 @@
-type ChartTone = 'accent' | 'success' | 'warning' | 'error' | 'muted';
+/** 色调名：内置 5 语义名（经 --token-* 取色）；`string & {}` 保自动补全同时放行 registerChartTone 注册的命名档 */
+type ChartTone = 'accent' | 'success' | 'warning' | 'error' | 'muted' | (string & {});
 interface ChartSeriesOptions extends ChartChromeOptions {
     labels: string[];
     values: number[];
@@ -16,6 +17,20 @@ interface ChartSegmentsOptions extends ChartChromeOptions {
     emptyLabel?: string;
     formatValue?: (value: number) => string;
 }
+/**
+ * 注册自定义调色盘档位（CSS 变量名，宿主须在样式里提供该变量）；tone 取值在
+ * 内置 5 语义名（accent/success/warning/error/muted）与调色盘序号之外的自定义
+ * 命名档。注册后任意 tone 槽位（spec.series[i].tone / segments[].tone / 各渲染器
+ * opts.tone）用该名字取色；查不到该变量时浏览器回退到初始色。
+ *
+ * @example
+ * ```css
+ * :root { --my-brand: #e2543e; }
+ * ```
+ * registerChartTone('brand', '--my-brand');
+ * spec.series[0].tone = 'brand';
+ */
+declare function registerChartTone(name: string, cssVar: string): void;
 /** 多系列系列项（ChartSpec 的 series 与各图型共用形态）；tone 可为语义名或调色盘序号 1..6 */
 interface ChartSeriesSpec {
     name: string;
@@ -35,10 +50,6 @@ interface ChartChromeOptions {
     title?: string;
     legend?: boolean;
 }
-/** 跨渲染存活的图例隐藏状态（renderChart 的 update 复渲染沿用；直调不传=每次新状态） */
-interface ChartLegendState {
-    hidden: boolean | null;
-}
 /** 垂直柱状图（单系列，或 series 多系列分组/堆叠——通用层与 renderChart 消费） */
 interface ChartVBarOptions extends ChartSeriesOptions {
     /** 多系列（labels 共用，values 长度对齐）；缺省回落单系列 values */
@@ -46,13 +57,13 @@ interface ChartVBarOptions extends ChartSeriesOptions {
     /** 多系列时堆叠（默认分组并排） */
     stacked?: boolean;
 }
-declare function renderVBar(el: HTMLElement, opts: ChartVBarOptions): void;
+declare function renderVBar(el: HTMLElement, opts: ChartVBarOptions): HTMLElement;
 /** 水平条形图 */
-declare function renderHBar(el: HTMLElement, opts: ChartSeriesOptions): void;
+declare function renderHBar(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
 /** 堆叠条形图（单条 100% + 图例） */
-declare function renderStack(el: HTMLElement, opts: ChartSegmentsOptions): void;
+declare function renderStack(el: HTMLElement, opts: ChartSegmentsOptions): HTMLElement;
 /** 环形图（SVG stroke-dasharray 累加）+ 图例百分比 */
-declare function renderDonut(el: HTMLElement, opts: ChartSegmentsOptions): void;
+declare function renderDonut(el: HTMLElement, opts: ChartSegmentsOptions): HTMLElement;
 /** 折线图（面积渐变 + 网格 + 数据点 + 底部 ≤7 个轴标签；series 多系列走调色盘 + 可切换图例） */
 interface ChartLineOptions extends ChartSeriesOptions {
     /** 多系列（labels 共用）；缺省回落单系列 values */
@@ -60,12 +71,12 @@ interface ChartLineOptions extends ChartSeriesOptions {
     /** 多系列时是否填充面积（默认首系列填充；area 类型全填充） */
     fill?: boolean;
 }
-declare function renderLine(el: HTMLElement, opts: ChartLineOptions): void;
+declare function renderLine(el: HTMLElement, opts: ChartLineOptions): HTMLElement;
 /** 面积图（与折线同族，以面积填充为视觉主体） */
-declare function renderArea(el: HTMLElement, opts: ChartSeriesOptions): void;
+declare function renderArea(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
 interface RadarSeries {
     name: string;
-    /** 各轴的值（0..max，顺序与 axes 一致）。元素类型须可转 number。 */
+    /** 各轴的值（0..max，顺序与 axes 一致） */
     values: number[];
     tone?: ChartTone;
 }
@@ -82,12 +93,23 @@ interface ChartRadarOptions extends ChartChromeOptions {
     formatValue?: (value: number) => string;
 }
 /** 雷达图（N 轴蛛网 + 多系列多边形 + 图例）。 */
-declare function renderRadar(el: HTMLElement, opts: ChartRadarOptions): void;
+declare function renderRadar(el: HTMLElement, opts: ChartRadarOptions): HTMLElement;
 interface HeatmapDatum {
     /** YYYY-MM-DD；仅用于 tooltip 与首周对齐 */
     date: string;
     value: number;
 }
+/** calendar/heatmap 本地化文案：纯字符串描述符，保持 JSON 可序列化（ChartSpec 是 AI 可调用的纯 JSON 契约，禁函数） */
+interface ChartI18nLabels {
+    /** 周标签（7 项，行序与 weekStart 对齐；缺省 ['一','','三','','五','','日']，weekStart=0 时自动旋转为周日首） */
+    weekdays?: string[];
+    /** 月标签（12 项，索引即月 0..11；缺省 `${m+1}月`） */
+    months?: string[];
+    /** 色阶图例左端文案（默认「少」） */
+    less?: string;
+    /** 色阶图例右端文案（默认「多」） */
+    more?: string;
+}
 interface ChartHeatmapOptions extends ChartChromeOptions {
     /** 精确形态：日期 + 值（旧 → 新）。与 values 二选一，data 优先。 */
     data?: HeatmapDatum[];
@@ -96,13 +118,16 @@ interface ChartHeatmapOptions extends ChartChromeOptions {
     /** 列数（周），默认按数据量推算（向上取整到整周） */
     weeks?: number;
     tone?: ChartTone;
+    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
+    weekStart?: 0 | 1;
+    labels?: ChartI18nLabels;
     emptyLabel?: string;
     formatValue?: (value: number) => string;
 }
-/** GitHub 贡献图式热力格：7 行（周一 → 周日）× N 周列，5 档色阶。 */
-declare function renderHeatmap(el: HTMLElement, opts: ChartHeatmapOptions): void;
+/** GitHub 贡献图式热力格：7 行（默认周一 → 周日，weekStart=0 则周日起）× N 周列，5 档色阶。 */
+declare function renderHeatmap(el: HTMLElement, opts: ChartHeatmapOptions): HTMLElement;
 /** 迷你趋势线（无轴小图，适合嵌入指标卡）。 */
-declare function renderSparkline(el: HTMLElement, opts: ChartSeriesOptions): void;
+declare function renderSparkline(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
 interface ChartGaugeOptions {
     value: number;
     max?: number;
@@ -112,7 +137,7 @@ interface ChartGaugeOptions {
     formatValue?: (value: number) => string;
 }
 /** 进度环（环形单值 + 中心百分比）。 */
-declare function renderGauge(el: HTMLElement, opts: ChartGaugeOptions): void;
+declare function renderGauge(el: HTMLElement, opts: ChartGaugeOptions): HTMLElement;
 interface ChartCalendarOptions extends ChartChromeOptions {
     /** ISO 日期数组（YYYY-MM-DD，与 values 配对；或用 data） */
     dates?: string[];
@@ -120,11 +145,14 @@ interface ChartCalendarOptions extends ChartChromeOptions {
     /** 精确形态：{date, value}[]（与 dates+values 二选一，优先） */
     data?: HeatmapDatum[];
     tone?: ChartTone;
+    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
+    weekStart?: 0 | 1;
+    labels?: ChartI18nLabels;
     emptyLabel?: string;
     formatValue?: (value: number) => string;
 }
-/** 贡献日历（calendar heatmap）：dates → 自动周布局 + 月份标签，GitHub 同款 */
-declare function renderCalendar(el: HTMLElement, opts: ChartCalendarOptions): void;
+/** 贡献日历（calendar heatmap）：dates → 自动周布局 + 月份标签，GitHub 同款。周首日与文案可经 weekStart/labels 本地化。 */
+declare function renderCalendar(el: HTMLElement, opts: ChartCalendarOptions): HTMLElement;
 interface ChartPointSpec {
     x: number;
     y: number;
@@ -142,7 +170,7 @@ interface ChartScatterOptions extends ChartChromeOptions {
     formatValue?: (value: number) => string;
 }
 /** 散点图（可选 size 第三维 → 气泡）；坐标域自动 nice 取整 + 边界刻度 */
-declare function renderScatter(el: HTMLElement, opts: ChartScatterOptions): void;
+declare function renderScatter(el: HTMLElement, opts: ChartScatterOptions): HTMLElement;
 type ChartType = 'line' | 'area' | 'vbar' | 'hbar' | 'stack' | 'donut' | 'radar' | 'heatmap' | 'calendar' | 'sparkline' | 'gauge' | 'scatter';
 /** 数值格式化描述符（替代函数回调——可 JSON 序列化，AI 可给） */
 interface ChartValueFormat {
@@ -203,6 +231,10 @@ interface ChartSpec {
     /** 图例：false = 初始隐藏（头部行的小眼睛仍可再展开）；true/缺省 = 显示 */
     legend?: boolean;
     emptyLabel?: string;
+    /** 本地化透传（calendar/heatmap）：weekStart 0=周日/1=周一 与标签文案，纯字符串保持 JSON 可序列化 */
+    i18n?: ChartI18nLabels & {
+        weekStart?: 0 | 1;
+    };
 }
 /** 格式化描述符 → 函数（底层渲染器的 formatValue 槽） */
 declare function chartFormatValue(format?: ChartValueFormat): (value: number) => string;
@@ -235,9 +267,23 @@ interface ChartHandle {
     update(next: ChartSpec | unknown): void;
     /** icen:chart-<name> 监听糖（hover/click/dblclick/contextmenu）；返回解绑函数 */
     on(name: ChartEventName, listener: (detail: ChartEventDetail, event: Event) => void): () => void;
-    /** 清空渲染并摘除绑定标记（委托随 el 生存期，destroy 后可重新 renderChart） */
+    /** 清空渲染并解绑交互委托（destroy 后可重新 renderChart） */
     destroy(): void;
 }
+/**
+ * 在图表容器上挂交互委托（幂等，沿用 __icenChartBound 标记）：pointer / click /
+ * dblclick / contextmenu 归一到 [data-chart-mark] 标记 → icen:chart-hover
+ * （phase enter/move/leave）/ icen:chart-click / icen:chart-dblclick /
+ * icen:chart-contextmenu（均 bubbles，detail 含 index/seriesIndex/seriesName/
+ * label/value/指针坐标；右键默认 preventDefault），内置 tooltip portal 跟随指针。
+ *
+ * renderChart 内部即调它；12 个底层渲染器（renderVBar…renderScatter）收尾也会
+ * 自动调用——**直调底层渲染器同样能收 icen:chart-\* 事件**，无需经过 renderChart
+ * （detail.chart 报该渲染器的图型）。容器已处于某个绑定了委托的外层图表容器
+ * 内时自动跳过（renderChart → 底层渲染器路径，外层已覆盖该子树，防重复派发）。
+ * 返回解绑函数（移除全部监听并复位标记；解绑后可重新 bind / 重新渲染）。
+ */
+declare function bindChartEvents(root: HTMLElement): () => void;
 /**
  * 统一入口：normalizeChartSpec → inferChartType（type 缺省时）→ 分发到底层
  * 渲染器，并在 el 上挂交互委托（hover/click/dblclick/contextmenu → icen:chart-*，
@@ -247,4 +293,4 @@ interface ChartHandle {
  */
 declare function renderChart(el: HTMLElement, raw: ChartSpec | unknown): ChartHandle;
 
-export { type ChartCalendarOptions, type ChartChromeOptions, type ChartDims, type ChartEventDetail, type ChartEventName, type ChartGaugeOptions, type ChartHandle, type ChartHeatmapOptions, type ChartLegendState, type ChartLineOptions, type ChartMarkData, type ChartPointSpec, type ChartRadarOptions, type ChartScatterOptions, type ChartSegment, type ChartSegmentsOptions, type ChartSeriesOptions, type ChartSeriesSpec, type ChartSpec, type ChartTone, type ChartType, type ChartVBarOptions, type ChartValueFormat, type HeatmapDatum, type RadarSeries, chartFormatValue, inferChartType, normalizeChartSpec, renderArea, renderCalendar, renderChart, renderDonut, renderGauge, renderHBar, renderHeatmap, renderLine, renderRadar, renderScatter, renderSparkline, renderStack, renderVBar };
+export { type ChartCalendarOptions, type ChartChromeOptions, type ChartDims, type ChartEventDetail, type ChartEventName, type ChartGaugeOptions, type ChartHandle, type ChartHeatmapOptions, type ChartI18nLabels, type ChartLineOptions, type ChartMarkData, type ChartPointSpec, type ChartRadarOptions, type ChartScatterOptions, type ChartSegment, type ChartSegmentsOptions, type ChartSeriesOptions, type ChartSeriesSpec, type ChartSpec, type ChartTone, type ChartType, type ChartVBarOptions, type ChartValueFormat, type HeatmapDatum, type RadarSeries, bindChartEvents, chartFormatValue, inferChartType, normalizeChartSpec, registerChartTone, renderArea, renderCalendar, renderChart, renderDonut, renderGauge, renderHBar, renderHeatmap, renderLine, renderRadar, renderScatter, renderSparkline, renderStack, renderVBar };