@open-dy/vibecoding-sdk-taro 0.0.1-beta.4 → 0.0.1

package/dist/ui/alert.js

@@ -22,6 +22,17 @@ const alertVariants = cva(
         variant: "default",
     },
 });
+/**
+ * @desc 提示信息组件。
+ * @param {Parameters<typeof Alert>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof Alert>[0]["variant"]} props.variant 提示色彩，默认 default；destructive 使用危险操作颜色并同步到 AlertDescription，只控制视觉，不执行错误处理。
+ * @return {ReturnType<typeof Alert>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Alert } from '@open-dy/vibecoding-sdk-taro/ui/alert'
+ * <Alert />
+ * ```
+ */
 function Alert({ className, variant, children, ...props }) {
     const resolvedVariant = variant ?? "default";
     const childArray = React.Children.toArray(children);
@@ -34,14 +45,44 @@ function Alert({ className, variant, children, ...props }) {
     });
     return (_jsx(AlertContext.Provider, { value: { hasAction, hasMedia, variant: resolvedVariant }, children: _jsx(View, { "data-slot": "alert", className: cn(alertVariants({ variant: resolvedVariant }), hasAction && "relative pr-18", hasMedia && "grid-cols-[auto_1fr] gap-x-2", className), ...props, children: children }) }));
 }
+/**
+ * @desc 提示信息标题。
+ * @param {Parameters<typeof AlertTitle>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AlertTitle>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Alert, AlertTitle } from '@open-dy/vibecoding-sdk-taro/ui/alert'
+ * <Alert><AlertTitle /></Alert>
+ * ```
+ */
 function AlertTitle({ className, ...props }) {
     const { hasMedia } = React.useContext(AlertContext);
     return (_jsx(View, { "data-slot": "alert-title", className: cn("font-medium [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground", hasMedia && "col-start-2", className), ...props }));
 }
+/**
+ * @desc 提示信息说明文本。
+ * @param {Parameters<typeof AlertDescription>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AlertDescription>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Alert, AlertDescription } from '@open-dy/vibecoding-sdk-taro/ui/alert'
+ * <Alert><AlertDescription /></Alert>
+ * ```
+ */
 function AlertDescription({ className, ...props }) {
     const { variant } = React.useContext(AlertContext);
     return (_jsx(View, { "data-slot": "alert-description", className: cn("text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4", variant === "destructive" && "text-destructive/90", className), ...props }));
 }
+/**
+ * @desc 提示信息操作入口。
+ * @param {Parameters<typeof AlertAction>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AlertAction>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Alert, AlertAction } from '@open-dy/vibecoding-sdk-taro/ui/alert'
+ * <Alert><AlertAction /></Alert>
+ * ```
+ */
 function AlertAction({ className, ...props }) {
     return (_jsx(View, { "data-slot": "alert-action", className: cn("absolute top-2 right-2", className), ...props }));
 }

package/dist/ui/alert.js.map

