@kkwww/casual-ui 0.0.0-stage → 2.0.3

package/BRAND.md

@@ -0,0 +1,34 @@
+# Casual UI 品牌资源
+
+```vue
+<CuCasualLogo :width="24" :height="24" />
+<CuCasualLogo variant="wordmark" :width="176" :height="40" />
+```
+
+普通 Vue 使用 `CasualLogo`，React 使用同名组件。默认是独立图标，`wordmark` 是完整字标。Logo 使用原始透明 PNG 的内嵌 alpha 蒙版，不依赖外部图片 URL，跟随 `currentColor` 适配主题；不同实例的蒙版 ID 独立，支持 SSR。SVG 文件是嵌入位图的包装，不是纯矢量描摹。
+
+包内 `brand` 目录提供：
+
+- `casual-ui-logo-v1.png`：原始透明 Logo。
+- `casual-ui-wordmark.svg`：完整字标。
+- `casual-ui-symbol.svg`：独立图标。
+- `favicon.svg`：跟随系统明暗主题。
+- `favicon-light.svg`：浅色页面使用深色图标。
+- `favicon-dark.svg`：深色页面使用浅色图标。
+
+资源可通过 `@kkwww/casual-ui/brand/*` 或 React 包的对应入口访问。模块不会自动覆盖业务项目自己的 favicon。
+
+Nuxt 项目可将所需网站图标复制到 `public/brand`，在已有主题状态上配置：
+
+```ts
+useHead(() => ({
+  link: [{
+    key: 'casual-favicon',
+    rel: 'icon',
+    type: 'image/svg+xml',
+    href: `/brand/favicon-${theme.value === 'dark' ? 'dark' : 'light'}.svg`,
+  }],
+}))
+```
+
+若只跟随系统主题，配置 `/brand/favicon.svg` 即可。示例项目已经包含资源和主题切换接入。

package/COMPATIBILITY-2.0.2.md

@@ -0,0 +1,45 @@
+# Casual UI 2.0.2 兼容修复
+
+## 日期占位文案
+
+DatePicker / DateRangePicker 的文字 placeholder 仅用于触发器显示和辅助标签，不再透传为底层 DateValue。CalendarPicker 使用明确的日期属性和安全 DOM 属性，支持 class、style、id、aria-* 和 data-*；选择默认月份使用 defaultMonth，不使用字符串 placeholder。
+
+自定义中英文占位、空值及已选值、打开、清空和应用已检查。DateTimePicker 和 DateTimeRangePicker 保留各自显式日期属性传递方式，未将它们描述为已经复现相同缺陷。
+
+## FormField 多节点
+
+辅助 span、div 和 Fragment 不再复制字段 ID。原生控件及内置控件按顺序获得不同 ID；标签关联第一个可直接发现的控件。只有自定义组件包装时，后代库控件通过表单上下文领取独立 ID，第一个使用字段 ID。
+
+支持 Input、PasswordInput、Select、原生输入、条件节点、Fragment、嵌套 DOM 包装及上下文组件包装。description / error 继续使用字段独立的描述 ID。多个独立业务字段应分别使用 FormField；同一字段下多个控件时，后续控件需由宿主提供各自的辅助标签。自定义原生控件或显式自定义 ID 时，使用 FormField 的 id 和默认插槽提供的属性保持关联。
+
+## 通知窄屏
+
+通知视口改为 width:384px 与 max-width:100%，按可布局宽度约束，避免 100vw 把滚动条宽度算入容器。长文案及 action 按钮允许换行。
+
+公开样式入口：
+
+```vue
+<CuToastProvider
+  viewport-class="app-notifications"
+  :viewport-style="{ width: '360px' }"
+>
+  <NuxtPage />
+</CuToastProvider>
+```
+
+自定义视口时：
+
+```vue
+<CuToastProvider :viewport="false">
+  <NuxtPage />
+  <CuToastViewport class="app-notifications" :style="{ width: '360px' }" />
+</CuToastProvider>
+```
+
+class / style 应用于每个实际位置的视口，不再依赖覆盖内部类名。请保留最大宽度约束。
+
+## 验证与迁移
+
+在线示例和 Nuxt 示例增加自定义日期占位、多节点字段及长通知测试。窄屏通知覆盖 320/390px、明暗主题、有/无垂直滚动条、七种位置；实测有滚动条时宽度减少 15px。
+
+这次修复发生在组件库。外部业务项目的规避代码未自动修改；升级后应运行原有业务回归，再移除相应规避规则。

package/LICENSE-icons

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+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/NUXT.md

