Interactive Controls

/**
 * Interactive controls for manipulating story arguments
 * @param props - Controls configuration options
 * @returns React component with argument controls
 */
function Controls(props: ControlsProps): React.ReactElement;

interface ControlsProps {
  /** Component or CSF file to extract controls from */
  of?: React.ComponentType | ModuleExports;
  /** Controls to include */
  include?: PropDescriptor;
  /** Controls to exclude */
  exclude?: PropDescriptor;
  /** Sorting configuration */
  sort?: SortType;
}

interface ControlProps<T> {
  /** Control name/identifier */
  name: string;
  /** Current value */
  value?: T;
  /** Default value */
  defaultValue?: T;
  /** Argument type metadata */
  argType?: ArgType;
  /** Value change handler */
  onChange: (value?: T) => T | void;
  /** Focus event handler */
  onFocus?: (evt: any) => void;
  /** Blur event handler */
  onBlur?: (evt: any) => void;
}

interface ArgType {
  name: string;
  description?: string;
  defaultValue?: any;
  type?: {
    name: string;
    value?: any;
  };
  table?: {
    type?: { summary: string };
    defaultValue?: { summary: string };
    category?: string;
  };
  control?: ControlType | false;
  if?: {
    arg: string;
    exists?: boolean;
    eq?: any;
    neq?: any;
    truthy?: boolean;
  };
}

/**
 * Toggle control for boolean values
 * @param props - Boolean control configuration
 * @returns React component with checkbox/toggle input
 */
function BooleanControl(props: BooleanProps): React.ReactElement;

interface BooleanProps extends ControlProps<BooleanValue> {
  /** Boolean control configuration */
  config?: BooleanConfig;
}

type BooleanValue = boolean;

interface BooleanConfig {
  /** Disable the control */
  disable?: boolean;
}

/**
 * Color picker with presets and advanced selection
 * @param props - Color control configuration  
 * @returns React component with color picker interface
 */
const ColorControl: React.FC<ColorProps>;

interface ColorProps extends ControlProps<ColorValue> {
  /** Color control configuration */
  config?: ColorConfig;
}

type ColorValue = string;

interface ColorConfig {
  /** Array of preset color values */
  presetColors?: string[];
  /** Start with color picker open */
  startOpen?: boolean;
}

// Basic color control
<ColorControl 
  name="backgroundColor"
  value="#ffffff"
  onChange={(color) => setBackgroundColor(color)}
/>

// With preset colors
<ColorControl 
  name="themeColor"
  value="#007acc"
  config={{
    presetColors: ['#007acc', '#ff6b6b', '#4ecdc4', '#45b7d1'],
    startOpen: false
  }}
  onChange={(color) => setThemeColor(color)}
/>

/**
 * Date/time input control with validation
 * @param props - Date control configuration
 * @returns React component with date/time input
 */
function DateControl(props: DateProps): React.ReactElement;

interface DateProps extends ControlProps<DateValue> {
  /** Date control configuration */
  config?: DateConfig;
}

type DateValue = Date | number;

interface DateConfig {
  /** Disable the control */
  disable?: boolean;
}

/**
 * Numeric input with validation and constraints
 * @param props - Number control configuration
 * @returns React component with number input
 */
function NumberControl(props: NumberProps): React.ReactElement;

interface NumberProps extends ControlProps<NumberValue> {
  /** Number control configuration */
  config?: NumberConfig;
}

type NumberValue = number;

interface NumberConfig {
  /** Minimum allowed value */
  min?: number;
  /** Maximum allowed value */
  max?: number;
  /** Step increment */
  step?: number;
}

/**
 * Slider for numeric ranges with visual feedback
 * @param props - Range control configuration
 * @returns React component with range slider
 */
function RangeControl(props: RangeProps): React.ReactElement;

interface RangeProps extends ControlProps<RangeValue> {
  /** Range control configuration */
  config?: RangeConfig;
}

type RangeValue = number;

interface RangeConfig extends NumberConfig {
  /** Additional range-specific options */
}

/**
 * Text input field with validation
 * @param props - Text control configuration
 * @returns React component with text input
 */
function TextControl(props: TextProps): React.ReactElement;

