@zhang_jifan/fanui 2.1.0

package/src/fanui.d.ts

@@ -0,0 +1,353 @@
+/* =============================================================================
+ * fanUI v2.1.0 · TypeScript 类型声明
+ * -----------------------------------------------------------------------------
+ * tsconfig 中配置 "types": ["@zhang_jifan/fanui"] 或在代码里：
+ *   import FanUI from "@zhang_jifan/fanui";
+ *   FanUI.theme.setAccent("violet");
+ * ========================================================================== */
+
+/** 12 套内置主题色名，或任意自定义主题名（createAccent 生成） */
+export type AccentName =
+  | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple"
+  | "pink" | "rose" | "red" | "orange" | "emerald" | "teal" | (string & {});
+
+/** 明暗模式：light / dark / 跟随系统 */
+export type ThemeMode = "light" | "dark" | "auto";
+
+/** 液态玻璃厚度预设 */
+export type GlassPreset = "thin" | "regular" | "thick" | "ultra" | "lens";
+
+/** 主题快照（持久化到 localStorage 的完整状态） */
+export interface ThemeSnapshot {
+  accent: AccentName;
+  mode: ThemeMode;
+  /** mode 为 auto 时解析出的实际模式 */
+  effectiveMode: "light" | "dark";
+  glass: boolean;
+  glassPreset: GlassPreset;
+  glassIntensity: number;
+}
+
+/**
+ * 每套主题色在指定模式下解析出的关键令牌。
+ * 数据源是 CSS 自定义属性 —— `available` 为 false 表示样式表尚未加载，
+ * 此时各字段为空串（并在控制台给出一次性告警）。
+ */
+export interface AccentColors {
+  primary: string;
+  primaryFg: string;
+  vivid: string;
+  vivid2: string;
+  accent: string;
+  accentVivid: string;
+  available: boolean;
+}
+
+export interface CreateAccentOptions {
+  /** 主题名，缺省自动命名为 "custom-<hex>" */
+  name?: string;
+}
+
+export interface GlassOptions {
+  preset?: GlassPreset;
+  /** 强度 0–2，最终 = preset.intensity × 该值 */
+  intensity?: number;
+}
+
+export interface ThemeAPI {
+  /** 当前主题色名 */
+  getAccent(): AccentName;
+  /** 运行时切换主题色（全站即时生效并持久化） */
+  setAccent(name: AccentName): void;
+  /** 循环切换到下一套内置主题色 */
+  nextAccent(): void;
+  /** 12 套内置主题色元数据 */
+  readonly accents: ReadonlyArray<{ key: AccentName; label: string; en: string; vibe: string }>;
+  /** 读取某主题色在某模式下的角色令牌 */
+  readAccentColors(accent: AccentName, mode?: ThemeMode): AccentColors;
+  /** 明暗模式 */
+  getMode(): ThemeMode;
+  setMode(mode: ThemeMode): void;
+  /** 实际生效的模式（auto 已解析） */
+  getEffectiveMode(): "light" | "dark";
+  cycleMode(): void;
+  toggleMode(): void;
+  /** 液态玻璃 */
+  getGlass(): boolean;
+  setGlass(on: boolean, options?: GlassOptions): void;
+  toggleGlass(): void;
+  setGlassPreset(preset: GlassPreset): void;
+  setGlassIntensity(intensity: number): void;
+  getGlassPreset(): GlassPreset;
+  getGlassIntensity(): number;
+  /** 任意品牌色 → 合规主题（对比度自动择优，白字恒 ≥ 4.5:1）；返回主题名 */
+  createAccent(hex: string, options?: CreateAccentOptions): AccentName;
+  /** 完整状态快照 / 恢复 */
+  snapshot(): ThemeSnapshot;
+  /**
+   * 恢复主题状态。
+   * @param snapshot 传入 `snapshot()` 的返回值即可往返还原（保存用户预设 / 撤销 / SSR 注水）；
+   *                 不传则读取 localStorage 持久化偏好。
+   * @returns 生效后的完整状态
+   */
+  restore(snapshot?: Partial<ThemeSnapshot>): ThemeSnapshot;
+}
+
+export interface ToastAPI {
+  show(message: string, options?: { type?: "info" | "success" | "warning" | "error"; duration?: number; title?: string }): void;
+  info(message: string): void;
+  success(message: string): void;
+  warning(message: string): void;
+  error(message: string): void;
+}
+
+export interface OverlayInstance {
+  open(): OverlayInstance;
+  close(): OverlayInstance;
+  toggle(): OverlayInstance;
+  isOpen(): boolean;
+  destroy(): void;
+  readonly el: HTMLElement;
+}
+
+export interface OverlayOptions {
+  onClose?: () => void;
+  onOpen?: () => void;
+}
+
+export interface CommandItem {
+  group?: string;
+  id: string;
+  icon?: string;
+  title: string;
+  desc?: string;
+  keywords?: string;
+  hint?: string;
+  disabled?: boolean;
+}
+
+export interface CommandInstance extends OverlayInstance {
+  setItems(items: CommandItem[]): void;
+  getItems(): CommandItem[];
+}
+
+export interface LoadingBarAPI {
+  start(): LoadingBarAPI;
+  /** 设置确定进度 0–100 */
+  set(progress: number): LoadingBarAPI;
+  /** 不确定态（进度未知，如路由跳转） */
+  indeterminate(): LoadingBarAPI;
+  done(): LoadingBarAPI;
+  isLoading(): boolean;
+}
+
+export interface DatePickerInstance {
+  readonly el: HTMLInputElement;
+  open(): void;
+  close(): void;
+  value(): string;
+  setValue(value: string | Date | null): void;
+  destroy(): void;
+}
+
+export interface TimePickerInstance {
+  readonly el: HTMLInputElement;
+  open(): void;
+  close(): void;
+  value(): string;
+  setValue(value: string): void;
+}
+
+export interface ColorPickerInstance {
+  readonly el: HTMLInputElement;
+  open(): void;
+  close(): void;
+  value(): string;
+  setValue(hex: string): void;
+}
+
+export interface CascaderNode {
+  label: string;
+  value?: string;
+  children?: CascaderNode[];
+  disabled?: boolean;
+}
+
+export interface CascaderInstance {
+  readonly el: HTMLElement;
+  open(): void;
+  close(): void;
+  value(): Array<string | undefined>;
+  labels(): string[];
+  setValue(values: string[]): void;
+}
+
+export interface TreeNode {
+  label: string;
+  value?: string;
+  icon?: string;
+  badge?: string;
+  children?: TreeNode[];
+}
+
+export interface TreeInstance {
+  readonly el: HTMLElement;
+  getChecked(): string[];
+  checkAll(checked: boolean): void;
+  expandAll(expanded: boolean): void;
+}
+
+export interface TransferItem {
+  label: string;
+  value?: string;
+  tag?: string;
+  disabled?: boolean;
+}
+
+export interface TransferInstance {
+  readonly el: HTMLElement;
+  value(): string[];
+  set(values: string[]): void;
+}
+
+export interface I18NAPI {
+  readonly locale: string;
+  /** 取词：t("today")、t("selectedCount", { n: 3 }) */
+  t(key: string, vars?: Record<string, string | number>): string;
+  setLocale(locale: string): I18NAPI;
+  register(locale: string, dict: Record<string, unknown>): I18NAPI;
+}
+
+export interface FormatAPI {
+  date(value: string | number | Date, opts?: Intl.DateTimeFormatOptions): string;
+  time(value: string | number | Date, opts?: Intl.DateTimeFormatOptions): string;
+  number(value: number, opts?: Intl.NumberFormatOptions): string;
+  currency(value: number, currency?: string): string;
+}
+
+export interface StudioAPI {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  isOpen(): boolean;
+  refresh(): void;
+  destroy(): void;
+}
+
+export interface A11yFocusableOptions {
+  /** 默认 "pre, .fanui-scroll-area, [data-fanui-scrollable]" */
+  selector?: string;
+  /** 补充的可访问名，默认 "可滚动区域，使用方向键滚动" */
+  label?: string;
+}
+
+export interface A11yAPI {
+  /**
+   * 给「确实可滚动、但内部没有可聚焦内容」的容器补 tabindex + region 角色 + 可访问名，
+   * 解决 axe 的 scrollable-region-focusable。幂等，重复调用不会重复标记。
+   * @returns 本次处理的元素个数
+   */
+  focusableScrollables(scope?: Element | Document, opts?: A11yFocusableOptions): number;
+  init(scope?: Element | Document): void;
+}
+
+export interface InitResult {
+  destroyed: boolean;
+}
+
+declare const FanUI: {
+  readonly version: string;
+  /** CSS 类名前缀（恒为 "fanui"） */
+  readonly prefix: string;
+
+  /** 主题引擎：12 色 × 明暗 × 玻璃，三条正交运行时轴 */
+  theme: ThemeAPI;
+  /** 主题工作台（右下角悬浮调参面板） */
+  studio: { mount(options?: { defaultOpen?: boolean }): StudioAPI; api(): StudioAPI | null };
+  /** 顶部全局加载条 */
+  loadingBar: LoadingBarAPI;
+
+  modal: Record<string, unknown>;
+  /** 浮层工厂：模态框 / 抽屉 / Sheet 通用 */
+  overlay(target: string | HTMLElement, options?: OverlayOptions): OverlayInstance;
+  toast: ToastAPI;
+
+  tabs(target: string | HTMLElement): InitResult;
+  dropdown(target: string | HTMLElement): InitResult;
+  collapse(target: string | HTMLElement): InitResult;
+  form(target: string | HTMLElement): InitResult;
+  /** 注意：switch 是 JS 保留字，ESM 具名导入请用 `switchModule` */
+  switch(target: string | HTMLElement): InitResult;
+  command(target: string | HTMLElement, options?: { items?: CommandItem[] }): CommandInstance;
+  carousel(target: string | HTMLElement): InitResult;
+  rate(target: string | HTMLElement): InitResult;
+  tags(target: string | HTMLElement): InitResult;
+  stepper(target: string | HTMLElement): InitResult;
+  pin(target: string | HTMLElement): InitResult;
+  swatch(target: string | HTMLElement): InitResult;
+  upload(target: string | HTMLElement): InitResult;
+  combobox(target: string | HTMLElement): InitResult;
+  kanban(target: string | HTMLElement): InitResult;
+  notify(target: string | HTMLElement): InitResult;
+  filterBar(target: string | HTMLElement): InitResult;
+
+  /** 进阶数据录入组件（data-fanui-* 可声明式自动初始化） */
+  datePicker(target: string | HTMLElement, options?: { range?: boolean }): DatePickerInstance;
+  timePicker(target: string | HTMLElement, options?: { step?: number }): TimePickerInstance;
+  colorPicker(target: string | HTMLElement, options?: { asTheme?: boolean }): ColorPickerInstance;
+  cascader(target: string | HTMLElement, options?: { items?: CascaderNode[]; searchable?: boolean }): CascaderInstance;
+  tree(target: string | HTMLElement, options?: { items?: TreeNode[]; checkable?: boolean }): TreeInstance;
+  transfer(target: string | HTMLElement, options?: { items?: TransferItem[]; value?: string[] }): TransferInstance;
+
+  /** i18n 词表与 Intl 格式化层 */
+  i18n: I18NAPI;
+  format: FormatAPI;
+
+  /** 无障碍增强（随 init 自动执行，也可手动调用） */
+  a11y: A11yAPI;
+
+  scroll: Record<string, unknown>;
+  counter(target: string | HTMLElement): InitResult;
+  ripple(host: HTMLElement, event?: MouseEvent): void;
+  copy(target: string | HTMLElement): InitResult;
+  track: Record<string, unknown>;
+
+  lockScroll(): void;
+  unlockScroll(): void;
+  /** 手动初始化（默认 DOMContentLoaded 自动执行；data-fanui-auto="false" 可关闭） */
+  init(scope?: ParentNode): void;
+  $(selector: string, scope?: ParentNode): HTMLElement | null;
+  $$(selector: string, scope?: ParentNode): HTMLElement[];
+};
+
+export default FanUI;
+export { FanUI };
+
+/** 模块级自定义事件（bubbles: true） */
+export interface FanUIEventMap {
+  "fanui:accentchange": CustomEvent<{ accent: AccentName }>;
+  "fanui:themechange": CustomEvent<{ mode: ThemeMode }>;
+  "fanui:glasschange": CustomEvent<{ glass: boolean }>;
+  "fanui:localechange": CustomEvent<{ locale: string }>;
+  "fanui:command": CustomEvent<{ id: string }>;
+  "fanui:datechange": CustomEvent<{ value: string; start: Date | null; end: Date | null }>;
+  "fanui:timechange": CustomEvent<{ value: string }>;
+  "fanui:colorchange": CustomEvent<{ value: string }>;
+  "fanui:cascaderchange": CustomEvent<{ labels: string[]; value: Array<string | undefined> }>;
+  "fanui:treechange": CustomEvent<string[]>;
+  "fanui:treeselect": CustomEvent<{ value: string; label: string }>;
+  "fanui:transferchange": CustomEvent<{ value: string[] }>;
+}
+
+declare global {
+  interface Document {
+    addEventListener<K extends keyof FanUIEventMap>(
+      type: K,
+      listener: (ev: FanUIEventMap[K]) => void,
+      options?: boolean | AddEventListenerOptions
+    ): void;
+  }
+  interface Window {
+    FanUI: typeof FanUI;
+  }
+}