@@ -0,0 +1,140 @@
+# Nuxt 4 接入
+
+发行包：`@kkwww/casual-ui` **2.0.3**。在 Vue 版基础上增加正式 Nuxt module；普通 Vue 项目仍可使用原入口。验证目标为 Nuxt **4.6.4**、Vue **3.5.45**。Nuxt 4.6.4 要求 Node `^22.22.3 || ^24.15.0 || >=26.0.0`。
+
+## 安装与配置
+
+```sh
+pnpm add --save-exact @kkwww/casual-ui@2.0.3
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@kkwww/casual-ui/nuxt'],
+  casualUI: {
+    prefix: 'Cu',
+    locale: 'zh-CN',
+  },
+})
+```
+
+模块自动加载全局 CSS、本地字体和 SSR/客户端通用插件，并注册按需导入的组件及 composables。无需重复手动导入样式，也无需全局注册或 ClientOnly。
+
+组件名使用 `Cu` 前缀，例如 `CuButton`、`CuInput`、`CuSearchInput`、`CuSelect`、`CuDataTable`、`CuConfirmDialog`、`CuAppShell`、`CuIcon`、`CuSearch`。原组件名和所有 76 个具名图标均可自动导入。前缀可以配置为其他非空字母数字前缀，不占用已有的无前缀组件。
+
+## 页面示例
+
+```vue
+<script setup lang="ts">
+const { locale, setLocale, t } = useCasualI18n()
+const search = ref('')
+const page = ref(1)
+const pageSize = ref(15)
+const open = ref(false)
+const columns = computed(() => [
+  { key: 'id', header: 'ID' },
+  { key: 'status', header: locale.value.startsWith('zh') ? '状态' : 'Status' },
+])
+const rows = ref([{ id: 'OP-001', status: 'OK' }])
+</script>
+
+<template>
+  <CuPageContainer>
+    <CuPageHeader :title="locale.startsWith('zh') ? '订单' : 'Orders'">
+      <template #actions>
+        <CuButton @click="open = true"><CuPlus />{{ t('actions.confirm') }}</CuButton>
+        <CuButton variant="outline" @click="setLocale(locale === 'en' ? 'zh-CN' : 'en')">中文 / English</CuButton>
+      </template>
+    </CuPageHeader>
+    <CuFilterBar><CuSearchInput v-model="search" /><CuPeriodTabs /></CuFilterBar>
+    <CuDataTable :columns="columns" :rows="rows">
+      <template #cell-status="{ value }"><CuBadge variant="secondary">{{ value }}</CuBadge></template>
+    </CuDataTable>
+    <CuTablePagination v-model:page="page" v-model:page-size="pageSize" :total="75" />
+    <CuConfirmDialog v-model:open="open" title="Confirm" description="Demo" @confirm="open = false" />
+  </CuPageContainer>
+</template>
+```
+
+完整可运行示例使用 Nuxt 4 的 `app/` 目录结构，见 `examples/nuxt/`，包含布局、NuxtLink 导航、订单表格、设置表单和语言切换。生产构建使用 Nitro Node server。
+
+## 国际化与 SSR
+
+`useCasualI18n()` 返回 `locale`（只读 Ref）、`setLocale`、`t`、`formatNumber`、`formatDate`、`formatCurrency`。`useCasualLocale()` 返回 `locale`、`setLocale`。这两个名称不与 vue-i18n 的 `useI18n()` 冲突。
+
+模块在每次应用/SSR 请求中独立创建上下文；默认通过 `casual-locale` Cookie 记忆语言，首次 SSR 与 hydration 读取同一偏好。`setLocale('en')` 会同步组件文案、Cookie 和 `html.lang`。不依赖 localStorage，不在服务端共享用户状态。
+
+内置中英文控件、分页、弹窗和无障碍文案。业务标题、表头、选项标签等仍由项目翻译，不自动猜测业务含义。可按语言覆盖组件文案：
+
+```ts
+casualUI: {
+  locale: 'zh-CN',
+  messages: {
+    'zh-CN': { 'form.search': '查找订单…' },
+    en: { 'form.search': 'Find orders…' },
+  },
+}
+```
+
+日期格式化时显式传入业务 `timeZone`，避免服务端与浏览器时区不同导致展示差异。不要格式化接口提交值或改变金额计算。
+
+### 已有 @nuxtjs/i18n
+
+继续以项目的 i18n 为唯一语言来源，并关闭模块的 `html.lang` 管理。使用 Provider 将项目语言传给组件，无需安装第二套业务翻译系统：
+
+```ts
+// nuxt.config.ts：保留现有 @nuxtjs/i18n 配置
+casualUI: { syncHtmlLang: false }
+```
+
+```vue
+<!-- app/app.vue -->
+<script setup lang="ts">
+const { locale } = useI18n() // 项目原有 vue-i18n / @nuxtjs/i18n
+</script>
+<template>
+  <CuI18nProvider :locale="locale">
+    <NuxtLayout><NuxtPage /></NuxtLayout>
+  </CuI18nProvider>
+</template>
+```
+
+此模式由项目原有 i18n 管理语言持久化、路由、SEO 和业务 `t()`；不调用模块的 `setLocale()`。Provider 后代组件的内置文案跟随项目 locale。若要读取该局部 Provider 的格式化 API，可显式 `import { useI18n as useCasualProviderI18n } from '@kkwww/casual-ui'`，在其后代组件中调用。`useCasualI18n` 始终指向模块全局上下文。
+
+## 路由和响应式
+
+`CuAppShell` 默认保留 Vue 版普通链接行为。Nuxt 项目通过 `#link` 插槽使用 NuxtLink，保留 `attrs` 的样式、ARIA 和点击事件，以正确关闭移动抽屉：
+
+```vue
+<CuAppShell :groups="groups" base-path="" :current-path="route.path">
+  <template #link="{ href, title, icon, attrs }">
+    <NuxtLink :to="href" v-bind="{ ...attrs, href: undefined }">
+      <CuIcon :name="icon" /><span>{{ title }}</span>
+    </NuxtLink>
+  </template>
+  <slot />
+</CuAppShell>
+```
+
+需要本地化路由时用项目的 `localePath(href)` 处理 `to`。侧栏为桌面 256px/折叠 64px，768px 以下使用 288px 抽屉。筛选换行、卡片网格、表格容器滚动和弹窗窄屏边距沿用 Vue 版规则。
+
+弹层默认以 `#teleports` 为 Nuxt 目标容器；模块在客户端 hydration 前补齐缺少的默认容器。底层 Reka Portal 按其设计在挂载后呈现交互弹层，页面、表格和表单主体保持 SSR。不需要关闭全局 SSR。自定义 portalTarget 时由应用保证目标存在。
+
+## 配置项
+
+| 选项 | 默认值 | 用途 |
+| --- | --- | --- |
+| prefix | `Cu` | 组件自动导入前缀 |
+| components | `true` | 注册组件按需自动导入 |
+| composables | `true` | 自动导入 Casual composables |
+| css | `true` | 加载全局样式和字体；关闭后自行加载 |
+| locale | `en` | 没有偏好 Cookie 时的默认语言 |
+| cookieKey | `casual-locale` | 语言 Cookie 名 |
+| syncHtmlLang | `true` | 同步根元素 lang |
+| messages | `{}` | 按 locale 分类的扁平控件文案覆盖 |
+| portalTarget | `#teleports` | 弹层 Teleport 目标 |
+
+关闭 composables 自动导入后可从 `@kkwww/casual-ui/nuxt/composables` 显式导入。关闭 components 后可继续从包根/分类入口显式导入 Vue 组件。明暗主题继续通过根元素 `.dark` 管理，可接入项目已有的 Nuxt color-mode 方案。
+
+CSS 含原站基础样式，迁移已有项目时应检查全局样式冲突。模块不修改路由、权限、接口、Pinia、SSR 开关、Nitro preset 或项目的国际化路由策略。

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# Casual UI · Vue 3
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+独立 Vue 3.5+ 组件库 `@kkwww/casual-ui`，使用 Composition API、原生 `v-model` 与插槽。共享 React 版本的原始 SVG、Instrument Sans 字体、设计变量及响应式断点。无需 React。
+
+## 安装
+
+通过 pnpm 从 npm 官方 registry 远程安装：
+
+```sh
+pnpm add --save-exact @kkwww/casual-ui@2.0.3
+```
+
+包内包含样式和三种字重的本地字体。Reka UI 作为依赖自动安装，提供焦点管理、键盘操作、Escape 关闭和弹层行为。适用于 Vue 3.5+ / Vite；Vue 2 不适用。
+
+## 基本接入
+
+**Nuxt 4 项目：** 2.0.3 提供 `@kkwww/casual-ui/nuxt` 模块，支持 Cu 前缀组件自动导入、按请求隔离的 SSR 国际化上下文、Cookie 语言记忆及 Nuxt Teleport。配置与完整示例见包内 [NUXT.md](./NUXT.md)。普通 Vue 接入方式如下。
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { I18nProvider, PageContainer, PageHeader, FilterBar,
+  SearchInput, Select, PeriodTabs, DataTable, Badge,
+  TablePagination, ConfirmDialog, Button } from '@kkwww/casual-ui'
+import '@kkwww/casual-ui/styles.css'
+
+const locale = ref('zh-CN')
+const search = ref('')
+const currency = ref('VND')
+const period = ref('today')
+const page = ref(1)
+const pageSize = ref(15)
+const open = ref(false)
+const columns = [
+  { key: 'id', header: 'ID' },
+  { key: 'status', header: '状态' },
+]
+const rows = ref([{ id: 'OP-001', status: '已完成' }])
+function confirm() { open.value = false /* 在这里调用项目现有业务逻辑 */ }
+</script>
+
+<template>
+  <I18nProvider v-model:locale="locale">
+    <PageContainer>
+      <PageHeader title="订单">
+        <template #actions><Button @click="open = true">创建订单</Button></template>
+      </PageHeader>
+      <FilterBar>
+        <SearchInput v-model="search" />
+        <Select v-model="currency" label="币种"
+          :options="[{ value: 'VND', label: 'VND' }, { value: 'USD', label: 'USD' }]" />
+        <PeriodTabs v-model="period" />
+      </FilterBar>
+      <DataTable :columns="columns" :rows="rows">
+        <template #cell-status="{ value }"><Badge variant="secondary">{{ value }}</Badge></template>
+      </DataTable>
+      <TablePagination v-model:page="page" v-model:page-size="pageSize" :total="75" />
+      <ConfirmDialog v-model:open="open" title="确认操作" description="请确认信息。" @confirm="confirm" />
+    </PageContainer>
+  </I18nProvider>
+</template>
+```
+
+## 分类与 API
+
+所有组件支持标准 `class` / `style` 和适用的 HTML 属性。可从包根或 `primitives`、`forms`、`data-display`、`overlays`、`navigation`、`layout`、`icons`、`i18n` 子路径导入。
+
+| 分类 | 组件与主要接口 |
+| --- | --- |
+| 基础 | `Button`：variant default / outline / secondary / ghost / destructive / link，size default / sm / lg / icon，asChild；`Input`：v-model；`Label`；`Badge`；`Avatar`：src/name/size；`Separator`：orientation；`Heading`：title/description/variant |
+| 表单 | `FormField`：id/label/description/error，默认插槽自动关联 id 和错误说明；`PasswordInput`、`SearchInput`：v-model；`Select`：v-model、options、disabled、defaultValue、placeholder、label、name、id、size；`PeriodTabs`：v-model，options 可覆盖 |
+| 数据 | `Card`、`CardHeader`、`CardTitle`、`CardDescription`、`CardContent`；`StatCard`：title/value/currency/description；`Table`、`TableHeader`、`TableBody`、`TableRow`、`TableHead`、`TableCell`；`EmptyState`：title/description/icon、#action；`DataTable`：columns/rows/getRowKey/emptyTitle/emptyDescription，#cell-[key]({value,row,index})、#empty；`TablePagination`：v-model:page、v-model:page-size、total |
+| 弹层 | `Dialog`：v-model:open；`DialogTrigger`、`DialogClose`：asChild；`DialogContent`：showClose；`DialogTitle`、`DialogDescription`、`DialogHeader`、`DialogFooter`；`ConfirmDialog`：v-model:open、title/description/confirmLabel/cancelLabel/destructive，@confirm（成功后由调用方关闭） |
+| 导航 | `AppShell`：groups/basePath/currentPath/organizationName/user/breadcrumbs；#default / #footer / #link；@navigate、@organization；桌面 256px，可折叠为 64px，768px 以下为 288px 抽屉；`SidebarContent`、`NavGroup`、`Breadcrumbs`、`defaultNavigation` |
+| 布局 | `PageContainer`、`PageHeader`：title/description、#actions；`FilterBar`；`StatsGrid`：1 / sm 2 / xl 4 列；`ContentGrid`：xl 2 列；`SettingsLayout`：#navigation / #default，lg 切双列 |
+| 图标 | `Icon`：name/size/strokeWidth，`iconNames` 包含全部 76 个原站图标；同时提供具名图标导出；`CasualLogo` |
+
+`columns` 格式为 `{ key, header, className?, render?: (value,row) => VNodeChild }`。优先使用单元格插槽。表格自身横向滚动，筛选自动换行。`AppShell` 默认链接是普通 `<a>`，Vue Router 可使用 `#link="{href,title,icon,active,attrs}"` 自行渲染 RouterLink，并保留 attrs 中样式、ARIA 和导航事件；也可拦截 `@navigate` 并调用 router.push。
+
+## 国际化与主题
+
+```vue
+<script setup>
+import { useI18n } from '@kkwww/casual-ui'
+// 在 I18nProvider 的后代组件中调用
+const { locale, setLocale, t, formatNumber, formatDate, formatCurrency } = useI18n()
+// locale 是只读 Ref；setLocale('en')；t('actions.save')
+</script>
+<template><span>{{ formatCurrency(12345.67, 'USD') }}</span></template>
+```
+
+`I18nProvider` 支持受控 `v-model:locale`，或非受控 `default-locale`，以及扁平 `messages` 字典覆盖。无 Provider 时默认英语。内置 `en` / `zh-CN`，导出 `messagesByLocale`、`supportedLocales`、`createI18n`、`normalizeLocale`。默认控件文案及无障碍文案自动翻译；业务标题、列名、选项标签和传入的显式文案由调用方通过 `t()` 提供。Provider 不写全局 DOM 和存储，语言持久化由项目自己实现。
+
+在根元素切换 `.dark` 即可切换暗色。字体采用原站 Instrument Sans，中文按系统字体回退。可覆盖 `--primary`、`--background`、`--foreground`、`--radius` 等变量。样式含原站基础样式，接入既有项目时应在预发布环境核对全局样式影响。
+
+## 源码、构建与预览
+
+源码在 `components-vue/`，使用标准 Vue render functions，可直接导入 `.js` 或改写为 `.vue` 单文件组件。JS 实现配套 `.d.ts`，保留 Vue 模板和插槽的用法。
+
+```sh
+pnpm run build
+pnpm run dev
+```
+
+组件预览 `/components/vue`，完整侧栏示例 `/components/vue/shell`。独立发行包位于 `dist/ui-kit-vue/`。
+
+完整单文件组件示例：`examples/vue/App.vue`。仓库内该示例从源码导入，接入其他项目时将导入路径改成 `@kkwww/casual-ui` 并导入 `@kkwww/casual-ui/styles.css`。可执行 `pnpm exec vue-tsc -p examples/vue/tsconfig.json` 检查模板和 TypeScript 接口。
+
+## 1.3 增强
+
+新增日期、表单上下文、Textarea、浮层、通知和命令面板；扩展 Shell 插槽、Select、分页、loading 按钮和语义徽标。详细 API 与两端迁移步骤见 [UPGRADE-1.3.md](./UPGRADE-1.3.md)。
+
+日期区间对齐和秒级 TimePicker / DateTimePicker 用法见 [UPGRADE-1.3.1.md](./UPGRADE-1.3.1.md)。
+
+## 2.0.3 日期时间区间
+
+新增 DateTimeRangePicker，开始和结束均支持秒级时间、区间校验及响应式布局。详见 [UPGRADE-1.4.md](./UPGRADE-1.4.md)。
+
+## 2.0.3 通知位置与日期检查
+
+七种通知位置、跨月跨年和手机日期检查说明见 [UPGRADE-1.5.md](./UPGRADE-1.5.md)。
+
+2.0.3 增加时、分、秒输入段的滚轮切换，详见 [UPGRADE-1.5.md](./UPGRADE-1.5.md)。
+
+
+
+2.0.3 使用全新的 Casual UI 命名，不提供旧命名兼容别名。迁移方式见 [UPGRADE-2.0.md](./UPGRADE-2.0.md)。
+
+品牌 Logo、字标和主题网站图标用法见 [BRAND.md](./BRAND.md)。
+
+2.0.3 修复日期 placeholder、FormField 多节点 ID 和窄屏通知问题，详见 [COMPATIBILITY-2.0.2.md](./COMPATIBILITY-2.0.2.md)。
+
+## 2.0.3 气泡提示宽度
+
+Tooltip 默认最大宽度 320px，按浮层可用空间进一步缩小，长文本和无空格字符串自动换行。通过 `maxWidth`（数字为 px，或 CSS 长度字符串）自定义；Nuxt 示例：`<CuTooltip :max-width="240" text="提示内容"><CuButton>显示提示</CuButton></CuTooltip>`。

