/**
 * `<toc-ui>` — Auto-generated in-page table of contents. Scans a target container
for headings (default `h2,h3`), ensures each has an `id` (slugifies
the text content if missing), and stamps a `<nav>` list of anchor
links. An `IntersectionObserver` tracks the active heading and
applies `[data-active]` to the matching link so consumers can style
the currently-visible section. Smooth-scroll on click is handled by
the global `scroll-behavior: smooth` set in resets.css.

Pair with a sticky container (`position: sticky; top: <offset>;`) in
an aside / right rail for the classic docs-site outline pattern.

 *
 * @see https://ui-kit.exe.xyz/site/components/toc
 *
 * 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 TableOfContentsSectionChangeEventDetail {
  activeId: string;
}

export type TableOfContentsSectionChangeEvent = CustomEvent<TableOfContentsSectionChangeEventDetail>;

export class UITableOfContents extends UIElement {
  /** CSS selector listing the heading tags to include (e.g. `h2,h3`).
The selector is matched against the target container's
descendants. Default `h2,h3` produces the common two-level
outline.
 */
  headings: string;
  /** `aria-label` for the nav. Defaults to `Table of contents`.
 */
  label: string;
  /** Top offset in pixels for active-state detection. The
IntersectionObserver's `rootMargin` is set to
`-<offset>px 0px -50% 0px` so the active item becomes the
heading nearest the top of the viewport BELOW any sticky header
chrome. Tune to match the height of your sticky topbar (default
`80` is a reasonable docs-shell value).
 */
  offset: number;
  /** CSS selector pointing to the container to scan. Empty (default)
scans the toc-ui's parent element. Set to `#article` /
`[data-toc-target]` / `main` for a specific scope.
 */
  target: string;

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