import { A11yNode, A11ySemanticKind } from './a11y-tree.types';
/**
 * Semantic DTO layer for the A11y Tree.
 *
 * Authoring an A11y Tree with raw `A11yNode` literals asks the developer to
 * think in ARIA terms (`role: 'group'`, `decorative: true`, etc.). The DTO
 * classes here provide a higher-level vocabulary that names the *content's
 * meaning* — "this is a container", "this is a heading", "this is a
 * decorative icon" — and lets the strategy layer translate intent into ARIA.
 *
 * ## Design (Visitor / Strategy + typed semantic DTOs)
 *
 * - DTOs are *type-holders for semantic intent*. They do NOT contain ARIA
 *   generation logic themselves.
 * - Each DTO compiles to an `A11yNode` whose `kind` field carries the
 *   semantic discriminator. Strategies can then dispatch on `kind`
 *   (preferred) or fall back to `role` (for plain `A11yNode` authors).
 * - This keeps strategies pure and independently testable, while letting
 *   authors write:
 *
 *   ```ts
 *   new A11yContainerNode('st-root', { label, description })
 *     .childrenWith(
 *       new A11yHeadingNode('st-heading', { level: 2, label }),
 *       new A11yIconNode('st-icon'),
 *     );
 *   ```
 *
 *   instead of hand-shaping `{ role: 'group', label, description, … }`.
 *
 * ## Migration path
 *
 * Phase 1 (this file): DTOs are an additive layer on top of `A11yNode`.
 * Existing strategies continue to work unchanged because each DTO emits
 * a fully-populated `A11yNode` with `role` set correctly.
 *
 * Phase 2 (follow-up): strategies grow `compileNode(node)` methods that
 * dispatch on `node.kind` for cases where semantic intent is richer than
 * `role` alone can express.
 */
/**
 * Base class for all semantic DTO nodes. Provides the `childrenWith()`
 * composition helper and the abstract `toA11yNode()` contract.
 */
export declare abstract class A11yNodeDto {
  protected childDtos: A11yNodeDto[];
  abstract readonly kind: A11ySemanticKind;
  /**
   * Declare the semantic children of this node in reading order.
   *
   * @param {...A11yNodeDto} children - Semantic child DTOs in reading order.
   * @returns {this} `this`, for fluent chaining.
   */
  childrenWith(...children: A11yNodeDto[]): this;
  /**
   * Compile the declared child DTOs into their `A11yNode` representations.
   *
   * @returns {A11yNode[] | undefined} The compiled children, or `undefined` when none.
   */
  protected compileChildren(): A11yNode[] | undefined;
  /** Compile this DTO (and its subtree) into an `A11yNode`. */
  abstract toA11yNode(): A11yNode;
}
/**
 * A generic container that groups related content. Maps to `role="group"`
 * by default; strategies may upgrade to `role="region"` when a description
 * is present and the platform benefits (e.g. Firefox+NVDA landmark
 * navigation — see `firefox-nvda-strategy.ts`).
 */
export declare class A11yContainerNode extends A11yNodeDto {
  readonly id: string;
  readonly opts: {
    label?: string;
    description?: string;
  };
  readonly kind: A11ySemanticKind;
  constructor(id: string, opts?: {
    label?: string;
    description?: string;
  });
  /**
   * Compile this DTO into its `A11yNode` representation.
   *
   * @returns {A11yNode} The compiled semantic node.
   */
  toA11yNode(): A11yNode;
}
/**
 * A navigable / discoverable section (landmark). Always renders as
 * `role="region"` so it appears in AT landmark navigation.
 */
export declare class A11yLandmarkNode extends A11yNodeDto {
  readonly id: string;
  readonly opts: {
    label?: string;
    description?: string;
  };
  readonly kind: A11ySemanticKind;
  constructor(id: string, opts?: {
    label?: string;
    description?: string;
  });
  /**
   * Compile this DTO into its `A11yNode` representation.
   *
   * @returns {A11yNode} The compiled semantic node.
   */
  toA11yNode(): A11yNode;
}
/**
 * A heading at the given level (1–6, defaults to 2).
 *
 * Use this instead of a raw `{ role: 'heading', level: 2 }` literal to
 * benefit from the default-level guard and the `kind` discriminator.
 */
export declare class A11yHeadingNode extends A11yNodeDto {
  readonly id: string;
  readonly opts: {
    level?: 1 | 2 | 3 | 4 | 5 | 6;
    label?: string;
  };
  readonly kind: A11ySemanticKind;
  constructor(id: string, opts?: {
    level?: 1 | 2 | 3 | 4 | 5 | 6;
    label?: string;
  });
  /**
   * Compile this DTO into its `A11yNode` representation.
   *
   * @returns {A11yNode} The compiled semantic node.
   */
  toA11yNode(): A11yNode;
}
/**
 * A purely decorative icon. `decorative` is always `true` so authors never
 * have to remember the flag — that is the whole point of this DTO class.
 *
 * Produces `aria-hidden="true"` via the baseline strategy; webkit-voiceover
 * additionally sets `role="none"` as a belt-and-suspenders guard.
 */
export declare class A11yIconNode extends A11yNodeDto {
  readonly id: string;
  readonly kind: A11ySemanticKind;
  constructor(id: string);
  /**
   * Compile this DTO into its `A11yNode` representation.
   *
   * @returns {A11yNode} The compiled semantic node.
   */
  toA11yNode(): A11yNode;
}
/**
 * An informative image that requires an accessible label (alt text).
 *
 * Produces `role="img"` + `aria-label` via the baseline strategy.
 * Contrast with `A11yIconNode` which is always decorative.
 */
export declare class A11yImageNode extends A11yNodeDto {
  readonly id: string;
  readonly opts: {
    label: string;
  };
  readonly kind: A11ySemanticKind;
  constructor(id: string, opts: {
    label: string;
  });
  /**
   * Compile this DTO into its `A11yNode` representation.
   *
   * @returns {A11yNode} The compiled semantic node.
   */
  toA11yNode(): A11yNode;
}