package/UPGRADE-1.3.1.md

@@ -0,0 +1,43 @@
+# 1.3.1：日期区间对齐与秒级时间
+
+## 日期区间修正
+
+- 日期数字在 32×32px 单元内水平、垂直居中。
+- 对齐原始后台控件：每个月独立标题、两端无边框翻月按钮、16px 月间距、12px 面板内边距、从周日开始。
+- 区间首尾为主色端点，中间为浅色背景，不再把整段填成深色。
+- 日期区间改为草稿选择，提供清空/应用操作。选择完成不会立即关闭；点击应用、点击外部或 Escape 关闭时提交，与保存的原站控件行为一致。只选起始日时提交为同一天区间。
+- 触发器显示本地化日期；模型仍是 YYYY-MM-DD，不改变业务日期或时区。
+- 保留组件库的窄屏单月约定，768px 起默认双月；numberOfMonths 可显式覆盖。
+
+## TimePicker：精确到秒
+
+```vue
+<script setup lang="ts">
+const time = ref('14:30:45')
+</script>
+<template><CuTimePicker v-model="time" /></template>
+```
+
+普通 Vue 从 `@kkwww/casual-ui` 或 `@kkwww/casual-ui/time` 导入 TimePicker；Nuxt 模块自动导入 CuTimePicker。
+
+固定使用 24 小时制、时/分/秒三个可编辑段。支持数字输入、上下方向键调整、左右方向键/Tab 切换。模型为 `HH:mm:ss`，空值为空字符串；输入 `HH:mm` 模型时秒显示为 00，下一次编辑输出完整秒值。支持 min/max、disabled、readonly、label、name、id、change/blur 及表单上下文。
+
+## DateTimePicker：日期＋时间
+
+```vue
+<script setup lang="ts">
+const dateTime = ref<string|null>('2026-11-07T14:30:45')
+</script>
+<template>
+  <CuDateTimePicker v-model="dateTime" default-month="2026-11-01"
+    min="2026-01-01T00:00:00" max="2026-12-31T23:59:59" />
+</template>
+```
+
+弹窗包含单月日历、秒级时间编辑及清空/应用。草稿中的内部时间字段不写入外层表单状态，应用后才发送完整值。
+
+模型为无时区的民用日期时间 `YYYY-MM-DDTHH:mm:ss`，清空为 null。允许传入使用空格分隔的同类值，输出统一使用 T。拒绝 Z、UTC offset 和无效日期；组件不会自动换算时区。需要 UTC 时间戳时，宿主必须按既定业务时区明确转换。
+
+支持 defaultMonth、min/max、disabled、isDateDisabled/isDateUnavailable、placeholder、clearable、name、id、change，以及 #value({value})。同一日的时间边界也会验证，超出边界时禁用应用按钮。
+
+新增 Clock 本地图标，总数 76 个。Vue/Reka/Nuxt 支持范围及共享依赖方式沿用 1.3.0。

