tango-ui-cw 0.9.9 → 1.0.0

package/README.md

@@ -1,39 +1,124 @@
-# tango-ui-cw
-
-**版本**：0.9.9  
-**支持**：React 18.x/19.x & Next 14-16.x  
-**作者**：ClayW  
-**创建时间**：2025-01-16  
-**更新时间**：2026-04-21
-
----
-
-## 官方文档
-https://tango-ui-new.vercel.app/
-
-
----
-
-## 简介
-
-`tango-ui-cw` 是一个用于 React / Next.js 的 UI 组件库，‘零’依赖，助您轻松快捷的开发新功能；您可以从我们功能齐全的 Tango UI 组件库入手，也可以将您自己的设计系统添加到我们可用于生产的组件中。支持：
-
-- 直观的定制
-- 零依赖特性
-- Headless风格
-- 稳定的可访问性
-- ‘sx’属性样式增强
-- 主题定制
-- 高自由度组件定制
-
-
----
-
-## 安装
-
-```bash
-npm install tango-ui-cw@latest
-```
-
-
-
+# Tango UI
+
+A lightweight, zero-dependency React UI library for Next.js, powered by Tailwind CSS.
+
+**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 react-dom@>=18 next@>=14 tailwind-merge@^3.6.0 tailwindcss@^4
+```
+
+> `next` and `react-dom` are optional peers — only required if you use SSR/SSG features.
+
+---
+
+## 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";
+```
+
+---
+
+## Supported Versions
+
+| Package | Version |
+|---------|---------|
+| React | >= 18 |
+| React DOM | >= 18 |
+| Next.js | >= 14 |
+| Tailwind CSS | ^4 |
+| tailwind-merge | ^3.6.0 |
+
+---
+
+## Features
+
+- **Zero dependencies** — no runtime deps bloating your bundle
+- **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
+
+### 特性（中文）
+
+- **零依赖** — 没有运行时依赖，不会增加你的包体积
+- **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

package/dist/component/CSSFab/index.d.ts

@@ -0,0 +1,55 @@
+import type { CSSProperties } from "react";
+
+export type SxStyleObject = CSSProperties & {
+  [key: string]: unknown;
+};
+
+export type SxSlotValue =
+  | string
+  | SxStyleObject
+  | {
+      tw?: string;
+      className?: string;
+      css?: SxStyleObject;
+      style?: SxStyleObject;
+    };
+
+export type SxValue =
+  | string
+  | SxStyleObject
+  | {
+      root?: SxSlotValue;
+      slots?: Record<string, SxSlotValue>;
+      tw?: string;
+      className?: string;
+      css?: SxStyleObject;
+      style?: SxStyleObject;
+      [slotOrStyle: string]: unknown;
+    };
+
+export type NormalizedSxSlot = {
+  tw: string;
+  css: SxStyleObject;
+};
+
+export declare const useTangoStyle: (sx?: SxStyleObject) => SxStyleObject;
+
+export declare const mergeTwClassNames: (
+  ...inputs: Array<string | null | undefined | false>
+) => string;
+
+export declare const normalizeSxSlots: (
+  sx: SxValue,
+  slotNames?: string[]
+) => Record<string, NormalizedSxSlot>;
+
+export declare const createSlotProps: (options?: {
+  baseClassName?: string;
+  className?: string;
+  baseStyle?: SxStyleObject;
+  style?: SxStyleObject;
+  sxSlot?: NormalizedSxSlot;
+}) => {
+  className: string;
+  style: SxStyleObject;
+};

package/dist/component/CSSFab/useTangoStyle.d.ts

@@ -0,0 +1 @@
+export * from "./index";

package/dist/component/TBanner/index.d.ts

