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

package/src/ui/dropdown-menu.tsx

@@ -0,0 +1,547 @@
+import * as React from "react"
+import { View, type ViewProps } from "@tarojs/components"
+
+import { cn } from "../lib/utils"
+import { Check, ChevronRight, Circle } from "@open-dy/lucide-taro"
+
+const DropdownMenuContext = React.createContext<{
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}>({ open: false, onOpenChange: () => {} })
+
+type DropdownMenuTriggerRenderProps = Omit<ViewProps, "children"> & {
+  /** @desc 组件自动注入的触发器标识；自定义 render 应转发到触发节点，不手动修改。 */
+  "data-slot": "dropdown-menu-trigger"
+  /** @desc 组件自动注入的展开状态；自定义 render 应转发到触发节点。 */
+  "aria-expanded": boolean
+}
+
+type DropdownMenuTriggerClickEvent = Parameters<
+  NonNullable<ViewProps["onClick"]>
+>[0]
+
+type DropdownMenuTriggerProps = Omit<ViewProps, "children"> & {
+  /** @desc 默认触发器内的内容；设置 render 时由自定义渲染结果取代。 */
+  children?: React.ReactNode
+  /** @desc 自定义触发器元素或渲染函数；省略时使用 View。元素会被克隆并合并点击处理；函数收到状态和事件 props，必须传给实际可点击节点。 */
+  render?:
+    | React.ReactElement
+    | ((props: DropdownMenuTriggerRenderProps) => React.ReactNode)
+}
+
+/**
+ * @desc 下拉菜单组件。
+ * @param {Parameters<typeof DropdownMenu>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenu>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu />
+ * ```
+ */
+function DropdownMenu({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  children,
+}: {
+  /** @desc 受控展开状态；传入后以该值为准，需在 onOpenChange 中更新。省略时由组件内部管理。 */
+  open?: boolean
+  /** @desc 非受控模式的初始展开状态，默认 false；仅初始化时读取，传入 open 后不生效。 */
+  defaultOpen?: boolean
+  /** @desc 触发器或关闭操作请求改变展开状态时调用，参数为下一状态；受控模式需由调用方同步 open。 */
+  onOpenChange?: (open: boolean) => void
+  /** @desc 同一实例的触发器、内容区等组合子组件；省略时不显示内容，子组件通过上下文共享状态。 */
+  children?: React.ReactNode
+}) {
+  const [internal, setInternal] = React.useState(defaultOpen ?? false)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : internal
+
+  return (
+    <DropdownMenuContext.Provider
+      value={{
+        open,
+        onOpenChange: (v) => {
+          if (!controlled) setInternal(v)
+          onOpenChange?.(v)
+        },
+      }}
+    >
+      <View data-slot="dropdown-menu" className="relative z-50 inline-block">
+        {children}
+      </View>
+    </DropdownMenuContext.Provider>
+  )
+}
+
+/**
+ * @desc 下拉菜单触发器。
+ * @param {Parameters<typeof DropdownMenuTrigger>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuTrigger>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuTrigger } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuTrigger /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuTrigger({
+  children,
+  render,
+  onClick,
+  ...props
+}: DropdownMenuTriggerProps) {
+  const { onOpenChange, open } = React.useContext(DropdownMenuContext)
+  const handleClick = (event: DropdownMenuTriggerClickEvent) => {
+    onClick?.(event)
+    onOpenChange(!open)
+  }
+
+  const triggerProps: DropdownMenuTriggerRenderProps = {
+    "data-slot": "dropdown-menu-trigger",
+    "aria-expanded": open,
+    onClick: handleClick,
+    ...props,
+  }
+
+  if (render) {
+    if (typeof render === "function") {
+      return <>{render(triggerProps)}</>
+    }
+
+    if (React.isValidElement(render)) {
+      const element = render as React.ReactElement<{
+        onClick?: ViewProps["onClick"]
+      }>
+
+      return React.cloneElement(element, {
+        ...triggerProps,
+        onClick: (event: DropdownMenuTriggerClickEvent) => {
+          element.props.onClick?.(event)
+          handleClick(event)
+        },
+      })
+    }
+  }
+
+  return (
+    <View {...triggerProps}>
+      {children}
+    </View>
+  )
+}
+
+/**
+ * @desc 下拉菜单跨层级渲染入口。
+ * @param {Parameters<typeof DropdownMenuPortal>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuPortal>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuPortal } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuPortal /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuPortal({ children }: {
+  /** @desc 要渲染的子节点；该兼容包装只返回 Fragment，不额外创建原生容器或执行挂载迁移。 */
+  children?: React.ReactNode }) {
+  return <>{children}</>
+}
+
+/**
+ * @desc 下拉菜单内容容器。
+ * @param {Parameters<typeof DropdownMenuContent>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuContent>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuContent } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuContent /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuContent({
+  className,
+  children,
+  sideOffset: _sideOffset,
+  ...props
+}: ViewProps & {
+  /** @desc 兼容属性；当前实现未使用该值定位，内容固定在触发器下方并使用 mt-1 间隔。 */
+  sideOffset?: number }) {
+  const { open, onOpenChange } = React.useContext(DropdownMenuContext)
+  if (!open) return null
+
+  return (
+    <>
+      <View className="fixed inset-0 z-40" onClick={() => onOpenChange(false)} />
+      <View
+        data-slot="dropdown-menu-content"
+        className={cn(
+          "absolute top-full left-0 z-50 mt-1 min-w-[8rem] overflow-hidden rounded-lg border bg-popover p-1 text-popover-foreground shadow-md",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </View>
+    </>
+  )
+}
+
+/**
+ * @desc 下拉菜单分组容器。
+ * @param {Parameters<typeof DropdownMenuGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuGroup } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuGroup /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuGroup({ ...props }: ViewProps) {
+  return <View data-slot="dropdown-menu-group" {...props} />
+}
+
+/**
+ * @desc 下拉菜单条目。
+ * @param {Parameters<typeof DropdownMenuItem>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuItem>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuItem } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuItem /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: ViewProps & {
+  /** @desc 是否增加左侧内边距以对齐含图标的项目；默认 false，为 true 时使用 pl-8。 */
+  inset?: boolean;
+  /** @desc 项目样式，默认 default；destructive 用危险操作文字及按压色，仅改变样式，不自动执行删除。 */
+  variant?: "default" | "destructive" }) {
+  const { onOpenChange } = React.useContext(DropdownMenuContext)
+  return (
+    <View
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none active:bg-accent active:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        variant === "destructive" &&
+          "text-destructive active:bg-destructive/10 active:text-destructive",
+        inset && "pl-8",
+        className
+      )}
+      onClick={(event) => {
+        props.onClick?.(event)
+        onOpenChange(false)
+      }}
+      {...props}
+    />
+  )
+}
+
+/**
+ * @desc 下拉菜单复选条目。
+ * @param {Parameters<typeof DropdownMenuCheckboxItem>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuCheckboxItem>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuCheckboxItem } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuCheckboxItem /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  onCheckedChange,
+  ...props
+}: ViewProps & {
+  /** @desc 外部控制的勾选状态，默认不勾选；组件不会自己保存状态，需在 onCheckedChange 中同步。 */
+  checked?: boolean
+  /** @desc 点击时传入 !checked；调用方负责更新 checked，没有 defaultChecked 或非受控模式。 */
+  onCheckedChange?: (checked: boolean) => void
+}) {
+  return (
+    <View
+      data-slot="dropdown-menu-checkbox-item"
+      className={cn(
+        "relative flex items-center gap-2 rounded-sm py-1.5 pl-8 pr-2 text-sm outline-hidden select-none active:bg-accent active:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      onClick={() => onCheckedChange?.(!checked)}
+      {...props}
+    >
+      <View className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        {checked ? <Check className="size-4" /> : null}
+      </View>
+      {children}
+    </View>
+  )
+}
+
+/**
+ * @desc 下拉菜单单选分组。
+ * @param {Parameters<typeof DropdownMenuRadioGroup>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuRadioGroup>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuRadioGroup } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuRadioGroup /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuRadioGroup({
+  children,
+  ...props
+}: ViewProps) {
+  return (
+    <View data-slot="dropdown-menu-radio-group" {...props}>
+      {children}
+    </View>
+  )
+}
+
+/**
+ * @desc 下拉菜单单选条目。
+ * @param {Parameters<typeof DropdownMenuRadioItem>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuRadioItem>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuRadioItem } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuRadioItem checked /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuRadioItem({
+  className,
+  children,
+  checked,
+  ...props
+}: ViewProps & {
+  /** @desc 是否显示选中指示，默认 false；该项不管理组值，选择和更新由调用方通过点击事件处理。 */
+  checked?: boolean }) {
+  return (
+    <View
+      data-slot="dropdown-menu-radio-item"
+      className={cn(
+        "relative flex items-center gap-2 rounded-sm py-1.5 pl-8 pr-2 text-sm outline-hidden select-none active:bg-accent active:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <View className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        {checked ? <Circle className="size-2 fill-current" /> : null}
+      </View>
+      {children}
+    </View>
+  )
+}
+
+/**
+ * @desc 下拉菜单标签文本。
+ * @param {Parameters<typeof DropdownMenuLabel>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuLabel>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuLabel } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuLabel /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: ViewProps & {
+  /** @desc 是否增加左侧内边距以对齐含图标的项目；默认 false，为 true 时使用 pl-8。 */
+  inset?: boolean }) {
+  return (
+    <View
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-sm font-medium",
+        inset && "pl-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * @desc 下拉菜单分隔线。
+ * @param {Parameters<typeof DropdownMenuSeparator>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuSeparator>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuSeparator } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuSeparator /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuSeparator({ className, ...props }: ViewProps) {
+  return (
+    <View
+      data-slot="dropdown-menu-separator"
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+/**
+ * @desc 下拉菜单快捷键说明。
+ * @param {Parameters<typeof DropdownMenuShortcut>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuShortcut>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuShortcut } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuShortcut /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuShortcut({ className, ...props }: ViewProps) {
+  return (
+    <View
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const DropdownMenuSubContext = React.createContext<{
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}>({ open: false, onOpenChange: () => {} })
+
+/**
+ * @desc 下拉菜单子菜单上下文。
+ * @param {Parameters<typeof DropdownMenuSub>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuSub>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuSub } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuSub /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuSub({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  children,
+}: {
+  /** @desc 受控展开状态；传入后以该值为准，需在 onOpenChange 中更新。省略时由组件内部管理。 */
+  open?: boolean
+  /** @desc 非受控模式的初始展开状态，默认 false；仅初始化时读取，传入 open 后不生效。 */
+  defaultOpen?: boolean
+  /** @desc 触发器或关闭操作请求改变展开状态时调用，参数为下一状态；受控模式需由调用方同步 open。 */
+  onOpenChange?: (open: boolean) => void
+  /** @desc 同一实例的触发器、内容区等组合子组件；省略时不显示内容，子组件通过上下文共享状态。 */
+  children?: React.ReactNode
+}) {
+  const [internal, setInternal] = React.useState(defaultOpen ?? false)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : internal
+
+  return (
+    <DropdownMenuSubContext.Provider
+      value={{
+        open,
+        onOpenChange: (v) => {
+          if (!controlled) setInternal(v)
+          onOpenChange?.(v)
+        },
+      }}
+    >
+      {children}
+    </DropdownMenuSubContext.Provider>
+  )
+}
+
+/**
+ * @desc 下拉菜单子菜单触发器。
+ * @param {Parameters<typeof DropdownMenuSubTrigger>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuSubTrigger>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuSubTrigger } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuSubTrigger /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: ViewProps & {
+  /** @desc 是否增加左侧内边距以对齐含图标的项目；默认 false，为 true 时使用 pl-8。 */
+  inset?: boolean }) {
+  const { onOpenChange, open } = React.useContext(DropdownMenuSubContext)
+  return (
+    <View
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      data-state={open ? "open" : "closed"}
+      className={cn(
+        "flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        open && "bg-accent",
+        inset && "pl-8",
+        className
+      )}
+      onClick={() => onOpenChange(!open)}
+      {...props}
+    >
+      {children}
+      <ChevronRight className="ml-auto" />
+    </View>
+  )
+}
+
+/**
+ * @desc 下拉菜单子菜单内容。
+ * @param {Parameters<typeof DropdownMenuSubContent>[0]} props 组件属性；自有字段的用途及默认行为见下表，继承属性另列。
+ * @return {ReturnType<typeof DropdownMenuSubContent>} 组件渲染结果；类型见返回值契约。
+ * @example
+ * ```tsx
+ * import { DropdownMenu, DropdownMenuSubContent } from '@open-dy/vibecoding-sdk-taro/ui/dropdown-menu'
+ * <DropdownMenu><DropdownMenuSubContent /></DropdownMenu>
+ * ```
+ */
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: ViewProps) {
+  const { open } = React.useContext(DropdownMenuSubContext)
+  if (!open) return null
+
+  return (
+    <View
+      data-slot="dropdown-menu-sub-content"
+      className={cn(
+        "z-50 min-w-[8rem] overflow-hidden rounded-lg border bg-popover p-1 text-popover-foreground shadow-lg",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+}