/**
 * `<drawer-ui>` — Slide-out panel anchored to a viewport edge. Uses native <dialog> for focus trap, Escape dismiss, and ::backdrop. Panel is a flex column that scrolls as a whole — the header and footer stick to the top/bottom of the panel when the body overflows. Authors can compose content with either card-ui-style bare tags (<header>, <section>, <footer>) or explicit [slot="header|body|footer"] attributes; multiple <section> siblings are allowed and stack in author order between the sticky header and footer. The header activates a card-ui-aligned 3-column grid (icon | heading+description | action+close) when any direct [slot="icon|heading|description|action"] child is present.
 *
 * @see https://ui-kit.exe.xyz/site/components/drawer
 *
 * Type declarations generated by scripts/build/dts-codegen.mjs from
 * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
 * run `npm run build:components`, then `npm run codegen:dts` to
 * regenerate; or hand-author this file fully if rich event types are
 * needed beyond what the yaml `events:` block can express.
 */

import { UIElement } from '../../core/element.js';

export interface DrawerCloseEventDetail {
  /** `'escape'` (Escape key) / `'backdrop'` (backdrop click) / `'close-button'` ([slot="close"] button click) / `'programmatic'` (consumer set `.open = false` from JS). Defaults to `'programmatic'` when no event-driven path captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2. */
  reason: 'escape' | 'backdrop' | 'close-button' | 'programmatic';
}

export type DrawerCloseEvent = CustomEvent<DrawerCloseEventDetail>;
export type DrawerOpenedEvent = CustomEvent<unknown>;

export class UIDrawer extends UIElement {
  /** Controls visibility. When false, backdrop and panel are removed from DOM. */
  open: boolean;
  /** When true, hide close button and suppress backdrop/Escape dismiss */
  permanent: boolean;
  /** Anchor side */
  side: 'left' | 'right' | 'top' | 'bottom';
  /** Panel width/height */
  size: 'sm' | 'md' | 'lg';
  /** Title text displayed in the drawer header */
  text: string;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UIDrawer, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'close', listener: (ev: DrawerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'opened', listener: (ev: DrawerOpenedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