@@ -0,0 +1,50 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type BannerLevel = "info" | "success" | "warning" | "error";
+export type BannerSize = "small" | "normal" | "large";
+
+export type BannerI18nKey = "cancel" | "action" | (string & {});
+
+export type BannerLocaleText = Partial<
+  Record<"cancel" | "action" | string, string>
+>;
+
+export interface BannerProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "style" | "className" | "children"> {
+  /** Banner content text; falls back to i18n cancel text if omitted */
+  children?: ReactNode;
+  /** Fired when close/cancel button is clicked */
+  onCancel?: () => void;
+  /** Fired when action button is clicked */
+  onAction?: () => void;
+  /** Banner size variant */
+  size?: BannerSize;
+  /** Custom cancel button text (overrides i18n) */
+  cancelText?: string;
+  /** Custom action button text (overrides i18n) */
+  actionText?: string;
+  /** Level determines icon & color scheme */
+  level?: BannerLevel;
+  /** Transparent mode: background becomes transparent, text turns gray */
+  transparent?: boolean;
+  /** Custom background color (overrides level default) */
+  bannerBgColor?: string;
+  /** Custom border color (overrides level default) */
+  bannerBorderColor?: string;
+  /** Custom icon color (overrides level default) */
+  bannerIconColor?: string;
+  /** Style extension via CSSFab sx (string / object / slot) */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** i18n key for built-in text lookup */
+  i18nKey?: BannerI18nKey;
+  /** Override locale text map */
+  localeText?: BannerLocaleText;
+}
+
+declare function Banner(props: BannerProps): JSX.Element;
+
+export { Banner };
+export default Banner;

package/dist/component/TButton/index.d.ts

@@ -0,0 +1,107 @@
+import type {
+  ButtonHTMLAttributes,
+  CSSProperties,
+  ElementType,
+  ReactNode,
+} from "react";
+import type { SxValue } from "../CSSFab";
+
+export type ButtonVariant = "default" | "transparent" | "danger" | "success";
+export type ButtonSize = "small" | "medium" | "large" | "huge";
+export type LoadingMode = boolean | "light" | "dark" | [boolean | "light" | "dark", "light" | "dark"];
+export type ButtonI18nKey =
+  | "default"
+  | "loading"
+  | "submit"
+  | "confirm"
+  | "cancel"
+  | "search"
+  | "save"
+  | "delete"
+  | "back"
+  | "next"
+  | "prev"
+  | "add"
+  | (string & {});
+
+export type ButtonLocaleText = Partial<
+  Record<
+    | "default"
+    | "loading"
+    | "iconAlt"
+    | "submit"
+    | "confirm"
+    | "cancel"
+    | "search"
+    | "save"
+    | "delete"
+    | "back"
+    | "next"
+    | "prev"
+    | "add"
+    | string,
+    string
+  >
+>;
+
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "style" | "className" | "children"> {
+  type?: ButtonVariant;
+  size?: ButtonSize;
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  children?: ReactNode;
+  disabled?: boolean;
+  outline?: boolean;
+  icon?: ElementType | ReactNode | string;
+  iconPosition?: "left" | "right";
+  loading?: LoadingMode;
+  i18nKey?: ButtonI18nKey;
+  localeText?: ButtonLocaleText;
+}
+
+declare function Button(props: ButtonProps): JSX.Element;
+
+// MaterialButton 类型
+export type MaterialButtonVariant = "default" | "transparent" | "danger" | "success";
+export type MaterialButtonSize = "small" | "medium" | "large" | "huge";
+
+export interface MaterialButtonLocaleText {
+  default?: string;
+  loading?: string;
+  iconAlt?: string;
+  [key: string]: string | undefined;
+}
+
+export interface MaterialButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "style" | "className" | "children"> {
+  type?: MaterialButtonVariant;
+  size?: MaterialButtonSize;
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  children?: ReactNode;
+  disabled?: boolean;
+  outline?: boolean;
+  icon?: ElementType | ReactNode | string;
+  iconPosition?: "left" | "right";
+  loading?: LoadingMode;
+  i18nKey?: string;
+  localeText?: MaterialButtonLocaleText;
+  /** 涟漪颜色，默认使用 --material-button-ripple */
+  rippleColor?: string;
+}
+
+declare function MaterialButton(props: MaterialButtonProps): JSX.Element;
+
+// antd 风格：Button.MaterialButton / const { MaterialButton } = Button
+interface ButtonNamespace {
+  (props: ButtonProps): JSX.Element;
+  MaterialButton: typeof MaterialButton;
+}
+
+declare const ButtonWithType: ButtonNamespace;
+export { ButtonWithType as Button };
+export { MaterialButton };
+export default Button;

