/**
 * `<table-ui>` — Data table with sorting, selection, pagination, search, column resize, keyboard nav, cell types, and CSV export. CSS grid + ARIA grid roles.
 *
 * @see https://ui-kit.exe.xyz/site/components/table
 *
 * 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 TableCellClickEventDetail {
  /** Row index in the underlying data array. */
  dataIndex: number;
  /** Column key. */
  key: string;
  /** Row data object. */
  row: Record<string, unknown>;
  /** Cell value (type depends on column). */
  value: string;
}

export type TableCellClickEvent = CustomEvent<TableCellClickEventDetail>;
export interface TableFilterChangeEventDetail {
  /** Map of `{ [columnKey]: filterValue }` reflecting active filters. */
  filters: Record<string, unknown>;
}

export type TableFilterChangeEvent = CustomEvent<TableFilterChangeEventDetail>;
export interface TablePageEventDetail {
  /** New active page index (1-based). */
  page: number;
}

export type TablePageEvent = CustomEvent<TablePageEventDetail>;
export interface TableResizeEventDetail {
  /** Column key being resized. */
  key: string;
  /** New column width in pixels. */
  width: number;
}

export type TableResizeEvent = CustomEvent<TableResizeEventDetail>;
export interface TableRowClickEventDetail {
  /** Row index in the underlying data array. */
  dataIndex: number;
  /** Row data object. */
  row: Record<string, unknown>;
}

export type TableRowClickEvent = CustomEvent<TableRowClickEventDetail>;
export interface TableRowCollapseEventDetail {
  /** Row index in the underlying data array. */
  index: number;
  /** Row data object. */
  row: Record<string, unknown>;
}

export type TableRowCollapseEvent = CustomEvent<TableRowCollapseEventDetail>;
export interface TableRowExpandEventDetail {
  /** Row index in the underlying data array. */
  index: number;
  /** Row data object. */
  row: Record<string, unknown>;
}

export type TableRowExpandEvent = CustomEvent<TableRowExpandEventDetail>;
export interface TableSelectEventDetail {
  /** Array of selected row indices or IDs (driven by [select-mode]). */
  selected: unknown[];
}

export type TableSelectEvent = CustomEvent<TableSelectEventDetail>;
export interface TableSortEventDetail {
  /** Sort direction — "asc" / "desc" / null (cleared). The detail field is `dir` (not `direction`). */
  dir: string;
  /** Column key being sorted — the detail field is `key` (not `column`). */
  key: string;
  /** Full sort state array (multi-column support). */
  sortState: unknown[];
}

export type TableSortEvent = CustomEvent<TableSortEventDetail>;

export class UITable extends UIElement {
  /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children. */
  columns: string;
  /** Row records. Array of plain objects keyed to columns[].key. */
  data: string;
  /** Controls cell padding and row height. 'compact' for dense data, 'standard' for default spacing, 'comfortable' for spacious rows. */
  density: 'compact' | 'standard' | 'comfortable';
  /** Enable row expansion */
  expandable: boolean;
  /** Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy="true" on the host. Data updates are deferred until loading is set back to false. */
  loading: boolean;
  /** Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar below the table. */
  paginate: number;
  /** Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom "No data" overlay. v0.6.33+ matches the documented contract. */
  raw: boolean;
  /** Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Resets to page 1 on change. */
  search: string;
  /** Show checkbox column for row selection. Select-all checkbox in header. Shift+click for range select. */
  selectable: boolean;
  /** Enable click-to-sort on column headers. Supports multi-sort via Shift+click. */
  sortable: boolean;
  /** Alternate row background colors for visual scanning. */
  striped: boolean;
  /** Allow body-cell content to wrap onto multiple lines. Default is single-line with ellipsis truncation (matches the row convention shared by <select-ui> + <nav-item-ui>); long unbreakable strings clip gracefully rather than rewrapping the row. With [wrap], row height auto-grows to fit wrapped content. For surgical opt-in on a single column, set [data-wrap] on the cell / col-def instead. */
  wrap: boolean;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UITable, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'cell-click', listener: (ev: TableCellClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'resize', listener: (ev: TableResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'row-click', listener: (ev: TableRowClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'row-collapse', listener: (ev: TableRowCollapseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'sort', listener: (ev: TableSortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
