asciitorium/dist/components/Button.d.ts

an ASCII CLUI framework

import { Component, ComponentProps } from '../core/Component.js';
/**
 * Configuration options for the Button component.
 *
 * Extends ComponentProps with button-specific properties like content and click handlers.
 */
export interface ButtonOptions extends Omit<ComponentProps, 'children'> {
    /** Text content to display on the button */
    content?: string;
    /** Callback function invoked when the button is clicked */
    onClick?: () => void;
    /** Child content (for JSX compatibility) */
    children?: string | string[];
}
/**
 * Interactive button component with visual feedback.
 *
 * Features:
 * - Press animation with shadow effects
 * - Focus indicators (> and < brackets)
 * - Keyboard activation (Enter or Space)
 * - Hotkey support with visual indicators
 * - Automatic sizing based on content
 *
 * The button uses a 3D shadow effect that shifts when pressed to provide
 * tactile feedback. Focus state is indicated by brackets around the content.
 *
 * @example
 * Basic button with click handler:
 * ```typescript
 * const button = new Button({
 *   content: 'Click Me',
 *   onClick: () => console.log('Clicked!'),
 *   width: 20,
 *   height: 4
 * });
 * ```
 *
 * @example
 * Button with hotkey:
 * ```typescript
 * const button = new Button({
 *   content: 'Save',
 *   hotkey: 's',
 *   onClick: () => saveFile()
 * });
 * ```
 *
 * @example
 * Using JSX:
 * ```tsx
 * <Button onClick={() => alert('Hello')}>
 *   Click Me
 * </Button>
 * ```
 */
export declare class Button extends Component {
    /** Public click handler that includes press animation */
    readonly onClick?: () => void;
    /** Private click handler from options */
    private privateOnClick?;
    /** Whether the button can receive focus */
    focusable: boolean;
    /** Whether the button currently has focus */
    hasFocus: boolean;
    /** Whether the button is currently in pressed state */
    private isPressed;
    /** Timer for press animation duration */
    private pressTimer?;
    /**
     * Creates a new Button instance.
     *
     * @param options - Button configuration options including content and click handler
     */
    constructor({ onClick, ...options }: ButtonOptions);
    /**
     * Triggers the press animation.
     *
     * Sets the button to pressed state for 100ms, shifting the shadow effect
     * to provide visual feedback. Automatically returns to normal state after the animation.
     *
     * @private
     */
    private press;
    /**
     * Handles keyboard events for the button.
     *
     * Activates the button when Enter or Space is pressed.
     *
     * @param event - The keyboard event string (e.g., 'Enter', ' ')
     * @returns `true` if the event was handled, `false` otherwise
     */
    handleEvent(event: string): boolean;
    /**
     * Renders the button to a 2D character buffer.
     *
     * Draws the button with:
     * - 3D shadow effect (position shifts based on press state)
     * - Border with rounded corners
     * - Centered text content
     * - Focus indicators (> and < brackets)
     * - Hotkey label (when hotkey visibility is enabled)
     *
     * @returns 2D array of characters representing the button
     */
    draw(): string[][];
}