package/UPGRADE-1.3.md

@@ -0,0 +1,128 @@
+# 1.3.0：商户端、代理端组件缺项补齐
+
+依据 `casual-ui-component-gaps.md` 的十类需求，在 1.2.0 Nuxt 接入上增量补齐。普通 Vue 的显式导入入口仍然可用。建议先替换项目公共包装层，再迁移各页面，不在此发行包内改写业务接口。
+
+## 安装及依赖
+
+```sh
+pnpm add --save-exact @kkwww/casual-ui@2.0.2
+```
+
+Vue 3.5+；Nuxt 集成适用 Nuxt 4.6.4+ 的 4.x。Reka UI **2.11.0** 为必须共享的 peer dependency，不在库内打包副本。项目仍保留 Nuxt UI 时，应确认依赖树 `pnpm why reka-ui`，用包管理器 overrides/resolutions 统一兼容的版本。不要强制覆盖与该版本不兼容的第三方组件。日期使用随包声明的 `@internationalized/date`。补充图标为本地 Lucide SVG 数据，不调用远程图标服务。
+
+Nuxt 配置不变：`modules: ['@kkwww/casual-ui/nuxt']`，默认前缀 Cu。新增分类子路径为 `dates`、`floating`、`feedback`、`command`，Nuxt 中所有新增组件也自动导入。
+
+## 1. 日期及日期区间
+
+`Calendar` 仍然是原图标，避免破坏旧代码。日期控件名称为 `CalendarPicker`、`DatePicker`、`DateRangePicker`。
+
+```vue
+<script setup lang="ts">
+const date = ref<string|null>(null)
+const range = ref<{start:string;end:string}|null>(null)
+</script>
+<template>
+  <CuDatePicker v-model="date" default-month="2026-11-01" />
+  <CuDateRangePicker v-model="range" min="2026-01-01" max="2026-12-31"
+    :is-date-disabled="date => date === '2026-11-10'" />
+</template>
+```
+
+值使用 `YYYY-MM-DD` 字符串，清空为 `null`；区间中未选择的一端为空字符串。也可使用 `v-model:start` / `v-model:end`，不要与 `v-model` 同时控制。`change` 与 `update:modelValue` 传递相同原值。`clearable=false` 隐藏清空按钮。
+
+共同属性：`defaultMonth`、`min`、`max`、`disabled`、`isDateDisabled(date)`、`isDateUnavailable(date)`、`timeZone`、`numberOfMonths`。`#value({value})` 自定义触发器文字。独立 `CalendarPicker` 使用 `range` 切换区间模式。
+
+默认窄屏单月，640px 起区间双月；首次 SSR 单月，挂载后更新，避免 hydration 差异。日期值不转换为时间戳；`timeZone` 仅用于默认“今天”的参考日期，默认 UTC。需要组织时区或跨午夜严格一致时，由业务传入该时区算出的 `defaultMonth` 和日期，不修改原有查询边界。
+
+## 2. 表单上下文和 schema 验证
+
+```vue
+<script setup lang="ts">
+import { z } from 'zod' // 使用项目已有依赖，不是组件库运行依赖
+const state = reactive({ email: '', note: '' })
+const schema = z.object({ email: z.email(), note: z.string().max(200) })
+async function save(data: typeof state) { /* 原业务请求 */ }
+</script>
+<template>
+  <CuForm :state="state" :schema="schema" :submit-handler="save">
+    <template #default="{submitting}">
+      <CuFormField name="email" label="Email"><CuInput v-model="state.email" /></CuFormField>
+      <CuFormField name="note" label="Note"><CuTextarea v-model="state.note" /></CuFormField>
+      <CuButton type="submit" :loading="submitting">Save</CuButton>
+    </template>
+  </CuForm>
+</template>
+```
+
+支持 Standard Schema 的 `~standard.validate`、Zod 的 `safeParseAsync/safeParse`，及 `validate(state)` 返回 `[{name,message}]` 的同步/异步业务验证。点路径字段名如 `profile.email` 可关联嵌套字段。`validateOn` 默认 input/blur/change，可设置为 `['blur']` 或 `[]`（仅提交验证）。
+
+`FormField` 的 `name` 注册到表单，自动连接 label、稳定 ID、说明、错误和 ARIA。`Input`、`Textarea`、`Select` 产生字段事件，并继承表单禁用状态。仍建议显式使用 v-model，以保留原有业务状态流。
+
+`submitHandler(state)` 在验证通过后等待业务异步操作，期间 `submitting` 为 true。`@submit({data,event})` 是成功通知事件；不要同时在该事件和 submitHandler 内重复发送请求。`@error({errors,cause})` 接收验证/操作失败。`disabled` 和外部 `loading` 可阻止提交。schema 仅用于验证，不隐式转换业务提交值。
+
+模板 ref 暴露 `validate({name?,silent?})`、`submit()`、`clear(name?)`、`setErrors(errors)`、`getErrors()` 和 `submitting`。支持把接口字段错误传给 setErrors。
+
+## 3. Textarea
+
+`v-model`、`rows`（默认 3）、`resize`（默认 vertical），支持 disabled、name、id、maxlength、aria-*、input/change/blur 等原生属性与事件。使用标准组件 class/style，不引入项目特有表单依赖。
+
+## 4. 菜单、Popover、Tooltip
+
+```vue
+<CuDropdownMenu>
+  <CuDropdownMenuTrigger as-child><CuButton>Menu</CuButton></CuDropdownMenuTrigger>
+  <CuDropdownMenuContent>
+    <CuDropdownMenuLabel>Account</CuDropdownMenuLabel>
+    <CuDropdownMenuItem @select="existingAction">Action</CuDropdownMenuItem>
+    <CuDropdownMenuSeparator />
+    <CuDropdownMenuItem disabled>Unavailable</CuDropdownMenuItem>
+  </CuDropdownMenuContent>
+</CuDropdownMenu>
+<CuPopover>
+  <CuPopoverTrigger as-child><CuButton>Details</CuButton></CuPopoverTrigger>
+  <CuPopoverContent>Content</CuPopoverContent>
+</CuPopover>
+<CuTooltip text="Full remark"><CuButton variant="ghost">Remark</CuButton></CuTooltip>
+```
+
+Content 支持 side、align、sideOffset；其余底层事件/属性透传给 Reka。共享 Nuxt 的 portalTarget；具备碰撞避让、内容限高和滚动、键盘选择、Escape 和焦点返回。Tooltip 可通过聚焦、悬停或点击触发，支持 `#content`、disabled 和 delayDuration。
+
+## 5. Toast、Alert、Skeleton
+
+Nuxt 应用根层增加一次 `<CuToastProvider>...</CuToastProvider>`，在页面 setup 中使用自动导入的 `useCasualToast()`：
+
+```ts
+const toast = useCasualToast()
+const id = toast.add({title:'Saved',description:'Done',variant:'success',duration:5000})
+toast.update(id, {description:'Updated'})
+toast.remove(id)
+```
+
+普通 Vue 从 `feedback` 导入 `ToastProvider` 和 `useToast`，在 Provider 后代中调用。每个应用独立存储，最多展示 5 条。duration 单位毫秒，0 表示常驻，支持关闭和 `action:{label,onClick}`。无需 UApp。不要在 SSR 全局模块单例中保存 store。
+
+`Alert` 支持 title、description、icon、variant、默认插槽及 #actions。`Skeleton` 支持 rectangle/circle，尺寸通过 class/style 指定，减少动画偏好下不播放动画。通知和骨架辅助文案来自组件库字典。
+
+## 6. CommandPalette
+
+```vue
+<CuCommandPalette v-model:open="open" v-model:query="query" :groups="groups"
+  :loading="loading" @select="item => existingNavigate(item)" />
+```
+
+groups 格式为 `[{label,items:[{id,label,description?,icon?,keywords?,disabled?}]}]`。按文字、说明、keywords 过滤，支持分组、上下键、Enter、Escape、loading/空状态；`#item({item})`、`#empty` 自定义展示。宿主继续管理 Ctrl+K、权限过滤、异步搜索数据及路由跳转；库不注册全局快捷键或自动跳转。
+
+## 7–10. 原有组件增强
+
+- `AppShell/SidebarContent`：新增 #brand({href})、#organization({organizationName})、#user({user,organizationName,href})，AppShell 另有 #header-actions。新增 brandHref、userHref。原 #link、#footer、navigate/organization 事件保留；NuxtLink 插槽继续透传 attrs，以保留移动导航关闭行为。
+- `Icon`：扫描商户端、代理端静态 i-lucide 使用集合，补入 22 个缺失定义，包括 Languages、ShieldPlus、CalendarDays、TrendingUp 等。原有定义优先，总计 75 个，全部随包提供；具体差集见 qa/project-icon-coverage.json。后续新增动态图标名需要另行登记。
+- `Select`：新增 #value({option,value})、#option({option,selected})；选项支持 icon、color、description。原值保留 string/number 类型，禁用及键盘操作沿用 Reka。选中值默认省略并带完整 title，展开选项可换行阅读；默认值也能在 SSR 中显示。
+- `TablePagination`：新增 pageSizeOptions（默认 15/30/50/100）及 showPageSize。当前 pageSize 即使不在选项中也会加入，支持 999；showPageSize=false 仅关闭条数选择，保留页码及总数。切换条数是否重置第一页仍由业务处理。
+- `Button`：loading 产生加载图标及 aria-busy，并阻止重复点击。
+- `Badge`：增加 success/info/warning/error，配套明暗语义色。
+- `FormField`：深色错误文字使用更高对比度。
+
+## 项目迁移顺序
+
+先在两端安装新版并统一 Reka，然后依次替换 DateRangeCalendar、Form/输入包装层、菜单/提示、通知提供层、搜索面板、Shell/公司选择器、图标回退和分页包装。保留原业务回调、状态及接口；只有所有引用迁移并验证后，再移除旧 Nuxt UI 依赖。
+
+本次只交付组件库和示例，不直接改动两端业务项目。示例 `/components` 覆盖新增交互；升级验证应包含两端已有业务用例和实际部署环境。

