@icen.ai/ui 0.5.0 → 0.8.1

package/dist/behaviors/back-top.d.mts

@@ -0,0 +1,20 @@
+interface BackTopOptions {
+    /** 是否自动创建一个默认按钮（portal 到 body） */
+    autoCreate?: boolean;
+    /** 显示阈值（px），默认 320 */
+    threshold?: number;
+    /** 滚动容器选择器，默认 window */
+    target?: string;
+    /** 滚动到多少 px，默认 0 */
+    offset?: number;
+    /** 扫描根节点，默认 document */
+    root?: ParentNode;
+}
+/**
+ * 初始化：扫描 root 下的 .back-top[data-back-top] 与 [data-back-top-auto]。
+ * 传 autoCreate 时自动创建一个默认按钮。
+ * 返回销毁函数：移除本次初始化挂上的全部 scroll/resize/click 监听。
+ */
+declare function initBackTop(opts?: BackTopOptions): () => void;
+
+export { initBackTop };

package/dist/behaviors/back-top.mjs

@@ -1,4 +1,16 @@
+// 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;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
 var AUTO_BTN_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>';
 function prefersReducedMotion() {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
@@ -26,11 +38,11 @@ function scrollToTop(target, offset = 0) {
 }
 function setup(btn, opts = {}) {
   const el = btn;
-  if (el.__icenBackTopInit) return;
+  if (el.__icenBackTopInit) return void 0;
   el.__icenBackTopInit = true;
-  const threshold = Number(btn.dataset.backTopThreshold ?? opts.threshold ?? 320) || 320;
+  const threshold = numOr(btn.dataset.backTopThreshold ?? opts.threshold, 320);
   const target = btn.dataset.backTopTarget ?? opts.target;
-  const offset = Number(btn.dataset.backTopOffset ?? opts.offset ?? 0) || 0;
+  const offset = numOr(btn.dataset.backTopOffset ?? opts.offset, 0);
   let ticking = false;
   const apply = () => {
     ticking = false;
@@ -43,41 +55,61 @@ function setup(btn, opts = {}) {
     window.requestAnimationFrame(apply);
   };
   const { el: targetEl, isWindow } = getScrollTarget(target);
-  if (isWindow) {
-    window.addEventListener("scroll", onScroll, { passive: true });
-  } else if (targetEl) {
-    targetEl.addEventListener("scroll", onScroll, { passive: true });
-  }
+  const scrollHost = !isWindow && targetEl ? targetEl : window;
+  scrollHost.addEventListener("scroll", onScroll, { passive: true });
   window.addEventListener("resize", onScroll, { passive: true });
-  btn.addEventListener("click", () => scrollToTop(target, offset));
+  const onClick = () => {
+    scrollToTop(target, offset);
+    emitIcen(btn, "icen:back-top", {});
+  };
+  btn.addEventListener("click", onClick);
   apply();
+  return () => {
+    scrollHost.removeEventListener("scroll", onScroll);
+    window.removeEventListener("resize", onScroll);
+    btn.removeEventListener("click", onClick);
+    el.__icenBackTopInit = false;
+  };
 }
 function initBackTop(opts = {}) {
-  if (typeof document === "undefined") return;
-  if (typeof window === "undefined") return;
-  const root = opts.root ?? document;
-  if (opts.autoCreate) {
-    let btn = document.body.querySelector(".back-top[data-back-top-auto]");
-    if (!btn) {
-      btn = document.createElement("button");
-      btn.type = "button";
-      btn.className = "back-top";
-      btn.setAttribute("data-back-top", "");
-      btn.setAttribute("data-back-top-auto", "");
-      btn.setAttribute("aria-label", "\u56DE\u5230\u9876\u90E8");
-      btn.innerHTML = AUTO_BTN_SVG;
-      document.body.appendChild(btn);
+  const cleanups = [];
+  if (typeof document !== "undefined" && typeof window !== "undefined") {
+    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";
+        btn.className = "back-top";
+        btn.setAttribute("data-back-top", "");
+        btn.setAttribute("data-back-top-auto", "");
+        btn.setAttribute("aria-label", "\u56DE\u5230\u9876\u90E8");
+        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);
+    candidates.push(...Array.from(root.querySelectorAll(".back-top[data-back-top]")));
+    for (const c of candidates) {
+      const el = c;
+      if (el.hasAttribute("data-back-top-auto") && opts.autoCreate) continue;
+      const cleanup = setup(el, opts);
+      if (cleanup) cleanups.push(cleanup);
     }
-    setup(btn, opts);
-  }
-  const candidates = [];
-  if (root instanceof Element && root.matches(".back-top[data-back-top]")) candidates.push(root);
-  candidates.push(...Array.from(root.querySelectorAll(".back-top[data-back-top]")));
-  for (const c of candidates) {
-    const el = c;
-    if (el.hasAttribute("data-back-top-auto") && opts.autoCreate) continue;
-    setup(el, opts);
   }
+  return () => {
+    for (const fn of cleanups) fn();
+    cleanups.length = 0;
+  };
 }
 export {
   initBackTop

package/dist/behaviors/carousel.d.mts

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

package/dist/behaviors/carousel.mjs

@@ -1,50 +1,74 @@
+// 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;
+  if (el.__icenCarouselInit) return void 0;
   const track = carousel.querySelector(":scope > .carousel-track");
-  if (!track) return;
-  const slides = Array.from(track.querySelectorAll(":scope > .carousel-slide"));
-  const count = slides.length;
-  if (count === 0) return;
+  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;
-  const dots = [];
-  if (dotsBox && count > 1) {
+  let slides = querySlides();
+  let count = slides.length;
+  if (count === 0) return void 0;
+  el.__icenCarouselInit = true;
+  let dots = [];
+  let dotOffs = [];
+  function buildDots() {
+    for (const off of dotOffs) off();
+    dotOffs = [];
+    if (!dotsBox) return;
+    while (dotsBox.firstChild) dotsBox.removeChild(dotsBox.firstChild);
+    dots = [];
+    if (count <= 1) return;
     for (let i = 0; i < count; i++) {
       const dot = document.createElement("button");
       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);
     }
   }
-  function render() {
-    if (!track) return;
+  function syncSlides() {
+    slides = querySlides();
+    if (slides.length === count) return;
+    count = slides.length;
+    if (index >= count) index = Math.max(0, count - 1);
+    buildDots();
+  }
+  const render = () => {
     track.style.transform = `translateX(${-index * 100}%)`;
     slides.forEach((s, i) => s.setAttribute("aria-hidden", String(i !== index)));
     dots.forEach((d, i) => {
-      d.classList.toggle("active", i === index);
+      d.classList.toggle("is-active", i === index);
       if (i === index) d.setAttribute("aria-current", "true");
       else d.removeAttribute("aria-current");
     });
-    carousel.dispatchEvent(new CustomEvent("icen:carousel-change", {
-      bubbles: true,
-      detail: { index, count }
-    }));
-  }
+  };
   function go(i) {
+    syncSlides();
+    if (count === 0) return;
     index = (i % count + count) % count;
     render();
+    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":
@@ -64,15 +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 = document) {
-  if (typeof document === "undefined") return;
-  const containers = [];
-  if (root instanceof Element && root.matches(".carousel")) containers.push(root);
-  containers.push(...Array.from(root.querySelectorAll(".carousel")));
-  for (const c of containers) setup(c);
+function initCarousel(root) {
+  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

@@ -0,0 +1,296 @@
+/** 色调名：内置 5 语义名（经 --token-* 取色）；`string & {}` 保自动补全同时放行 registerChartTone 注册的命名档 */
+type ChartTone = 'accent' | 'success' | 'warning' | 'error' | 'muted' | (string & {});
+interface ChartSeriesOptions extends ChartChromeOptions {
+    labels: string[];
+    values: number[];
+    tone?: ChartTone;
+    emptyLabel?: string;
+    formatValue?: (value: number) => string;
+}
+interface ChartSegment {
+    label: string;
+    value: number;
+    tone?: ChartTone;
+}
+interface ChartSegmentsOptions extends ChartChromeOptions {
+    segments: ChartSegment[];
+    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;
+    values: number[];
+    tone?: ChartTone | number;
+}
+/** 交互事件携带的标记数据（renderChart 委托层据此派 icen:chart-* 事件） */
+interface ChartMarkData {
+    index?: number;
+    seriesIndex?: number;
+    seriesName?: string;
+    label?: string;
+    value?: number;
+}
+/** chrome 选项（各渲染器 options 皆含）：title 进头部行；legend=false 初始隐藏图例 */
+interface ChartChromeOptions {
+    title?: string;
+    legend?: boolean;
+}
+/** 垂直柱状图（单系列，或 series 多系列分组/堆叠——通用层与 renderChart 消费） */
+interface ChartVBarOptions extends ChartSeriesOptions {
+    /** 多系列（labels 共用，values 长度对齐）；缺省回落单系列 values */
+    series?: ChartSeriesSpec[];
+    /** 多系列时堆叠（默认分组并排） */
+    stacked?: boolean;
+}
+declare function renderVBar(el: HTMLElement, opts: ChartVBarOptions): HTMLElement;
+/** 水平条形图 */
+declare function renderHBar(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
+/** 堆叠条形图（单条 100% + 图例） */
+declare function renderStack(el: HTMLElement, opts: ChartSegmentsOptions): HTMLElement;
+/** 环形图（SVG stroke-dasharray 累加）+ 图例百分比 */
+declare function renderDonut(el: HTMLElement, opts: ChartSegmentsOptions): HTMLElement;
+/** 折线图（面积渐变 + 网格 + 数据点 + 底部 ≤7 个轴标签；series 多系列走调色盘 + 可切换图例） */
+interface ChartLineOptions extends ChartSeriesOptions {
+    /** 多系列（labels 共用）；缺省回落单系列 values */
+    series?: ChartSeriesSpec[];
+    /** 多系列时是否填充面积（默认首系列填充；area 类型全填充） */
+    fill?: boolean;
+}
+declare function renderLine(el: HTMLElement, opts: ChartLineOptions): HTMLElement;
+/** 面积图（与折线同族，以面积填充为视觉主体） */
+declare function renderArea(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
+interface RadarSeries {
+    name: string;
+    /** 各轴的值（0..max，顺序与 axes 一致） */
+    values: number[];
+    tone?: ChartTone;
+}
+interface ChartRadarOptions extends ChartChromeOptions {
+    /** 各轴名（顺时针排列，首轴指向正上方） */
+    axes: string[];
+    /** 一个或多个系列。values 长度须等于 axes 长度 */
+    series: RadarSeries[];
+    /** 各轴最大值（默认取全部系列该轴最大向上取整） */
+    max?: number;
+    /** 网格环层数（默认 4） */
+    levels?: number;
+    emptyLabel?: string;
+    formatValue?: (value: number) => string;
+}
+/** 雷达图（N 轴蛛网 + 多系列多边形 + 图例）。 */
+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[];
+    /** 便捷形态：最近 N 天的值（旧 → 新），日期从今天回推 */
+    values?: number[];
+    /** 列数（周），默认按数据量推算（向上取整到整周） */
+    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 行（默认周一 → 周日，weekStart=0 则周日起）× N 周列，5 档色阶。 */
+declare function renderHeatmap(el: HTMLElement, opts: ChartHeatmapOptions): HTMLElement;
+/** 迷你趋势线（无轴小图，适合嵌入指标卡）。 */
+declare function renderSparkline(el: HTMLElement, opts: ChartSeriesOptions): HTMLElement;
+interface ChartGaugeOptions {
+    value: number;
+    max?: number;
+    tone?: ChartTone;
+    /** 中心百分比下方的小标签 */
+    label?: string;
+    formatValue?: (value: number) => string;
+}
+/** 进度环（环形单值 + 中心百分比）。 */
+declare function renderGauge(el: HTMLElement, opts: ChartGaugeOptions): HTMLElement;
+interface ChartCalendarOptions extends ChartChromeOptions {
+    /** ISO 日期数组（YYYY-MM-DD，与 values 配对；或用 data） */
+    dates?: string[];
+    values?: number[];
+    /** 精确形态：{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 同款。周首日与文案可经 weekStart/labels 本地化。 */
+declare function renderCalendar(el: HTMLElement, opts: ChartCalendarOptions): HTMLElement;
+interface ChartPointSpec {
+    x: number;
+    y: number;
+    /** 第三维：气泡大小（映射到半径 3–10） */
+    size?: number;
+    label?: string;
+}
+interface ChartScatterOptions extends ChartChromeOptions {
+    points: ChartPointSpec[];
+    tone?: ChartTone;
+    /** X 轴名称（图例/tooltip 用） */
+    xLabel?: string;
+    yLabel?: string;
+    emptyLabel?: string;
+    formatValue?: (value: number) => string;
+}
+/** 散点图（可选 size 第三维 → 气泡）；坐标域自动 nice 取整 + 边界刻度 */
+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 {
+    /** 值后缀单位（"ms" / "¥" / "个"） */
+    unit?: string;
+    /** compact：1.2k/3.4M；percent：原值即百分数补 %；ms：时长自适应（800ms/1.2s/3m）；raw（默认） */
+    notation?: 'compact' | 'percent' | 'ms' | 'raw';
+}
+/** 任意维度数据记录 + 维度映射（data[] 路径：字段名可完全自定义） */
+interface ChartDims {
+    /** 类目/横轴字段（默认 'label'） */
+    label?: string;
+    /** 系列分组字段（默认 'series'；存在即多系列） */
+    series?: string;
+    /** 数值字段（默认 'value'） */
+    value?: string;
+    /** 散点 x 字段（默认 'x'） */
+    x?: string;
+    /** 散点 y 字段（默认 'y'） */
+    y?: string;
+    /** 散点 size 字段（默认 'size'） */
+    size?: string;
+}
+/** 统一图表规格（纯 JSON；type 缺省由 inferChartType 推断） */
+interface ChartSpec {
+    type?: string;
+    title?: string;
+    /** 类目轴（line/area/vbar/hbar） */
+    labels?: string[];
+    /** 单系列值（labels 配对；多系列用 series） */
+    values?: number[];
+    /** 多系列（line/vbar/radar） */
+    series?: ChartSeriesSpec[];
+    /** 占比型（donut/stack） */
+    segments?: ChartSegment[];
+    /** 雷达轴 */
+    axes?: string[];
+    /** 散点（或经 dims 从 data[] 提取） */
+    points?: ChartPointSpec[];
+    /** 任意维度原始记录 + dims 字段映射（pivot 到上述形态） */
+    data?: Record<string, unknown>[];
+    dims?: ChartDims;
+    /** 贡献日历：ISO 日期（与 values 配对） */
+    dates?: string[];
+    tone?: ChartTone;
+    /** vbar 多系列：堆叠（默认分组） */
+    stacked?: boolean;
+    /** line 多系列：填充面积 */
+    fill?: boolean;
+    weeks?: number;
+    /** radar/gauge 的值域上限 */
+    max?: number;
+    /** radar 网格层数 */
+    levels?: number;
+    format?: ChartValueFormat;
+    /** 内置 tooltip（默认开；false 关闭后只派事件） */
+    tooltip?: boolean;
+    /** 图例：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;
+/**
+ * 归一化 ChartSpec：字符串输入尝试 JSON.parse；类型别名纠正；数值容错转换；
+ * data[] + dims pivot 到 labels/values/series/points。不抛异常——纠不了的
+ * 字段丢弃，返回的 spec 一定可交给 infer/render（空数据走 .chart-empty）。
+ */
+declare function normalizeChartSpec(raw: unknown): ChartSpec;
+/** 未指定 type 时的自动选型（确定性规则，AI 只给数据也能画对） */
+declare function inferChartType(spec: ChartSpec): ChartType;
+type ChartEventName = 'hover' | 'click' | 'dblclick' | 'contextmenu';
+interface ChartEventDetail extends ChartMarkData {
+    type: ChartEventName;
+    /** hover 专有：enter / leave / move */
+    phase?: 'enter' | 'move' | 'leave';
+    /** 归一后的图型 */
+    chart: ChartType;
+    /** 事件发生时的标记元素 */
+    target?: Element;
+    /** 指针视口坐标（tooltip 定位/自定义浮层用） */
+    pointerX?: number;
+    pointerY?: number;
+}
+interface ChartHandle {
+    el: HTMLElement;
+    /** 归一 + 推断后的当前规格 */
+    spec: ChartSpec;
+    /** 原地重渲染（保留事件委托与句柄） */
+    update(next: ChartSpec | unknown): void;
+    /** icen:chart-<name> 监听糖（hover/click/dblclick/contextmenu）；返回解绑函数 */
+    on(name: ChartEventName, listener: (detail: ChartEventDetail, event: Event) => void): () => void;
+    /** 清空渲染并解绑交互委托（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-*，
+ * bubbles，detail 含 index/seriesIndex/seriesName/label/value/指针坐标）与可选
+ * tooltip（spec.tooltip !== false 时 portal 跟随指针；右键默认 preventDefault）。
+ * spec.title 有值时渲染 .chart-title。返回 { el, spec, update, on, destroy }。
+ */
+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 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 };