@soybeanjs/ui 0.28.2 → 0.29.0-beta.2

package/README.md

@@ -1,10 +1,4 @@
-<p align="center">
-  <a href="https://github.com/soybeanjs/soybean-ui">
-    <img src="./public/logo.svg" alt="Logo" width="150" />
-  </a>
-</p>
-
-# SoybeanUI
+# @soybeanjs/ui
 
 English | [中文](./README.zh-CN.md)
 
@@ -13,60 +7,128 @@ English | [中文](./README.zh-CN.md)
 [![npm downloads](https://img.shields.io/npm/dt/@soybeanjs/ui)](https://www.npmjs.com/package/@soybeanjs/ui)
 [![github stars](https://img.shields.io/github/stars/soybeanjs/soybean-ui)](https://github.com/soybeanjs/soybean-ui)
 
-SoybeanUI is an elegant, modern, accessible and high-quality UI component library with shadcn-like design for Vue 3, built on top of a robust headless foundation. It provides a comprehensive set of accessible, customizable, and performant components.
+An elegant, modern, accessible UI component library with shadcn-like design for Vue 3, built on top of `@soybeanjs/headless`.
 
-## 📚 Architecture
+## 📖 Introduction
 
-SoybeanUI is built on a strict **two-layer separation** model:
+`@soybeanjs/ui` provides ready-to-use styled components powered by UnoCSS and `@soybeanjs/cva` class-variance recipes. Each component is an `S`-prefixed wrapper around the corresponding `@soybeanjs/headless` primitive, following the **style injection** pattern: styled wrappers compute classes and inject them via `provide{Name}Ui`, which headless components read through `useUiContext()`.
 
+```ts
+// Style injection — one-way data flow
+const ui = computed(() => accordionVariants({ size: props.size }, props.ui, { root: props.class }));
+provideAccordionUi(ui); // headless reads this via useAccordionUi()
 ```
-┌─────────────────────────────────────────┐
-│           @soybeanjs/ui (src/)          │
-│  S-prefixed components   (SButton…)     │
-│  UnoCSS classes · @soybeanjs/cva        │
-│  provideXUi(ui)  ──────────────────┐    │
-└────────────────────────────────────┼────┘
-                                     │ style injection
-┌────────────────────────────────────▼────┐
-│        @soybeanjs/headless (headless/)  │
-│  Logic · State · A11y · Keyboard nav    │
-│  useUiContext() reads injected classes  │
-│  Zero styles — works with any CSS       │
-└─────────────────────────────────────────┘
+
+## 📦 Installation
+
+```bash
+pnpm add @soybeanjs/ui
 ```
 
-### Packages
+## 🚀 Usage
 
-| Package                 | Role                                                | Components                        |
-| ----------------------- | --------------------------------------------------- | --------------------------------- |
-| **@soybeanjs/headless** | Logic, state, a11y. Zero styles.                    | 95 component dirs, 25 composables |
-| **@soybeanjs/ui**       | Styled wrappers. UnoCSS + `@soybeanjs/cva` recipes. | 91 `S`-prefixed components        |
+### 1. Import Styles
 
-**Data flow is strictly one-way**: `headless` → `src`. The styled layer never imports from headless's internals — it injects style tokens via `provideXUi(computedUi)` which headless components read through `useUiContext()`.
+Import the pre-built UnoCSS stylesheet in your main entry file (e.g., `main.ts`):
 
-Some multi-slot headless components also expose `Compact` aggregators, such as `AccordionCompact` and `TableCompact`. They keep item iteration and default content/icon composition inside headless, while the UI layer stays focused on styling and prop forwarding.
+```ts
+import '@soybeanjs/ui/styles.css';
+```
 
-Current Compact-style coverage also includes flows such as card, date-field, dialog, editable, hover-card, layout, navigation-menu, pagination, popover, and stepper, when those structures are stable enough to live in headless.
+### 2. On-demand Import (Recommended)
 
-### Style Injection
+Use `unplugin-vue-components` with the built-in resolver for auto-importing:
 
-Every multi-slot headless component exposes a `provide{Name}Ui` function. The styled wrapper computes classes with `@soybeanjs/cva` recipes and injects them:
+```ts
+// vite.config.ts
+import Components from 'unplugin-vue-components/vite';
+import UiResolver from '@soybeanjs/ui/resolver';
+
+export default defineConfig({
+  plugins: [
+    Components({
+      resolvers: [UiResolver()]
+    })
+  ]
+});
+```
+
+### 3. Nuxt Module
 
 ```ts
-// In the styled wrapper (src/)
-const ui = computed(() => accordionVariants({ size: props.size }, props.ui, { root: props.class }));
-provideAccordionUi(ui); // headless reads this via useAccordionUi()
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@soybeanjs/ui/nuxt']
+});
 ```
 
-### Theme System
+### 4. Direct Import
+
+```vue
+<script setup>
+import { SButton, SDialog } from '@soybeanjs/ui';
+</script>
+
+<template>
+  <SDialog>
+    <SButton>Open Dialog</SButton>
+  </SDialog>
+</template>
+```
+
+## ✨ Features
+
+- **shadcn-like design**: Modern, clean aesthetic inspired by shadcn/ui.
+- **Accessible**: Built on `@soybeanjs/headless` primitives with full WAI-ARIA support.
+- **RTL ready**: Switch between LTR and RTL layouts with `ConfigProvider`.
+- **Customizable at every level**: Override individual slot classes via the `ui` prop, or swap the entire style layer.
+- **Theme system**: 8 semantic colors and 6 sizes, controlled via `ConfigProvider`.
+- **Lightweight & Tree-shakable**: Import only the components you use.
+- **Type Safe**: Fully typed in strict TypeScript.
+- **Nuxt ready**: First-class Nuxt module with auto-registration.
+- **unplugin support**: Auto-import resolver for `unplugin-vue-components`.
+
+## 🎨 Theme System
+
+### Theme Colors
+
+| Color           | Token         | Usage                             |
+| --------------- | ------------- | --------------------------------- |
+| **Primary**     | `primary`     | Primary actions, active states    |
+| **Destructive** | `destructive` | Delete, error, danger actions     |
+| **Success**     | `success`     | Confirm, positive status          |
+| **Warning**     | `warning`     | Caution, pending status           |
+| **Info**        | `info`        | Information, hints                |
+| **Carbon**      | `carbon`      | Neutral backgrounds, surfaces     |
+| **Secondary**   | `secondary`   | Secondary actions, muted elements |
+| **Accent**      | `accent`      | Highlights, badges                |
+
+### Theme Sizes
+
+| Size  | Base (rem) | Pixel equivalent |
+| ----- | ---------- | ---------------- |
+| `xs`  | 0.75       | 12px             |
+| `sm`  | 0.875      | 14px             |
+| `md`  | 1          | 16px (default)   |
+| `lg`  | 1.125      | 18px             |
+| `xl`  | 1.25       | 20px             |
+| `2xl` | 1.5        | 24px             |
+
+```vue
+<script setup>
+import { SConfigProvider, SButton } from '@soybeanjs/ui';
+</script>
 
-- **`ThemeColor`** — 8 semantic colors: `primary` · `destructive` · `success` · `warning` · `info` · `carbon` · `secondary` · `accent`
-- **`ThemeSize`** — 6 sizes: `xs` · `sm` · `md` · `lg` · `xl` · `2xl` (base 16px at `md`)
-- **`ConfigProvider`** — sets global `dir`, `locale`, `nonce`, and default `tooltip` config for the entire component tree, including RTL layout switching
+<template>
+  <SConfigProvider :theme="{ color: 'primary', size: 'md' }">
+    <SButton>Click me</SButton>
+  </SConfigProvider>
+</template>
+```
 
-### Locale Support
+## 🌐 Locale Support
 
-`ConfigProvider` supports the following locale bundles:
+`@soybeanjs/ui` inherits locale support from `@soybeanjs/headless` via `ConfigProvider`:
 
 | Code    | Language            |
 | ------- | ------------------- |
@@ -84,47 +146,28 @@ provideAccordionUi(ui); // headless reads this via useAccordionUi()
 | `tr`    | Turkish             |
 | `id`    | Indonesian          |
 
-Only `en` and `zh-CN` are pre-registered by default. `registerLocale` supports two registration styles:
-
-- Pass a `LocaleRegistry` object. Built-in locale files from `@soybeanjs/headless/locale/{code}` already export this shape, including `dir` metadata.
-- Pass a locale key plus `LocaleMessages` for a lightweight custom locale.
-
-The shorthand `registerLocale(key, messages)` form uses the key as the locale name and falls back to `ltr`. Use the object form when you need explicit metadata such as `rtl`.
-
-```ts
-import { en, registerLocale } from '@soybeanjs/headless/locale';
-import type { LocaleMessages } from '@soybeanjs/headless/locale';
-import ar from '@soybeanjs/headless/locale/ar';
-
-registerLocale(ar);
-
-const customMessages: LocaleMessages = {
-  ...en.messages,
-  pagination: {
-    ...en.messages.pagination,
-    nextPage: 'Next →',
-    prevPage: '← Prev'
-  }
-};
-
-registerLocale('custom', customMessages);
+```vue
+<template>
+  <SConfigProvider :locale="zhCN">
+    <App />
+  </SConfigProvider>
+</template>
 ```
 
-### Package Exports
-
-**@soybeanjs/headless** ships fine-grained sub-paths:
+## 📚 Package Structure
 
-```ts
-import { AccordionRoot } from '@soybeanjs/headless'; // all components
-import { useControllableState } from '@soybeanjs/headless/composables'; // 25 composables
-import { transformPropsToContext } from '@soybeanjs/headless/shared'; // pure TS utils
-import { createMonth } from '@soybeanjs/headless/date'; // shared date helpers
-import * as Headless from '@soybeanjs/headless/namespaced'; // namespace object
-import type { AccordionUiSlot } from '@soybeanjs/headless/accordion'; // per-component
-import type { UiClass } from '@soybeanjs/headless/types'; // shared type surface
+```
+packages/ui/src/
+├── components/    # 86 styled component dirs (SButton, SDialog, SSelect…)
+├── styles/        # UnoCSS style recipes and layer definitions
+├── theme/         # Theme tokens, color scales, and size mappings
+├── constants/     # Component and theme constants
+├── nuxt/          # Nuxt module entry
+├── resolver/      # unplugin-vue-components resolver
+└── index.ts       # Main barrel export
 ```
 
-**@soybeanjs/ui** exports:
+### Package Exports
 
 ```ts
 import { SButton, SAccordion } from '@soybeanjs/ui'; // all components
@@ -132,116 +175,39 @@ import '@soybeanjs/ui/styles.css'; // pre-built UnoCSS stylesheet
 // Also: @soybeanjs/ui/nuxt · @soybeanjs/ui/resolver
 ```
 
-## 🛠 Development Workflow
-
-If you contribute new public components, exports, or API descriptions, keep generated surfaces in sync through the official scripts instead of editing generated files by hand.
-
-```bash
-pnpm sui headless                 # sync headless component names and namespaced exports
-pnpm sui ui                       # sync ui component names
-pnpm sui api                      # regenerate docs api json and locale baseline data
-pnpm sui api-locales              # refresh api locale template data only
-pnpm sui changelog                # regenerate docs changelog json and locale baseline data
-pnpm sui api-translate -- --locale zh-CN
-pnpm sui changelog-translate -- --locale zh-CN
-```
-
-The docs site now renders component docs through `UsageCode`, `PlaygroundGallery`, and `ComponentApi`. Component detail pages and `/releases` also read generated changelog data from `docs/src/generated/changelog/` and `docs/src/generated/changelog-locales/`.
-
-Public API or demo delivery changes should keep docs, playground examples, and generated API data aligned. Changelog mapping, release presentation, and changelog locale template changes should keep generated changelog data aligned as well.
-
-## 📦 Installation
-
-### Using the Styled UI Library (Recommended)
-
-If you want ready-to-use components with a modern design:
-
-```bash
-pnpm add @soybeanjs/ui
-```
-
-### Using the Headless Library
-
-If you want to build your own design system from scratch:
-
-```bash
-pnpm add @soybeanjs/headless
-```
-
-## 🚀 Usage
-
-### @soybeanjs/ui
-
-1. **Import Styles**
-
-   Import the CSS file in your main entry file (e.g., `main.ts`):
-
-```ts
-import '@soybeanjs/ui/styles.css';
-```
+## 🧩 Components
 
-2. **Global Registration (Optional)**
+`@soybeanjs/ui` ships 86 `S`-prefixed styled components, each wrapping a `@soybeanjs/headless` primitive:
 
-   You can register components globally or import them on demand.
+| Category        | Components                                                          |
+| --------------- | ------------------------------------------------------------------- |
+| **Layout**      | `SAccordion`, `SCard`, `SDialog`, `SDrawer`, `SPopover`, `STooltip` |
+| **Form**        | `SButton`, `SCheckbox`, `SInput`, `SSelect`, `SSwitch`, `STextarea` |
+| **Navigation**  | `SBreadcrumb`, `SPagination`, `SStepper`, `STabs`                   |
+| **Data**        | `STable`, `SDataList`, `STree`                                      |
+| **Feedback**    | `SAlert`, `SBadge`, `SToast`, `SProgress`                           |
+| **Typography**  | `SHeading`, `SText`, `SCode`, `SKbd`                                |
+| **Date & Time** | `SCalendar`, `SDatePicker`, `STimePicker`                           |
+| **Media**       | `SAvatar`, `SCarousel`, `SImage`                                    |
 
-3. **On-demand Import (Recommended)**
+## 🔧 Customizing Components
 
-   We recommend using `unplugin-vue-components` for auto-importing components.
-
-```ts
-// vite.config.ts
-import Components from 'unplugin-vue-components/vite';
-import UiResolver from '@soybeanjs/ui/resolver';
-
-export default defineConfig({
-  plugins: [
-    Components({
-      resolvers: [UiResolver()]
-    })
-  ]
-});
-```
-
-4. **Nuxt Module**
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@soybeanjs/ui/nuxt']
-});
-```
-
-### @soybeanjs/headless
-
-The headless components provide the functionality without the styles.
-
-For data-driven multi-slot patterns, prefer the exported `Compact` variant when it exists. It is the headless entry point for opinionated composition, while the regular parts remain available for fully manual assembly.
+Override individual slot classes via the `ui` prop:
 
 ```vue
-<script setup>
-import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';
-</script>
-
 <template>
-  <AccordionRoot>
-    <AccordionItem value="item-1">
-      <AccordionTrigger>Is it accessible?</AccordionTrigger>
-      <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
-    </AccordionItem>
-  </AccordionRoot>
+  <SAccordion :ui="{ trigger: 'bg-blue-100 hover:bg-blue-200 rounded-lg' }">
+    <SAccordionItem value="item-1">
+      <SAccordionTrigger>Custom styled trigger</SAccordionTrigger>
+      <SAccordionContent>Content here</SAccordionContent>
+    </SAccordionItem>
+  </SAccordion>
 </template>
 ```
 
-## ✨ Features
+## 📖 Documentation
 
-- **Accessible**: Follows WAI-ARIA patterns for roles, focus management, and keyboard navigation.
-- **RTL ready**: Switch supported components between LTR and RTL layouts with `ConfigProvider`.
-- **Headless-first**: Logic and styles are fully separated — use `@soybeanjs/headless` alone to build any design system.
-- **Type Safe**: Written in strict TypeScript. All props, emits, slots, and context values are typed.
-- **Customizable at every level**: Override individual slot classes via the `ui` prop, or swap the entire style layer.
-- **Lightweight & Tree-shakable**: Import only the components you use. Each component is individually tree-shakable.
-- **Nuxt ready**: First-class Nuxt module with auto-registration (`@soybeanjs/ui/nuxt`).
-- **unplugin support**: Auto-import resolver for `unplugin-vue-components` (`@soybeanjs/ui/resolver`).
+For full documentation, playground examples, and component API references, visit the [SoybeanUI docs site](https://soybeanjs.github.io/soybean-ui).
 
 ## 💝 Credits