package/UPGRADE-1.4.md

@@ -0,0 +1,35 @@
+# 1.4.0：秒级日期时间区间
+
+新增 `DateTimeRangePicker`，可从包根或 `@kkwww/casual-ui/time` 显式导入。Nuxt 模块自动导入 `CuDateTimeRangePicker`。
+
+```vue
+<script setup lang="ts">
+const range = ref<{start:string;end:string}|null>({
+  start: '2026-11-07T09:00:00',
+  end: '2026-11-08T18:30:59',
+})
+</script>
+<template>
+  <CuDateTimeRangePicker v-model="range"
+    min="2026-11-01T00:00:00" max="2026-12-31T23:59:59" />
+</template>
+```
+
+- 共用已对齐原始后台的日历、32px 居中日期、深色端点/浅色区间，以及底部清空/应用按钮。
+- 两个独立的 24 小时制时/分/秒编辑器，支持数字输入及键盘调整。开始、结束各自保留秒数。
+- 宽屏默认双月和双列时间，768px 以下默认单月并纵向排列时间。窄屏或低高度弹窗可滚动；numberOfMonths 可覆盖默认月数。
+- 在弹窗里编辑草稿，内部时间编辑不写外层 Form。应用或关闭弹窗时提交合法区间；非法区间不能应用，关闭时保留原值。清空后应用提交 null。
+- 同一天可以选择任意合法的秒级时间段。只选一个日期时视为同一天；空值打开时开始/结束默认 00:00:00 / 23:59:59。
+- 结束不能早于开始；min/max 验证精确到秒，边界值允许相等。错误提示支持中英文并允许字典覆盖，不会交换或修改用户输入来绕过错误。
+
+## API
+
+模型：`{start:'YYYY-MM-DDTHH:mm:ss', end:'YYYY-MM-DDTHH:mm:ss'} | null`。这是不带时区的民用日期时间，不自动转 UTC，不接受 Z/offset。宿主按既有业务时区转换和提交。
+
+支持：`v-model`，或 `v-model:start` / `v-model:end`；不要同时使用两种控制方式。`change` 事件与模型值一致。其他 props：defaultMonth、numberOfMonths、min/max、disabled、clearable、placeholder、isDateDisabled、isDateUnavailable、name、id。
+
+`#value({value})` 自定义触发器文案。表单上下文中的 label/错误属性会透传，提交时产生 `name[start]`、`name[end]` 两个隐藏字段；无效或清空值为空字符串。
+
+可使用 `getDateTimeRangeError(value, options)` 获取同样的验证结果，成功为空字符串，失败为可交给 `t()` 的文案 key。组件支持 Vue 3.5+、Nuxt 4.6.4+，继续共享 Reka UI 2.11.0。
+
+在线示例“日期与区间”和 Nuxt 示例 `/components` 已加入该组件。远程安装：`pnpm add --save-exact @kkwww/casual-ui@2.0.2`。