@will-ui/vue 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 will-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @will-ui/vue
+
+Vue 3 UI component library (TypeScript + JSX). Design tokens and component CSS are **embedded** under `dist/theme` at publish time.
+
+## Install
+
+```bash
+npm install -S @will-ui/vue vue vue-i18n
+```
+
+## Usage
+
+```ts
+import { createApp } from 'vue'
+import UI, { Btn } from '@will-ui/vue'
+import '@will-ui/vue/style.css'
+
+const app = createApp(App)
+app.use(UI, {
+  locale: 'zh-CN',
+  components: {
+    Btn: { type: 'primary' },
+  },
+})
+app.mount('#app')
+```
+
+On-demand:
+
+```ts
+import { Btn, Write } from '@will-ui/vue'
+import '@will-ui/vue/style.css'
+```
+
+Theme tokens only:
+
+```ts
+import '@will-ui/vue/theme.css'
+```
+
+## Tailwind CSS v4
+
+业务项目若同时使用 Tailwind v4，可用 `@theme inline` 把全局 `--w-*` 桥进原子类（库不随包提供桥接 CSS，配置需复制到业务侧）。完整步骤与可复制配置见 [TAILWIND.md](./TAILWIND.md)。
+
+## Peer dependencies
+
+- `vue` ^3.5
+- `vue-i18n` ^9 || ^10

package/TAILWIND.md

