/**
 * A code block component for displaying source code with syntax highlighting,
 * line numbers, and copy-to-clipboard functionality. Powered by Shiki.
 * @category Content
 * @useCases code display, code snippet, syntax highlighting, API response, terminal output
 * @keywords code, codeblock, syntax, highlight, copy, pre, snippet
 * @related UiKbd
 */
export interface UiCodeBlockProps {
  /**
   * The source code to display.
   */
  code: string;

  /**
   * The programming language for syntax highlighting.
   * Supports all languages available in Shiki (e.g., 'typescript', 'python', 'json', 'bash').
   * Use 'text' for plain text without highlighting.
   * @default 'text'
   */
  language?: string;

  /**
   * Optional filename to display in the header.
   * When provided, takes precedence over the language label.
   * @example 'app.config.ts'
   */
  filename?: string;

  /**
   * Whether to show line numbers alongside the code.
   * @default false
   */
  showLineNumbers?: boolean;

  /**
   * Whether to show the copy-to-clipboard button in the header.
   * @default true
   */
  showCopyButton?: boolean;

  /**
   * Maximum height of the code area before scrolling.
   * Accepts any valid CSS height value.
   * @example '300px'
   */
  maxHeight?: string;

  /**
   * Aria label for the copy button in its default state.
   * @default 'Copy code'
   */
  copyLabel?: string;

  /**
   * Aria label for the copy button after copying.
   * @default 'Copied'
   */
  copiedLabel?: string;
}
