diff --git a/vendor/ui/.agents/skills/cloudflare-sites/SKILL.md b/vendor/ui/.agents/skills/cloudflare-sites/SKILL.md new file mode 100644 index 0000000..f4d22e1 --- /dev/null +++ b/vendor/ui/.agents/skills/cloudflare-sites/SKILL.md @@ -0,0 +1,113 @@ +--- +name: cloudflare-sites +description: Deploy froQ static sites and Nuxt sites to Cloudflare as Workers with the cf CLI. Use when adding Cloudflare deploy, Workers Builds, migrating a Pages project, migrating wrangler.jsonc, or when asked to copy void, paper-landing, or lig. Do not create new Pages projects. +metadata: + author: froQ + version: "2026.10.11" + source: Hand-written from the 1000-observations Workers migration. https://github.com/0froq/skills-pack +--- + +新的 froQ 静态站和 Nuxt 站发布到 Cloudflare Workers,用 `cf`。不要新建 Pages 项目,也不要照抄 void、paper-landing、lig。 + +## 不要照抄的仓库 + +- `void`:先是 Worker 加 GitHub Action(仓库里放 API token),后来改成 Pages 的 GitHub 连接。那是旧决定。 +- `paper-landing`:Pages 的 GitHub 连接,构建 `pnpm generate`,发布 `.output/public`。没有 wrangler。 +- `lig`:没有部署。 + +不要照抄它们的部署方式。新站点和从 Pages 迁过来的站点都读这份 skill。迁的时候新建 Worker,不要沿用 Pages 项目、仓库里的 API token,或 `preset: 'cloudflare_pages'`。 + +## Pages + +`cf` 不能创建 Pages 项目。控制台里新建 Pages 的入口已经被收起来。官方文档仍说现有 Pages 不会被关掉,新项目从 Workers 开始。静态资源请求在 Workers 上和 Pages 一样不按请求计费。Wrangler 还有 `wrangler pages project create`,那不是新站点的路径。 + +## 已有 wrangler 配置时 + +仓库里有 `wrangler.jsonc` 或 `wrangler.toml`,还没有 `cloudflare.config.ts`: + +1. 工作区要干净。`cf migrate` 在脏工作区会停,除非加上 `--force`。 +2. 安装 wrangler,至少 4.136。`cf` 的 Wrangler bundler 需要它。 +3. 跑 `cf migrate`。它写出 `cloudflare.config.ts`。没有 `@cloudflare/vite-plugin` 时,资源目录写在 `wrangler.config.ts` 的 `assetsDirectory`。 +4. 它不覆盖已有的 `cloudflare.config.ts`,也不删除旧的 `wrangler.jsonc`。 +5. `cf deploy --dry-run` 通过之后,再删 `wrangler.jsonc`。 + +还没有 `cloudflare.config.ts` 时,不要跑 `cf init`、`cf dev`、`cf build`、`cf deploy`。它们不读 `wrangler.jsonc`,可能改写配置。 + +## Nuxt 静态站 + +Nitro 用静态预设,公开目录指到 `dist`。不要设 `preset: 'cloudflare_pages'`。那个预设会写 `_routes.json` 和 `_redirects`(`/* /404.html 404`),并警告要切到 D1。 + +```ts +nitro: { + output: { + publicDir: 'dist', + }, +} +``` + +`cloudflare.config.ts` 放 Worker 本身。`compatibilityDate` 用动手那天的日期。名字可以以数字开头。 + +```ts +import { defineConfig } from 'cf/config' + +export default defineConfig({ + worker: { + name: '', + compatibilityDate: '', + observability: { + enabled: true, + traces: { enabled: true }, + }, + assets: { + htmlHandling: 'drop-trailing-slash', + notFoundHandling: '404-page', + }, + }, +}) +``` + +`wrangler.config.ts` 只放构建侧的资源目录。它不是 Pages 配置,不要写 `pages_build_output_dir`。 + +```ts +import { defineWranglerConfig } from 'wrangler/experimental-config' + +export default defineWranglerConfig({ + types: { generate: false }, + assetsDirectory: './dist', +}) +``` + +`package.json` 保留 `dev`、`build`、`generate`。另加: + +```json +"deploy": "pnpm generate && cf deploy" +``` + +`cf build` 和 `cf deploy` 不跑 `package.json` 脚本,所以生成要写在 deploy 前面。不要把 `pnpm dev` 换成 `cf dev`。 + +Nuxt 路由没有尾斜杠,静态文件却是 `folder/index.html`。`auto-trailing-slash` 会把 `/s/0001/homepage` 307 到 `/s/0001/homepage/`,空段再进文档路径就会 404。用 `drop-trailing-slash`。页面如果自己拼接 slug,丢掉空段。 + +Workers Builds 设 `NODE_VERSION=22`。构建命令 `pnpm generate`。生产分支的部署命令是 `pnpm exec cf deploy`,用项目里钉住的 `cf`。仓库里不放 API token。 + +非生产分支的预览部署命令是 `pnpm exec cf previews deploy`。预览不继承生产的变量和绑定;静态站两边都只要 `NODE_VERSION`。分支预览地址按分支名固定,后面的构建更新同一条。日志里另外一条带哈希的地址每次都会变。 + +PR 评论里的 Preview URL 只在部署命令执行 `wrangler preview` 时出现。`cf previews deploy` 会把预览部署上去,地址在构建日志里,评论不写链接。继续用 `cf`,不要为了那条评论改成 wrangler。 + +已经连上 Workers Builds、还在用旧的非生产 trigger 的 Worker,才能做一次 `cf workers-builds workers migrate-to-previews`。这一步不能撤销。新建的 Worker 默认就是预览,不要再跑迁移。 + +`public/_headers` 会被复制进 `dist`,用来给 `/_nuxt` 加缓存头。`.cloudflare` 和 `.wrangler` 放进 `.gitignore`。 + +## 工具版本 + +- `cf` 是 beta,命令和配置格式还会变。验证过的版本是 `1.0.0-beta.12`,钉死这个版本,不要跟 latest。 +- 加载 `cloudflare.config.ts` 需要 Node.js >= 22.18(`module.registerHooks`)。报错文案可能让人以为是 Bun,先看 `node -v`。 +- 项目声明了 `cf` 之后,全局的 `cf` 会转给项目里的那份。 +- `cf deploy --dry-run` 不需要登录,用来确认资源打进了包。 +- `cf auth login` 要浏览器。无人值守用环境变量 `CLOUDFLARE_API_TOKEN`,不要写进仓库。 + +## 文档 + +- https://developers.cloudflare.com/cf/wrangler/migrate/ +- https://developers.cloudflare.com/cf/projects/ +- https://developers.cloudflare.com/workers/static-assets/routing/static-site-generation/ +- https://developers.cloudflare.com/pages/get-started/ diff --git a/vendor/ui/.agents/skills/oq/SKILL.md b/vendor/ui/.agents/skills/oq/SKILL.md new file mode 100644 index 0000000..e5c47e4 --- /dev/null +++ b/vendor/ui/.agents/skills/oq/SKILL.md @@ -0,0 +1,156 @@ +--- +name: oq +description: oQ's opinionated tooling and conventions for JavaScript/TypeScript projects. Based on Anthony Fu's style with personal customizations for UnoCSS, ESLint, pnpm catalog, and automated releases. Use when setting up new projects with these preferences. +metadata: + author: oQ + version: "2026.03.10" + source: Hand-written. https://github.com/0froq/skills-pack +--- + +## Coding Practices + +### Code Organization + +- **Single responsibility**: Each source file should have a clear, focused scope/purpose +- **Split large files**: Break files when they become large or handle too many concerns +- **Type separation**: Always separate types and interfaces into `types.ts` or `types/*.ts` +- **Constants extraction**: Move constants to a dedicated `constants.ts` file + +### Runtime Environment + +- **Prefer isomorphic code**: Write runtime-agnostic code that works in Node, browser, and workers whenever possible +- **Clear runtime indicators**: When code is environment-specific, add a comment at the top of the file: + +```ts +// @env node +// @env browser +``` + +### TypeScript + +- **Explicit return types**: Declare return types explicitly when possible +- **Avoid complex inline types**: Extract complex types into dedicated `type` or `interface` declarations + +### Comments + +- **Avoid unnecessary comments**: Code should be self-explanatory +- **Explain "why" not "how"**: Comments should describe the reasoning or intent, not what the code does + +### Testing (Vitest) + +- Test files: `foo.ts` → `foo.test.ts` (same directory) +- Use `describe`/`it` API (not `test`) +- Use `toMatchSnapshot` for complex outputs +- Use `toMatchFileSnapshot` with explicit path for language-specific snapshots + +--- + +## Tooling Choices + +### @antfu/ni Commands + +| Command | Description | +|---------|-------------| +| `ni` | Install dependencies | +| `ni ` / `ni -D ` | Add dependency / dev dependency | +| `nr + + +``` + +### State Management + +| Scenario | Choice | +|----------|--------| +| Component state | `shallowRef()` over `ref()` | +| Objects | Use `ref()`, avoid `reactive()` | +| Global state | Pinia | +| URL state | `useRoute()` / `useRouter()` | + +### Props and Emits + +Always type with interfaces: + +```vue + +``` + +### Component Structure + +```vue + + + + + +``` + +## UnoCSS Conventions + +### Attribute Usage + +Always use `un-` prefixed attributes: + +```vue + +
+ + +
+``` + +### Shortcuts + +Use defined shortcuts for common patterns: + +```vue + +
+ +
+``` + +### Icon Usage + +```vue + +
+
+
+ + +
+
+``` + +### Responsive Design + +```vue +
+ +
+``` + +Custom breakpoints: +- `sm`: 600px +- `md`: 900px + +## Nuxt Conventions + +### File Structure + +``` +app/ +├── components/ # Vue components +│ ├── ui/ # UI primitives +│ ├── forms/ # Form components +│ └── layouts/ # Layout components +├── composables/ # Auto-imported composables +├── layouts/ # Page layouts +├── pages/ # File-based routes +├── server/ # API routes +│ └── api/ # Server API +├── types/ # TypeScript types +├── utils/ # Utility functions +├── app.vue # App root +└── nuxt.config.ts # Nuxt configuration +``` + +### Server Routes + +```ts +// server/api/users.get.ts +export default defineEventHandler(async (event) => { + // Handle GET /api/users + return await fetchUsers() +}) + +// server/api/users.post.ts +export default defineEventHandler(async (event) => { + const body = await readBody(event) + return await createUser(body) +}) +``` + +### Composables + +Place in `composables/` for auto-import: + +```ts +// composables/useUser.ts +export function useUser() { + const user = useState('user', () => null) + + async function login(credentials) { + user.value = await $fetch('/api/login', { + method: 'POST', + body: credentials + }) + } + + return { + user: readonly(user), + login + } +} +``` + +### Layouts + +```vue + + +``` + +## Font Usage + +### Apply Font Classes + +```vue + +``` + +## Utilities + +### Preferred Libraries + +| Purpose | Library | +|---------|---------| +| Vue utilities | @vueuse/core | +| HTTP client | $fetch (built-in) | +| Date formatting | date-fns or Intl.DateTimeFormat | +| Validation | zod | +| Testing | vitest + @vue/test-utils | + +### VueUse Composables + +```ts +// Common VueUse composables +import { + useDark, + useToggle, + useStorage, + useFetch, + useIntersectionObserver +} from '@vueuse/core' +``` diff --git a/vendor/ui/.agents/skills/oq/references/library-development.md b/vendor/ui/.agents/skills/oq/references/library-development.md new file mode 100644 index 0000000..662c78a --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/library-development.md @@ -0,0 +1,161 @@ +--- +name: library-development +description: Library bundling with tsdown and pure ESM publishing. Use when creating npm packages. +--- + +# Library Development + +## Bundling with tsdown + +Use [tsdown](https://github.com/rolldown/tsdown) for TypeScript library bundling (powered by Rolldown). + +### Installation + +```bash +pnpm add -D tsdown +``` + +### Configuration + +```ts +// tsdown.config.ts +import { defineConfig } from 'tsdown' + +export default defineConfig({ + entry: ['./src/index.ts'], + outDir: 'dist', + format: ['esm'], // Pure ESM + dts: true, // Generate declarations + clean: true, // Clean outDir before build + splitting: true, // Code splitting + minify: false, // Keep readable for debugging +}) +``` + +### Package.json + +```json +{ + "name": "@myorg/my-lib", + "version": "1.0.0", + "type": "module", + "main": "./dist/index.js", + "module": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsdown", + "dev": "tsdown --watch", + "prepack": "pnpm build" + } +} +``` + +## Pure ESM + +Publish only ESM (no CommonJS): + +```json +{ + "type": "module" +} +``` + +Benefits: +- Smaller bundle size +- Tree-shaking support +- Native async imports +- Future-proof + +## Export Patterns + +### Named Exports + +```ts +// src/index.ts +export { foo, bar } from './foo' +export type { FooOptions } from './types' +export { default as MyComponent } from './MyComponent.vue' +``` + +### Subpath Exports + +```json +{ + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./utils": { + "types": "./dist/utils.d.ts", + "import": "./dist/utils.js" + }, + "./package.json": "./package.json" + } +} +``` + +Usage: +```ts +import { foo } from 'my-lib' +import { util } from 'my-lib/utils' +``` + +## TypeScript Configuration + +```json +{ + "compilerOptions": { + "target": "ESNext", + "module": "ESNext", + "moduleResolution": "bundler", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "resolveJsonModule": true, + "isolatedModules": true, + "declaration": true, + "declarationMap": true, + "noEmit": true + }, + "include": ["src"], + "exclude": ["node_modules", "dist"] +} +``` + +## Testing Libraries + +```ts +// vitest.config.ts +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + test: { + environment: 'node', + globals: true, + }, +}) +``` + +## GitHub Actions for Release + +See [release-workflow](release-workflow.md) for automated releases. + +## Versioning Strategy + +Follow semantic versioning: + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +Use conventional commits for automatic changelog generation. diff --git a/vendor/ui/.agents/skills/oq/references/monorepo.md b/vendor/ui/.agents/skills/oq/references/monorepo.md new file mode 100644 index 0000000..85b33e8 --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/monorepo.md @@ -0,0 +1,208 @@ +--- +name: monorepo +description: Monorepo setup with pnpm workspaces, centralized aliases, and Turborepo. Use when creating or managing multi-package repositories. +--- + +# Monorepo Setup + +## pnpm Workspaces + +Use pnpm workspaces for monorepo management: + +```yaml +# pnpm-workspace.yaml +packages: + - 'packages/*' + - 'apps/*' +``` + +## Scripts Convention + +Have scripts in each package, and use `-r` (recursive) flag at root. +Enable ESLint cache for faster linting in monorepos. + +```json +// root package.json +{ + "scripts": { + "build": "pnpm run -r build", + "test": "vitest", + "lint": "eslint . --cache --concurrency=auto", + "lint:fix": "eslint . --cache --concurrency=auto --fix", + "dev": "pnpm run -r --parallel dev", + "clean": "rm -rf node_modules packages/*/node_modules apps/*/node_modules" + } +} +``` + +In each package's `package.json`, add the scripts: + +```json +// packages/*/package.json +{ + "scripts": { + "build": "tsdown", + "dev": "tsdown --watch", + "prepack": "pnpm build" + } +} + +// apps/*/package.json +{ + "scripts": { + "build": "nuxt build", + "dev": "nuxt dev", + "generate": "nuxt generate" + } +} +``` + +## ESLint Cache + +```json +{ + "scripts": { + "lint": "eslint . --cache --concurrency=auto" + } +} +``` + +## Turborepo (Optional) + +For monorepos with many packages or long build times, use Turborepo for task orchestration and caching. + +### Configuration + +```json +// turbo.json +{ + "$schema": "https://turbo.build/schema.json", + "globalDependencies": ["**/.env.*local"], + "pipeline": { + "build": { + "dependsOn": ["^build"], + "outputs": [".nuxt/**", ".output/**", "dist/**"] + }, + "lint": { + "outputs": [] + }, + "dev": { + "cache": false, + "persistent": true + } + } +} +``` + +## Centralized Alias + +For better DX across Vite, Nuxt, Vitest configs, create a centralized `alias.ts` at project root: + +```ts +// alias.ts +import fs from 'node:fs' +import { fileURLToPath } from 'node:url' +import { join, relative } from 'pathe' + +const root = fileURLToPath(new URL('.', import.meta.url)) +const r = (path: string) => fileURLToPath(new URL(`./packages/${path}`, import.meta.url)) + +export const alias = { + '@myorg/core': r('core/src/index.ts'), + '@myorg/utils': r('utils/src/index.ts'), + '@myorg/ui': r('ui/src/index.ts'), + // Add more aliases as needed +} + +// Auto-update tsconfig.alias.json paths +const raw = fs.readFileSync(join(root, 'tsconfig.alias.json'), 'utf-8').trim() +const tsconfig = JSON.parse(raw) +tsconfig.compilerOptions.paths = Object.fromEntries( + Object.entries(alias).map(([key, value]) => [key, [`./${relative(root, value)}`]]), +) +const newRaw = JSON.stringify(tsconfig, null, 2) +if (newRaw !== raw) + fs.writeFileSync(join(root, 'tsconfig.alias.json'), `${newRaw}\n`, 'utf-8') +``` + +Then update the `tsconfig.json` to use the alias file: + +```json +{ + "extends": [ + "./tsconfig.alias.json" + ] +} +``` + +### Using Alias in Configs + +Reference the centralized alias in all config files: + +```ts +// vite.config.ts +import { alias } from './alias' + +export default defineConfig({ + resolve: { alias }, +}) +``` + +```ts +// nuxt.config.ts +import { alias } from './alias' + +export default defineNuxtConfig({ + alias, +}) +``` + +```ts +// vitest.config.ts +import { alias } from './alias' + +export default defineConfig({ + resolve: { alias }, +}) +``` + +## Package Naming + +Use scoped packages for internal packages: + +```json +// packages/core/package.json +{ + "name": "@myorg/core", + "version": "1.0.0", + "main": "./dist/index.js", + "types": "./dist/index.d.ts" +} +``` + +## Internal Dependencies + +Reference workspace packages with `workspace:` protocol: + +```json +{ + "dependencies": { + "@myorg/core": "workspace:*", + "@myorg/utils": "workspace:*" + } +} +``` + +## Build Order + +pnpm automatically handles build order based on `workspace:` dependencies. No need for manual sequencing. + +## Publishing + +```bash +# Version all packages +pnpm version [major|minor|patch] + +# Publish all +pnpm publish -r +``` diff --git a/vendor/ui/.agents/skills/oq/references/oq-eslint-config.md b/vendor/ui/.agents/skills/oq/references/oq-eslint-config.md new file mode 100644 index 0000000..c1149d8 --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/oq-eslint-config.md @@ -0,0 +1,183 @@ +--- +name: oq-eslint-config +description: Custom @antfu/eslint-config setup with specific Vue formatting rules and dprint for markdown. Use when configuring ESLint for oQ-style projects. +--- + +# oQ's ESLint Configuration + +Based on `@antfu/eslint-config` with personal customizations for Vue projects and specific formatting preferences. + +## Base Configuration + +```ts +// eslint.config.ts +import antfu from '@antfu/eslint-config' +import nuxt from './.nuxt/eslint.config.mjs' + +export default antfu( + { + unocss: true, + pnpm: true, + typescript: true, + vue: true, + rules: { + // Vue template formatting - one attribute per line + 'vue/max-attributes-per-line': ['error', { + singleline: { max: 1 }, + multiline: { max: 1 }, + }], + // Disable unused imports auto-removal (manual cleanup preferred) + 'unused-imports/no-unused-imports': 'off', + }, + formatters: { + css: true, // Format CSS, LESS, SCSS + html: true, // Format HTML + markdown: 'dprint' // Use dprint for markdown (not prettier) + }, + }, +) + .append(nuxt()) // Append Nuxt's ESLint config if using Nuxt +``` + +## Key Customizations + +### Vue Template Formatting + +Strict attribute-per-line enforcement for Vue templates: + +```vue + +
+ + +
+``` + +### Unused Imports + +Unlike the default antfu config, unused imports are NOT automatically removed. This allows for: +- Intentional side-effect imports +- Gradual refactoring without breaking builds +- Manual review of what to remove + +### Markdown Formatting + +Uses **dprint** instead of Prettier for markdown files: +- Faster formatting +- Better control over formatting rules +- Consistent with modern tooling + +## Required Dependencies + +```bash +# Core +pnpm add -D @antfu/eslint-config + +# For Nuxt projects +pnpm add -D @nuxt/eslint + +# Formatters (CSS/HTML/Markdown) +pnpm add -D eslint-plugin-format + +# If using dprint for markdown +pnpm add -D dprint +``` + +## Formatters Setup + +### dprint Configuration (Optional) + +Create `dprint.json` for markdown formatting: + +```json +{ + "typescript": {}, + "json": {}, + "markdown": { + "lineWidth": 100, + "deno": true + }, + "excludes": [ + "**/node_modules", + "**/.nuxt", + "**/dist" + ], + "plugins": [ + "https://plugins.dprint.dev/typescript-0.88.0.wasm", + "https://plugins.dprint.dev/json-0.19.0.wasm", + "https://plugins.dprint.dev/markdown-0.16.0.wasm" + ] +} +``` + +## VS Code Settings + +Add to `.vscode/settings.json`: + +```jsonc +{ + "prettier.enable": false, + "editor.formatOnSave": false, + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit", + "source.organizeImports": "never" + }, + "eslint.rules.customizations": [ + { "rule": "style/*", "severity": "off", "fixable": true }, + { "rule": "format/*", "severity": "off", "fixable": true }, + { "rule": "*vue/max-attributes-per-line", "severity": "error", "fixable": true } + ], + "eslint.validate": [ + "javascript", + "javascriptreact", + "typescript", + "typescriptreact", + "vue", + "html", + "markdown", + "json", + "jsonc", + "yaml", + "css", + "less", + "scss" + ] +} +``` + +## Running ESLint + +```bash +# Lint and fix +pnpm run lint --fix + +# Check only +pnpm run lint +``` + +## Additional Rule Overrides + +If needed, add overrides after the main config: + +```ts +export default antfu({ + // ... base config +}) + .append(nuxt()) + .override('my-custom-rules', { + files: ['**/*.vue'], + rules: { + // Additional Vue-specific rules + }, + }) +``` + + diff --git a/vendor/ui/.agents/skills/oq/references/oq-unocss-config.md b/vendor/ui/.agents/skills/oq/references/oq-unocss-config.md new file mode 100644 index 0000000..ad3461b --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/oq-unocss-config.md @@ -0,0 +1,228 @@ +--- +name: oq-unocss-config +description: Custom UnoCSS configuration with specific fonts, prefixed attributify, and icon collections. Use when setting up UnoCSS for oQ-style projects. +--- + +# oQ's UnoCSS Configuration + +Personalized UnoCSS setup with custom fonts, prefixed attributify mode, and curated icon collections. + +## Configuration + +```ts +// uno.config.ts +import { + defineConfig, + presetAttributify, + presetIcons, + presetTagify, + presetTypography, + presetWind4, + transformerDirectives, + transformerVariantGroup, +} from 'unocss' + +// Optional: For Markdown support +// import extractorMdc from '@unocss/extractor-mdc' + +export default defineConfig({ + theme: { + breakpoints: { + sm: '600px', + md: '900px', + }, + }, + rules: [ + // Local fonts - place font files in assets/fonts/ + ['font-sans', { 'font-family': 'LXGW Neo ZhiSong Plus' }], + ['font-serif', { 'font-family': 'YshiPen-ShutiTC' }], + ['font-mono', { 'font-family': 'LXGW Bright Code TC' }], + // Google Fonts - loaded via Google Fonts CDN + ['font-stylish', { 'font-family': 'Caveat' }], + ['font-script', { 'font-family': 'Ephesis' }], + ], + content: { + pipeline: { + include: [ + /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html|css)($|\?)/, + ], + }, + }, + shortcuts: { + 'page-content': 'mx-auto max-w-[800px] block px-10 min-w-0', + }, + presets: [ + presetWind4(), + presetIcons({ + collections: { + carbon: () => import('@iconify-json/carbon/icons.json', { with: { type: 'json' } }).then(i => i.default), + solar: () => import('@iconify-json/solar/icons.json', { with: { type: 'json' } }).then(i => i.default), + openmoji: () => import('@iconify-json/openmoji/icons.json', { with: { type: 'json' } }).then(i => i.default), + }, + }), + presetAttributify({ + strict: true, + prefixedOnly: true, // Only match `un-` prefixed attributes + prefix: 'un-', + }), + presetTagify({ + prefix: 'un-', + }), + presetTypography(), + ], + transformers: [ + transformerDirectives(), + transformerVariantGroup(), + ], + extractors: [ + // Uncomment for Markdown support + // extractorMdc(), + ], + layers: { + default: 0, + components: 1, + utilities: 2, + }, +}) +``` + +## Key Features + +### Custom Fonts + +Five font families configured: + +| Class | Font | Type | Source | +|-------|------|------|--------| +| `font-sans` | LXGW Neo ZhiSong Plus | Sans-serif | Local files in `assets/fonts/` | +| `font-serif` | YshiPen-ShutiTC | Serif | Local files in `assets/fonts/` | +| `font-mono` | LXGW Bright Code TC | Monospace | Local files in `assets/fonts/` | +| `font-stylish` | Caveat | Handwriting | Google Fonts CDN | +| `font-script` | Ephesis | Script | Google Fonts CDN | + +### Prefixed Attributify Mode + +Uses `un-` prefix to avoid conflicts with other libraries: + +```html + +
+ + +
+``` + +Benefits: +- Avoids conflicts with Vue props or HTML attributes +- Clear separation of UnoCSS utilities +- Strict mode ensures only valid utilities work + +### Icon Collections + +Three curated icon sets: + +- **carbon**: IBM Carbon Design System icons +- **solar**: Solar icons by 480 Design +- **openmoji**: OpenMoji open source emojis + +Usage: +```html +
+
+
+``` + +### Shortcuts + +Pre-defined shortcuts for common patterns: + +```html + +
+ +
+``` + +## Dependencies + +```bash +# Core UnoCSS +pnpm add -D unocss + +# Presets +pnpm add -D @unocss/preset-attributify +pnpm add -D @unocss/preset-icons +pnpm add -D @unocss/preset-tagify +pnpm add -D @unocss/preset-typography +pnpm add -D @unocss/preset-wind4 + +# Transformers +pnpm add -D @unocss/transformer-directives +pnpm add -D @unocss/transformer-variant-group + +# Icon collections +pnpm add -D @iconify-json/carbon +pnpm add -D @iconify-json/solar +pnpm add -D @iconify-json/openmoji + +# Optional: Markdown support +# pnpm add -D @unocss/extractor-mdc +``` + +## Vite/Nuxt Integration + +### Vite + +```ts +// vite.config.ts +import UnoCSS from 'unocss/vite' +import { defineConfig } from 'vite' + +export default defineConfig({ + plugins: [ + UnoCSS(), + ], +}) +``` + +### Nuxt + +```ts +// nuxt.config.ts +export default defineNuxtConfig({ + modules: [ + '@unocss/nuxt', + ], + unocss: { + // Config loaded from uno.config.ts automatically + }, +}) +``` + +## Custom Breakpoints + +Custom responsive breakpoints: + +| Breakpoint | Width | +|------------|-------| +| `sm` | 600px | +| `md` | 900px | + +Usage: +```html +
+``` + +## Layers + +CSS layer ordering: + +1. `default` (0) - Base styles +2. `components` (1) - Component-specific styles +3. `utilities` (2) - Utility classes (highest specificity) + + diff --git a/vendor/ui/.agents/skills/oq/references/pnpm-catalog.md b/vendor/ui/.agents/skills/oq/references/pnpm-catalog.md new file mode 100644 index 0000000..84ad572 --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/pnpm-catalog.md @@ -0,0 +1,303 @@ +--- +name: pnpm-catalog +description: pnpm catalog configuration and management tools. Use when setting up workspace dependency management with strict catalog conventions. +--- + +# pnpm Catalog Configuration + +Strict pnpm catalog setup for consistent dependency management across workspaces. + +## What is pnpm Catalog? + +A centralized dependency version management system for pnpm workspaces. Instead of specifying versions in each package's `package.json`, you define them once in `pnpm-workspace.yaml`. + +**Benefits:** +- Single source of truth for dependency versions +- Easy bulk updates +- Prevents version drift across packages +- Automatic deduplication + +## Configuration + +### pnpm-workspace.yaml + +```yaml +packages: + - 'packages/*' + - 'apps/*' + +# Named catalogs - NEVER use default catalog +catalog: + # Production dependencies + prod: + vue: ^3.5.0 + pinia: ^2.2.0 + vue-router: ^4.4.0 + + # Bundler inlined dependencies + inlined: + defu: ^6.1.4 + scule: ^1.3.0 + + # Dev tools + dev: + typescript: ^5.6.0 + eslint: ^9.0.0 + vitest: ^2.1.0 + + # Frontend libraries + frontend: + '@vueuse/core': ^11.0.0 + '@vueuse/head': ^2.0.0 +``` + +### Using Catalog Dependencies + +In package.json, use `catalog:` protocol: + +```json +{ + "dependencies": { + "vue": "catalog:prod", + "pinia": "catalog:prod", + "defu": "catalog:inlined", + "@vueuse/core": "catalog:frontend" + }, + "devDependencies": { + "typescript": "catalog:dev", + "vitest": "catalog:dev" + } +} +``` + +### Catalog Protocol Syntax + +```json +{ + "package-name": "catalog:" // Use default catalog (AVOID) + "package-name": "catalog:prod", // Use 'prod' named catalog + "package-name": "catalog:dev" // Use 'dev' named catalog +} +``` + +## Catalog Organization Strategy + +### Recommended Categories + +| Catalog | Purpose | Examples | +|---------|---------|----------| +| `prod` | Production runtime deps | vue, pinia, vue-router | +| `inlined` | Bundled/inlined deps | defu, scule, pathe | +| `dev` | Development tools | typescript, eslint, vitest | +| `frontend` | UI/frontend libraries | @vueuse/core, unocss | +| `backend` | Server-side deps | h3, nitro, @trpc/server | +| `testing` | Testing utilities | @vue/test-utils, cypress | + +### Catalog Selection Rules + +1. **NEVER use the default catalog** - Always use named catalogs +2. **Group by function** - Similar purposes in same catalog +3. **Consider bundle size** - Separate inlined vs external deps +4. **Update frequency** - Group deps that update together + +## pnpm-workspace-utils + +Anthony Fu's tool for managing pnpm workspaces and catalogs. + +### Installation + +```bash +pnpm add -D pnpm-workspace-utils +``` + +### Usage + +```bash +# Check for catalog inconsistencies +pnpm exec pnpm-workspace-utils check + +# Update catalog versions interactively +pnpm exec pnpm-workspace-utils update + +# Sync catalog to all packages +pnpm exec pnpm-workspace-utils sync +``` + +### Features + +- Detects packages using non-catalog versions +- Shows outdated catalog entries +- Interactive version updates +- Validates workspace consistency + +## nip - Interactive Package Manager + +Interactive tool for managing dependencies in pnpm workspaces. + +### Installation + +```bash +pnpm add -D @antfu/nip +``` + +### Usage + +```bash +# Interactive dependency management +pnpm exec nip + +# Add dependency to specific workspace +pnpm exec nip add vue --workspace=apps/web + +# Update dependencies interactively +pnpm exec nip update + +# Remove dependency +pnpm exec nip remove lodash +``` + +### Features + +- Interactive UI for dependency management +- Workspace-aware operations +- Bulk add/remove/update +- Catalog integration + +## VS Code Integration + +### pnpm-catalog-lens Extension + +Shows catalog version hints inline: + +```json +// .vscode/extensions.json +{ + "recommendations": [ + "antfu.pnpm-catalog-lens" + ] +} +``` + +Features: +- Inline version hints +- Click to navigate to catalog definition +- Highlights non-catalog dependencies + +## Workflow + +### Adding a New Dependency + +1. **Check if it exists** in catalog: + ```bash + cat pnpm-workspace.yaml | grep package-name + ``` + +2. **If exists**: Use catalog protocol in package.json + ```json + { "package-name": "catalog:prod" } + ``` + +3. **If new**: Add to appropriate catalog first + ```yaml + catalog: + prod: + package-name: ^1.0.0 + ``` + +4. **Then install**: + ```bash + pnpm install + ``` + +### Updating Dependencies + +1. **Check status**: + ```bash + pnpm exec pnpm-workspace-utils check + ``` + +2. **Update catalog versions**: + ```bash + pnpm exec pnpm-workspace-utils update + ``` + +3. **Or manually** edit `pnpm-workspace.yaml` + +4. **Install updates**: + ```bash + pnpm update + ``` + +### Migration to Catalog + +Convert existing dependencies to use catalog: + +```bash +# Check for non-catalog deps +pnpm exec pnpm-workspace-utils check + +# Shows recommendations for migration +# Manually update package.json files to use catalog: protocol +``` + +## Common Patterns + +### Lockfile Maintenance + +```json +{ + "scripts": { + "clean": "rm -rf node_modules pnpm-lock.yaml", + "fresh": "pnpm clean && pnpm install", + "check-catalog": "pnpm-workspace-utils check" + } +} +``` + +### CI/CD with Catalog + +```yaml +# .github/workflows/ci.yml +- name: Install dependencies + run: pnpm install --frozen-lockfile + +# Lockfile ensures catalog versions are respected +``` + +## Best Practices + +1. **Always use named catalogs** - Never rely on default catalog +2. **Keep catalogs organized** - Group by purpose/function +3. **Regular consistency checks** - Run `pnpm-workspace-utils check` +4. **Document catalog categories** - Add comments in pnpm-workspace.yaml +5. **Update systematically** - Use tools for bulk updates +6. **Pin critical versions** - For sensitive deps, use exact versions + +## Troubleshooting + +### Dependency not found + +```bash +# Ensure catalog is defined +pnpm exec pnpm-workspace-utils check + +# Reinstall to pick up catalog changes +rm -rf node_modules pnpm-lock.yaml && pnpm install +``` + +### Version conflicts + +```bash +# Check which packages use different versions +pnpm why package-name + +# Update catalog to resolve +pnpm exec pnpm-workspace-utils update +``` + + diff --git a/vendor/ui/.agents/skills/oq/references/release-workflow.md b/vendor/ui/.agents/skills/oq/references/release-workflow.md new file mode 100644 index 0000000..fcc4013 --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/release-workflow.md @@ -0,0 +1,221 @@ +--- +name: release-workflow +description: Automated GitHub releases using changelogithub. Use when setting up release automation for oQ-style projects. +--- + +# Release Workflow + +Automated GitHub releases using [changelogithub](https://github.com/antfu/changelogithub) by Anthony Fu. + +## What is changelogithub? + +Generates beautiful changelogs from conventional commits and creates GitHub releases automatically. + +- Parses conventional commits +- Groups changes by type (features, fixes, etc.) +- Generates markdown changelog +- Creates GitHub releases with notes +- Cross-references issues and PRs + +## GitHub Actions Workflow + +**`.github/workflows/release.yml`**: + +```yaml +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install pnpm + uses: pnpm/action-setup@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: lts/* + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build + run: pnpm run build + + - name: Release + run: npx changelogithub + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +## Conventional Commits + +changelogithub parses conventional commits. Follow this format: + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### Types + +| Type | Description | Changelog Section | +|------|-------------|-------------------| +| `feat` | New feature | ✨ Features | +| `fix` | Bug fix | 🐞 Bug Fixes | +| `docs` | Documentation changes | 📖 Documentation | +| `style` | Code style changes | 🎨 Styles | +| `refactor` | Code refactoring | 🏗 Refactoring | +| `perf` | Performance improvements | ⚡ Performance | +| `test` | Adding/updating tests | 🧪 Tests | +| `chore` | Build/process changes | 🛠 Chore | + +### Examples + +```bash +# Feature +feat: add user authentication + +# Bug fix +fix(api): resolve null pointer exception + +# Breaking change +feat!: redesign API response format + +# With scope and body +feat(auth): implement OAuth2 login + +Adds support for Google and GitHub OAuth2 providers. +Closes #123 +``` + +## Versioning + +Use semantic versioning for tags: + +```bash +# Patch release (bug fixes) +git tag v1.0.1 + +# Minor release (features, backwards compatible) +git tag v1.1.0 + +# Major release (breaking changes) +git tag v2.0.0 +``` + +## Release Process + +1. **Ensure all changes are committed** with conventional commit messages +2. **Update version** in package.json (if applicable) +3. **Create and push tag**: + ```bash + git tag v1.0.0 + git push origin v1.0.0 + ``` +4. **GitHub Actions automatically**: + - Runs build + - Generates changelog + - Creates GitHub release + +## Changelog Preview + +Generated changelog includes: + +- ✨ Features +- 🐞 Bug Fixes +- 🏗 Refactoring +- 📖 Documentation +- 🧪 Tests +- ⚡ Performance +- 🎨 Styles +- 🛠 Chore + +## Custom Configuration + +Create `changelogithub.config.ts` for customization: + +```ts +import { defineConfig } from 'changelogithub' + +export default defineConfig({ + // Filter commits + types: { + feat: { title: '🚀 Features' }, + fix: { title: '🐛 Bug Fixes' }, + docs: { title: '📚 Documentation' }, + }, + + // Exclude certain commits + excludeScopes: ['deps', 'ci'], + + // Custom contributors section + contributors: true, +}) +``` + +## Alternative: sxzz/workflows + +For a simpler setup, use the reusable workflow: + +```yaml +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + release: + uses: sxzz/workflows/.github/workflows/release.yml@v1 + with: + publish: true + permissions: + contents: write + id-token: write +``` + +This uses changelogithub internally with sensible defaults. + +## Required Permissions + +Ensure GitHub Actions has write permissions: + +1. Go to **Settings → Actions → General** +2. Under **Workflow permissions**, select: + - ✅ Read and write permissions + - ✅ Allow GitHub Actions to create and approve pull requests + +## Troubleshooting + +### No changelog generated + +- Ensure commits follow conventional commit format +- Check that tags follow semantic versioning (`v*.*.*`) +- Verify GITHUB_TOKEN has write permissions + +### Missing entries + +- Only commits since last tag are included +- Squash merges preserve commit messages from the PR +- Use `!` suffix for breaking changes + + diff --git a/vendor/ui/.agents/skills/oq/references/setting-up.md b/vendor/ui/.agents/skills/oq/references/setting-up.md new file mode 100644 index 0000000..6574f7f --- /dev/null +++ b/vendor/ui/.agents/skills/oq/references/setting-up.md @@ -0,0 +1,214 @@ +--- +name: setting-up +description: Project setup files including .gitignore, GitHub Actions workflows, VS Code extensions, and font loading. Use when initializing new projects with oQ's style. +--- + +# Project Setup + +## .gitignore + +Create when `.gitignore` is not present: + +``` +*.log +*.tgz +.cache +.DS_Store +.eslintcache +.idea +.env +.env.local +.env.*.local +.nuxt +.temp +.output +.turbo +cache +coverage +dist +lib-cov +logs +node_modules +temp +``` + +## GitHub Actions + +### Autofix Workflow + +**`.github/workflows/autofix.yml`** - Auto-fix linting on PRs: + +```yaml +name: autofix.ci + +on: [pull_request] + +jobs: + autofix: + uses: sxzz/workflows/.github/workflows/autofix.yml@v1 + permissions: + contents: read +``` + +### Unit Test Workflow + +**`.github/workflows/unit-test.yml`** - Run tests on push/PR: + +```yaml +name: Unit Test + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: {} + +jobs: + unit-test: + uses: sxzz/workflows/.github/workflows/unit-test.yml@v1 +``` + +### Release Workflow + +See [release-workflow](release-workflow.md) for changelogithub setup. + +## VS Code Extensions + +Configure in `.vscode/extensions.json`: + +```json +{ + "recommendations": [ + "dbaeumer.vscode-eslint", + "antfu.pnpm-catalog-lens", + "antfu.iconify", + "antfu.unocss", + "antfu.slidev", + "vue.volar" + ] +} +``` + +| Extension | Description | +|-----------|-------------| +| `dbaeumer.vscode-eslint` | ESLint integration for linting and formatting | +| `antfu.pnpm-catalog-lens` | Shows pnpm catalog version hints inline | +| `antfu.iconify` | Iconify icon preview and autocomplete | +| `antfu.unocss` | UnoCSS IntelliSense and syntax highlighting | +| `antfu.slidev` | Slidev preview and syntax highlighting | +| `vue.volar` | Vue Language Features | + +## Font Loading + +### Local Fonts + +For LXGW Neo ZhiSong Plus, YshiPen-ShutiTC, and LXGW Bright Code TC: + +1. Place font files in `assets/fonts/` +2. Create CSS `@font-face` declarations: + +```css +/* assets/fonts/fonts.css */ +@font-face { + font-family: 'LXGW Neo ZhiSong Plus'; + src: url('./LXGWNeoZhiSongPlus-Regular.woff2') format('woff2'); + font-weight: normal; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'YshiPen-ShutiTC'; + src: url('./YshiPen-ShutiTC-Regular.woff2') format('woff2'); + font-weight: normal; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'LXGW Bright Code TC'; + src: url('./LXGWBrightCodeTC-Regular.woff2') format('woff2'); + font-weight: normal; + font-style: normal; + font-display: swap; +} +``` + +3. Import in your app entry: + +```ts +// main.ts or app.vue +import '~/assets/fonts/fonts.css' +``` + +### Google Fonts + +For Caveat and Ephesis, add to your HTML head: + +```html + + + +``` + +Or via Nuxt configuration: + +```ts +// nuxt.config.ts +export default defineNuxtConfig({ + app: { + head: { + link: [ + { rel: 'preconnect', href: 'https://fonts.googleapis.com' }, + { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }, + { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Caveat:wght@400;500;600;700&family=Ephesis&display=swap' }, + ], + }, + }, +}) +``` + +## package.json Scripts + +Standard scripts for oQ-style projects: + +```json +{ + "scripts": { + "dev": "nuxt dev", + "build": "nuxt build", + "generate": "nuxt generate", + "preview": "nuxt preview", + "lint": "eslint . --cache --concurrency=auto", + "lint:fix": "eslint . --cache --concurrency=auto --fix", + "postinstall": "nuxt prepare", + "prepare": "npx simple-git-hooks" + } +} +``` + +## TypeScript Configuration + +```json +{ + "compilerOptions": { + "target": "ESNext", + "module": "ESNext", + "moduleResolution": "bundler", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "resolveJsonModule": true, + "isolatedModules": true, + "noEmit": true, + "baseUrl": ".", + "paths": { + "~/*": ["./*"], + "@/*": ["./*"] + } + }, + "exclude": ["node_modules", ".nuxt", "dist"] +} +``` diff --git a/vendor/ui/.gitignore b/vendor/ui/.gitignore index bffefe6..b6d6d66 100644 --- a/vendor/ui/.gitignore +++ b/vendor/ui/.gitignore @@ -3,6 +3,8 @@ dist .nuxt .output .data +.cloudflare +.wrangler .eslintcache *.log .DS_Store diff --git a/vendor/ui/README.md b/vendor/ui/README.md index e7004d1..df44780 100644 --- a/vendor/ui/README.md +++ b/vendor/ui/README.md @@ -1,59 +1,70 @@ # @froq/ui -froq 自己项目用的 UI 库。共用的逻辑和 token 契约在 `core`、`vue`,组件在 `src/components`。 +Shared logic, a token contract, and the components. +`core` and `vue` have no project styles. +Components live in `src/components`. ``` src/ - core/ 纯 TS,不依赖任何框架:token 契约、键盘导航、笔画几何、减弱动效判断 - vue/ 无样式的 Vue 行为层(useChoice、useClipboard 等) - components/ 一个目录一个概念,例如 radio/、toggle/ - index.ts 从 @froq/ui 导出的组件 + core/ TypeScript. No framework. Tokens, keyboard, strokes, reduced motion + vue/ Vue behavior without styles + components/ One directory per concept, such as radio/ or toggle/ + index.ts Components exported from @froq/ui style.css tokens.css -docs/ 文档站(Nuxt Content)。workspace 依赖本库,改组件和改文档在同一次提交里 +docs/ Docs site. It depends on this package. Component and docs changes ship together ``` -## 组件 +## Components -**AI Draft · 待人工设计验证。** 当前所有组件均为 AI 生成的初稿,尚未经维护者手动设计或视觉验收。已有实现不等于设计定稿;组件旁的中英文说明以 `designStatus: ai-draft` 记录此状态,文档站统一展示标记。暂时接受当前实现不解除此标记。 +> [!NOTE] +> Design status is `ai-draft`, `reviewed`, or `stable`. +> Most notes are still `ai-draft`. A working component is not a finished design. +> Menu and Select lists are `reviewed`. +> The docs site shows the mark on each note. -都从 `@froq/ui` 导出: +Everything below is exported from `@froq/ui`. -| 组件 | 说明 | +| Component | Role | | --- | --- | -| Button / CopyButton | 原生按钮、异步剪贴板与稳定宽度反馈 | -| TextInput / TextArea / Select / Checkbox | 原生表单控件;native attributes/events 传到实际控件 | -| FormField / NumberInput / DateInput / Slider / FileUpload / RadioGroup | 标签与错误关联、原生数值/日期/范围/文件/单选;业务校验与重置由调用方负责 | -| Choice / ChoiceCircle / Toggle | 受控选择与开关;支持禁用;自定义 radio 不自动提交表单值 | -| ToggleGroup | 单选或多选二态按钮组;方向键只移动焦点,允许取消已选值 | -| Combobox | 搜索选择与多选;选中值、输入文本、展开状态独立,远程请求由调用方处理 | -| Calendar / DatePicker | 共用单月日历的内联选择与弹层选择;ISO 日期字符串、语言格式、范围及禁选日期 | -| Navigation / Sidebar | 扁平链接、多级可折叠导航;调用方负责路由 | -| Breadcrumb / Pagination | 有序路径、受控页码与真实分页链接;不生成路由或请求数据 | -| Collapsible / Accordion / Tabs | 受控展开与标签面板;保持面板内容挂载 | -| Skeleton / Progress / Spinner / Alert | 区域加载态、进度、等待和行内提示 | -| Banner | 站点级活动、公告与 WIP 通知;操作插槽与使用方管理的关闭 | -| Toast / ToastRegion | 受控临时通知、共享呈现区域与可清理暂停计时;消息队列留在调用方 | -| IconButton / EmptyState | 命名图标按钮、空内容与操作插槽 | -| Badge / Avatar / Separator / Card / AspectRatio / Table | 内容标记、图片占位、分隔、表面、媒体比例与原生表格 | -| Dialog / AlertDialog / Drawer / Popover / DropdownMenu / Tooltip | 弹窗、确认、侧边面板、锚定浮层、嵌套命令菜单与文字提示 | -| ContextMenu / HoverCard | 焦点/右键命令菜单与链接补充预览;预览不承载必需信息或操作 | -| Paper | 纸张纹理皮肤 | - -每个组件旁有 demo 和中英文 API 说明,文档站自动从源码发现,不维护第二份名单。已实现项目与后续范围见 [覆盖记录](./docs/component-roadmap.md);可导出不代表已完成手动视觉验收。 - -## Token 契约 - -`tokens.css` 在作用域类 `.ui` 上定义下面这些变量,组件只读它们,不读别的: +| Button / CopyButton | Native button. Async clipboard, stable width | +| TextInput / TextArea / Select / Checkbox | Native fields. Attributes and events reach the control | +| FormField / NumberInput / DateInput / Slider / FileUpload / RadioGroup | Label, error, native value. Validation stays with the caller | +| Choice / ChoiceCircle / Toggle | Controlled choice and switch. Custom radio does not submit a form value | +| ToggleGroup | Single or multiple. Arrow keys move focus. A selected value can be cleared | +| Combobox | Search and multiple selection. Remote requests stay with the caller | +| Calendar / DatePicker | One month. ISO dates, locale, range, disabled dates | +| Navigation / Sidebar | Flat links and collapsible groups. Routing stays with the caller | +| Breadcrumb / Pagination | Path and page links. No router and no data fetching | +| Collapsible / Accordion / Tabs | Controlled panels. Content stays mounted | +| Skeleton / Progress / Spinner / Alert | Loading, progress, wait, inline notice | +| Banner | Site notice. Actions slot. The caller owns dismissal | +| Toast / ToastRegion | Temporary notice and a shared region. The queue stays with the caller | +| IconButton / EmptyState | Named icon button. Empty content and an actions slot | +| Badge / Avatar / Separator / Card / AspectRatio / Table | Mark, image, rule, surface, ratio, native table | +| Dialog / AlertDialog / Drawer / Popover / Menu / Tooltip | Dialog, confirm, side panel, anchored layer, menu, tip | +| ContextMenu / HoverCard | Context menu and link preview. The preview is not required content | +| Paper | Paper texture | + +Each component has a demo, an English note, and a Chinese note. +The docs site discovers them from the source. +There is no second list. +Coverage is in [docs/component-roadmap.md](docs/component-roadmap.md). + +## Tokens + +`tokens.css` defines these on `.ui`. +Components read only these: `--ui-bg` `--ui-fg` `--ui-muted` `--ui-faint` `--ui-line` `--ui-accent` `--ui-font-display` `--ui-font-text` `--ui-font-meta` `--ui-ease` `--ui-dur` `--ui-radius` -- 颜色用 `light-dark()`,跟随系统;在自己或祖先元素上写 `data-theme="light|dark"` 可以强制。 -- 作用域是一个类,不是全局。把 `class="ui"` 放在页面里的一块区域上,那一块就用这些变量。 -- 只想要 token、不用 Vue 组件的项目,单独引 `@froq/ui/tokens.css` 就行。 -- `pnpm check:tokens` 检查所有变量都有定义,以及组件样式没有读取契约外的变量。 +Color uses `light-dark()` and follows the system. +Set `data-theme="light"` or `data-theme="dark"` on the scope, or an ancestor, to force one. +`.ui` is a class, not the document. +`@froq/ui/tokens.css` is enough when a project wants the tokens without the components. +`pnpm check:tokens` fails if a variable is missing, or if a component reads one outside this list. -## 使用 +## Use ```ts import '@froq/ui/style.css' @@ -66,23 +77,12 @@ import { Choice, Toggle } from '@froq/ui'
``` -字体不打包在库里。组件用 Instrument Serif、Geist、Geist Mono,项目自己引(比如 `@fontsource*`),没引就退回系统字体。 +Fonts are not in the package. +Components expect Instrument Serif, Geist, and Geist Mono. +Load them in the app, or the page falls back to system fonts. +Those faces are SIL OFL 1.1. -Skeleton 只管理显式的 `loading`,不等待字体、路由或请求。用默认插槽保留已知区域的布局;未知内容由调用方用 `width` / `height` 预留尺寸。不要为了静态内容刷新而套加载框。 - -Toast 在共享的 ToastRegion 里使用。消息队列、ID、请求结果和重要信息的持久展示留在调用方;Toast 不是限时确认框。无样式行为 `useAutoDismiss(active, { duration, paused?, onDismiss })` 从 `@froq/ui/vue` 导出,在组件 setup 中调用:挂载后开始计时,暂停保留余时,重新激活或修改 duration 重置,关闭/卸载清理;非有限或不大于零的时长不自动关闭。 - -Calendar / DatePicker 使用公历 `YYYY-MM-DD` 或空字符串,不把日期转换成当地时区的时间戳。`locale` 和空值时的 `initialDate` 由调用方提供;`today` 标记也是显式传入,以保持 SSR 一致。基础日期函数 `parseCalendarDate`、`calendarDateBounds`、`formatCalendarDate` 从 `@froq/ui/core` 导出。DatePicker 是日历按钮,不承诺原生表单必填校验;需要原生输入、必填和日期范围校验时使用 DateInput。 - -弹层组件依赖 `reka-ui`,使用方安装 file 依赖时由包管理器一并安装。默认 portal 目标是最近的 `.ui`,以保留主题与 token。指定 `portal-to` 时目标必须存在并由使用方提供同样的主题作用域;不要直接移到未配置 token 的 body。变换或裁剪该作用域可能影响 fixed 弹层,必要时指定独立的已配置作用域。 - -Dialog / Drawer 默认有内置触发器;外部列表条目控制打开时,设 `:show-trigger="false"`,并把实际开启按钮的 DOM 元素传给 `return-focus`。关闭后优先返回该可用元素,否则尝试打开时捕获的焦点;开启者已移除时,由调用方通过可取消的 `closeAutoFocus` 事件选择后备位置。`disabled` 不会替调用方禁用外部按钮。无样式 `useFocusReturn(open, target, captureFallback)` 从 `@froq/ui/vue` 导出,绑定层的可取消 open/close autofocus 事件;它不实现焦点陷阱。代表性组合源码在 [ConsumerAdapters.vue](docs/examples/ConsumerAdapters.vue),不是已迁移的外部项目或 UI 验收结果。 - -ContextMenu 通过组件 ref 暴露 `close()`,消费端可据此实现滚动或路由切换时关闭。禁用或关闭不会重挂载目标插槽;已排队的过期打开请求被拦截,但不声称取消了 Reka 内部计时器。无样式 `useContextMenuControl(disabled)` 从 `@froq/ui/vue` 导出,只能在 Reka ContextMenuRoot 后代中调用;返回 `close` 与供触发器 capture 事件使用的 `prepare`。菜单仍是内部状态,没有受控 `open` 或 `v-model`。 - -根包的运行时依赖必须写普通版本范围,不能用本 workspace 的 `catalog:`:外部项目通过 `file:vendor/ui` 安装时无法解析库的 catalog。开发工具仍使用具名 catalog。 - -包里发的是源码(`.vue`、`.ts`、`.css`),由使用方的构建工具编译。Vite 项目直接可用;Nuxt 需要: +Nuxt: ```ts export default defineNuxtConfig({ @@ -91,30 +91,104 @@ export default defineNuxtConfig({ }) ``` -## 放进别的项目 - -别的项目自己带一份源码,放在 `vendor/ui`,并提交在那个项目里。本地 dev 和远端构建都编译项目提交里的这一份。给 agent 的步骤写在 [`AGENTS.md`](./AGENTS.md)。安装时还要把「推送到上游」「拉取上游」和「把项目里的组件抽进库」写进该项目自己的 agent markdown。 - -## 加一个组件 - -先在 `src/vue/` 里写行为(不管样子),再在 `src/components//.vue` 里写组件,并从 `src/index.ts` 导出。旁边加 `.demo.vue`、`.md` 和 `.zh.md`。概念页在 `/components/`,放这个目录里的 demo。组件页在 `/components//`,渲染旁边的说明。左侧目录里分组标题不是页面,概念和组件是页面。 - -## 命令 +The package publishes source. +Vite compiles it. +The root dependencies use normal version ranges, not this workspace's `catalog:`. +A consumer that installs `file:vendor/ui` cannot see the catalog. +Dev tools may use a named catalog. + +## Behavior that stays with the caller + +Skeleton follows an explicit `loading` prop. +It does not wait for fonts, routes, or requests. +Use the default slot when the layout is known. +Use `width` and `height` when it is not. + +Toast renders inside `ToastRegion`. +The queue, ids, and anything that must remain on screen stay with the caller. +`useAutoDismiss(active, { duration, paused?, onDismiss })` is exported from `@froq/ui/vue`. +Call it in setup. +A pause keeps the remaining time. +A new duration or a new activation resets it. +A duration that is not finite and greater than zero does not auto-close. + +Calendar and DatePicker use a Gregorian `YYYY-MM-DD` string, or `''`. +They do not convert that string into a zoned timestamp. +The caller passes `locale`, `initialDate`, and `today`. +`parseCalendarDate`, `calendarDateBounds`, and `formatCalendarDate` come from `@froq/ui/core`. +DatePicker is a calendar button. +Use DateInput when the form needs a native date field. + +Overlays use `reka-ui`. +The default portal target is the nearest `.ui`, so the theme stays. +`portal-to` must exist and carry the same tokens. +Do not portal into a `body` that has none. +A transform or clip on the scope can break a fixed layer. + +Dialog and Drawer include a trigger. +For an external opener, set `:show-trigger="false"` and pass that opener's element as `return-focus`. +`disabled` does not disable the external button. +`useFocusReturn(open, target, captureFallback)` is exported from `@froq/ui/vue`. +It does not trap focus. +[docs/examples/ConsumerAdapters.vue](docs/examples/ConsumerAdapters.vue) shows the wiring. +It is not a migrated site and it is not a visual acceptance test. + +`ContextMenu` exposes `close()` on the component ref. +`useContextMenuControl(disabled)` must run under `ContextMenuRoot`. +The menu is not a `v-model`. + +## In another project + +That project keeps its own copy in `vendor/ui` and commits it. +Dev and the remote build compile that copy. +The agent steps are in [AGENTS.md](AGENTS.md). +On install, also write the push, pull, and extract steps into that project's agent markdown. + +## Add a component + +Write the behavior in `src/vue/` first. +Then `src/components//.vue`. +Export it from `src/index.ts`. +Add `.demo.vue`, `.md`, and `.zh.md` beside it. +`/components/` shows the demos. +`/components//` renders the note. +Group labels in the sidebar are not pages. +Concepts and components are. + +## Commands ```bash -pnpm dev # 文档站 http://localhost:3000 -pnpm generate # 静态导出到仓库根的 dist/,和 Cloudflare Pages 的输出目录一致 -pnpm check # lint + 类型检查 + token 契约检查 +pnpm dev # docs at http://localhost:3000 +pnpm generate # static files in dist/ +pnpm deploy # generate, then cf deploy +pnpm preview:deploy # generate, then cf previews deploy +pnpm check # lint, types, token contract ``` -## 文档站 +## Docs site + +https://ui.froq.me + +`docs/` is Nuxt Content. +The static output is `dist/` at the repo root. +It deploys to the Cloudflare Worker `ui`. +The Worker config is `cloudflare.config.ts`; the assets directory is in `wrangler.config.ts`. -https://ui-a09.pages.dev +Workers Builds (GitHub connection, no API token in the repo): `NODE_VERSION=22`, build `pnpm generate`, production `pnpm exec cf deploy`, preview `pnpm exec cf previews deploy`. -`docs/` 用 Nuxt Content。部署方式和 paper-landing 一样:Cloudflare Pages 连接这个 GitHub 仓库,生产分支 `main`,构建命令 `pnpm generate`,输出目录 `dist`,环境变量 `NODE_VERSION=22`。 +The docs live in the `docs/` subpackage, so root `cf deploy` does not run generate on its own. +That is why `deploy` is `pnpm generate && cf deploy`. +`docs` keeps `nuxt` in peerDependencies so root `cf deploy` bundles `dist/` instead of running `pnpm nuxt build`. -`nuxt generate` 在 Cloudflare 上会因为 `CF_PAGES=1` 把静态文件写到 `dist/`。文档站把 Nitro preset 固定成 `cloudflare-pages-static`,并把输出目录指到仓库根的 `dist/`,这样本地和线上是同一个目录。 +Queries run in the browser from the bundled WASM SQLite and SQL dump. +Do not use the `cloudflare_pages` Nitro preset. +A passing local generate is not a verified deploy. +See [the release audit](docs/release-audit.md). +CI installs from the lockfile. -当前发布路径是纯静态文件,不是 Pages Functions:内容查询在客户端使用打包的 WASM SQLite 和 SQL dump。Nuxt Content 的 Cloudflare preset 仍可能打印 D1 提示,但不要因此给这份静态产物虚构数据库绑定;若改为服务端 `cloudflare-pages` 部署,才需要按官方步骤配置 D1。参见 [Nuxt Content 静态部署](https://content.nuxt.com/docs/deploy/static) 与 [Pages 服务端部署](https://content.nuxt.com/docs/deploy/cloudflare-pages)。本地生成通过不等于已经部署或验收线上页面。 +## License -当前交付证据及待验收项见 [发布审计](docs/release-audit.md)。CI 按提交中的锁文件安装;不要依赖构建时重新解析版本来掩盖不兼容。 +This package has no root license file. +The handwriting strokes in `src/core/signature/` are SIL OFL 1.1. +Copyright 2010 The Allura Project Authors. +See `OFL.txt` and `NOTICE.md` beside that data. diff --git a/vendor/ui/cloudflare.config.ts b/vendor/ui/cloudflare.config.ts new file mode 100644 index 0000000..2285441 --- /dev/null +++ b/vendor/ui/cloudflare.config.ts @@ -0,0 +1,18 @@ +import { defineConfig } from 'cf/config' + +export default defineConfig({ + worker: { + name: 'ui', + compatibilityDate: '2026-10-12', + observability: { + enabled: true, + traces: { + enabled: true, + }, + }, + assets: { + htmlHandling: 'drop-trailing-slash', + notFoundHandling: '404-page', + }, + }, +}) diff --git a/vendor/ui/docs/app/app.config.ts b/vendor/ui/docs/app/app.config.ts index 7b08102..0ff44d4 100644 --- a/vendor/ui/docs/app/app.config.ts +++ b/vendor/ui/docs/app/app.config.ts @@ -1,4 +1,15 @@ export default defineAppConfig({ + ogCovers: { + mark: 'froQ', + colors: { + title: '#1a1917', + paper: '#f4f2ec', + border: 'rgba(26, 25, 23, 0.12)', + mark: 'rgba(26, 25, 23, 0.11)', + meta: '#85837c', + evergreen: 'rgba(22, 163, 74, 0.8)', + }, + }, site: { nav: [ { label: 'nav.docs', to: '/docs', external: false }, @@ -13,7 +24,7 @@ export default defineAppConfig({ }, { label: 'docs.groups.contract', - items: ['/docs/tokens'], + items: ['/docs/tokens', '/docs/language'], }, ], }, diff --git a/vendor/ui/docs/app/components/ComponentStatus.vue b/vendor/ui/docs/app/components/ComponentStatus.vue index 5048479..4577d54 100644 --- a/vendor/ui/docs/app/components/ComponentStatus.vue +++ b/vendor/ui/docs/app/components/ComponentStatus.vue @@ -1,21 +1,57 @@ diff --git a/vendor/ui/docs/app/composables/usePaperOgImage.ts b/vendor/ui/docs/app/composables/usePaperOgImage.ts new file mode 100644 index 0000000..9d3fbea --- /dev/null +++ b/vendor/ui/docs/app/composables/usePaperOgImage.ts @@ -0,0 +1,106 @@ +import type { MaybeRefOrGetter } from 'vue' +import type { ShareMetaInput } from './useShareMeta' +import { shareTitle, SITE_DESCRIPTION, SITE_NAME } from '~/utils/site' + +function cardTitle(value: string | undefined): string { + const titled = shareTitle(value) + return titled || SITE_NAME +} + +/** Generated paper card for routes that are not Nuxt Content entries. */ +export function usePaperOgImage( + share: ShareMetaInput, + paper?: { title?: MaybeRefOrGetter }, +): void { + const title = computed(() => cardTitle( + paper?.title != null ? toValue(paper.title) : toValue(share.title), + )) + + defineOgImage('Paper', { + title: () => title.value, + description: () => { + const raw = share.description == null ? undefined : toValue(share.description) + return (typeof raw === 'string' ? raw.trim() : '') || SITE_DESCRIPTION + }, + words: 0, + }, { + alt: () => title.value, + }) + + useShareMeta({ + ...share, + image: false, + }) +} + +interface ContentPage { + path: string + title?: string | null + description?: string | null + cover?: string | null + ogImage?: boolean | { url?: string, component?: string, props?: Record } | null + evergreen?: boolean | null + kind?: string | null + created?: string | null + date?: string | null + updated?: string | null + last_modified?: string | null + words?: number | null +} + +/** Cover precedence + generated paper card for a Nuxt Content entry. */ +export function useContentOgImage( + page: MaybeRefOrGetter, + collection: string, + share: Omit, +): void { + const files = useRuntimeConfig().public.publicFiles + const override = computed(() => contentOgOverride(toValue(page), collection, files)) + const current = computed(() => toValue(page)) + + if (override.value === undefined) { + defineOgImage(ogComponentName(current.value), { + title: () => paperFields(current.value).title, + description: () => paperFields(current.value, SITE_DESCRIPTION).description, + evergreen: () => paperFields(current.value).evergreen, + created: () => paperFields(current.value).created, + updated: () => paperFields(current.value).updated, + words: () => paperFields(current.value).words, + ...ogExtraProps(current.value), + }, { + alt: () => paperFields(current.value).title, + }) + } + + useShareMeta({ + ...share, + image: () => override.value === undefined ? false : override.value, + }) +} + +/** Index/list routes under a collection (e.g. changelog) without a content file. */ +export function useCollectionIndexOgImage( + source: { collection: string, path: string }, + share: ShareMetaInput, +): void { + const files = useRuntimeConfig().public.publicFiles + const override = computed(() => explicitContentCover(source, path => hasShareFile(files, path))) + + if (!override.value) { + defineOgImage('Paper', { + title: () => cardTitle(toValue(share.title)), + description: () => { + const raw = share.description == null ? undefined : toValue(share.description) + return (typeof raw === 'string' ? raw.trim() : '') || SITE_DESCRIPTION + }, + words: 0, + }, { + alt: () => cardTitle(toValue(share.title)), + }) + } + + useShareMeta({ + ...share, + image: () => override.value ?? false, + }) +} diff --git a/vendor/ui/docs/app/composables/useShareMeta.ts b/vendor/ui/docs/app/composables/useShareMeta.ts new file mode 100644 index 0000000..883b2bf --- /dev/null +++ b/vendor/ui/docs/app/composables/useShareMeta.ts @@ -0,0 +1,72 @@ +import type { MaybeRefOrGetter } from 'vue' +import { absoluteImageUrl, canonicalUrl, OG_IMAGE_HEIGHT, OG_IMAGE_PATH, OG_IMAGE_WIDTH, shareTitle, SITE_NAME } from '~/utils/site' + +export interface ShareMetaInput { + title?: MaybeRefOrGetter + description?: MaybeRefOrGetter + type?: MaybeRefOrGetter<'website' | 'article' | undefined> + /** + * Share image path or https URL. + * `false` when defineOgImage owns `og:image`. + * Omitted routes use `/og.png`. + */ + image?: MaybeRefOrGetter +} + +function filled(value: string | undefined, fallback: string): string { + const text = value?.trim() + return text || fallback +} + +/** Document title plus Open Graph / Twitter tags for the current route. */ +export function useShareMeta(input: ShareMetaInput = {}): void { + const route = useRoute() + + const title = computed(() => shareTitle(input.title == null ? undefined : toValue(input.title))) + const description = computed(() => { + const value = input.description == null ? undefined : toValue(input.description) + return filled(value, SITE_DESCRIPTION) + }) + const type = computed(() => toValue(input.type) ?? 'website') + const url = computed(() => canonicalUrl(route.path)) + const skipImage = toValue(input.image) === false + const image = computed(() => { + const value = toValue(input.image) + if (value === false || !value) + return absoluteImageUrl(OG_IMAGE_PATH) + return absoluteImageUrl(value) + }) + + useHead({ + title: () => input.title == null ? undefined : toValue(input.title) || undefined, + }) + + useSeoMeta({ + description: () => description.value, + ogTitle: () => title.value, + ogDescription: () => description.value, + ogUrl: () => url.value, + ogType: () => type.value, + ogSiteName: SITE_NAME, + twitterCard: 'summary_large_image', + twitterTitle: () => title.value, + twitterDescription: () => description.value, + }) + + if (!skipImage) { + useSeoMeta({ + ogImage: () => image.value, + ogImageSecureUrl: () => image.value, + ogImageType: 'image/png', + ogImageWidth: OG_IMAGE_WIDTH, + ogImageHeight: OG_IMAGE_HEIGHT, + ogImageAlt: () => title.value, + twitterImage: () => image.value, + twitterImageAlt: () => title.value, + }) + } + + useHead({ + link: [{ rel: 'canonical', href: () => url.value }], + }) +} diff --git a/vendor/ui/docs/app/error.vue b/vendor/ui/docs/app/error.vue index 127a015..cb4e7f4 100644 --- a/vendor/ui/docs/app/error.vue +++ b/vendor/ui/docs/app/error.vue @@ -1,12 +1,15 @@