@@ -0,0 +1,282 @@
+# 与 Tailwind CSS v4 对齐主题
+
+业务项目同时使用 `@will-ui/vue` / `@will-ui/react` 与 **Tailwind CSS v4** 时，推荐：**组件库 CSS 变量仍是唯一真相源**，在业务侧用 `@theme inline` 做一层薄桥接，让原子类与组件共用同一套色 / 尺度 / 圆角等规则。
+
+库**不会**随包提供 `tailwind-theme.css`；请按本文复制配置到业务项目。
+
+适用：Tailwind **v4**（CSS-first，`@theme`）。v3 请用 `theme.extend` + `var(--w-*)` 自行映射，思路相同。
+
+---
+
+## 1. 原则
+
+| 做 | 不做 |
+|----|------|
+| `:root` 的 `--w-*` 全局核作为唯一 token | 在 Tailwind 再抄一份色板 / 尺寸数字 |
+| `@theme inline { --color-*: var(--w-*) }` 桥接 | 把 `--w-btn-*`、`--w-modal-*` 等组件 token 全量映进 utility |
+| 改主题只覆写 `--w-color` / `--w-bg-color` / `--w-text-color` / `--w-size` / `--w-radius` 等 | 期望 `p-4` 跟随某个组件实例的 `size` / `color` prop |
+| 布局原子类跟**全局主题**对齐 | 用原子类复刻组件内部结构样式 |
+
+**为何用 `@theme inline`：** 工具类会直接写成 `color: var(--w-color)` 这类引用，运行时跟你们对 `:root` 的覆盖 / 暗色切换；普通 `@theme` 会再生成一层 `--color-brand`，容易和外部 token 脱节。
+
+**实例 prop 与原子类：** 组件 `size` / `color` / `cssVars` 写的是实例层（`--w-prop-*` → 组件根 `--__*`），只影响该组件子树。Tailwind 读的是全局 `--w-*`。页面壳子跟全局主题对齐即可。
+
+---
+
+## 2. 安装与引入顺序
+
+```bash
+npm install -D tailwindcss @tailwindcss/vite
+# 或 webpack / postcss 官方推荐插件，见 Tailwind v4 文档
+```
+
+**必须先有组件库 token，再声明 `@theme`。** 推荐单一入口 CSS（如 `src/styles/app.css`）：
+
+```css
+@import "tailwindcss";
+
+/* Vue */
+@import "@will-ui/vue/style.css";
+/* 若只要 token、不要全量组件样式，可用： */
+/* @import "@will-ui/vue/theme.css"; */
+
+/* React 则改为： */
+/* @import "@will-ui/react/style.css"; */
+
+/* 下方「§3 桥接配置」整段粘贴到这里 */
+```
+
+在 JS/TS 入口只引入这一份 CSS（或由 Vite 主入口 import）。不要重复 `@import` 组件样式导致顺序错乱。
+
+Vite 示例：
+
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+})
+```
+
+```ts
+// main.ts / main.tsx
+import './styles/app.css'
+```
+
+---
+
+## 3. 桥接配置（复制到业务 CSS）
+
+下面映射覆盖日常布局最常用的全局核。可按需增删；命名可改，但建议保持语义稳定。
+
+```css
+/**
+ * will-ui ↔ Tailwind v4
+ * 依赖：已通过 style.css / theme.css 注入 :root 的 --w-*
+ */
+@theme inline {
+  /* ---------- 颜色 → bg-* / text-* / border-* / outline-* / ring-* / fill-* / stroke-* ---------- */
+  --color-brand: var(--w-color);
+  --color-brand-soft: var(--w-color-primary-light-8);
+  --color-on-brand: var(--w-on-color);
+
+  --color-surface: var(--w-bg-color);
+  --color-surface-disabled: var(--w-bg-color-disabled);
+
+  --color-fg: var(--w-text-color);
+  --color-fg-2: var(--w-color-font-2);
+  --color-fg-3: var(--w-color-font-3);
+  --color-fg-4: var(--w-color-font-4);
+  --color-muted: var(--w-color-font-3);
+  --color-disabled: var(--w-color-disabled);
+
+  --color-border: var(--w-color-border);
+  --color-border-1: var(--w-color-border-1);
+  --color-border-2: var(--w-color-border-2);
+
+  --color-danger: var(--w-error);
+  --color-danger-soft: var(--w-error-soft);
+  --color-warn: var(--w-warn);
+  --color-warn-soft: var(--w-warn-soft);
+  --color-success: var(--w-success);
+  --color-success-soft: var(--w-success-soft);
+
+  /* 主色阶梯（需要时再用；日常优先 brand / brand-soft） */
+  --color-brand-0: var(--w-color-primary-light-0);
+  --color-brand-1: var(--w-color-primary-light-1);
+  --color-brand-2: var(--w-color-primary-light-2);
+  --color-brand-3: var(--w-color-primary-light-3);
+  --color-brand-4: var(--w-color-primary-light-4);
+  --color-brand-5: var(--w-color-primary-light-5);
+  --color-brand-6: var(--w-color-primary-light-6);
+  --color-brand-7: var(--w-color-primary-light-7);
+  --color-brand-8: var(--w-color-primary-light-8);
+  --color-brand-9: var(--w-color-primary-light-9);
+
+  /* ---------- 圆角 → rounded-* ---------- */
+  --radius-w: var(--w-radius);
+
+  /* ---------- 阴影 → shadow-* ---------- */
+  --shadow-w: var(--w-box-shadow);
+
+  /* ---------- 动效 ---------- */
+  --ease-w: var(--w-cubic-bezier);
+  --ease-w-quick: var(--w-cubic-bezier-quick);
+  --default-transition-duration: var(--w-transition-time);
+
+  /* ---------- 字号 → text-*（避开默认 text-sm / text-base 等名） ---------- */
+  --text-w: var(--w-font-size);
+  --text-w-2: var(--w-font-size-2);
+  --text-w-3: var(--w-font-size-3);
+  --text-w-4: var(--w-font-size-4);
+  --text-w-5: var(--w-font-size-5);
+
+  /*
+   * 间距 / 尺寸 → p-* / m-* / gap-* / w-* / h-* / size-* …
+   *
+   * --w-size 是「控件高度核」（默认约 44px），不是 Tailwind 默认的 0.25rem 刻度。
+   * 因此使用命名档，避免和默认 p-4 混成两套尺子还不自知。
+   */
+  --spacing-w-gap: var(--w-gap);
+  --spacing-w-px: var(--w-padding-x);
+  --spacing-w-py: var(--w-padding-y);
+  --spacing-ctrl: var(--w-size);
+}
+```
+
+### 可选：让默认 `p-*` / `gap-*` 也跟 `--w-size` 成比例
+
+仅当团队明确要「整站 spacing 跟控件核缩放」时再加（会改变 Tailwind 默认刻度语义）：
+
+```css
+@theme inline {
+  /* 使 spacing-1 ≈ --w-size / 11（默认 44px 时约 4px，接近 0.25rem） */
+  --spacing: calc(var(--w-size) / 11);
+}
+```
+
+未设置时保留 Tailwind 默认 `--spacing: 0.25rem`，与 will-ui 命名档（`gap-w-gap`、`h-ctrl`）并存即可。
+
+---
+
+## 4. 用法对照
+
+| 意图 | 原子类示例 | 对应 token |
+|------|------------|------------|
+| 页面底 / 卡片面 | `bg-surface` | `--w-bg-color` |
+| 正文 | `text-fg` | `--w-text-color` |
+| 次要说明 | `text-fg-2` / `text-muted` | `--w-color-font-2` / `font-3` |
+| 品牌底 / 字 | `bg-brand` `text-brand` | `--w-color` |
+| 实心品牌上的字 | `text-on-brand` | `--w-on-color` |
+| 浅品牌底 | `bg-brand-soft` / `bg-brand-8` | `--w-color-primary-light-8` |
+| 描边 | `border border-border` | `--w-color-border` |
+| 错误 / 警示 / 成功 | `text-danger` `bg-warn-soft` | `--w-error` 等 |
+| 与控件同圆角 | `rounded-w` | `--w-radius` |
+| 与主题同阴影 | `shadow-w` | `--w-box-shadow` |
+| 与主题同字号 | `text-w` `text-w-3` | `--w-font-size*` |
+| 与控件同高 | `h-ctrl` `min-h-ctrl` | `--w-size` |
+| 与主题间距 | `gap-w-gap` `px-w-px` `py-w-py` | `--w-gap` / padding |
+
+示例：
+
+```html
+<div class="bg-surface text-fg rounded-w shadow-w p-w-px gap-w-gap flex flex-col">
+  <h1 class="text-w-4 text-fg">标题</h1>
+  <p class="text-w text-muted">说明文字与 Btn / Write 同主题核</p>
+  <button type="button" class="h-ctrl px-w-px rounded-w bg-brand text-on-brand text-w">
+    与控件同高的业务按钮（示意；优先仍用库组件）
+  </button>
+</div>
+```
+
+偶发未桥接的 token，用任意值：
+
+```html
+<div class="bg-[var(--w-color-primary-light-6)]"></div>
+```
+
+---
+
+## 5. 换肤 / 暗色
+
+只改全局核，组件与原子类一起变：
+
+```css
+:root {
+  --w-color: #2563eb;
+  --w-size: 40px;
+  --w-radius: 8px;
+}
+
+html.dark {
+  --w-bg-color: #121212;
+  --w-text-color: #f3f3f3;
+  --w-color: #84cc16;
+  /* 主色阶梯、中性字色、描边由 _var 内 color-mix 跟随 bg/text 核重算 */
+}
+```
+
+React 还可通过 `UIProvider` 的 `config.cssVars`、实例 `cssVars` 写 `--w-prop-*` 或全局覆盖（视挂载节点而定）；**要让 Tailwind 同步**，覆盖需落在原子类祖先可继承到的节点上（通常仍是 `:root` / `html`）。
+
+---
+
+## 6. Preflight 与基础样式
+
+`@import "tailwindcss"` 含 Preflight；`@will-ui/*/style.css` 也含基础与组件样式。建议：
+
+1. **先 Tailwind，后 will-ui**（见 §2），避免 Preflight 盖掉组件所需规则。
+2. 若出现全局 `button` / `heading` 等冲突，可改为：
+
+```css
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@import "@will-ui/vue/style.css";
+/* … @theme inline … */
+```
+
+或按官方文档关闭 Preflight，改由业务 / will-ui 提供 reset（需团队统一约定）。
+
+**基础组件内部不要写 Tailwind 原子类**（库本身也不使用）；原子类只用于业务页面与拼装布局。
+
+---
+
+## 7. 边界与验收
+
+**应桥接：** `--w-color`、`--w-bg-color`、`--w-text-color`、中性阶梯、语义色、`--w-size`、`--w-radius`、`--w-gap`、`--w-font-size*`、`--w-box-shadow`、动效时长/曲线。
+
+**不必桥接：** 各组件 `--w-{comp}-*`、ratio/mix、复合 `border`/`outline` token；那些只给组件 CSS 消费。
+
+**验收：**
+
+1. `:root { --w-color: …; --w-size: … }` 后，库内 Btn 与页面上 `bg-brand` / `h-ctrl` / `gap-w-gap` 同步变化。
+2. `html.dark` 改 `--w-bg-color` / `--w-text-color` 后，`bg-surface` / `text-fg` / `border-border` 与组件表面一致。
+3. 改某个 `<Btn size={32} />` 时，旁边的 `p-4` / `h-ctrl` **不应**被带着变（实例与全局分离正确）。
+
+---
+
+## 8. Token 速查（全局核）
+
+完整定义见包内嵌入主题（构建产物 `theme` / 源码侧 `_var.css`）。常用：
+
+| 变量 | 含义 |
+|------|------|
+| `--w-color` | 品牌主色 |
+| `--w-bg-color` / `--w-text-color` | 表面 / 正文核 |
+| `--w-error` / `--w-warn` / `--w-success` | 语义色（+ `-soft`） |
+| `--w-on-color` | 实心主色上的对比色 |
+| `--w-color-font-1` … `5` | 中性字色由强到弱 |
+| `--w-color-border` / `-1` / `-2` | 描边 |
+| `--w-color-primary-light-0` … `9` | 主色向表面混合阶梯 |
+| `--w-size` | 控件高度核（派生字号、间距等） |
+| `--w-radius` | 全局圆角（独立，不跟 size） |
+| `--w-gap` / `--w-padding-x` / `--w-padding-y` | 间距 |
+| `--w-font-size` … `--w-font-size-5` | 字号档 |
+| `--w-box-shadow` | 浮层阴影 |
+| `--w-transition-time` 等 | 动效 |
+
+三级覆盖（组件实例）：`cssVars` / `--w-prop-{comp}-size|color|bg-color|text-color`，详见开发规范；**不要**用它们驱动整页 Tailwind。

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/components/audioPlayer/AudioPlayer.d.ts

@@ -0,0 +1,123 @@
+import { PropType } from 'vue';
+import { AudioPlayMode, AudioPlaylist, AudioTrack } from '../../use/useAudioPlayer';
+export type { AudioPlayMode, AudioPlaylist, AudioTrack };
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    playlists: {
+        type: PropType<AudioPlaylist[]>;
+        default: () => any[];
+    };
+    source: {
+        type: PropType<AudioTrack | null>;
+        default: any;
+    };
+    activePlaylistId: {
+        type: (NumberConstructor | StringConstructor)[];
+        default: any;
+    };
+    activeTrackId: {
+        type: (NumberConstructor | StringConstructor)[];
+        default: any;
+    };
+    playMode: {
+        type: PropType<AudioPlayMode>;
+        default: string;
+    };
+    autoplay: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    preload: {
+        type: PropType<"none" | "metadata" | "auto">;
+        default: string;
+    };
+    defaultVolume: {
+        type: NumberConstructor;
+        default: number;
+    };
+    defaultMuted: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    defaultPlaylistExpanded: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    nearby: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, ("error" | "ended" | "pause" | "play" | "time-update" | "volume-change" | "track-change" | "playlist-change" | "playlists-change" | "play-mode-change" | "loaded" | "update:activePlaylistId" | "update:activeTrackId" | "update:playMode" | "track-remove")[], "error" | "ended" | "pause" | "play" | "time-update" | "volume-change" | "track-change" | "playlist-change" | "playlists-change" | "play-mode-change" | "loaded" | "update:activePlaylistId" | "update:activeTrackId" | "update:playMode" | "track-remove", import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    playlists: {
+        type: PropType<AudioPlaylist[]>;
+        default: () => any[];
+    };
+    source: {
+        type: PropType<AudioTrack | null>;
+        default: any;
+    };
+    activePlaylistId: {
+        type: (NumberConstructor | StringConstructor)[];
+        default: any;
+    };
+    activeTrackId: {
+        type: (NumberConstructor | StringConstructor)[];
+        default: any;
+    };
+    playMode: {
+        type: PropType<AudioPlayMode>;
+        default: string;
+    };
+    autoplay: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    preload: {
+        type: PropType<"none" | "metadata" | "auto">;
+        default: string;
+    };
+    defaultVolume: {
+        type: NumberConstructor;
+        default: number;
+    };
+    defaultMuted: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    defaultPlaylistExpanded: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    nearby: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onError?: (...args: any[]) => any;
+    onEnded?: (...args: any[]) => any;
+    onPause?: (...args: any[]) => any;
+    onPlay?: (...args: any[]) => any;
+    onLoaded?: (...args: any[]) => any;
+    "onTime-update"?: (...args: any[]) => any;
+    "onVolume-change"?: (...args: any[]) => any;
+    "onTrack-change"?: (...args: any[]) => any;
+    "onPlaylist-change"?: (...args: any[]) => any;
+    "onPlaylists-change"?: (...args: any[]) => any;
+    "onPlay-mode-change"?: (...args: any[]) => any;
+    "onUpdate:activePlaylistId"?: (...args: any[]) => any;
+    "onUpdate:activeTrackId"?: (...args: any[]) => any;
+    "onUpdate:playMode"?: (...args: any[]) => any;
+    "onTrack-remove"?: (...args: any[]) => any;
+}>, {
+    source: AudioTrack;
+    autoplay: boolean;
+    preload: "none" | "auto" | "metadata";
+    nearby: boolean;
+    defaultVolume: number;
+    defaultMuted: boolean;
+    playlists: AudioPlaylist[];
+    activePlaylistId: string | number;
+    activeTrackId: string | number;
+    playMode: AudioPlayMode;
+    defaultPlaylistExpanded: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;