@@ -1 +1 @@
-{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../src/ui/alert.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../src/ui/alert.tsx"],"names":[],"mappings":"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"}

package/dist/ui/aspect-ratio.d.ts

@@ -1,5 +1,16 @@
 import { type ViewProps } from "@tarojs/components";
+/**
+ * @desc 固定宽高比容器组件。
+ * @param {Parameters<typeof AspectRatio>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AspectRatio>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { AspectRatio } from '@open-dy/vibecoding-sdk-taro/ui/aspect-ratio'
+ * <AspectRatio ratio={16 / 9} />
+ * ```
+ */
 declare function AspectRatio({ ratio, className, style, ...props }: ViewProps & {
+    /** @desc 必填宽高比（宽 ÷ 高），应为正数，例如 16 / 9；通过 CSS aspect-ratio 控制根容器，不设置固定宽度。 */
     ratio: number;
 }): import("react").JSX.Element;
 export { AspectRatio };

package/dist/ui/aspect-ratio.js

@@ -1,6 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { View } from "@tarojs/components";
 import { cn } from "../lib/utils.js";
+/**
+ * @desc 固定宽高比容器组件。
+ * @param {Parameters<typeof AspectRatio>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AspectRatio>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { AspectRatio } from '@open-dy/vibecoding-sdk-taro/ui/aspect-ratio'
+ * <AspectRatio ratio={16 / 9} />
+ * ```
+ */
 function AspectRatio({ ratio, className, style, ...props }) {
     return (_jsx(View, { "data-slot": "aspect-ratio", style: {
             "--ratio": ratio,

package/dist/ui/aspect-ratio.js.map

@@ -1 +1 @@
-{"version":3,"file":"aspect-ratio.js","sourceRoot":"","sources":["../../src/ui/aspect-ratio.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAEjC,SAAS,WAAW,CAAC,EACnB,KAAK,EACL,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACsB;IAC9B,OAAO,CACL,KAAC,IAAI,iBACO,cAAc,EACxB,KAAK,EACH;YACE,SAAS,EAAE,KAAK;SACM,EAE1B,SAAS,EAAE,EAAE,CAAC,2BAA2B,EAAE,SAAS,CAAC,KACjD,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"aspect-ratio.js","sourceRoot":"","sources":["../../src/ui/aspect-ratio.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAEjC;;;;;;;;;GASG;AACH,SAAS,WAAW,CAAC,EACnB,KAAK,EACL,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EAGO;IACf,OAAO,CACL,KAAC,IAAI,iBACO,cAAc,EACxB,KAAK,EACH;YACE,SAAS,EAAE,KAAK;SACM,EAE1B,SAAS,EAAE,EAAE,CAAC,2BAA2B,EAAE,SAAS,CAAC,KACjD,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/ui/avatar.d.ts

@@ -1,14 +1,79 @@
 import * as React from "react";
 import { Image, type ViewProps } from "@tarojs/components";
 type AvatarImageProps = React.ComponentPropsWithoutRef<typeof Image> & {
+    /** @desc 图片的可访问文本，传为原生 Image 的 aria-label；不会作为失败时的可见文字，请用 AvatarFallback。 */
     alt?: string;
 };
+/**
+ * @desc 头像组件。
+ * @param {Parameters<typeof Avatar>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof Avatar>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar />
+ * ```
+ */
 declare function Avatar({ className, size, ...props }: ViewProps & {
+    /** @desc 头像尺寸，默认 default（size-8），sm 为 size-6，lg 为 size-10；同时影响后备文字和徽标尺寸。 */
     size?: "default" | "sm" | "lg";
 }): React.JSX.Element;
+/**
+ * @desc 头像图片。
+ * @param {Parameters<typeof AvatarImage>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof AvatarImage>[0]["onLoad"]} props.onLoad 原生图片加载成功后调用；组件先将 Avatar 状态设为 loaded，再透传原生事件，从而隐藏 AvatarFallback。
+ * @param {Parameters<typeof AvatarImage>[0]["onError"]} props.onError 原生图片失败后调用；组件先将 Avatar 状态设为 error，再透传原生事件，可通过 AvatarFallback 展示替代内容。
+ * @param {Parameters<typeof AvatarImage>[0]["src"]} props.src 必填图片来源，透传给原生 Image；缺失或空值时 Avatar 状态为 error，请组合 AvatarFallback，不会自动生成替代文字。
+ * @return {ReturnType<typeof AvatarImage>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarImage } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarImage src="/assets/avatar.png" /></Avatar>
+ * ```
+ */
 declare function AvatarImage({ className, src, alt, onLoad, onError, ...props }: AvatarImageProps): React.JSX.Element;
+/**
+ * @desc 头像图片缺失时的替代内容。
+ * @param {Parameters<typeof AvatarFallback>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarFallback>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarFallback } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarFallback /></Avatar>
+ * ```
+ */
 declare function AvatarFallback({ className, ...props }: ViewProps): React.JSX.Element | null;
+/**
+ * @desc 头像角标。
+ * @param {Parameters<typeof AvatarBadge>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarBadge>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarBadge } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarBadge /></Avatar>
+ * ```
+ */
 declare function AvatarBadge({ className, ...props }: ViewProps): React.JSX.Element;
+/**
+ * @desc 头像分组容器。
+ * @param {Parameters<typeof AvatarGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarGroup } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarGroup /></Avatar>
+ * ```
+ */
 declare function AvatarGroup({ className, ...props }: ViewProps): React.JSX.Element;
+/**
+ * @desc 头像分组计数。
+ * @param {Parameters<typeof AvatarGroupCount>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarGroupCount>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarGroupCount } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarGroupCount /></Avatar>
+ * ```
+ */
 declare function AvatarGroupCount({ className, ...props }: ViewProps): React.JSX.Element;
 export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge, };

package/dist/ui/avatar.js

@@ -6,10 +6,33 @@ const AvatarContext = React.createContext(null);
 const AvatarGroupContext = React.createContext({
     size: "default",
 });
+/**
+ * @desc 头像组件。
+ * @param {Parameters<typeof Avatar>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof Avatar>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar />
+ * ```
+ */
 function Avatar({ className, size = "default", ...props }) {
     const [status, setStatus] = React.useState("loading");
     return (_jsx(AvatarContext.Provider, { value: { size, status, setStatus }, children: _jsx(View, { "data-slot": "avatar", "data-size": size, className: cn("group/avatar relative flex shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken dark:after:mix-blend-lighten", size === "lg" && "size-10", size === "sm" && "size-6", size === "default" && "size-8", className), ...props }) }));
 }
+/**
+ * @desc 头像图片。
+ * @param {Parameters<typeof AvatarImage>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof AvatarImage>[0]["onLoad"]} props.onLoad 原生图片加载成功后调用；组件先将 Avatar 状态设为 loaded，再透传原生事件，从而隐藏 AvatarFallback。
+ * @param {Parameters<typeof AvatarImage>[0]["onError"]} props.onError 原生图片失败后调用；组件先将 Avatar 状态设为 error，再透传原生事件，可通过 AvatarFallback 展示替代内容。
+ * @param {Parameters<typeof AvatarImage>[0]["src"]} props.src 必填图片来源，透传给原生 Image；缺失或空值时 Avatar 状态为 error，请组合 AvatarFallback，不会自动生成替代文字。
+ * @return {ReturnType<typeof AvatarImage>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarImage } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarImage src="/assets/avatar.png" /></Avatar>
+ * ```
+ */
 function AvatarImage({ className, src, alt, onLoad, onError, ...props }) {
     const context = React.useContext(AvatarContext);
     const setStatus = context?.setStatus;
@@ -24,16 +47,46 @@ function AvatarImage({ className, src, alt, onLoad, onError, ...props }) {
             onError?.(event);
         }, ...props }));
 }
+/**
+ * @desc 头像图片缺失时的替代内容。
+ * @param {Parameters<typeof AvatarFallback>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarFallback>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarFallback } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarFallback /></Avatar>
+ * ```
+ */
 function AvatarFallback({ className, ...props }) {
     const context = React.useContext(AvatarContext);
     if (context?.status === "loaded")
         return null;
     return (_jsx(View, { "data-slot": "avatar-fallback", className: cn("flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground", context?.size === "sm" && "text-xs", className), ...props }));
 }
+/**
+ * @desc 头像角标。
+ * @param {Parameters<typeof AvatarBadge>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarBadge>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarBadge } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarBadge /></Avatar>
+ * ```
+ */
 function AvatarBadge({ className, ...props }) {
     const context = React.useContext(AvatarContext);
     return (_jsx(View, { "data-slot": "avatar-badge", className: cn("absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground bg-blend-color ring-2 ring-background select-none", context?.size === "sm" && "size-2 [&>view]:hidden", context?.size === "default" && "size-2.5 [&>view]:size-2", context?.size === "lg" && "size-3 [&>view]:size-2", className), ...props }));
 }
+/**
+ * @desc 头像分组容器。
+ * @param {Parameters<typeof AvatarGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarGroup } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarGroup /></Avatar>
+ * ```
+ */
 function AvatarGroup({ className, ...props }) {
     const size = React.useMemo(() => {
         const childArray = React.Children.toArray(props.children);
@@ -42,6 +95,16 @@ function AvatarGroup({ className, ...props }) {
     }, [props.children]);
     return (_jsx(AvatarGroupContext.Provider, { value: { size }, children: _jsx(View, { "data-slot": "avatar-group", className: cn("group/avatar-group flex -space-x-2 [&>*]:ring-2 [&>*]:ring-background", className), ...props }) }));
 }
+/**
+ * @desc 头像分组计数。
+ * @param {Parameters<typeof AvatarGroupCount>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof AvatarGroupCount>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarGroupCount } from '@open-dy/vibecoding-sdk-taro/ui/avatar'
+ * <Avatar><AvatarGroupCount /></Avatar>
+ * ```
+ */
 function AvatarGroupCount({ className, ...props }) {
     const { size } = React.useContext(AvatarGroupContext);
     return (_jsx(View, { "data-slot": "avatar-group-count", className: cn("relative flex shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background", size === "lg" && "size-10 [&>view]:size-5", size === "sm" && "size-6 [&>view]:size-3", size === "default" && "size-8 [&>view]:size-4", className), ...props }));

package/dist/ui/avatar.js.map

@@ -1 +1 @@
-{"version":3,"file":"avatar.js","sourceRoot":"","sources":["../../src/ui/avatar.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"avatar.js","sourceRoot":"","sources":["../../src/ui/avatar.tsx"],"names":[],"mappings":"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"}

package/dist/ui/badge.d.ts

@@ -1,8 +1,30 @@
 import * as React from "react";
 import { type ViewProps } from "@tarojs/components";
 import { type VariantProps } from "class-variance-authority";
+/**
+ * @desc 生成徽标的样式类名；接受其声明的样式变体。
+ * @param {Parameters<typeof badgeVariants>[0]} props 样式变体以及附加的 class 或 className。
+ * @param {Parameters<typeof badgeVariants>[0]["variant"]} props.variant 徽标外观，默认 default（主题色）；secondary 次要、destructive 危险色、outline 描边、ghost 透明、link 链接样式。
+ * @return {string} 合并后的样式类名。
+ * @example
+ * ```tsx
+ * import { badgeVariants } from '@open-dy/vibecoding-sdk-taro/ui/badge'
+ * badgeVariants()
+ * ```
+ */
 declare const badgeVariants: (props?: ({
     variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * @desc 徽标组件。
+ * @param {Parameters<typeof Badge>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof Badge>[0]["variant"]} props.variant 徽标外观，默认 default（主题色）；secondary 次要、destructive 危险色、outline 描边、ghost 透明、link 链接样式。
+ * @return {ReturnType<typeof Badge>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Badge } from '@open-dy/vibecoding-sdk-taro/ui/badge'
+ * <Badge />
+ * ```
+ */
 declare function Badge({ className, variant, ...props }: ViewProps & VariantProps<typeof badgeVariants>): React.JSX.Element;
 export { Badge, badgeVariants };

package/dist/ui/badge.js

@@ -4,6 +4,17 @@ import { View } from "@tarojs/components";
 import { cva } from "class-variance-authority";
 import { cn } from "../lib/utils.js";
 import { collectDataIconState } from "./helpers.js";
+/**
+ * @desc 生成徽标的样式类名；接受其声明的样式变体。
+ * @param {Parameters<typeof badgeVariants>[0]} props 样式变体以及附加的 class 或 className。
+ * @param {Parameters<typeof badgeVariants>[0]["variant"]} props.variant 徽标外观，默认 default（主题色）；secondary 次要、destructive 危险色、outline 描边、ghost 透明、link 链接样式。
+ * @return {string} 合并后的样式类名。
+ * @example
+ * ```tsx
+ * import { badgeVariants } from '@open-dy/vibecoding-sdk-taro/ui/badge'
+ * badgeVariants()
+ * ```
+ */
 const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!", {
     variants: {
         variant: {
@@ -19,6 +30,17 @@ const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-cent
         variant: "default",
     },
 });
+/**
+ * @desc 徽标组件。
+ * @param {Parameters<typeof Badge>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof Badge>[0]["variant"]} props.variant 徽标外观，默认 default（主题色）；secondary 次要、destructive 危险色、outline 描边、ghost 透明、link 链接样式。
+ * @return {ReturnType<typeof Badge>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { Badge } from '@open-dy/vibecoding-sdk-taro/ui/badge'
+ * <Badge />
+ * ```
+ */
 function Badge({ className, variant = "default", ...props }) {
     const { hasInlineStartIcon, hasInlineEndIcon } = React.useMemo(() => collectDataIconState(props.children), [props.children]);
     return (_jsx(View, { "data-slot": "badge", className: cn(badgeVariants({ variant }), hasInlineStartIcon && "pl-1.5", hasInlineEndIcon && "pr-1.5", className), ...props }));

package/dist/ui/badge.js.map

@@ -1 +1 @@
-{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../src/ui/badge.tsx"],"names":[],"mappings":";AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,GAAG,EAAqB,MAAM,0BAA0B,CAAA;AAEjE,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhD,MAAM,aAAa,GAAG,GAAG,CACvB,saAAsa,EACta;IACE,QAAQ,EAAE;QACR,OAAO,EAAE;YACP,OAAO,EAAE,4DAA4D;YACrE,SAAS,EACP,kEAAkE;YACpE,WAAW,EACT,gKAAgK;YAClK,OAAO,EACL,kFAAkF;YACpF,KAAK,EACH,mEAAmE;YACrE,IAAI,EAAE,iDAAiD;SACxD;KACF;IACD,eAAe,EAAE;QACf,OAAO,EAAE,SAAS;KACnB;CACF,CACF,CAAA;AAED,SAAS,KAAK,CAAC,EACb,SAAS,EACT,OAAO,GAAG,SAAS,EACnB,GAAG,KAAK,EACuC;IAC/C,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC,OAAO,CAC5D,GAAG,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAC1C,CAAC,KAAK,CAAC,QAAQ,CAAC,CACjB,CAAA;IAED,OAAO,CACL,KAAC,IAAI,iBACO,OAAO,EACjB,SAAS,EAAE,EAAE,CACX,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,EAC1B,kBAAkB,IAAI,QAAQ,EAC9B,gBAAgB,IAAI,QAAQ,EAC5B,SAAS,CACV,KACG,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAED,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA"}
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../src/ui/badge.tsx"],"names":[],"mappings":";AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,GAAG,EAAqB,MAAM,0BAA0B,CAAA;AAEjE,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,aAAa,GAAG,GAAG,CACvB,saAAsa,EACta;IACE,QAAQ,EAAE;QACR,OAAO,EAAE;YACP,OAAO,EAAE,4DAA4D;YACrE,SAAS,EACP,kEAAkE;YACpE,WAAW,EACT,gKAAgK;YAClK,OAAO,EACL,kFAAkF;YACpF,KAAK,EACH,mEAAmE;YACrE,IAAI,EAAE,iDAAiD;SACxD;KACF;IACD,eAAe,EAAE;QACf,OAAO,EAAE,SAAS;KACnB;CACF,CACF,CAAA;AAED;;;;;;;;;;GAUG;AACH,SAAS,KAAK,CAAC,EACb,SAAS,EACT,OAAO,GAAG,SAAS,EACnB,GAAG,KAAK,EACuC;IAC/C,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC,OAAO,CAC5D,GAAG,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAC1C,CAAC,KAAK,CAAC,QAAQ,CAAC,CACjB,CAAA;IAED,OAAO,CACL,KAAC,IAAI,iBACO,OAAO,EACjB,SAAS,EAAE,EAAE,CACX,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,EAC1B,kBAAkB,IAAI,QAAQ,EAC9B,gBAAgB,IAAI,QAAQ,EAC5B,SAAS,CACV,KACG,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAED,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA"}

package/dist/ui/button-group.d.ts

@@ -2,13 +2,58 @@ import * as React from "react";
 import { type ViewProps } from "@tarojs/components";
 import { type VariantProps } from "class-variance-authority";
 import { Separator } from "./separator.js";
+/**
+ * @desc 生成按钮组的样式类名；接受其声明的样式变体。
+ * @param {Parameters<typeof buttonGroupVariants>[0]} props 样式变体以及附加的 class 或 className。
+ * @param {Parameters<typeof buttonGroupVariants>[0]["orientation"]} props.orientation 排列方向，默认 horizontal（横排）；vertical 纵排。同时调整子按钮的相连边框和首尾圆角。
+ * @return {string} 合并后的样式类名。
+ * @example
+ * ```tsx
+ * import { buttonGroupVariants } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * buttonGroupVariants()
+ * ```
+ */
 declare const buttonGroupVariants: (props?: ({
     orientation?: "horizontal" | "vertical" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * @desc 按钮组组件。
+ * @param {Parameters<typeof ButtonGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof ButtonGroup>[0]["orientation"]} props.orientation 排列方向，默认 horizontal（横排）；vertical 纵排。同时调整子按钮的相连边框和首尾圆角。
+ * @return {ReturnType<typeof ButtonGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup />
+ * ```
+ */
 declare function ButtonGroup({ className, orientation, children, ...props }: ViewProps & VariantProps<typeof buttonGroupVariants>): React.JSX.Element;
+/**
+ * @desc 按钮组文本区域。
+ * @param {Parameters<typeof ButtonGroupText>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof ButtonGroupText>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup, ButtonGroupText } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup><ButtonGroupText /></ButtonGroup>
+ * ```
+ */
 declare function ButtonGroupText({ asChild, className, children, ...props }: Omit<ViewProps, "children"> & {
+    /** @desc 文本内容；asChild 为 true 且提供单个有效 React 元素时，将样式和 props 合并到该元素。 */
     children?: React.ReactNode;
+    /** @desc 是否复用单个子元素作为容器，默认 false；否则使用 View。不是有效单元素时仍使用 View。 */
     asChild?: boolean;
 }): React.JSX.Element;
+/**
+ * @desc 按钮组分隔线。
+ * @param {Parameters<typeof ButtonGroupSeparator>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof ButtonGroupSeparator>[0]["orientation"]} props.orientation 分隔线方向，默认 vertical；横排按钮间使用 vertical，纵排按钮间可改为 horizontal。
+ * @return {ReturnType<typeof ButtonGroupSeparator>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup, ButtonGroupSeparator } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup><ButtonGroupSeparator /></ButtonGroup>
+ * ```
+ */
 declare function ButtonGroupSeparator({ className, orientation, ...props }: React.ComponentProps<typeof Separator>): React.JSX.Element;
 export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, };

package/dist/ui/button-group.js

@@ -4,6 +4,17 @@ import { View } from "@tarojs/components";
 import { cva } from "class-variance-authority";
 import { cn } from "../lib/utils.js";
 import { Separator } from "./separator.js";
+/**
+ * @desc 生成按钮组的样式类名；接受其声明的样式变体。
+ * @param {Parameters<typeof buttonGroupVariants>[0]} props 样式变体以及附加的 class 或 className。
+ * @param {Parameters<typeof buttonGroupVariants>[0]["orientation"]} props.orientation 排列方向，默认 horizontal（横排）；vertical 纵排。同时调整子按钮的相连边框和首尾圆角。
+ * @return {string} 合并后的样式类名。
+ * @example
+ * ```tsx
+ * import { buttonGroupVariants } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * buttonGroupVariants()
+ * ```
+ */
 const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 [&>input]:flex-1", {
     variants: {
         orientation: {
@@ -15,6 +26,17 @@ const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relati
         orientation: "horizontal",
     },
 });
+/**
+ * @desc 按钮组组件。
+ * @param {Parameters<typeof ButtonGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof ButtonGroup>[0]["orientation"]} props.orientation 排列方向，默认 horizontal（横排）；vertical 纵排。同时调整子按钮的相连边框和首尾圆角。
+ * @return {ReturnType<typeof ButtonGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup />
+ * ```
+ */
 function ButtonGroup({ className, orientation, children, ...props }) {
     const resolvedOrientation = orientation ?? "horizontal";
     const validChildren = React.Children.toArray(children).filter(React.isValidElement);
@@ -33,6 +55,16 @@ function ButtonGroup({ className, orientation, children, ...props }) {
             });
         }) }));
 }
+/**
+ * @desc 按钮组文本区域。
+ * @param {Parameters<typeof ButtonGroupText>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof ButtonGroupText>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup, ButtonGroupText } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup><ButtonGroupText /></ButtonGroup>
+ * ```
+ */
 function ButtonGroupText({ asChild = false, className, children, ...props }) {
     const textClassName = cn("flex items-center gap-2 rounded-lg border bg-muted px-2.5 text-sm font-medium [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4", className);
     if (asChild && React.isValidElement(children)) {
@@ -45,6 +77,17 @@ function ButtonGroupText({ asChild = false, className, children, ...props }) {
     }
     return (_jsx(View, { "data-slot": "button-group-text", className: textClassName, ...props, children: children }));
 }
+/**
+ * @desc 按钮组分隔线。
+ * @param {Parameters<typeof ButtonGroupSeparator>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @param {Parameters<typeof ButtonGroupSeparator>[0]["orientation"]} props.orientation 分隔线方向，默认 vertical；横排按钮间使用 vertical，纵排按钮间可改为 horizontal。
+ * @return {ReturnType<typeof ButtonGroupSeparator>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { ButtonGroup, ButtonGroupSeparator } from '@open-dy/vibecoding-sdk-taro/ui/button-group'
+ * <ButtonGroup><ButtonGroupSeparator /></ButtonGroup>
+ * ```
+ */
 function ButtonGroupSeparator({ className, orientation = "vertical", ...props }) {
     return (_jsx(Separator, { "data-slot": "button-group-separator", orientation: orientation, className: cn("relative self-stretch bg-input", orientation === "horizontal" && "mx-px w-auto", orientation === "vertical" && "my-px h-auto", className), ...props }));
 }

package/dist/ui/button-group.js.map

@@ -1 +1 @@
-{"version":3,"file":"button-group.js","sourceRoot":"","sources":["../../src/ui/button-group.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"button-group.js","sourceRoot":"","sources":["../../src/ui/button-group.tsx"],"names":[],"mappings":"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"}

package/dist/ui/button.d.ts

@@ -3,28 +3,80 @@ import { Button as TaroButton, type ViewProps } from "@tarojs/components";
 import { type VariantProps } from "class-variance-authority";
 type TaroButtonProps = React.ComponentProps<typeof TaroButton>;
 type OpenTypeDetailEvent = {
+    /** @desc 原生能力回调的结果明细；平台未提供时可缺省，使用前需判空。 */
     detail?: {
+        /** @desc 平台提供的结果或错误描述；可缺省，请保留原文用于判断和诊断。 */
         errMsg?: string;
+        /** @desc 平台提供的数值结果码；可缺省，含义以所用原生能力的契约为准。 */
         errNo?: number;
     };
 };
 type DouyinButtonExtras = {
+    /** @desc 抖音原生按钮能力类型；非空时改用 Taro Button 并透传该值，否则渲染 View。可用值和授权要求以目标平台能力为准。 */
     openType?: TaroButtonProps["openType"] | (string & {});
+    /** @desc navigateToVideoView 的视频标识；优先于 data-video-id，同时注入两种拼写给原生按钮。其他 openType 仅透传。 */
     dataVideoId?: string;
+    /** @desc 视频类型；优先于 data-video-type。navigateToVideoView 场景省略时为 "raw"，其他场景不设置默认值。 */
     dataVideoType?: string;
+    /** @desc 原生视频能力的渠道参数；优先于 data-channel，未提供时不注入。不控制 SDK 网络通道。 */
     dataChannel?: string;
+    /** @desc dataVideoId 的兼容写法；两者都提供时以 dataVideoId 为准。 */
     "data-video-id"?: string;
+    /** @desc dataVideoType 的兼容写法；两者都提供时以 dataVideoType 为准。 */
     "data-video-type"?: string;
+    /** @desc dataChannel 的兼容写法；两者都提供时以 dataChannel 为准。 */
     "data-channel"?: string;
+    /** @desc 仅在原生 navigateToVideoView 能力分支中透传的结果回调；event.detail 可缺省，不代表业务点击回调。 */
     onNavigateToVideoView?: (event: OpenTypeDetailEvent) => void;
+    /** @desc 仅在原生 addShortcut 能力分支中透传的结果回调；结果从 event.detail 读取，普通 View 按钮不会主动调用。 */
     onAddShortcut?: (event: OpenTypeDetailEvent) => void;
 };
 /** Taro Button `size`/`type` 与 CVA variant 同名，必须 Omit，否则 size 会收成只剩 `"default"`。 */
 type TaroButtonNativeKeys = keyof ViewProps | "className" | "style" | "children" | "size" | "type";
+/**
+ * @desc 按钮组件的属性类型；保留 Taro 原生能力，避免 size/type 与样式变体同名冲突。
+ * @property {ButtonProps["variant"]} variant 视觉变体，默认 default（主题色）；outline 描边、secondary 次要、ghost 无底色、destructive 危险色、link 链接样式。只控制样式，不执行业务动作。
+ * @property {ButtonProps["size"]} size 尺寸，默认 default（h-8）；xs/sm/lg 分别为 h-6/h-7/h-9；icon/icon-xs/icon-sm/icon-lg 为 size-8/6/7/9 正方形图标按钮。
+ * @example
+ * ```tsx
+ * import { ButtonProps } from '@open-dy/vibecoding-sdk-taro/ui/button'
+ * const props: ButtonProps = { children: '确认' }
+ * ```
+ */
 export type ButtonProps = ViewProps & VariantProps<typeof buttonVariants> & Omit<TaroButtonProps, TaroButtonNativeKeys> & DouyinButtonExtras;
+/**
+ * @desc 生成按钮的样式类名；接受其声明的样式变体。
+ * @param {Parameters<typeof buttonVariants>[0]} props 样式变体以及附加的 class 或 className。
+ * @param {Parameters<typeof buttonVariants>[0]["variant"]} props.variant 视觉变体，默认 default（主题色）；outline 描边、secondary 次要、ghost 无底色、destructive 危险色、link 链接样式。只控制样式，不执行业务动作。
+ * @param {Parameters<typeof buttonVariants>[0]["size"]} props.size 尺寸，默认 default（h-8）；xs/sm/lg 分别为 h-6/h-7/h-9；icon/icon-xs/icon-sm/icon-lg 为 size-8/6/7/9 正方形图标按钮。
+ * @return {string} 合并后的样式类名。
+ * @example
+ * ```tsx
+ * import { buttonVariants } from '@open-dy/vibecoding-sdk-taro/ui/button'
+ * buttonVariants()
+ * ```
+ */
 declare const buttonVariants: (props?: ({
     variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
     size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * @desc 支持主题样式和抖音 openType 的小程序按钮；用于普通小程序和兴趣卡落地页。
+ * @param {ButtonProps} props 按钮属性；variant 和 size 选择视觉样式，className 覆写容器，onClick 处理普通点击。
+ * @param {Parameters<typeof Button>[0]["variant"]} props.variant 视觉变体，默认 default（主题色）；outline 描边、secondary 次要、ghost 无底色、destructive 危险色、link 链接样式。只控制样式，不执行业务动作。
+ * @param {Parameters<typeof Button>[0]["size"]} props.size 尺寸，默认 default（h-8）；xs/sm/lg 分别为 h-6/h-7/h-9；icon/icon-xs/icon-sm/icon-lg 为 size-8/6/7/9 正方形图标按钮。
+ * @param {Parameters<typeof Button>[0]["className"]} props.className 追加到预置样式之后的容器类名，可覆写色彩、边框、圆角和尺寸。普通分支应用于 View，openType 分支应用于原生 Button。
+ * @param {Parameters<typeof Button>[0]["style"]} props.style 传给渲染根节点的内联样式；普通分支为 View，openType 分支为原生 Button。
+ * @param {Parameters<typeof Button>[0]["disabled"]} props.disabled 原生 Taro Button 的禁用属性，仅 openType 分支有原生禁用保证。普通 View 分支透传该值但未实现点击拦截，请在业务回调中处理。
+ * @return {React.JSX.Element} 普通交互返回 View；传入 openType 时返回原生 Taro Button。
+ * @remarks variant 默认 default（主题背景和前景色），size 默认 default（h-8）。className 合并在预置样式之后，可覆写背景、文字色、边框、圆角和尺寸。不要为获得另一种风格重写通用按钮；按 DESIGN.md 传入 className 或 variant。openType 走原生按钮能力，普通按钮走 View，两者使用同一组视觉样式。
+ * @example
+ * ```tsx
+ * import { Button } from '@open-dy/vibecoding-sdk-taro/ui/button'
+ * export function AddTaskButton() {
+ *   return <Button className="h-11 rounded-none border-4 border-black bg-black text-white" onClick={() => console.log('add task')}>添加</Button>
+ * }
+ * ```
+ */
 declare function Button({ className, variant, size, openType, dataVideoId, dataVideoType, dataChannel, "data-video-id": dataVideoIdAttr, "data-video-type": dataVideoTypeAttr, "data-channel": dataChannelAttr, style, ...props }: ButtonProps): React.JSX.Element;
 export { Button, buttonVariants };