/**
 * Base props shared by both single and multiple toggle groups.
 */
export interface UiToggleGroupBaseProps {
  /**
   * Whether the entire group is disabled.
   * @default false
   */
  disabled?: boolean;
  /**
   * The visual style variant applied to all items.
   * @default 'default'
   */
  variant?: 'default' | 'outline' | 'soft';
  /**
   * The size applied to all items.
   * @default 'default'
   */
  size?: 'default' | 'sm' | 'lg';
  /**
   * Whether navigation loops from last item to first and vice versa.
   * @default true
   */
  loop?: boolean;
  /**
   * Whether roving focus is enabled for keyboard navigation.
   * @default true
   */
  rovingFocus?: boolean;
  /**
   * The orientation of the toggle group for keyboard navigation.
   * @default 'horizontal'
   */
  orientation?: 'horizontal' | 'vertical';
}

/**
 * Props for single selection toggle group.
 * Only one item can be selected at a time.
 * @category Form Inputs
 * @useCases view toggles, alignment, exclusive options
 * @keywords toggle, group, single, select, exclusive, radio
 * @related UiToggle, UiRadioGroup
 */
export interface UiToggleGroupSingleProps extends UiToggleGroupBaseProps {
  /**
   * Single selection mode - only one item can be selected.
   */
  type: 'single';
  /**
   * The controlled value of the selected item. Use with v-model.
   */
  modelValue?: string;
  /**
   * The default value when initially rendered (uncontrolled mode).
   */
  defaultValue?: string;
}

/**
 * Props for multiple selection toggle group.
 * Multiple items can be selected simultaneously.
 * @category Form Inputs
 * @useCases text formatting, filters, feature toggles
 * @keywords toggle, group, multiple, multi-select, checkbox
 * @related UiToggle, UiCheckbox
 */
export interface UiToggleGroupMultipleProps extends UiToggleGroupBaseProps {
  /**
   * Multiple selection mode - multiple items can be selected.
   */
  type: 'multiple';
  /**
   * The controlled array of selected item values. Use with v-model.
   */
  modelValue?: string[];
  /**
   * The default values when initially rendered (uncontrolled mode).
   */
  defaultValue?: string[];
}

/**
 * A set of two-state buttons that can be toggled on or off.
 * Use for toolbar actions, formatting options, or any grouped toggle selections.
 *
 * This is a discriminated union type keyed by `type`:
 * - `type: 'single'` → `modelValue` is `string`
 * - `type: 'multiple'` → `modelValue` is `string[]`
 * @category Form Inputs
 * @useCases toolbar buttons, text formatting, view options, filter toggles
 * @keywords toggle, group, button, pressed, on, off, state, multiple, single
 * @related UiToggle, UiButton, UiRadioGroup
 */
export type UiToggleGroupProps =
  | UiToggleGroupSingleProps
  | UiToggleGroupMultipleProps;

/**
 * Conditional helper that maps the `type` discriminant to the correct value type.
 * - `'single'` → `string`
 * - `'multiple'` → `string[]`
 *
 * Used by the generic `UiToggleGroup` component to enforce that
 * `v-model` / `defaultValue` match the `type` prop at the template level.
 */
export type UiToggleGroupModelValue<T extends 'single' | 'multiple'> =
  T extends 'single' ? string : string[];

/**
 * An item within a toggle group.
 */
export interface UiToggleGroupItemProps {
  /**
   * The unique value for the toggle item.
   */
  value: string;
  /**
   * Whether this item is disabled.
   * @default false
   */
  disabled?: boolean;
  /**
   * Override the variant for this specific item.
   */
  variant?: 'default' | 'outline' | 'soft';
  /**
   * Override the size for this specific item.
   */
  size?: 'default' | 'sm' | 'lg';
}
