Buttons & Actions

/**
 * Primary button component for user actions and form submissions
 * @param props - Button styling, content, and interaction properties
 * @returns JSX element as an interactive button
 */
function Button(props: SpectrumButtonProps): JSX.Element;

interface SpectrumButtonProps extends DOMProps, StyleProps {
  /** Button content (text, icons, or elements) */
  children: React.ReactNode;
  /** Visual style variant */
  variant?: "accent" | "primary" | "secondary" | "negative";
  /** Fill style treatment */
  style?: "fill" | "outline";
  /** Static color scheme for specific backgrounds */
  staticColor?: "white" | "black";
  /** Size of the button */
  size?: "S" | "M" | "L" | "XL";
  /** Whether the button is disabled */
  isDisabled?: boolean;
  /** Whether the button should take full width */
  isQuiet?: boolean;
  /** Auto-focus the button on mount */
  autoFocus?: boolean;
  /** Button type for forms */
  type?: "button" | "submit" | "reset";
  /** Press event handler */
  onPress?: (e: PressEvent) => void;
  /** Press start event handler */
  onPressStart?: (e: PressEvent) => void;
  /** Press end event handler */
  onPressEnd?: (e: PressEvent) => void;
  /** Press change event handler */
  onPressChange?: (isPressed: boolean) => void;
  /** Press up event handler */
  onPressUp?: (e: PressEvent) => void;
  /** Focus event handler */
  onFocus?: (e: FocusEvent) => void;
  /** Blur event handler */
  onBlur?: (e: FocusEvent) => void;
  /** Focus change event handler */
  onFocusChange?: (isFocused: boolean) => void;
  /** Keyboard event handler */
  onKeyDown?: (e: KeyboardEvent) => void;
  /** Keyboard event handler */
  onKeyUp?: (e: KeyboardEvent) => void;
}

// Basic buttons with variants
<Button variant="accent" onPress={() => console.log('Save clicked')}>
  Save Changes
</Button>

<Button variant="secondary" onPress={handleCancel}>
  Cancel
</Button>

// Button with icon and different sizes
<Button variant="primary" size="L">
  <Icon size="M" src={SaveIcon} />
  <Text>Save Document</Text>
</Button>

// Disabled and quiet buttons
<Button isDisabled>Disabled Button</Button>
<Button isQuiet>Quiet Button</Button>

/**
 * Secondary button for toolbar actions and non-primary operations
 * @param props - ActionButton styling and interaction properties
 * @returns JSX element as toolbar action button
 */
function ActionButton(props: SpectrumActionButtonProps): JSX.Element;

