/**
 * Variant types for the UiItem primitive component
 */
export type UiItemVariants =
  | 'default'
  | 'active'
  | 'outline'
  | 'hover'
  | 'hover-action';

/**
 * Size types for the UiItem primitive component
 */
export type UiItemSizes = 'default' | 'sm' | 'minimal';

/**
 * Media variant types for the UiItemMedia component
 */
export type UiItemMediaVariants = 'default' | 'icon' | 'image' | 'avatar-group';

/**
 * Action variant types for the UiItemAction component
 */
export type UiItemActionVariants = 'default' | 'text' | 'button';

/**
 * A versatile component that you can use to display any content.
 * The Item component is a straightforward flex container that can house
 * nearly any type of content. Use it to display a title, description, and actions.
 * Group it with the ItemGroup component to create a list of items.
 * @category Layout
 * @useCases list item, menu entry, settings row, navigation item, notification, user card
 * @keywords item, list, row, entry, menu, settings, navigation, card
 * @related UiCard, UiButton, UiListbox
 */
export interface UiItemProps {
  /**
   * Visual variant of the item.
   * - `default`: Standard styling without interactive affordance
   * - `active`: Active row with a left-edge indicator and active background
   * - `outline`: Outlined style with clear borders and transparent background
   * - `hover`: Row with hover feedback
   * - `hover-action`: Actionable row with hover feedback, except while hovering actions
   * @default 'default'
   */
  variant?: UiItemVariants;

  /**
   * Size of the item.
   * - `default`: Standard size with comfortable padding
   * - `sm`: Compact size for dense layouts
   * - `minimal`: Compact size with smaller default action affordance
   * @default 'default'
   */
  size?: UiItemSizes;

  /**
   * Convenience title rendered with UiItemTitle.
   */
  title?: string;

  /**
   * Convenience description rendered with UiItemDescription.
   */
  description?: string;

  /**
   * Alias for `description`.
   */
  desc?: string;

  /**
   * Whether to render as a child element (using Radix's asChild pattern).
   * Useful for rendering the item as a link or custom component.
   * Variant and focus styles will be applied to the custom component.
   * @default false
   */
  asChild?: boolean;

  /**
   * When true, sets `role="listitem"` for use inside a parent with `role="list"`.
   * Keep false when rendering standalone items or when the parent already
   * provides list item semantics (e.g. an `<li>`).
   * @default false
   */
  withListSemantics?: boolean;
}

export interface UiItemEmits {
  /**
   * Emitted when the built-in default action button is clicked.
   */
  action: [event: MouseEvent];
}

/**
 * Props for the UiItemGroup component.
 * Container that groups related items together with consistent styling.
 */
export type UiItemGroupProps = Record<string, never>;

/**
 * Props for the UiItemSeparator component.
 * A separator that separates items in the item group.
 */
export type UiItemSeparatorProps = Record<string, never>;

/**
 * Props for the UiItemMedia component.
 * Use to display media content such as icons, images, or avatars.
 */
export interface UiItemMediaProps {
  /**
   * Visual variant of the media container.
   * - `default`: Standard styling, suitable for avatars
   * - `icon`: Styled for icon display with appropriate sizing
   * - `image`: Styled for a single avatar or image thumbnail
   * - `avatar-group`: Styled for stacked avatar groups
   * @default 'default'
   */
  variant?: UiItemMediaVariants;
}

/**
 * Props for the UiItemContent component.
 * Wraps the title and description of the item.
 */
export type UiItemContentProps = Record<string, never>;

/**
 * Props for the UiItemTitle component.
 * Displays the title of the item.
 */
export type UiItemTitleProps = Record<string, never>;

/**
 * Props for the UiItemDescription component.
 * Displays the description of the item.
 */
export type UiItemDescriptionProps = Record<string, never>;

/**
 * Props for the UiItemAction component.
 * Displays action buttons or other interactive elements.
 */
export interface UiItemActionProps {
  /**
   * Visual variant of the action container.
   * - `default`: Standard flex action layout
   * - `text`: Muted label action
   * - `button`: Compact button-like action affordance
   * @default 'default'
   */
  variant?: UiItemActionVariants;

  /**
   * Optional tooltip shown when hovering or focusing the action container.
   */
  tooltip?: string;
}

/**
 * Props for the UiItemHeader component.
 * Displays a header above the item content.
 */
export type UiItemHeaderProps = Record<string, never>;

/**
 * Props for the UiItemFooter component.
 * Displays a footer below the item content.
 */
export type UiItemFooterProps = Record<string, never>;