interface TextProps extends ControlProps<TextValue> {
  /** Text control configuration */
  config?: TextConfig;
}

type TextValue = string;

interface TextConfig {
  /** Maximum text length */
  maxLength?: number;
}

/**
 * JSON object editor with tree view and validation
 * @param props - Object control configuration  
 * @returns React component with object editor
 */
function ObjectControl(props: ObjectProps): React.ReactElement;

interface ObjectProps extends ControlProps<ObjectValue> {
  /** Object control configuration */
  config?: ObjectConfig;
}

type ObjectValue = any;

interface ObjectConfig {
  /** Disable the control */
  disable?: boolean;
}

/**
 * File upload control for file inputs
 * @param props - Files control configuration
 * @returns React component with file input
 */
function FilesControl(props: FilesProps): React.ReactElement;

interface FilesProps extends ControlProps<FilesValue> {
  /** Files control configuration */
  config?: FilesConfig;
}

type FilesValue = FileList | File[] | null;

interface FilesConfig {
  /** Accept file types */
  accept?: string;
  /** Allow multiple files */
  multiple?: boolean;
}

/**
 * Dropdown selection control
 * @param props - Select control configuration
 * @returns React component with select dropdown
 */
function SelectControl(props: SelectProps): React.ReactElement;

interface SelectProps extends ControlProps<any> {
  /** Select control configuration */
  config?: OptionsConfig;
}

/**
 * Radio button group for single selection
 * @param props - Radio control configuration
 * @returns React component with radio buttons
 */
function RadioControl(props: RadioProps): React.ReactElement;

interface RadioProps extends ControlProps<any> {
  /** Radio control configuration */
  config?: OptionsConfig;
}

/**
 * Checkbox group for multiple selection
 * @param props - Checkbox control configuration
 * @returns React component with checkbox group
 */
function CheckboxControl(props: CheckboxProps): React.ReactElement;

interface CheckboxProps extends ControlProps<any[]> {
  /** Checkbox control configuration */
  config?: OptionsConfig;
}

/**
 * Generic options control base
 * @param props - Options control configuration
 * @returns React component with options interface
 */
function OptionsControl(props: OptionsProps): React.ReactElement;

interface OptionsProps extends ControlProps<any> {
  /** Options control configuration */
  config?: OptionsConfig;
}

interface OptionsConfig {
  /** Available option values */
  options?: OptionsConfigOptions;
  /** Labels for options */  
  labels?: Record<string, string>;
  /** Control type override */
  type?: OptionsControlType;
}

type OptionsConfigOptions = 
  | string[] 
  | number[]
  | { label: string; value: any }[]
  | Record<string, any>;

type OptionsControlType = 
  | 'select'
  | 'multi-select' 
  | 'radio'
  | 'inline-radio'
  | 'check'
  | 'inline-check';

type ControlType = 
  | 'boolean'
  | 'color'
  | 'date'
  | 'number'
  | 'range'
  | 'text'
  | 'object'
  | 'file'
  | 'select'
  | 'multi-select'
  | 'radio'
  | 'inline-radio'
  | 'check'
  | 'inline-check';

type Control = 
  | BooleanConfig
  | ColorConfig
  | DateConfig
  | NumberConfig
  | RangeConfig
  | TextConfig
  | ObjectConfig
  | FilesConfig
  | OptionsConfig;

type PropDescriptor = string | string[] | RegExp;

type SortType = 'alpha' | 'requiredFirst' | 'none';

interface Renderer {
  component?: React.ComponentType;
  [key: string]: any;
}

import { Controls, BooleanControl, ColorControl } from "@storybook/addon-docs/blocks";

// Automatic controls for all args
<Controls of={ButtonStories} />

// Filtered controls
<Controls 
  of={ButtonStories}
  include={['size', 'variant', 'disabled']}
  sort="alpha"
/>

// Individual controls
<BooleanControl 
  name="disabled"
  value={false}
  onChange={(value) => updateArgs({ disabled: value })}
/>

<ColorControl
  name="color"
  value="#007acc"
  config={{ presetColors: ['#007acc', '#ff6b6b'] }}
  onChange={(value) => updateArgs({ color: value })}
/>