interface SpectrumActionButtonProps extends DOMProps, StyleProps {
  /** Button content */
  children: React.ReactNode;
  /** Static color scheme */
  staticColor?: "white" | "black";
  /** Size of the button */
  size?: "S" | "M" | "L" | "XL";
  /** Whether the button is disabled */
  isDisabled?: boolean;
  /** Whether the button should be quiet styled */
  isQuiet?: boolean;
  /** Whether the button is selected (pressed state) */
  isSelected?: boolean;
  /** Auto-focus the button on mount */
  autoFocus?: boolean;
  /** Press event handler */
  onPress?: (e: PressEvent) => void;
  /** Press change event handler */
  onPressChange?: (isPressed: boolean) => void;
  /** Focus change event handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Button that maintains selected/unselected state for toggle operations
 * @param props - ToggleButton state and interaction properties
 * @returns JSX element as a stateful toggle button
 */
function ToggleButton(props: SpectrumToggleButtonProps): JSX.Element;

interface SpectrumToggleButtonProps extends DOMProps, StyleProps {
  /** Button content */
  children: React.ReactNode;
  /** Whether the button is currently selected */
  isSelected?: boolean;
  /** Default selected state (uncontrolled) */
  defaultSelected?: boolean;
  /** Size of the button */
  size?: "S" | "M" | "L" | "XL";
  /** Whether the button is disabled */
  isDisabled?: boolean;
  /** Whether the button should be quiet styled */
  isQuiet?: boolean;
  /** Auto-focus the button on mount */
  autoFocus?: boolean;
  /** Selection change event handler */
  onChange?: (isSelected: boolean) => void;
  /** Press event handler */
  onPress?: (e: PressEvent) => void;
  /** Focus change event handler */
  onFocusChange?: (isFocused: boolean) => void;
}

/**
 * Button component for boolean logic operations and conditional workflows
 * @param props - LogicButton configuration and interaction properties
 * @returns JSX element as a logic operation button
 */
function LogicButton(props: SpectrumLogicButtonProps): JSX.Element;

interface SpectrumLogicButtonProps extends DOMProps, StyleProps {
  /** Button content */
  children: React.ReactNode;
  /** Logic variant type */
  variant?: "and" | "or" | "not";
  /** Size of the button */
  size?: "S" | "M" | "L" | "XL";
  /** Whether the button is disabled */
  isDisabled?: boolean;
  /** Press event handler */
  onPress?: (e: PressEvent) => void;
}

/**
 * Container for grouping related buttons with consistent styling
 * @param props - ButtonGroup layout and styling properties
 * @returns JSX element containing grouped buttons
 */
function ButtonGroup(props: SpectrumButtonGroupProps): JSX.Element;

interface SpectrumButtonGroupProps extends DOMProps, StyleProps {
  /** Button elements to group */
  children: React.ReactNode;
  /** Orientation of the button group */
  orientation?: "horizontal" | "vertical";
  /** Alignment of buttons within the group */
  align?: "start" | "center" | "end";
  /** Size applied to all buttons in the group */
  size?: "S" | "M" | "L" | "XL";
  /** Whether all buttons should be disabled */
  isDisabled?: boolean;
}

// Horizontal button group for form actions
<ButtonGroup orientation="horizontal" align="end">
  <Button variant="secondary">Cancel</Button>
  <Button variant="accent">Save</Button>
</ButtonGroup>

// Vertical button group for sidebar actions
<ButtonGroup orientation="vertical" size="M">
  <ActionButton>
    <Icon src={EditIcon} />
    <Text>Edit</Text>
  </ActionButton>
  <ActionButton>
    <Icon src={DeleteIcon} />
    <Text>Delete</Text>
  </ActionButton>
</ButtonGroup>

/**
 * Group of action buttons with selection capabilities
 * @param props - ActionGroup configuration and selection properties
 * @returns JSX element containing selectable action buttons
 */
function ActionGroup<T>(props: SpectrumActionGroupProps<T>): JSX.Element;

interface SpectrumActionGroupProps<T> extends DOMProps, StyleProps {
  /** Action items to render */
  items?: Iterable<T>;
  /** Child elements (Item components) */
  children: React.ReactElement<ItemProps<T>>[];
  /** Selection mode */
  selectionMode?: SelectionMode;
  /** Disallow empty selection */
  disallowEmptySelection?: boolean;
  /** Currently selected keys */
  selectedKeys?: Selection;
  /** Default selected keys (uncontrolled) */
  defaultSelectedKeys?: Selection;
  /** Orientation of the group */
  orientation?: "horizontal" | "vertical";
  /** Size of action buttons */
  size?: "S" | "M" | "L" | "XL";
  /** Whether buttons should be quiet styled */
  isQuiet?: boolean;
  /** Whether the group is disabled */
  isDisabled?: boolean;
  /** Static color scheme */
  staticColor?: "white" | "black";
  /** Selection change event handler */
  onSelectionChange?: (keys: Selection) => void;
  /** Action event handler for individual items */
  onAction?: (key: Key) => void;
  /** Focus change event handler */
  onFocusChange?: (isFocused: boolean) => void;
}

// Toolbar with single selection
<ActionGroup 
  selectionMode="single" 
  selectedKeys={[currentTool]}
  onSelectionChange={setCurrentTool}
>
  <Item key="select">
    <Icon src={SelectIcon} />
    <Text>Select</Text>
  </Item>
  <Item key="pen">
    <Icon src={PenIcon} />  
    <Text>Pen</Text>
  </Item>
  <Item key="brush">
    <Icon src={BrushIcon} />
    <Text>Brush</Text>
  </Item>
</ActionGroup>

// View options with multiple selection
<ActionGroup 
  selectionMode="multiple"
  selectedKeys={viewOptions}
  onSelectionChange={setViewOptions} 
>
  <Item key="grid">Grid View</Item>
  <Item key="details">Show Details</Item>
  <Item key="preview">Show Preview</Item>
</ActionGroup>

/**
 * Contextual toolbar that appears when items are selected
 * @param props - ActionBar configuration and content properties
 * @returns JSX element as contextual action toolbar
 */
function ActionBar(props: SpectrumActionBarProps): JSX.Element;

interface SpectrumActionBarProps extends DOMProps, StyleProps {
  /** Action buttons and content */
  children: React.ReactNode;
  /** Whether the action bar is currently visible */
  isOpen?: boolean;
  /** Selection count message */
  selectedItemCount?: number | "all";
  /** Clear selection action handler */
  onClearSelection?: () => void;
  /** Action event handler */
  onAction?: (key: Key) => void;
}

/**
 * Container that manages ActionBar positioning and visibility
 * @param props - ActionBarContainer layout and behavior properties
 * @returns JSX element containing action bar and target content
 */
function ActionBarContainer(props: SpectrumActionBarContainerProps): JSX.Element;

interface SpectrumActionBarContainerProps extends DOMProps, StyleProps {
  /** Content that can trigger action bar appearance */
  children: React.ReactNode;
  /** Maximum height before scrolling */
  maxHeight?: DimensionValue;
}

// Action bar for selected table rows
function DataTable() {
  const [selectedKeys, setSelectedKeys] = useState(new Set());
  
  return (
    <ActionBarContainer>
      <TableView 
        selectedKeys={selectedKeys}
        onSelectionChange={setSelectedKeys}
      >
        {/* table content */}
      </TableView>
      
      <ActionBar 
        isOpen={selectedKeys.size > 0}
        selectedItemCount={selectedKeys.size}
        onClearSelection={() => setSelectedKeys(new Set())}
      >
        <Item key="delete" textValue="Delete">
          <Icon src={DeleteIcon} />
          <Text>Delete</Text>
        </Item>
        <Item key="share" textValue="Share">
          <Icon src={ShareIcon} />
          <Text>Share</Text>
        </Item>
      </ActionBar>
    </ActionBarContainer>
  );
}

/** Press event information */
interface PressEvent {
  /** Event type */
  type: "press";
  /** Target element */
  target: Element;
  /** Input method used for the press */
  pointerType: PointerType;
  /** Whether Alt key was pressed */
  altKey: boolean;
  /** Whether Ctrl key was pressed */
  ctrlKey: boolean;
  /** Whether Meta key was pressed */
  metaKey: boolean;
  /** Whether Shift key was pressed */
  shiftKey: boolean;
  /** Prevent default behavior */
  preventDefault(): void;
  /** Continue propagation */
  continuePropagation(): void;
}

/** Input method types */
type PointerType = "mouse" | "pen" | "touch" | "keyboard" | "virtual";

/** Focus event information */
interface FocusEvent {
  /** Event type */
  type: "focus" | "blur";
  /** Target element */
  target: Element;
  /** Related target element */
  relatedTarget: Element | null;
}

/** Collection item key type */
type Key = string | number;

/** Selection state type */
type Selection = "all" | Set<Key>;

/** Selection behavior modes */
type SelectionMode = "none" | "single" | "multiple";

/** Collection item properties */
interface ItemProps<T = any> {
  /** Unique key for the item */
  key?: Key;
  /** Text value for accessibility and filtering */
  textValue?: string;
  /** Item content */
  children: React.ReactNode;
  /** Whether the item is disabled */
  isDisabled?: boolean;
}