package/dist/component/TColorPicker/index.d.ts

@@ -0,0 +1,41 @@
+import type { CSSProperties, InputHTMLAttributes } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type ColorPickerSize = "small" | "medium" | "large";
+export type ColorPickerFormat = "hex" | "rgb" | "hsl";
+export type ColorPickerShowText = boolean | ColorPickerFormat;
+export type ColorPickerI18nKey = "hex" | "rgb" | "hsl" | (string & {});
+export type ColorPickerLocaleText = Partial<
+  Record<"hex" | "rgb" | "hsl" | string, string>
+>;
+
+export interface ColorPickerProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "style" | "className" | "size" | "type" | "value" | "onChange"> {
+  /** 受控颜色值（HEX） */
+  value?: string;
+  /** 非受控默认颜色值 */
+  defaultValue?: string;
+  /** 颜色变化回调，参数为 HEX 值 */
+  onChange?: (hex: string) => void;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 是否显示颜色文本；传格式字符串仅显示对应格式 */
+  showText?: ColorPickerShowText;
+  /** 文本输出格式（showText 为 true 时决定主格式） */
+  format?: ColorPickerFormat;
+  /** 尺寸变体 */
+  size?: ColorPickerSize;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** i18n key */
+  i18nKey?: ColorPickerI18nKey;
+  /** 覆盖 locale 文案 */
+  localeText?: ColorPickerLocaleText;
+}
+
+declare function ColorPicker(props: ColorPickerProps): JSX.Element;
+
+export { ColorPicker };
+export default ColorPicker;

package/dist/component/TDate/index.d.ts

@@ -0,0 +1,41 @@
+import type { CSSProperties, HTMLAttributes } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type DateType =
+  | "default"
+  | "line"
+  | "full"
+  | "full-line"
+  | "year-week"
+  | "year-week-line"
+  | "week-time"
+  | "no-s"
+  | "no-s-line";
+
+export type DateI18nKey = DateType | (string & {});
+
+export type DateLocaleText = Partial<{
+  weekdayPrefix: string;
+  weekdayShortPrefix: string;
+}>;
+
+export interface DateProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "style" | "className"> {
+  /** 显示格式类型 */
+  type?: DateType;
+  /** 中文星期简写：true 显示"周X"，false 显示"星期X" */
+  single?: boolean;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** i18n key，可指定 type 作为快捷格式 */
+  i18nKey?: DateI18nKey;
+  /** 覆盖 locale 文案 */
+  localeText?: DateLocaleText;
+}
+
+declare function DateDisplay(props: DateProps): JSX.Element;
+
+export { DateDisplay };
+export default DateDisplay;

package/dist/component/TDatePicker/index.d.ts

@@ -0,0 +1,49 @@
+import type { CSSProperties, HTMLAttributes } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type DatePickerSize = "small" | "medium" | "large";
+
+export type DatePickerI18nKey = "placeholder" | "placeholderTime" | "timeLabel" | "confirm" | "cancel" | "prevMonth" | "nextMonth" | (string & {});
+
+export type DatePickerLocaleText = Partial<{
+  placeholder: string;
+  placeholderTime: string;
+  timeLabel: string;
+  confirm: string;
+  cancel: string;
+  prevMonth: string;
+  nextMonth: string;
+  weekDays: string[];
+  monthFormat: string;
+}>;
+
+export interface DatePickerProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "style" | "className" | "onChange"> {
+  /** 受控值（YYYY-MM-DD 或 YYYY-MM-DD HH:mm） */
+  value?: string;
+  /** 非受控默认值 */
+  defaultValue?: string;
+  /** 日期变化回调：(formatted, raw) => void */
+  onChange?: (formatted: string, raw: string) => void;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 是否显示时间选择 */
+  time?: boolean;
+  /** 尺寸变体 */
+  size?: DatePickerSize;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** i18n key */
+  i18nKey?: DatePickerI18nKey;
+  /** 覆盖 locale 文案 */
+  localeText?: DatePickerLocaleText;
+  /** 输入框占位文本，优先级高于 i18n / localeText */
+  placeholder?: string;
+}
+
+declare function DatePicker(props: DatePickerProps): JSX.Element;
+
+export { DatePicker };
+export default DatePicker;

