/**
 * `<router-ui>` provider — declarative + imperative client-side
 * routing built on {@link RouteController} (re-declared here for
 * historical reasons; the canonical export lives in `core/controller.js`).
 *
 * Two consumer paths:
 *
 *  1. **Declarative** — assign `router.routes = [...]` and the provider
 *     instantiates its own controller, wires `popstate`, intercepts
 *     same-origin link clicks, fetches each matched route's `content`
 *     URL, and injects into the host element.
 *
 *  2. **Controller-driven** — construct a {@link RouteController}
 *     yourself + assign to `router.controller`. Useful when multiple
 *     UI surfaces need to share routing state.
 *
 * Side-effect: importing this module calls
 * `customElements.define('router-ui', UIRouter)`.
 *
 * Runtime exports mirror `core/provider.js`. `.d.ts` authored in v0.5.6
 * §191 to close the §178 audit-script baseline missing-sibling gap.
 *
 * @see ./provider.js (runtime SoT — also defines `customElements`)
 * @see ./controller.d.ts (canonical `RouteController` typing)
 */

import { UIElement } from './element.js';
import type { Route, RouteCommands, RouteState, ControllerSchema, RouteControllerOptions } from './controller.js';
import { BaseController } from './controller.js';

/**
 * Routing-state controller. Re-declared from `core/controller.js` for
 * historical compatibility — both files define the same class shape;
 * consumers can import either. New code should prefer
 * `import { RouteController } from '@adia-ai/web-components/core/controller'`
 * for the canonical path.
 */
export class RouteController extends BaseController {
  static schema: ControllerSchema;
  constructor(options?: RouteControllerOptions);
  getState(): RouteState;
  commands: RouteCommands;
}

/**
 * Optional async transform applied to fetched route content before
 * injection. Useful for wrapping content in a layout shell.
 */
export type TemplateResolver = (html: string, route: Route) => string | Promise<string>;

/**
 * `<router-ui>` custom element. Side-effect-registered on module load.
 */
export class UIRouter extends UIElement {
  /** Currently-bound controller (declarative-mode controller is auto-created). */
  controller?: RouteController;

  /** Optional template wrapper hook — see {@link TemplateResolver}. */
  templateResolver?: TemplateResolver;

  /**
   * Declarative-mode setter — assigning routes auto-creates an
   * internal {@link RouteController} on first assignment, or
   * `setRoutes`-replaces the table on subsequent ones.
   */
  set routes(list: ReadonlyArray<Route>);

  /** Shortcut for `controller.commands.navigate(path)`. */
  navigate(path: string): void;

  /** Shortcut for `controller.commands.replace(path)`. */
  replace(path: string): void;
}

/**
 * `router-ui` is registered as a side-effect of module load.
 */
declare global {
  interface HTMLElementTagNameMap {
    'router-ui': UIRouter;
  }
}
