import type { MdyStateName } from "../state.js";
import type { MdyWidgetSemanticElement } from "../structure.js";
import type { MdyWidgetDefinition, MdyWidgetKind, MdyWidgetVariant } from "./kinds.js";
/**
 * Carried by every `popup` part, whatever widget owns it.
 *
 * An overlay must never take part in layout: a popup left in flow resizes its field and pushes the
 * rest of the form down the page the moment it opens. Naming the guarantee in the contract — rather
 * than leaving each renderer and each theme to arrange it — is what makes it hold everywhere.
 */
export declare const MDY_POPUP_CLASS = "mdy-popup";
/**
 * The popup's *appearance*, carried separately from the popup itself.
 *
 * {@link MDY_POPUP_CLASS} says where a popup is and that it is out of flow. This says what it looks
 * like — a surface, an edge, a radius, an elevation, the room its content sits in — and the two are
 * separate because they are separate questions with different owners.
 *
 * They were one class, and a container that paints is a wrapper around the thing it was supposed to
 * present: a material applied to the content then sits on an opaque panel rather than on the page,
 * which is a translucent effect with nothing to be translucent against. A theme dressing the popup
 * had no way to decline the surface without also fighting the positioning that shares its selector.
 *
 * Every popup carries it, so nothing changes by not asking. A theme that wants the content to
 * present itself neutralises this one class and leaves the coordinates alone.
 */
export declare const MDY_POPUP_SURFACE_CLASS = "mdy-popup--surface";
/**
 * Where each part hangs. Candidates are tried in order and the first one the widget actually
 * declares wins, so the same table serves a control with an input wrapper and one without.
 * The anatomy is nested rather than flat because containment is part of what an adapter must
 * reproduce: a control outside its wrapper is a different control.
 */
export declare const PARENT_CANDIDATES: Readonly<Record<string, readonly string[]>>;
/**
 * The class a shell part carries when its widget does not override it.
 *
 * `MDY_FIELD_SHELL_CLASSES` declared this vocabulary from the start and nothing checked it: every
 * shell part came out of `define()` with an empty class list, so `mdy-label` could be renamed to
 * anything and the conformance suite agreed. Declaring it here is what gives the existing
 * `PART_CLASS_MISSING` rule something to enforce.
 *
 * `control` is deliberately absent. The shell maps it to `mdy-input-wrapper__inliner`, which is the
 * box *around* the control rather than the control itself — requiring it of the `control` part would
 * assert something no renderer means.
 */
