/**
 * Layout orientation supported by `UiField`.
 * - `vertical`: stacked layout (label above input).
 * - `responsive`: horizontal by default, collapses to vertical on small screens.
 */
export type UiFieldOrientation = 'vertical' | 'responsive';

/**
 * Error shape supported by `UiFieldError`.
 */
export type UiFieldErrorLike =
  | string
  | {
      /** The error message text. */
      message: string | undefined;
    }
  | undefined;

/**
 * Where the description text is rendered relative to the field.
 */
export type UiFieldDescriptionPlacement = 'under-label' | 'under-input';

/**
 * A form field wrapper that groups label, input, description, and error messages.
 * Provides consistent layout and accessibility for form controls.
 * @category Form Inputs
 * @useCases form layout, input wrapper, field grouping, validation display
 * @keywords field, form, label, input, error, validation, wrapper
 * @related UiInput, UiLabel
 */
export interface UiFieldProps {
  /**
   * Layout orientation of the field.
   * @default 'vertical'
   */
  orientation?: UiFieldOrientation;

  /**
   * Where the description is placed relative to the field layout.
   * - `under-label`: description renders between the label and the input.
   * - `under-input`: description renders after the input.
   * @default 'under-input'
   */
  descriptionPlacement?: UiFieldDescriptionPlacement;

  /**
   * When `true`, the child `UiFieldDescription` renders with a checkbox
   * next to the description text (unless the description sets its own `variant` prop).
   * @default false
   */
  descriptionCheckbox?: boolean;
}

/**
 * Props for `UiFieldError` component.
 */
export interface UiFieldErrorProps {
  /**
   * List of errors to render. Supports strings or objects with a `message` field.
   */
  errors?: UiFieldErrorLike[];
}

/**
 * Visual variant for `UiFieldDescription`.
 */
export type UiFieldDescriptionVariant = 'default' | 'input';

/**
 * Props for `UiFieldDescription` component.
 */
export interface UiFieldDescriptionProps {
  /**
   * Visual variant of the description.
   * Use `input` to render a checkbox next to the description text.
   * @default 'default'
   */
  variant?: UiFieldDescriptionVariant;

  /**
   * Name attribute for the checkbox (required when `variant="input"`).
   */
  name?: string;

  /**
   * Disables the checkbox.
   * @default false
   */
  disabled?: boolean;
}

/**
 * Props for `UiFieldLabel` component.
 */
export interface UiFieldLabelProps {
  /**
   * The id of the element the label is associated with.
   * Use together with `id` on an input.
   */
  for?: string;

  /**
   * When provided, renders a `UiFieldLabelInfo` icon next to the label
   * that shows this text as a tooltip on hover/focus.
   */
  tooltip?: string;

  /**
   * Lucide icon name for the tooltip trigger when `tooltip` is set.
   * @default 'circle-help'
   * @see https://lucide.dev/icons
   */
  tooltipIcon?: string;
}

/**
 * An interactive info icon placed next to a field label that reveals a tooltip on hover or focus.
 * Uses a ghost icon button as the trigger for keyboard and pointer accessibility.
 * @category Form Inputs
 * @useCases field hint, label help, input context
 * @keywords field, label, info, tooltip, help, hint
 * @related UiFieldLabel, UiTooltip, UiButton
 */
export interface UiFieldLabelInfoProps {
  /**
   * Tooltip text shown on hover / focus.
   */
  description: string;

  /**
   * Lucide icon name in kebab-case or PascalCase.
   * @default 'circle-help'
   * @see https://lucide.dev/icons
   */
  icon?: string;
}