package/dist/component/TDrawer/index.d.ts

@@ -0,0 +1,58 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type DrawerType = "top" | "bottom" | "left" | "right";
+
+export type DrawerI18nKey = "title" | "okText" | "cancelText" | "closeAriaLabel" | (string & {});
+
+export type DrawerLocaleText = Partial<{
+  title: string;
+  okText: string;
+  cancelText: string;
+  closeAriaLabel: string;
+}>;
+
+export type DrawerFooterButton = {
+  key: string;
+  text: string;
+  onClick: () => void;
+};
+
+export interface DrawerProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "style" | "className"> {
+  /** 抽屉内容 */
+  children?: ReactNode;
+  /** 标题，优先级高于 i18n */
+  title?: string;
+  /** 确定按钮文案，优先级高于 i18n */
+  okText?: string;
+  /** 取消按钮文案，优先级高于 i18n */
+  cancelText?: string;
+  /** 是否打开 */
+  open?: boolean;
+  /** 关闭回调 */
+  onClose?: () => void;
+  /** 确定回调，若未传则默认调用 onClose */
+  onOk?: () => void;
+  /** 抽屉方向 */
+  type?: DrawerType;
+  /** 容器宽度（left/right 生效） */
+  width?: string | number;
+  /** 容器高度（top/bottom 生效） */
+  height?: string | number;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** 点击遮罩是否关闭 */
+  maskClosable?: boolean;
+  /** 自定义底部按钮，传入后替代默认的取消/确定 */
+  footerButtons?: DrawerFooterButton[];
+  /** 覆盖 locale 文案 */
+  localeText?: DrawerLocaleText;
+}
+
+declare function Drawer(props: DrawerProps): JSX.Element;
+
+export { Drawer };
+export default Drawer;

package/dist/component/TInput/index.d.ts

@@ -0,0 +1,81 @@
+import type { CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes } from "react";
+import type { SxValue } from "../CSSFab";
+
+export type InputType = "default" | "textarea" | "password";
+export type InputSize = "small" | "medium" | "large" | "huge";
+export type InputStatus = "default" | "error";
+
+export interface InputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement> & TextareaHTMLAttributes<HTMLTextAreaElement>, "style" | "className" | "size" | "type" | "onChange"> {
+  /** 输入类型 */
+  type?: InputType;
+  /** 尺寸 */
+  size?: InputSize;
+  /** 校验状态 */
+  status?: InputStatus;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** 点击事件 */
+  onClick?: (e: React.MouseEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  /** 值变化回调，参数为当前输入值 */
+  onChange?: (value: string) => void;
+  /** 受控值 */
+  value?: string;
+  /** 非受控默认值 */
+  defaultValue?: string;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 占位文案 */
+  placeholder?: string;
+  /** 最大字符数 */
+  maxlength?: number;
+}
+
+declare function Input(props: InputProps): JSX.Element;
+
+// antd 风格：Input.MaterialInput / const { MaterialInput } = Input
+interface InputNamespace {
+  (props: InputProps): JSX.Element;
+  MaterialInput: typeof MaterialInput;
+}
+
+declare const InputWithType: InputNamespace;
+export { InputWithType as Input };
+export default Input;
+
+// MaterialInput 类型
+export type MaterialInputSize = "small" | "medium" | "large" | "huge";
+
+export interface MaterialInputLocaleText {
+  label?: string;
+}
+
+export interface MaterialInputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "style" | "className" | "size" | "onChange" | "type"> {
+  /** 浮动标签文案 */
+  label?: string;
+  /** 原生 input type */
+  type?: string;
+  /** 尺寸 */
+  size?: MaterialInputSize;
+  /** Style extension via CSSFab sx */
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  /** 值变化回调，参数为当前输入值 */
+  onChange?: (value: string) => void;
+  /** 受控值 */
+  value?: string;
+  /** 非受控默认值 */
+  defaultValue?: string;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 覆盖标签文案 */
+  localeText?: MaterialInputLocaleText;
+}
+
+declare function MaterialInput(props: MaterialInputProps): JSX.Element;
+
+export { MaterialInput };