export declare const SHELL_CLASS_FALLBACK: Readonly<Record<string, readonly string[]>>;
/** Per-widget deviations from the shared tables: where a part hangs, and the class it carries. */
interface MdyWidgetShape<TPart extends string = string> {
    /** The native control this kind is rendered with — see {@link MdyWidgetDefinition.controlType}. */
    readonly controlType?: string;
    /** Whether the control conceals what is typed into it — see {@link MdyWidgetDefinition.concealed}. */
    readonly concealed?: boolean;
    readonly parents?: Readonly<Partial<Record<TPart, TPart>>>;
    readonly classes?: Readonly<Partial<Record<TPart, readonly string[]>>>;
    /**
     * The ARIA role a part must carry, where the contract requires one.
     *
     * Distinct from `element`, which says what a part may *be*: `SEMANTIC_ELEMENTS` lists the roles a
     * semantic admits, and this names the one it has to have. Without it the contract could say a part
     * may be a listbox and never say that it is one.
     */
    readonly roles?: Readonly<Record<string, string>>;
    /** States this widget's parts may be in, over and above {@link SHARED_STATES}. */
    readonly states?: Readonly<Record<string, readonly MdyStateName[]>>;
    /**
     * Semantic element overrides. A boolean control wraps its text in the `<label>` itself, so the
     * `label` *part* there is the text inside it — declaring it a `<label>` would ask a renderer for
     * a label inside a label, which is not valid HTML and not what any of them emit.
     */
    readonly elements?: Readonly<Partial<Record<TPart, MdyWidgetSemanticElement>>>;
    /**
     * Classes a renderer of this kind may carry that are not parts.
     *
     * Structure the themes style and the contract does not otherwise constrain: a spacer, a header
     * label, a variant marker. They are declared because a theme has to be able to enumerate what it
     * may target and a renderer has to know what it may emit — and deliberately not as parts. A part
     * has anatomy: an element, a parent, an order, a place in every relation and state check.
     * Claiming that for a visual container would freeze the DOM well past what has to be shared,
     * which is the one thing this contract sets out not to do.
     */
    readonly presentation?: readonly string[];
    /**
     * Anatomy that depends on how the kind is configured, keyed by the value that decides it.
     *
     * One kind whose parts genuinely differ between configurations, rather than two kinds or a part
     * left unconstrained because no single answer fits. `multiselect` is the case: a toggle option
     * *is* the control and a counter option *contains* two, so naming one element for both would be
     * naming the wrong one half the time — and naming neither is what left the kind uncheckable.
     *
     * The key is the value the public config already carries, never a vocabulary invented here. A
     * variant that has to teach a consumer a new word is a variant that belongs in the config first.
     *
     * What a variant may say is deliberately small: which elements its parts are, what they announce
     * as, and which of them it requires. Anything wider — different parents, different relations —
     * would be a second catalogue rather than a qualification of this one.
     *
     * `roles` is here for the same reason `elements` is, and arrived when a counter chip needed to be
     * a `spinbutton` while a toggle chip stays a `group`: both statements answer *what this part is*,
     * and both genuinely differ between two modes of one widget. Declaring the stronger role for both
     * would promise a value to spin on a chip that holds membership.
     */
    readonly variants?: Readonly<Partial<Record<MdyWidgetVariant, {
        readonly elements?: Readonly<Partial<Record<TPart, MdyWidgetSemanticElement>>>;
        readonly roles?: Readonly<Partial<Record<TPart, string>>>;
        readonly required?: readonly TPart[];
    }>>>;
    /**
     * Parts this kind must render at rest, over and above the ones every field has.
     *
     * `REQUIRED_PARTS` names the eight parts that are mandatory whatever the widget is — the control
     * and whatever holds it. Everything else was optional by default, which is not the same as a
     * decision that it may be absent: it meant no renderer could be caught omitting a checkbox's
     * indicator or a select's arrow, because the contract had never been asked.
     *
     * What goes here is measured, not assumed: a part all three renderers emit in the resting state.
     * A part some of them omit stays optional, and the reason belongs next to it.
     *
     * A part that only exists inside an overlay is required **of an open widget**: a closed picker
     * renders no popup, so nothing inside one can be demanded at rest. `overlayOnlyParts` decides
     * which those are, so naming one here is a statement about what an open popup must frame.
     */
    readonly required?: readonly TPart[];
}
/**
 * States every field-like widget's shell parts share.
 *
 * Declared in `structure.ts` beside the shell's classes, because the two answer one question — what
 * a shell part is called and what it may be doing — and `MDY_FIELD_STATE_CLASSES` is derived from
 * both. Kept re-bound here under its old name so the catalogue reads as it always has.
 */
export declare const SHARED_STATES: Readonly<Record<string, readonly ("above" | "active" | "animated" | "compact" | "confirm" | "disabled" | "dragging" | "dragover" | "error" | "filled" | "focused" | "ghost" | "hasError" | "hidden" | "horizontal" | "inRange" | "inner" | "invalid" | "loading" | "open" | "outside" | "overlay" | "rangeEnd" | "rangeStart" | "readonly" | "removable" | "right" | "selected" | "today" | "touched" | "unwritten")[]>>;
/**
 * Where the popup ended up, reflected onto the popup itself.
 *
 * `anchorOverlay` already decides this and writes the coordinates; the class is how a theme reacts
 * to the decision — an arrow that points down when the popup sits above, a shadow that lifts the
 * other way. Every popup declares the same two because it is the same decision for all of them:
 * "below" is the ordinary case and needs no class.
 */
export declare const POPUP_PLACEMENT_STATES: readonly MdyStateName[];
/**
 * Everything a day in a calendar can be at once.
 *
 * A single cell is routinely several of these together — today, selected, and the start of a range —
 * which is why they are states rather than variants: they compose, and a theme paints each one
 * without knowing which others are on. Shared by the datepicker and the range picker, because a day
 * does not mean something different depending on how many dates the field collects.
 */
export declare const CALENDAR_CELL_STATES: readonly MdyStateName[];
/**
 * A month or a year in the views that replace the day grid.
 *
 * One state, because one is what a theme paints. Nothing here is "today" or "outside" — a month
 * picker shows exactly one year's twelve — and a period the bounds refuse carries the native
 * `disabled`, which every theme already styles through `:disabled`. A class declared and painted
 * nowhere is a promise to a theme author that nothing keeps.
 */
export declare const CALENDAR_PERIOD_CELL_STATES: readonly MdyStateName[];
/**
 * The part that opens each overlay, and therefore the part that must carry `aria-controls` naming
 * the popup and `aria-expanded` saying whether it is showing.
 *
 * Select and multiselect had this relation uniformly; the pickers and the colour field did not —
 * some popups had no id an `aria-controls` could name, and in the timepicker the element that opens
 * the dialog is a different element from the input under test. Declaring the opener is what turns
 * "some element around here has aria-controls" into a contract an adapter can be held to.
 *
 * `file` is absent deliberately: the browser owns its picker, so there is no overlay the contract
 * can observe and nothing to relate.
 */
