tango-ui-cw/README.md

A lightweight ui library with ClayW

# Tango UI

A lightweight React UI library for Next.js, powered by Tailwind CSS. Pre-compiled utilities — no Tailwind setup required for consumers.

**Author**: ClayW

---

## Official Docs

🔗 [https://tango-ui-new.vercel.app/](https://tango-ui-new.vercel.app/)

---

## Installation

```bash
npm install tango-ui-cw
```

### Peer Dependencies

```bash
npm install react@>=18 next@>=14 tailwind-merge@^3.6.0
```

> `next` and `react-dom` are optional peers — only required if you use SSR/SSG features.
>
> `tailwindcss` is an optional peer — not required. All Tailwind utility classes are pre-compiled and bundled in `style.css`. Only install it if your own project also uses Tailwind.

---

## Quick Start

```js
// Import components
import { Button, Input, Layout, Upload } from "tango-ui-cw";

// Import styles (required)
import "tango-ui-cw/style.css";
```

### Compound Components

```jsx
import { Button, Layout } from "tango-ui-cw";

const { MaterialButton } = Button
const { Header, Content } = Layout

// Access sub-components via dot notation
<MaterialButton>Click</MaterialButton>
<Header>...</Header>
<Content>...</Content>

// Or import directly
import { MaterialButton, Header, Content } from "tango-ui-cw";
```

---

## Compatible Versions

| Package | Version | Note |
|---------|---------|------|
| React | >= 18 | Required |
| Next.js | >= 14 | Supported |
| React DOM | >= 18 | Required for SSR/SSG |
| tailwind-merge | ^3.6.0 | Required |
| Tailwind CSS | ^4 | Not required — utilities are pre-compiled |

---

## Features

- **Zero-config Tailwind** — all utility classes are pre-compiled into the package; consumers don't need Tailwind installed
- **18+ components** — Button, Input, Layout, Upload, Modal, Drawer, Table, DatePicker, ColorPicker, Search, Tooltip, Notice, Banner, Space, Line, Mark, and more
- **`sx` prop styling** — three input forms: Tailwind string, CSS shorthand object, or slot-structured object for per-slot control
- **70+ CSS shorthand properties** — `useTangoStyle()` auto-resolves shorthand like `mt`, `bgc`, `aic` to full CSS properties
- **Slot-based architecture** — every component declares named slots, `normalizeSxSlots()` decomposes `sx` into per-slot `{ tw, css }`
- **CSS variable token system** — use `$primary`, `$border` in `sx` values, auto-expanded to `var(--primary)`
- **Tailwind CSS powered** — `mergeTwClassNames()` for intelligent class conflict resolution via tailwind-merge
- **Material Design variants** — `Button.MaterialButton` with ripple effect, `Input.MaterialInput` with floating label
- **Compound component pattern** — `Layout.Header`, `Layout.Sider`, `Button.MaterialButton` etc., also available as named exports
- **Theme customization** — light/dark mode via `ThemeProvider`, runtime token overrides with `setThemeTokens()` / `setThemeColor()`
- **100+ CSS custom properties** — oklch color space, semantic tokens for every component, responsive breakpoints
- **Smooth theme transitions** — automatic transition animation when switching light/dark mode
- **i18n built-in** — `TangoI18nProvider` with zh-CN / en-US packs, custom message merging, dot-path `t()` lookup
- **Imperative notifications** — `useNotice()` with success / fail / caution variants and auto-dismiss
- **Neumorphism support** — Button `enu` variant with soft-UI shadow effects
- **Controlled & uncontrolled** — Input, DatePicker, ColorPicker, Tooltip all support both patterns
- **`'use client'` ready** — all components marked as client components, fully compatible with Next.js RSC
- **forwardRef support** — ref forwarding on Layout sub-components, Space, Tooltip, Notice, Upload, and more
- **Data attributes** — `data-variant`, `data-size` on Button for external CSS selector hooks
- **Tree-shakable** — ESM first with CJS fallback
- **TypeScript ready** — full `.d.ts` type declarations included and Support editor auto-inference

### 特性（中文）

- **零配置 Tailwind** — 所有工具类已预编译打包，消费者无需安装 Tailwind
- **18+ 组件** — Button、Input、Layout、Upload、Modal、Drawer、Table、DatePicker、ColorPicker、Search、Tooltip、Notice、Banner、Space、Line、Mark 等
- **`sx` 属性样式** — 三种输入形式：Tailwind 字符串、CSS 简写对象、或按 slot 分层的结构化对象
- **70+ CSS 简写属性** — `useTangoStyle()` 自动将 `mt`、`bgc`、`aic` 等简写解析为完整 CSS 属性
- **Slot 架构** — 每个组件声明命名 slot，`normalizeSxSlots()` 将 `sx` 分解为每个 slot 的 `{ tw, css }`
- **CSS 变量 Token 系统** — 在 `sx` 值中使用 `$primary`、`$border`，自动展开为 `var(--primary)`
- **Tailwind CSS 驱动** — `mergeTwClassNames()` 基于 tailwind-merge 智能解决类名冲突
- **Material Design 变体** — `Button.MaterialButton` 带涟漪效果，`Input.MaterialInput` 带浮动标签
- **复合组件模式** — `Layout.Header`、`Layout.Sider`、`Button.MaterialButton` 等，同时支持命名导出
- **主题定制** — 通过 `ThemeProvider` 切换亮/暗模式，`setThemeTokens()` / `setThemeColor()` 运行时覆盖 token
- **100+ CSS 自定义属性** — oklch 色彩空间，每个组件的语义化 token，响应式断点
- **平滑主题过渡** — 切换亮/暗模式时自动播放过渡动画
- **内置国际化** — `TangoI18nProvider` 支持 zh-CN / en-US 语言包，自定义消息合并，点路径 `t()` 查找
- **命令式通知** — `useNotice()` 提供 success / fail / caution 变体，支持自动消失
- **拟物风支持** — Button `enu` 变体带柔和 UI 阴影效果
- **受控与非受控** — Input、DatePicker、ColorPicker、Tooltip 均支持两种模式
- **`'use client'` 就绪** — 所有组件标记为客户端组件，完全兼容 Next.js RSC
- **forwardRef 支持** — Layout 子组件、Space、Tooltip、Notice、Upload 等支持 ref 转发
- **Data 属性** — Button 上的 `data-variant`、`data-size` 可用于外部 CSS 选择器
- **可 Tree-shaking** — ESM 优先，同时提供 CJS 回退
- **TypeScript 就绪** — 包含完整的 `.d.ts` 类型声明，支持编辑器自动推断

---

## License

MIT