@icen.ai/ui 0.8.0 → 0.9.0

package/dist/behaviors/split-pane.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/split-pane.ts
 function numOr(value, fallback) {
   if (value === void 0 || value === "") return fallback;
@@ -9,11 +16,10 @@ function pct(value, min, max) {
 }
 function setup(container) {
   const el = container;
-  if (el.__icenSplitPaneInit) return;
+  if (el.__icenSplitPaneInit) return void 0;
+  const divider = el.querySelector(".split-pane-divider");
+  if (!divider) return void 0;
   el.__icenSplitPaneInit = true;
-  const dividerQuery = el.querySelector(".split-pane-divider");
-  if (!dividerQuery) return;
-  const divider = dividerQuery;
   const min = numOr(el.dataset.splitMin, 10);
   const max = numOr(el.dataset.splitMax, 90);
   const step = numOr(el.dataset.splitStep, 2);
@@ -28,20 +34,25 @@ function setup(container) {
     const v = parseFloat(getComputedStyle(el).getPropertyValue("--split"));
     return Number.isFinite(v) ? v : 50;
   }
-  function write(p) {
+  let cur = readCurrent();
+  const write = (p) => {
     const v = pct(p, min, max);
+    cur = v;
     el.style.setProperty("--split", v + "%");
     divider.setAttribute("aria-valuenow", String(Math.round(v)));
+  };
+  function emitChange() {
+    emitIcen(el, "icen:split-change", { value: Math.round(cur * 10) / 10 });
   }
   if (!el.style.getPropertyValue("--split")) write(50);
   divider.setAttribute("aria-valuenow", String(Math.round(readCurrent())));
   let dragging = false;
-  divider.addEventListener("pointerdown", (ev) => {
+  const onDown = (ev) => {
     dragging = true;
     divider.classList.add("is-dragging");
     divider.setPointerCapture(ev.pointerId);
     el.style.userSelect = "none";
-  });
+  };
   const onUp = (ev) => {
     if (!dragging) return;
     dragging = false;
@@ -51,14 +62,16 @@ function setup(container) {
     } catch {
     }
     el.style.userSelect = "";
+    emitChange();
   };
-  divider.addEventListener("pointerup", onUp);
-  divider.addEventListener("pointercancel", () => {
+  const onCancel = () => {
+    if (!dragging) return;
     dragging = false;
     divider.classList.remove("is-dragging");
     el.style.userSelect = "";
-  });
-  divider.addEventListener("pointermove", (ev) => {
+    emitChange();
+  };
+  const onMove = (ev) => {
     if (!dragging) return;
     const rect = el.getBoundingClientRect();
     if (vertical) {
@@ -70,9 +83,12 @@ function setup(container) {
       const p = (ev.clientX - rect.left) / rect.width * 100;
       write(p);
     }
-  });
-  divider.addEventListener("dblclick", () => write(50));
-  divider.addEventListener("keydown", (ev) => {
+  };
+  const onDblClick = () => {
+    write(50);
+    emitChange();
+  };
+  const onKeyDown = (ev) => {
     const current = readCurrent();
     let next = null;
     if (vertical) {
@@ -87,15 +103,40 @@ function setup(container) {
     if (next === null) return;
     ev.preventDefault();
     write(next);
-  });
+    emitChange();
+  };
+  divider.addEventListener("pointerdown", onDown);
+  divider.addEventListener("pointerup", onUp);
+  divider.addEventListener("pointercancel", onCancel);
+  divider.addEventListener("pointermove", onMove);
+  divider.addEventListener("dblclick", onDblClick);
+  divider.addEventListener("keydown", onKeyDown);
+  return () => {
+    divider.removeEventListener("pointerdown", onDown);
+    divider.removeEventListener("pointerup", onUp);
+    divider.removeEventListener("pointercancel", onCancel);
+    divider.removeEventListener("pointermove", onMove);
+    divider.removeEventListener("dblclick", onDblClick);
+    divider.removeEventListener("keydown", onKeyDown);
+    el.__icenSplitPaneInit = false;
+  };
 }
 function initSplitPane(root) {
-  if (typeof document === "undefined") return;
-  const scope = root ?? document;
-  const panes = [];
-  if (scope instanceof Element && scope.matches(".split-pane[data-split-pane]")) panes.push(scope);
-  panes.push(...Array.from(scope.querySelectorAll(".split-pane[data-split-pane]")));
-  for (const p of panes) setup(p);
+  const cleanups = [];
+  if (typeof document !== "undefined") {
+    const scope = root ?? document;
+    const panes = [];
+    if (scope instanceof Element && scope.matches(".split-pane[data-split-pane]")) panes.push(scope);
+    panes.push(...Array.from(scope.querySelectorAll(".split-pane[data-split-pane]")));
+    for (const p of panes) {
+      const cleanup = setup(p);
+      if (cleanup) cleanups.push(cleanup);
+    }
+  }
+  return () => {
+    for (const fn of cleanups) fn();
+    cleanups.length = 0;
+  };
 }
 export {
   initSplitPane

package/dist/behaviors/tabs.d.mts

@@ -1,7 +1,8 @@
 /**
  * 为 root 下每个 [data-tabs] 容器初始化（root 自身是 [data-tabs] 也算）。
- * 返回销毁函数：调用后移除所有容器监听与 window hashchange，并复位幂等标记
- * （销毁后的容器可被再次 initTabs 重新接管）。SSR 下返回 no-op 函数。
+ * 返回销毁函数：调用后移除所有容器监听、window hashchange/resize 监听与行为层创建的
+ * .tabs-ink 元素，并复位幂等标记（销毁后的容器可被再次 initTabs 重新接管）。
+ * SSR 下返回 no-op 函数。
  */
 declare function initTabs(root?: ParentNode): () => void;
 

package/dist/behaviors/tabs.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/tabs.ts
 function tabButtons(container) {
   return Array.from(container.querySelectorAll("[data-tab]"));
@@ -8,6 +15,20 @@ function tabNames(container) {
 function currentHash() {
   return window.location.hash.replace(/^#/, "");
 }
+function hashWriteMethod(container) {
+  const raw = container.getAttribute("data-tabs-hash");
+  if (raw === null || raw === "false") return null;
+  return raw === "push" ? "push" : "replace";
+}
+function syncInk(container, name) {
+  const btn = tabButtons(container).find((b) => b.getAttribute("data-tab") === name);
+  const tablist = btn?.parentElement;
+  if (!btn || !tablist) return;
+  const ink = tablist.querySelector(":scope > .tabs-ink");
+  if (!ink) return;
+  ink.style.width = `${btn.offsetWidth}px`;
+  ink.style.transform = `translateX(${btn.offsetLeft}px)`;
+}
 function activate(container, name, writeHash, emit = false) {
   const buttons = tabButtons(container);
   let matched = false;
@@ -32,15 +53,14 @@ function activate(container, name, writeHash, emit = false) {
     }
   });
   if (writeHash && typeof window !== "undefined") {
-    window.history.replaceState(null, "", `#${name}`);
+    const method = hashWriteMethod(container);
+    if (method) window.history[method === "push" ? "pushState" : "replaceState"](null, "", `#${name}`);
   }
+  syncInk(container, name);
   if (emit) {
     const index = buttons.findIndex((b) => b.getAttribute("data-tab") === name);
     const tab = buttons[index] ?? null;
-    container.dispatchEvent(new CustomEvent("icen:tab-change", {
-      bubbles: true,
-      detail: { tab, panel, index }
-    }));
+    emitIcen(container, "icen:tab-change", { tab, panel, index });
   }
 }
 function isDisabled(btn) {
@@ -65,10 +85,11 @@ function nextEnabled(container, from, dir) {
 function setup(container) {
   const el = container;
   if (el.__icenTabsInit) return void 0;
-  el.__icenTabsInit = true;
-  const useHash = container.hasAttribute("data-tabs-hash");
+  const useHash = hashWriteMethod(container) !== null;
+  const autoActivate = container.getAttribute("data-tabs-activation") === "auto";
   const names = tabNames(container);
   if (names.length === 0) return;
+  el.__icenTabsInit = true;
   const buttons = tabButtons(container);
   buttons.forEach((b) => {
     if (!b.getAttribute("role")) b.setAttribute("role", "tab");
@@ -76,6 +97,18 @@ function setup(container) {
   });
   const tablist = buttons[0]?.parentElement;
   if (tablist && !tablist.getAttribute("role")) tablist.setAttribute("role", "tablist");
+  let ink = null;
+  if (tablist instanceof HTMLElement && tablist.hasAttribute("data-tabs-ink")) {
+    ink = document.createElement("div");
+    ink.className = "tabs-ink";
+    ink.setAttribute("aria-hidden", "true");
+    const initialBtn = buttons.find((b) => b.classList.contains("is-active")) ?? buttons.find((b) => b.getAttribute("data-tab") === names[0]);
+    if (initialBtn) {
+      ink.style.width = `${initialBtn.offsetWidth}px`;
+      ink.style.transform = `translateX(${initialBtn.offsetLeft}px)`;
+    }
+    tablist.appendChild(ink);
+  }
   const onClick = (ev) => {
     const target = ev.target;
     if (!(target instanceof Element)) return;
@@ -85,6 +118,14 @@ function setup(container) {
     const name = btn.getAttribute("data-tab");
     if (name) activate(container, name, useHash, true);
   };
+  const followFocus = (idx) => {
+    focusTab(container, idx);
+    if (!autoActivate) return;
+    const target = tabButtons(container)[idx];
+    if (!target || isDisabled(target)) return;
+    const name = target.getAttribute("data-tab");
+    if (name) activate(container, name, useHash, true);
+  };
   const onKeyDown = (ev) => {
     const kev = ev;
     const target = kev.target;
@@ -98,25 +139,23 @@ function setup(container) {
       case "ArrowRight":
       case "ArrowDown": {
         kev.preventDefault();
-        const next = nextEnabled(container, currentIdx, 1);
-        if (next >= 0) focusTab(container, next);
+        followFocus(nextEnabled(container, currentIdx, 1));
         break;
       }
       case "ArrowLeft":
       case "ArrowUp": {
         kev.preventDefault();
-        const prev = nextEnabled(container, currentIdx, -1);
-        if (prev >= 0) focusTab(container, prev);
+        followFocus(nextEnabled(container, currentIdx, -1));
         break;
       }
       case "Home": {
         kev.preventDefault();
-        focusTab(container, nextEnabled(container, -1, 1));
+        followFocus(nextEnabled(container, -1, 1));
         break;
       }
       case "End": {
         kev.preventDefault();
-        focusTab(container, nextEnabled(container, buttonsList.length, -1));
+        followFocus(nextEnabled(container, buttonsList.length, -1));
         break;
       }
       case "Enter":
@@ -148,13 +187,25 @@ function setup(container) {
   if (useHash && typeof window !== "undefined") {
     window.addEventListener("hashchange", onHash);
   }
+  const onResize = () => {
+    const active = tabButtons(container).find((b) => b.classList.contains("is-active"));
+    const name = active?.getAttribute("data-tab");
+    if (name) syncInk(container, name);
+  };
+  if (ink && typeof window !== "undefined") {
+    window.addEventListener("resize", onResize, { passive: true });
+  }
   const cleanup = () => {
     container.removeEventListener("click", onClick);
     container.removeEventListener("keydown", onKeyDown);
     window.removeEventListener("hashchange", onHash);
+    if (ink) {
+      window.removeEventListener("resize", onResize);
+      ink.remove();
+      ink = null;
+    }
     el.__icenTabsInit = false;
   };
-  el.__icenTabsCleanup = cleanup;
   return cleanup;
 }
 function initTabs(root) {

package/dist/behaviors/tag-input.d.mts

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

package/dist/behaviors/tag-input.mjs

@@ -1,37 +1,54 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/tag-input.ts
 function setup(wrap) {
   const el = wrap;
-  if (el.__icenTagInit) return;
+  if (el.__icenTagInit) return void 0;
   el.__icenTagInit = true;
   const fieldEl = wrap.querySelector(".tag-input-field");
-  if (!fieldEl) return;
+  if (!fieldEl) return void 0;
   const field = fieldEl;
   const maxAttr = wrap.getAttribute("data-max");
   const max = maxAttr ? Number(maxAttr) || Infinity : Infinity;
   const placeholder = field.placeholder;
+  let alive = true;
   let isComposing = false;
-  field.addEventListener("compositionstart", () => {
+  const onCompositionStart = () => {
     isComposing = true;
-  });
-  field.addEventListener("compositionend", () => {
+  };
+  const onCompositionEnd = () => {
     isComposing = false;
-  });
+  };
   let tags = (wrap.getAttribute("data-tags") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const autoLabel = !wrap.hasAttribute("aria-label");
   function sync() {
     wrap.setAttribute("data-tags", tags.join(","));
     wrap.classList.toggle("is-max", tags.length >= max);
     field.placeholder = tags.length === 0 ? placeholder : "";
-    if (!wrap.hasAttribute("aria-label")) {
-      wrap.setAttribute("aria-label", `\u6807\u7B7E\u8F93\u5165\uFF0C\u5171 ${tags.length} \u4E2A`);
-    }
+    if (autoLabel) wrap.setAttribute("aria-label", `\u6807\u7B7E\u8F93\u5165\uFF0C\u5171 ${tags.length} \u4E2A`);
   }
   function emit() {
-    wrap.dispatchEvent(new CustomEvent("icen:tags-change", {
-      bubbles: true,
-      detail: { tags: [...tags] }
-    }));
+    if (!alive) return;
+    emitIcen(wrap, "icen:tags-change", { tags: [...tags] });
+  }
+  let shakeTimer = null;
+  function shake() {
+    el.classList.remove("is-shake");
+    void el.offsetWidth;
+    el.classList.add("is-shake");
+    if (shakeTimer) clearTimeout(shakeTimer);
+    shakeTimer = setTimeout(() => {
+      el.classList.remove("is-shake");
+      shakeTimer = null;
+    }, 320);
   }
   function remove(index) {
+    if (!alive) return;
     tags.splice(index, 1);
     render();
     emit();
@@ -57,11 +74,13 @@ function setup(wrap) {
     sync();
   }
   function commit() {
+    if (!alive) return;
     const v = field.value.trim();
     if (!v) return;
     if (tags.length >= max) return;
     if (tags.includes(v)) {
       field.value = "";
+      shake();
       return;
     }
     tags.push(v);
@@ -69,7 +88,7 @@ function setup(wrap) {
     render();
     emit();
   }
-  field.addEventListener("keydown", (ev) => {
+  const onKeyDown = (ev) => {
     if (isComposing || ev.isComposing) return;
     if (ev.key === "Enter" || ev.key === ",") {
       ev.preventDefault();
@@ -77,17 +96,38 @@ function setup(wrap) {
     } else if (ev.key === "Backspace" && !field.value && tags.length > 0) {
       remove(tags.length - 1);
     }
-  });
+  };
+  field.addEventListener("compositionstart", onCompositionStart);
+  field.addEventListener("compositionend", onCompositionEnd);
+  field.addEventListener("keydown", onKeyDown);
   field.addEventListener("blur", commit);
   render();
+  return () => {
+    alive = false;
+    if (shakeTimer) clearTimeout(shakeTimer);
+    field.removeEventListener("compositionstart", onCompositionStart);
+    field.removeEventListener("compositionend", onCompositionEnd);
+    field.removeEventListener("keydown", onKeyDown);
+    field.removeEventListener("blur", commit);
+    el.__icenTagInit = false;
+  };
 }
 function initTagInput(root) {
-  if (typeof document === "undefined") return;
-  const scope = root ?? document;
-  const containers = [];
-  if (scope instanceof HTMLElement && scope.matches(".tag-input")) containers.push(scope);
-  containers.push(...Array.from(scope.querySelectorAll(".tag-input")));
-  for (const c of containers) setup(c);
+  const cleanups = [];
+  if (typeof document !== "undefined") {
+    const scope = root ?? document;
+    const containers = [];
+    if (scope instanceof HTMLElement && scope.matches(".tag-input")) containers.push(scope);
+    containers.push(...Array.from(scope.querySelectorAll(".tag-input")));
+    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 {
   initTagInput

package/dist/behaviors/theme.d.mts

@@ -6,20 +6,31 @@ interface ThemeState {
 declare const PRESETS: readonly ["clay", "piano", "art", "vangogh", "ink", "retro"];
 declare const STYLES: readonly ["modern", "retro", "terminal"];
 declare const STORAGE_KEY = "icen.ui.theme";
+/**
+ * 注册宿主自建预设（宿主先在自家 CSS 写好 `.<name>` 与 `.<name>.dark` 完整 token 面，
+ * 仿照 colors.css 现有 6 套）。名字须命中 /^[a-z][a-z0-9-]{1,20}$/ 且不与
+ * dark / style-* 保留字冲突；注册只影响 listThemePresets() 枚举（UI 切换器用），
+ * 不注册的自建预设同样可以 setTheme（校验同样放行）。返回是否接受注册。
+ */
+declare function registerThemePreset(name: string): boolean;
+/** 全部可用预设名：内置 6 套 + 已注册的自建预设（UI 切换器枚举用，顺序稳定）。 */
+declare function listThemePresets(): string[];
 /** 默认主题：clay + 跟随系统明暗 + modern。SSR 下返回离线兜底值。 */
 declare function getDefaultTheme(): ThemeState;
 /** 读 localStorage 中的持久化主题；缺失或坏数据回退默认。 */
 declare function getTheme(): ThemeState;
-/** 把主题应用到 <html>：先清掉所有 preset/style/dark 相关类，再按 t 挂回。 */
+/** 把主题应用到 <html> 并在状态实际变化时派发 icen:theme-change（见私有 apply）。 */
 declare function applyTheme(t: ThemeState): void;
 /** 合并当前主题与 patch，应用并持久化，返回新态。patch 中的非法枚举值回退默认。 */
 declare function setTheme(patch: Partial<ThemeState>): ThemeState;
 /** 切换明暗，返回新态。 */
 declare function toggleDark(): ThemeState;
+/** 只切风格 profile（modern / retro / terminal；非法值回退 modern），返回新态。 */
+declare function setStyle(style: string): ThemeState;
 /** 页面加载早期调用：读持久化主题并应用，防闪烁。
  *  无持久化偏好时，自动跟随系统的 prefers-color-scheme 变化（实时）；
  *  一旦用户显式 setTheme / toggleDark，跟随停止（持久化优先）。
  *  重复调用幂等（系统监听不会重复挂）。 */
 declare function initTheme(): ThemeState;
 
-export { PRESETS, STORAGE_KEY, STYLES, type ThemeState, applyTheme, getDefaultTheme, getTheme, initTheme, setTheme, toggleDark };
+export { PRESETS, STORAGE_KEY, STYLES, type ThemeState, applyTheme, getDefaultTheme, getTheme, initTheme, listThemePresets, registerThemePreset, setStyle, setTheme, toggleDark };

package/dist/behaviors/theme.mjs

@@ -1,11 +1,32 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/theme.ts
 var PRESETS = ["clay", "piano", "art", "vangogh", "ink", "retro"];
 var STYLES = ["modern", "retro", "terminal"];
 var STORAGE_KEY = "icen.ui.theme";
+var PRESET_NAME_RE = /^[a-z][a-z0-9-]{1,20}$/;
+var RESERVED_PRESET_NAMES = /* @__PURE__ */ new Set(["dark", ...STYLES.map((s) => `style-${s}`)]);
+var customPresets = /* @__PURE__ */ new Set();
 var FALLBACK = { preset: "clay", dark: false, style: "modern" };
 function isBrowser() {
   return typeof document !== "undefined";
 }
+function isValidPreset(name) {
+  return PRESETS.includes(name) || PRESET_NAME_RE.test(name) && !RESERVED_PRESET_NAMES.has(name);
+}
+function registerThemePreset(name) {
+  if (!PRESET_NAME_RE.test(name) || RESERVED_PRESET_NAMES.has(name)) return false;
+  customPresets.add(name);
+  return true;
+}
+function listThemePresets() {
+  return [...PRESETS, ...customPresets];
+}
 function getDefaultTheme() {
   if (!isBrowser() || typeof window.matchMedia !== "function") {
     return { ...FALLBACK };
@@ -19,7 +40,8 @@ function getDefaultTheme() {
 function isThemeState(v) {
   if (typeof v !== "object" || v === null) return false;
   const t = v;
-  return typeof t.preset === "string" && PRESETS.includes(t.preset) && typeof t.dark === "boolean" && typeof t.style === "string" && STYLES.includes(t.style);
+  return typeof t.preset === "string" && /* 持久化路径与 setTheme 同一开放白名单：自建预设跨刷新存活 */
+  isValidPreset(t.preset) && typeof t.dark === "boolean" && typeof t.style === "string" && STYLES.includes(t.style);
 }
 function getTheme() {
   if (!isBrowser()) return getDefaultTheme();
@@ -33,24 +55,40 @@ function getTheme() {
     return getDefaultTheme();
   }
 }
-function applyTheme(t) {
+var lastApplied = null;
+function apply(t) {
   if (!isBrowser()) return;
   const cls = document.documentElement.classList;
+  if (lastApplied && !PRESETS.includes(lastApplied.preset)) {
+    cls.remove(lastApplied.preset);
+  }
   for (const p of PRESETS) cls.remove(p);
   for (const s of STYLES) cls.remove(`style-${s}`);
   cls.remove("dark");
   cls.add(t.preset);
   if (t.dark) cls.add("dark");
   cls.add(`style-${t.style}`);
+  const changed = lastApplied !== null && (lastApplied.preset !== t.preset || lastApplied.dark !== t.dark || lastApplied.style !== t.style);
+  lastApplied = { ...t };
+  if (changed) {
+    emitIcen(document.documentElement, "icen:theme-change", {
+      preset: t.preset,
+      dark: t.dark,
+      style: t.style
+    });
+  }
+}
+function applyTheme(t) {
+  apply(t);
 }
 function setTheme(patch) {
   const merged = { ...getTheme(), ...patch };
   const next = {
-    preset: PRESETS.includes(merged.preset) ? merged.preset : FALLBACK.preset,
+    preset: isValidPreset(merged.preset) ? merged.preset : FALLBACK.preset,
     dark: merged.dark === true,
     style: STYLES.includes(merged.style) ? merged.style : FALLBACK.style
   };
-  applyTheme(next);
+  apply(next);
   if (isBrowser()) {
     try {
       window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
@@ -62,6 +100,9 @@ function setTheme(patch) {
 function toggleDark() {
   return setTheme({ dark: !getTheme().dark });
 }
+function setStyle(style) {
+  return setTheme({ style });
+}
 var systemListenerAttached = false;
 function initTheme() {
   const t = getTheme();
@@ -103,6 +144,9 @@ export {
   getDefaultTheme,
   getTheme,
   initTheme,
+  listThemePresets,
+  registerThemePreset,
+  setStyle,
   setTheme,
   toggleDark
 };

package/dist/behaviors/toast.d.mts

@@ -1,4 +1,4 @@
-type ToastKind = 'ok' | 'err' | 'warn' | 'info';
+type ToastKind = 'ok' | 'err' | 'warn' | 'info' | 'success' | 'error';
 interface ToastOptions {
     /** 保留时长（毫秒），默认 2600；带 action 时默认 6000 */
     ms?: number;
@@ -6,21 +6,43 @@ interface ToastOptions {
     actionLabel?: string;
     /** action 触发回调；返回 false 阻止 toast 关闭 */
     onAction?: () => void | Promise<void> | boolean;
+    /** 内联 SVG 字符串图标（消毒后渲染为 .toast-icon）；非 <svg> 开头或解析失败静默忽略 */
+    icon?: string;
+    /** 显示右上角关闭按钮（.toast-close，点击即关闭本条），默认 false */
+    closable?: boolean;
+    /** 显示底部超时进度条（.toast-progress，动画时长 = 本条保留时长），默认 false */
+    progress?: boolean;
+}
+/** 单条 toast 句柄：dismiss() 立即关闭本条（幂等，可重复调用）。 */
+interface ToastHandle {
+    dismiss(): void;
 }
 interface ToastConfig {
     /** 同屏最大堆叠，默认 5；超出从最早的开始移除 */
     maxStack?: number;
 }
 interface ToastFn {
-    (message: string, kind?: ToastKind, ms?: number): void;
-    ok(message: string, ms?: number): void;
-    err(message: string, ms?: number): void;
-    warn(message: string, ms?: number): void;
-    info(message: string, ms?: number): void;
-    action(message: string, actionLabel: string, onAction: () => void, ms?: number): void;
+    (message: string, kind?: ToastKind, ms?: number): ToastHandle;
+    /** success 语义（.toast--success），规范词表入口 */
+    success(message: string, ms?: number): ToastHandle;
+    /**
+     * success 语义（.toast--success）。
+     * @deprecated 词表统一：改用 toast.success()，本别名下个大版本删除。
+     */
+    ok(message: string, ms?: number): ToastHandle;
+    /** error 语义（.toast--error），规范词表入口 */
+    error(message: string, ms?: number): ToastHandle;
+    /**
+     * error 语义（.toast--error）。
+     * @deprecated 词表统一：改用 toast.error()，本别名下个大版本删除。
+     */
+    err(message: string, ms?: number): ToastHandle;
+    warn(message: string, ms?: number): ToastHandle;
+    info(message: string, ms?: number): ToastHandle;
+    action(message: string, actionLabel: string, onAction: () => void, ms?: number): ToastHandle;
     dismiss(): void;
     config(opts: ToastConfig): void;
 }
 declare const toast: ToastFn;
 
-export { type ToastConfig, type ToastKind, type ToastOptions, toast };
+export { type ToastConfig, type ToastHandle, type ToastKind, type ToastOptions, toast };