/**
 * `<list-ui>` — Styled flat list with optional row dividers and icons — each row
is a <list-item-ui> child. Selectable mode via [selectable] +
[selectedKey] / `select` event. Composes <icon-ui> for row leading
glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
(tabular data with columns). Use list-ui for non-navigable,
non-tabular vertical rows — comment lists, file lists, message
streams outside chat-shell.

 *
 * @see https://ui-kit.exe.xyz/site/components/list
 *
 * 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 ListSelectionChangeEventDetail {
  /** New selection key. */
  key: string;
  /** Previously selected key. */
  previousKey: string;
}

export type ListSelectionChangeEvent = CustomEvent<ListSelectionChangeEventDetail>;

export class UIList extends UIElement {
  /** Add inline padding to list items so content aligns with surrounding
card/section insets. Pairs with [divider] — combining `[divider]
[contained]` gives full-width borders between items but inset
content. Without contained, [divider] items have `padding-inline: 0`
so content sits at the list-ui edges (canonical edge-to-edge style).
 */
  contained: boolean;
  /** Show dividers between items */
  divider: boolean;
  /** Enable selection on child listitems (roving tabindex + aria-selected). */
  selectable: boolean;
  /** ID (or data-key) of the currently-selected child listitem. */
  selectedKey: string;
  /** Item spacing */
  spacing: string;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UIList, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}

export class UIListItem extends UIElement {
  /** Secondary line below the primary text. Subtle color. */
  description: string;
  /** Optional leading icon name (Phosphor). */
  icon: string;
  /** Primary text. Renders as semibold inline body. */
  text: string;
}