export interface MdyPopupOpener {
    /** The part the user operates to open the overlay, and the one that must carry the relation. */
    readonly opener: string;
    /**
     * A second part a pointer opens the same overlay from, where the kind has one.
     *
     * The calendar button beside a typeable date, the clock beside a typed time, the box a
     * multiselect's chips sit in, the swatch beside a colour. All three renderers answer a press on
     * these and none was asked to: the door worked everywhere, nothing declared it, and a renderer
     * could have lost it with every suite green.
     *
     * It carries no relation. `aria-expanded` and `aria-controls` belong to the part that *holds the
     * value* — one control says whether the overlay is showing, and a second element claiming it
     * announces two comboboxes for one list. This says a pointer may open from here, which is what a
     * check needs to press and what a renderer needs to know it owes. ADR 0177.
     */
    readonly alsoOpensFrom?: string;
    /** The part the relation names — the element carrying the overlay's role. */
    readonly controls: string;
    /**
     * The role the opener takes, where the pattern requires one.
     *
     * A typeable control that also opens a list is a combobox, and `aria-expanded` and
     * `aria-controls` are only allowed on it once it says so. An opener that is already a button
     * needs no role and declares none.
     */
    readonly role?: string;
    /**
     * Whether the opener is a control the user types into.
     *
     * `opener` names the element that carries the overlay relation, and for the combobox kinds that is
     * correctly the typeable control — the pattern puts `aria-expanded` nowhere else. But the same
     * declaration was being read as "the element that toggles the overlay", and those are not the same
     * element's job: a pointer landing in a text field is the user reaching for the caret, not for a
     * switch, and a press of the space bar there is a space character.
     *
     * Saying so once here is what keeps the relation on the element the pattern requires while the
     * behaviour follows what the element actually is.
     */
    readonly typeable?: boolean;
    /**
     * What the opener promises will appear, as `aria-haspopup` states it.
     *
     * A screen reader announces this with the control — "combobox, has popup listbox" — so a person
     * decides whether to open the thing from what they were told it is. The words are not
     * interchangeable: `listbox` means options with a selected state and a listbox's keyboard, `grid`
     * means a table walked with the arrow keys, `dialog` means somewhere to go and come back from. A
     * promise the popup does not keep is worse than none, because it is acted on.
     *
     * Declared here because the promise and the thing promised must have one source. Written as a
     * literal at each opener it was written five times across two renderers, and two of them said
     * different words for the same widget.
     *
     * Each value is read off the anatomy the same catalogue declares: the kind whose popup frames a
     * part with `role=listbox` promises `listbox`, the ones framing a `grid` promise `grid`, and a
     * popup holding a composite — a search field beside a chooser, a clock face — is a `dialog`.
     */
    readonly promises?: "listbox" | "grid" | "dialog" | "menu" | "tree";
    /**
     * The shape of the kind this relation belongs to, where the kind has more than one.
     *
     * A select drawn as the platform's own chooser opens nothing this contract can see: a `<select>`
     * carrying `aria-expanded`, `aria-controls` or `aria-haspopup` is claiming to be a combobox, which
     * is a lie about what it is and what a reader will find. The relation is the combobox's.
     *
     * Absent means the relation holds for every shape the kind has, which is every other kind here.
     * ADR 0176 records the decision and named this as the half nothing enforced; this is the
     * declaration a checker reads to enforce it.
     */
    readonly variant?: MdyWidgetVariant;
}
export declare const MDY_POPUP_OPENERS: Readonly<Partial<Record<MdyWidgetKind, MdyPopupOpener>>>;
/**
 * `NoInfer` on the shape, and it is load-bearing rather than tidy.
 *
 * The part names come from `partNames` and nowhere else. Without this the shape is a second
 * inference site, so a part named only there — a typo, a rename half-applied — widens `TPart` to
 * include it and compiles. The declaration would then be checked against itself: exactly the class
 * of stale key this catalogue has already shipped twice.
 */
export declare function define<const TPart extends string>(kind: MdyWidgetKind, rootClasses: readonly string[], partNames: readonly TPart[], overlay: boolean, shape?: MdyWidgetShape<NoInfer<TPart>>): MdyWidgetDefinition<TPart>;
export {};
/**
 * The semantic every part answers to, declared rather than defaulted.
 *
 * A name missing from here throws rather than falling back to `group`: the contract does not get to
 * have no opinion by accident. A default would let an unclassified part silently admit any element
 * at all, and the absence of an answer is indistinguishable from a deliberate one.
 *
 * `group` still appears, and means a container the contract does not constrain further — an answer,
 * not the absence of one.
 */