tango-ui-cw 1.1.0 → 1.2.0

package/README.md

@@ -12,12 +12,18 @@ A lightweight React UI library for Next.js, powered by Tailwind CSS. Pre-compile
 
 ---
 
+![npm-rate](./npm-rate.png)
+
 ## Installation
 
 ```bash
 npm install tango-ui-cw
 ```
 
+```bash
+pnpm install tango-ui-cw
+```
+
 ### Peer Dependencies
 
 ```bash

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

@@ -53,3 +53,9 @@ export declare const createSlotProps: (options?: {
   className: string;
   style: SxStyleObject;
 };
+
+export declare const resolveSupportedValue: <T>(
+  value: T,
+  fallback: T,
+  map: Record<string, unknown>
+) => T;

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

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type BannerSlotNames = readonly ["root", "icon", "content", "actions", "closeIcon"];
 export type BannerLevel = "info" | "success" | "warning" | "error";
 export type BannerSize = "small" | "normal" | "large";
 

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

@@ -6,6 +6,7 @@ import type {
 } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type ButtonSlotNames = readonly ["root", "content", "icon", "loading"];
 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"];
@@ -64,6 +65,7 @@ export interface ButtonProps
 declare function Button(props: ButtonProps): JSX.Element;
 
 // MaterialButton 类型
+export type MaterialButtonSlotNames = readonly ["root", "content", "icon", "loading"];
 export type MaterialButtonVariant = "default" | "transparent" | "danger" | "success";
 export type MaterialButtonSize = "small" | "medium" | "large" | "huge";
 

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

@@ -0,0 +1,40 @@
+import type {
+  CSSProperties,
+  HTMLAttributes,
+  ReactNode,
+  Ref,
+} from "react";
+
+/** Card sx slot 名列表 */
+export type CardSlotNames = readonly ["root", "header", "body"];
+
+/** sx 值类型 */
+export type SxValue =
+  | string
+  | { tw?: string; className?: string; css?: CSSProperties; style?: CSSProperties }
+  | Record<string, unknown>;
+
+/** Card Props */
+export interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "style" | "title"> {
+  /** 卡片标题 */
+  title?: ReactNode;
+  /** 卡片标题右侧额外内容（如操作按钮） */
+  extra?: ReactNode;
+  /** 是否显示边框 */
+  bordered?: boolean;
+  /** 样式扩展 */
+  sx?: SxValue;
+  /** 行内样式 */
+  style?: CSSProperties;
+  /** 额外 CSS 类名 */
+  className?: string;
+  /** 卡片内容 */
+  children?: ReactNode;
+  /** ref 转发 */
+  ref?: Ref<HTMLDivElement>;
+}
+
+declare const Card: React.ForwardRefExoticComponent<
+  CardProps & React.RefAttributes<HTMLDivElement>
+>;
+export default Card;

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

@@ -1,6 +1,7 @@
 import type { CSSProperties, InputHTMLAttributes } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type ColorPickerSlotNames = readonly ["root", "input", "text"];
 export type ColorPickerSize = "small" | "medium" | "large";
 export type ColorPickerFormat = "hex" | "rgb" | "hsl";
 export type ColorPickerShowText = boolean | ColorPickerFormat;

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

@@ -1,6 +1,7 @@
 import type { CSSProperties, HTMLAttributes } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type DateSlotNames = readonly ["root", "date", "weekday", "time"];
 export type DateType =
   | "default"
   | "line"

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

@@ -3,7 +3,9 @@ import type { SxValue } from "../CSSFab";
 
 export type DatePickerSize = "small" | "medium" | "large";
 
-export type DatePickerI18nKey = "placeholder" | "placeholderTime" | "timeLabel" | "confirm" | "cancel" | "prevMonth" | "nextMonth" | (string & {});
+export type DatePickerSlotNames = readonly ["root", "input", "panel", "header", "body", "footer"];
+
+export type DatePickerI18nKey = "placeholder" | "placeholderTime" | "timeLabel" | "confirm" | "cancel" | "prevMonth" | "nextMonth" | "hourLabel" | "minuteLabel" | "panelAriaLabel" | (string & {});
 
 export type DatePickerLocaleText = Partial<{
   placeholder: string;
@@ -15,6 +17,9 @@ export type DatePickerLocaleText = Partial<{
   nextMonth: string;
   weekDays: string[];
   monthFormat: string;
+  hourLabel: string;
+  minuteLabel: string;
+  panelAriaLabel: string;
 }>;
 
 export interface DatePickerProps

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

@@ -1,6 +1,7 @@
 import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type DrawerSlotNames = readonly ["overlay", "container", "header", "title", "closeBtn", "content", "footer"];
 export type DrawerType = "top" | "bottom" | "left" | "right";
 
 export type DrawerI18nKey = "title" | "okText" | "cancelText" | "closeAriaLabel" | (string & {});

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

@@ -1,10 +1,17 @@
-import type { CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes } from "react";
+import type { CSSProperties, InputHTMLAttributes, ReactNode, TextareaHTMLAttributes } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type InputSlotNames = readonly ["root", "input", "prefix", "suffix", "clearIcon"];
 export type InputType = "default" | "textarea" | "password";
 export type InputSize = "small" | "medium" | "large" | "huge";
 export type InputStatus = "default" | "error";
 
+// added by clayw on 20260624: Input localeText 类型
+export type InputLocaleText = Partial<{
+  clearAriaLabel: string;
+  countTemplate: string;
+}>;
+
 export interface InputProps
   extends Omit<InputHTMLAttributes<HTMLInputElement> & TextareaHTMLAttributes<HTMLTextAreaElement>, "style" | "className" | "size" | "type" | "onChange"> {
   /** 输入类型 */
@@ -30,7 +37,17 @@ export interface InputProps
   /** 占位文案 */
   placeholder?: string;
   /** 最大字符数 */
-  maxlength?: number;
+  maxLength?: number;
+  /** 前缀图标/文字，位于输入框内左侧 added by clayw on 20260624 */
+  prefix?: ReactNode;
+  /** 后缀图标/文字，位于输入框内右侧 added by clayw on 20260624 */
+  suffix?: ReactNode;
+  /** 是否显示清除按钮，默认 true，值为空时隐藏图标 added by clayw on 20260624 */
+  allowClear?: boolean;
+  /** 是否显示字数统计，默认 false，支持 i18n added by clayw on 20260624 */
+  showCount?: boolean;
+  /** 覆盖内置文案 added by clayw on 20260624 */
+  localeText?: InputLocaleText;
 }
 
 declare function Input(props: InputProps): JSX.Element;
@@ -46,11 +63,14 @@ export { InputWithType as Input };
 export default Input;
 
 // MaterialInput 类型
+export type MaterialInputSlotNames = readonly ["root", "input", "label", "prefix", "suffix", "clearIcon"];
 export type MaterialInputSize = "small" | "medium" | "large" | "huge";
 
-export interface MaterialInputLocaleText {
+export type MaterialInputLocaleText = Partial<{
   label?: string;
-}
+  clearAriaLabel?: string;
+  countTemplate?: string;
+}>;
 
 export interface MaterialInputProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, "style" | "className" | "size" | "onChange" | "type"> {
@@ -74,6 +94,16 @@ export interface MaterialInputProps
   disabled?: boolean;
   /** 覆盖标签文案 */
   localeText?: MaterialInputLocaleText;
+  /** 前缀图标/文字 added by clayw on 20260624 */
+  prefix?: ReactNode;
+  /** 后缀图标/文字 added by clayw on 20260624 */
+  suffix?: ReactNode;
+  /** 是否显示清除按钮，默认 true added by clayw on 20260624 */
+  allowClear?: boolean;
+  /** 是否显示字数统计，默认 false added by clayw on 20260624 */
+  showCount?: boolean;
+  /** 最大字符数 added by clayw on 20260624 */
+  maxLength?: number;
 }
 
 declare function MaterialInput(props: MaterialInputProps): JSX.Element;

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

@@ -5,6 +5,9 @@ import type {
   Ref,
 } from "react";
 
+/** Layout sx slot 名列表 */
+export type LayoutSlotNames = readonly ["root"];
+
 /** sx 值类型（引用自 CSSFab） */
 export type SxValue =
   | string

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

@@ -5,6 +5,9 @@ import type {
   Ref,
 } from "react";
 
+/** Line sx slot 名列表 */
+export type LineSlotNames = readonly ["root", "text"];
+
 /** sx 值类型 */
 export type SxValue =
   | string

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

@@ -5,6 +5,9 @@ import type {
   Ref,
 } from "react";
 
+/** Mark sx slot 名列表 */
+export type MarkSlotNames = readonly ["root"];
+
 /** sx 值类型 */
 export type SxValue =
   | string

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

@@ -1,13 +1,19 @@
 import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
-export type ModalI18nKey = "title" | "okText" | "cancelText" | "closeAriaLabel" | (string & {});
+export type ModalSlotNames = readonly ["overlay", "container", "header", "title", "closeBtn", "content", "footer"];
+export type ModalI18nKey = "title" | "okText" | "cancelText" | "closeAriaLabel" | "confirmTitle" | "successTitle" | "errorTitle" | "warningTitle" | (string & {});
 
 export type ModalLocaleText = Partial<{
   title: string;
   okText: string;
   cancelText: string;
   closeAriaLabel: string;
+  // added by clayw on 20260624: 静态方法默认标题
+  confirmTitle: string;
+  successTitle: string;
+  errorTitle: string;
+  warningTitle: string;
 }>;
 
 export type ModalFooterButton = {
@@ -30,8 +36,8 @@ export interface ModalProps
   open?: boolean;
   /** 关闭回调 */
   onClose?: () => void;
-  /** 确定回调，若未传则默认调用 onClose */
-  onOk?: () => void;
+  /** 确定回调，若未传则默认调用 onClose；支持返回 Promise，自动 loading */
+  onOk?: () => void | Promise<void>;
   /** 容器宽度 */
   width?: string | number;
   /** Style extension via CSSFab sx */
@@ -42,11 +48,60 @@ export interface ModalProps
   maskClosable?: boolean;
   /** 自定义底部按钮，传入后替代默认的取消/确定 */
   footerButtons?: ModalFooterButton[];
+  /**
+   * 底部区域控制：
+   * - `undefined`：使用 footerButtons 或默认取消/确定按钮
+   * - `null`：不渲染底部区域
+   * - `ReactNode`：自定义底部内容
+   * added by clayw on 20260624
+   */
+  footer?: ReactNode | null;
+  /**
+   * 关闭时是否卸载 children DOM，适用于需要重置内部状态的场景
+   * added by clayw on 20260624
+   */
+  destroyOnClose?: boolean;
   /** 覆盖 locale 文案 */
   localeText?: ModalLocaleText;
 }
 
-declare function Modal(props: ModalProps): JSX.Element;
+/** 静态方法配置 */
+export interface ModalStaticConfig {
+  title?: string;
+  content?: ReactNode;
+  okText?: string;
+  cancelText?: string;
+  onOk?: () => void | Promise<void>;
+  onCancel?: () => void;
+  width?: string | number;
+  sx?: SxValue;
+  style?: CSSProperties;
+  className?: string;
+  maskClosable?: boolean;
+  footerButtons?: ModalFooterButton[];
+  localeText?: ModalLocaleText;
+}
+
+/** 静态方法返回值 */
+export interface ModalStaticResult {
+  close: () => void;
+  update: (config: Partial<ModalStaticConfig>) => void;
+}
+
+// added by clayw on 20260624: 静态方法类型声明
+interface ModalStaticMethods {
+  confirm: (config: ModalStaticConfig) => ModalStaticResult;
+  success: (config: ModalStaticConfig) => ModalStaticResult;
+  error: (config: ModalStaticConfig) => ModalStaticResult;
+  warning: (config: ModalStaticConfig) => ModalStaticResult;
+}
+
+// Modal 组件类型 = 函数签名 + 静态方法
+interface ModalComponent extends ModalStaticMethods {
+  (props: ModalProps): JSX.Element;
+}
+
+declare const Modal: ModalComponent;
 
 export { Modal };
 export default Modal;

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

@@ -1,18 +1,26 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type NoticeSlotNames = readonly ["root", "icon", "content"];
 export type NoticeType = "success" | "fail" | "caution";
 export type NoticeVariant = "default" | "md";
+// added by clayw on 20260624: placement 四角位置类型（大小写均可）
+export type NoticePlacement = "TL" | "TR" | "BL" | "BR" | "tl" | "tr" | "bl" | "br";
 
 export interface NoticeProps extends React.HTMLAttributes<HTMLDivElement> {
   /** 通知类型 */
   type?: NoticeType;
-  /** 图标（default 模式显示，md 模式隐藏） */
+  /** 图标（default 模式和 placement 模式显示，md 模式隐藏） */
   icon?: ReactNode;
   /** 通知内容 */
   message?: ReactNode;
   /** 变体：default 顶部居中，md 左下角 */
   variant?: NoticeVariant;
+  /**
+   * 四角位置，优先级高于 variant
+   * added by clayw on 20260624
+   */
+  placement?: NoticePlacement;
   /** 自动关闭时间（ms），0 或不传则不自动关闭 */
   duration?: number;
   /** 关闭回调 */
@@ -23,6 +31,15 @@ export interface NoticeProps extends React.HTMLAttributes<HTMLDivElement> {
   className?: string;
 }
 
+/** useNotice 调用的 options 参数 */
+// added by clayw on 20260624
+export interface NoticeCallOptions {
+  variant?: NoticeVariant;
+  duration?: number;
+  placement?: NoticePlacement;
+  key?: string;
+}
+
 declare const Notice: React.ForwardRefExoticComponent<
   NoticeProps & React.RefAttributes<HTMLDivElement>
 >;

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

@@ -1,6 +1,7 @@
-import type { CSSProperties, HTMLAttributes } from "react";
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type SearchSlotNames = readonly ["root", "input", "button", "prefix", "clearIcon"];
 export type SearchSize = "small" | "medium" | "large" | "huge";
 
 export type SearchI18nKey = "placeholder" | "btnText" | (string & {});
@@ -8,6 +9,9 @@ export type SearchI18nKey = "placeholder" | "btnText" | (string & {});
 export type SearchLocaleText = Partial<{
   placeholder: string;
   btnText: string;
+  // added by clayw on 20260624
+  clearAriaLabel: string;
+  countTemplate: string;
 }>;
 
 export interface SearchProps
@@ -20,6 +24,8 @@ export interface SearchProps
   className?: string;
   /** 搜索回调，参数为输入框当前值 */
   onSearch?: (value: string) => void;
+  /** 输入值变化回调，参数为当前输入值 */
+  onChange?: (value: string) => void;
   /** 受控值 */
   value?: string;
   /** 非受控默认值 */
@@ -34,6 +40,14 @@ export interface SearchProps
   path?: string;
   /** 覆盖 locale 文案 */
   localeText?: SearchLocaleText;
+  /** 前缀图标/文字，位于输入框内左侧 added by clayw on 20260624 */
+  prefix?: ReactNode;
+  /** 是否显示清除按钮，默认 true，值为空时隐藏图标 added by clayw on 20260624 */
+  allowClear?: boolean;
+  /** 是否显示字数统计，默认 false，支持 i18n added by clayw on 20260624 */
+  showCount?: boolean;
+  /** 最大字符数，默认 524288 added by clayw on 20260624 */
+  maxLength?: number;
 }
 
 declare function Search(props: SearchProps): JSX.Element;

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

@@ -5,6 +5,9 @@ import type {
   Ref,
 } from "react";
 
+/** Space sx slot 名列表 */
+export type SpaceSlotNames = readonly ["root"];
+
 /** Space 布局变体 */
 export type SpaceType =
   | "default"

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

@@ -1,3 +1,6 @@
+/** Table sx slot 名列表 */
+export type TableSlotNames = readonly ["root", "wrapper", "thead", "headerCell", "body", "row", "cell", "empty", "pagination", "loading", "footer"];
+
 import type { CSSProperties, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
@@ -8,6 +11,12 @@ export interface TableColumn<T = Record<string, unknown>> {
   key?: string | number;
   width?: string | number;
   hide?: boolean;
+  // added by clayw on 20260623
+  /** 是否开启数字排序，默认 false */
+  sortable?: boolean;
+  // added by clayw on 20260623
+  /** 是否固定列，最后一列 fixed=true 固定右侧，其余固定左侧，默认 false */
+  fixed?: boolean;
   render?: (value: unknown, row: T, rowIndex: number) => ReactNode;
 }
 
@@ -25,6 +34,21 @@ export interface TablePagination {
   showSizeChanger?: boolean;
 }
 
+// added by clayw on 20260624
+/** 行选择配置 */
+export interface TableRowSelection<T = Record<string, unknown>> {
+  /** 选择类型，仅支持 checkbox */
+  type?: "checkbox";
+  /** 受控选中的行 key 列表 */
+  selectedRowKeys?: (string | number)[];
+  /** 选择变化回调 */
+  onChange?: (selectedRowKeys: (string | number)[], selectedRows: T[]) => void;
+  /** 是否固定选择列，默认 true（横向滚动时选择列始终可见）；设为 false 取消固定 */
+  fixed?: boolean;
+  /** 选择列宽度，默认 50 */
+  width?: string | number;
+}
+
 /** i18n 覆盖字段 */
 export interface TableLocaleText {
   empty?: string;
@@ -33,6 +57,13 @@ export interface TableLocaleText {
   page?: string;
   total?: string;
   perPage?: string;
+  // added by clayw on 20260624
+  /** 行选择 footer 计数模板，支持 {total} 和 {selected} 占位 */
+  selectedSummary?: string;
+  /** 全选复选框 aria-label */
+  selectAll?: string;
+  /** 行选择复选框 aria-label */
+  selectRow?: string;
   [key: string]: string | undefined;
 }
 
@@ -65,6 +96,15 @@ export interface TableProps {
     | CSSProperties;
   /** 自定义 hover 颜色（覆盖默认主题 hover） */
   hoverColor?: string;
+  // added by clayw on 20260624
+  /** 加载状态，默认自动模式：dataSource 为空时显示骨架屏；传 true 强制骨架屏；传 false 关闭骨架屏 */
+  loading?: boolean;
+  // added by clayw on 20260624
+  /** 行选择配置 */
+  rowSelection?: TableRowSelection;
+  // added by clayw on 20260624
+  /** 行事件，参考 AntD 写法：(record, rowIndex) => ({ onClick: event => {}, onDoubleClick: event => {} }) */
+  onRow?: (record: Record<string, unknown>, rowIndex: number) => React.HTMLAttributes<HTMLTableRowElement>;
   /** i18n key */
   i18nKey?: string;
   /** 覆盖内置文案 */
@@ -74,3 +114,4 @@ export interface TableProps {
 declare function Table(props: TableProps): JSX.Element;
 
 export default Table;
+

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

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { SxValue } from "../CSSFab";
 
+export type TooltipSlotNames = readonly ["root", "tooltip"];
 export type TooltipPlacement = "top" | "bottom" | "left" | "right";
 
 export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
@@ -18,6 +19,8 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   onOpenChange?: (open: boolean) => void;
   /** 是否禁用提示 */
   disabled?: boolean;
+  /** z-index 层叠顺序，默认 50 */
+  zIndex?: number;
   /** 样式扩展 */
   sx?: SxValue;
   style?: CSSProperties;

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

@@ -1,4 +1,17 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { CSSProperties } from "react";
+
+/** Upload sx slot 名列表 */
+export type UploadSlotNames = readonly ["root", "button", "list", "item", "dragger", "preview"];
+
+// added by clayw on 20260624: Upload i18n 文案类型
+export interface UploadLocaleText {
+  /** 选择按钮文字 */
+  btnText?: string;
+  /** 拖拽区域提示文字 */
+  dragPlaceholder?: string;
+  /** 拖拽悬停时提示文字 */
+  dragActivePlaceholder?: string;
+}
 
 export interface UploadProps {
   /** 样式扩展（字符串/对象/slot） */
@@ -23,7 +36,7 @@ export interface UploadProps {
   maxCount?: number;
   /** 单文件最大体积（MB） */
   maxSize?: number;
-  /** 选择按钮文字 */
+  /** 选择按钮文字（覆盖 i18n 默认） */
   btnText?: string;
   /** 选择按钮样式 */
   btnStyle?: CSSProperties;
@@ -31,13 +44,29 @@ export interface UploadProps {
   showSize?: boolean;
   /** 是否禁用 */
   disabled?: boolean;
-  /** 子元素 */
-  children?: ReactNode;
+  // added by clayw on 20260624: 拖拽上传新增 props
+  /** 是否启用拖拽上传（启用后渲染拖拽区域代替按钮） */
+  draggable?: boolean;
+  /** 拖拽区域提示文字（覆盖 i18n 默认） */
+  dragPlaceholder?: string;
+  /** 拖拽文件悬停时提示文字（覆盖 i18n 默认） */
+  dragActivePlaceholder?: string;
+  // added by clayw on 20260624: i18n 文案覆盖
+  /** i18n 文案覆盖，优先级高于 prop 和 i18n Provider */
+  localeText?: UploadLocaleText;
+  // added by clayw on 20260624: 预览 + loading 新增 props
+  /** 是否显示图片缩略图预览（原生 img 实现，后续可用 Image 组件替换） */
+  preview?: boolean;
+  /** 是否显示上传中状态（按钮模式传 Button loading，拖拽模式显示 spinner overlay） */
+  loading?: boolean;
 }
 
 /** beforeUpload 返回此值时，文件不展示在列表中 */
 export const LIST_IGNORE: unique symbol;
 
+// added by clayw on 20260624: Upload i18n key 类型
+export type UploadI18nKey = "upload.btnText" | "upload.dragPlaceholder" | "upload.dragActivePlaceholder";
+
 declare const Upload: ((props: UploadProps) => JSX.Element) & {
   LIST_IGNORE: typeof LIST_IGNORE;
 };