@icen.ai/ui 0.5.0 → 0.8.0

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,9 @@
 // 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 +31,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 +48,53 @@ 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);
+  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]");
+      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);
+      }
+      const cleanup = setup(btn, opts);
+      if (cleanup) cleanups.push(cleanup);
+    }
+    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,4 @@
+/** 为 root 下每个 .carousel 初始化（root 自身是 .carousel 也算）。 */
+declare function initCarousel(root?: ParentNode): void;
+
+export { initCarousel };

package/dist/behaviors/carousel.mjs

@@ -3,17 +3,25 @@ function setup(carousel) {
   const el = carousel;
   if (el.__icenCarouselInit) return;
   el.__icenCarouselInit = true;
-  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;
+  const trackQ = carousel.querySelector(":scope > .carousel-track");
+  if (!trackQ) return;
+  const track = trackQ;
   const prev = carousel.querySelector(".carousel-arrow--prev");
   const next = carousel.querySelector(".carousel-arrow--next");
   const dotsBox = carousel.querySelector(".carousel-dots");
   let index = 0;
-  const dots = [];
-  if (dotsBox && count > 1) {
+  let slides = querySlides();
+  let count = slides.length;
+  if (count === 0) return;
+  let dots = [];
+  function querySlides() {
+    return Array.from(track.querySelectorAll(":scope > .carousel-slide"));
+  }
+  function buildDots() {
+    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";
@@ -24,23 +32,31 @@ function setup(carousel) {
       dots.push(dot);
     }
   }
+  function syncSlides() {
+    slides = querySlides();
+    if (slides.length === count) return;
+    count = slides.length;
+    if (index >= count) index = Math.max(0, count - 1);
+    buildDots();
+  }
   function render() {
-    if (!track) return;
     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();
+    carousel.dispatchEvent(new CustomEvent("icen:carousel-change", {
+      bubbles: true,
+      detail: { index, count }
+    }));
   }
   prev?.addEventListener("click", () => go(index - 1));
   next?.addEventListener("click", () => go(index + 1));
@@ -65,13 +81,15 @@ function setup(carousel) {
         break;
     }
   });
+  buildDots();
   render();
 }
-function initCarousel(root = document) {
+function initCarousel(root) {
   if (typeof document === "undefined") return;
+  const scope = root ?? document;
   const containers = [];
-  if (root instanceof Element && root.matches(".carousel")) containers.push(root);
-  containers.push(...Array.from(root.querySelectorAll(".carousel")));
+  if (scope instanceof Element && scope.matches(".carousel")) containers.push(scope);
+  containers.push(...Array.from(scope.querySelectorAll(".carousel")));
   for (const c of containers) setup(c);
 }
 export {

package/dist/behaviors/charts.d.mts

@@ -0,0 +1,250 @@
+type ChartTone = 'accent' | 'success' | 'warning' | 'error' | 'muted';
+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;
+}
+/** 多系列系列项（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;
+}
+/** 跨渲染存活的图例隐藏状态（renderChart 的 update 复渲染沿用；直调不传=每次新状态） */
+interface ChartLegendState {
+    hidden: boolean | null;
+}
+/** 垂直柱状图（单系列，或 series 多系列分组/堆叠——通用层与 renderChart 消费） */
+interface ChartVBarOptions extends ChartSeriesOptions {
+    /** 多系列（labels 共用，values 长度对齐）；缺省回落单系列 values */
+    series?: ChartSeriesSpec[];
+    /** 多系列时堆叠（默认分组并排） */
+    stacked?: boolean;
+}
+declare function renderVBar(el: HTMLElement, opts: ChartVBarOptions): void;
+/** 水平条形图 */
+declare function renderHBar(el: HTMLElement, opts: ChartSeriesOptions): void;
+/** 堆叠条形图（单条 100% + 图例） */
+declare function renderStack(el: HTMLElement, opts: ChartSegmentsOptions): void;
+/** 环形图（SVG stroke-dasharray 累加）+ 图例百分比 */
+declare function renderDonut(el: HTMLElement, opts: ChartSegmentsOptions): void;
+/** 折线图（面积渐变 + 网格 + 数据点 + 底部 ≤7 个轴标签；series 多系列走调色盘 + 可切换图例） */
+interface ChartLineOptions extends ChartSeriesOptions {
+    /** 多系列（labels 共用）；缺省回落单系列 values */
+    series?: ChartSeriesSpec[];
+    /** 多系列时是否填充面积（默认首系列填充；area 类型全填充） */
+    fill?: boolean;
+}
+declare function renderLine(el: HTMLElement, opts: ChartLineOptions): void;
+/** 面积图（与折线同族，以面积填充为视觉主体） */
+declare function renderArea(el: HTMLElement, opts: ChartSeriesOptions): void;
+interface RadarSeries {
+    name: string;
+    /** 各轴的值（0..max，顺序与 axes 一致）。元素类型须可转 number。 */
+    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): void;
+interface HeatmapDatum {
+    /** YYYY-MM-DD；仅用于 tooltip 与首周对齐 */
+    date: string;
+    value: number;
+}
+interface ChartHeatmapOptions extends ChartChromeOptions {
+    /** 精确形态：日期 + 值（旧 → 新）。与 values 二选一，data 优先。 */
+    data?: HeatmapDatum[];
+    /** 便捷形态：最近 N 天的值（旧 → 新），日期从今天回推 */
+    values?: number[];
+    /** 列数（周），默认按数据量推算（向上取整到整周） */
+    weeks?: number;
+    tone?: ChartTone;
+    emptyLabel?: string;
+    formatValue?: (value: number) => string;
+}
+/** GitHub 贡献图式热力格：7 行（周一 → 周日）× N 周列，5 档色阶。 */
+declare function renderHeatmap(el: HTMLElement, opts: ChartHeatmapOptions): void;
+/** 迷你趋势线（无轴小图，适合嵌入指标卡）。 */
+declare function renderSparkline(el: HTMLElement, opts: ChartSeriesOptions): void;
+interface ChartGaugeOptions {
+    value: number;
+    max?: number;
+    tone?: ChartTone;
+    /** 中心百分比下方的小标签 */
+    label?: string;
+    formatValue?: (value: number) => string;
+}
+/** 进度环（环形单值 + 中心百分比）。 */
+declare function renderGauge(el: HTMLElement, opts: ChartGaugeOptions): void;
+interface ChartCalendarOptions extends ChartChromeOptions {
+    /** ISO 日期数组（YYYY-MM-DD，与 values 配对；或用 data） */
+    dates?: string[];
+    values?: number[];
+    /** 精确形态：{date, value}[]（与 dates+values 二选一，优先） */
+    data?: HeatmapDatum[];
+    tone?: ChartTone;
+    emptyLabel?: string;
+    formatValue?: (value: number) => string;
+}
+/** 贡献日历（calendar heatmap）：dates → 自动周布局 + 月份标签，GitHub 同款 */
+declare function renderCalendar(el: HTMLElement, opts: ChartCalendarOptions): void;
+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): void;
+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;
+}
+/** 格式化描述符 → 函数（底层渲染器的 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;
+    /** 清空渲染并摘除绑定标记（委托随 el 生存期，destroy 后可重新 renderChart） */
+    destroy(): 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 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 };