import { type MdyStateName } from "./state.js";
/**
 * Version of the framework-agnostic UI contract implemented by this package.
 *
 * It names the **anatomy**, not the shape of the declaration: an adapter reads it to say *"the parts
 * I build are the parts this number describes"*, and the audits that check a renderer against the
 * catalogue refuse a version they were not written for. So it moves whenever a part a renderer was
 * told to build stops existing, changes its element, or gains a role — the changes
 * `contract:diff --since <tag>` classifies major.
 *
 * It stayed at 1 across a release that removed `datepicker.actions` and `daterange.actions` and
 * turned `multiselect.searchButton` from a `button` into an `input` with `role="combobox"`. Two
 * renderers written against "contract version 1" would then have implemented two different
 * anatomies, and the number that exists to prevent exactly that said they were the same.
 *
 * 3 names an anatomy where `multiselect.popup` carries `role="dialog"`. A renderer built against 2
 * emits that panel with no role, which is a conforming renderer under 2 and a non-conforming one
 * here — the case this number exists to make visible rather than to let pass.
 *
 * 4 moved a boolean's indicator and a toggle's track under the label. 5 gives a timepicker's dial
 * two more parts — the layer of stretches that carry no selectable time, and each stretch in it —
 * which sit between the face and the hand, so a renderer built against 4 draws them nowhere.
 */
export declare const MDY_WIDGET_CONTRACT_VERSION: 5;
/** Semantic element categories that presenters can map to their native rendering API. */
export type MdyWidgetSemanticElement = "root" | "label" | "input" | "button" | "group" | "status" | "submission" | "listbox" | "option" | "radio" | "dialog" | "grid" | "gridcell" | "container" | "presentation" | "popup" | "text" | "affordance" | "columnheader" | "image";
/**
 * The conditions under which an optional part is on the page.
 *
 * Closed, and each entry is a question a renderer can already answer without asking the contract
 * anything further. Free text would be unreadable to a check, and a check is the whole point: an
 * unwritten condition is what let the same optional part appear under three different rules.
 */
/**
 * The conditions an optional part is on the page under.
 *
 * `undoIsOnOffer` was here and is not: the control it governed stopped coming and going when a
 * control that is part of a field's design became always present and merely unavailable. The word
 * still means something — it is what decides whether that button can act — but a condition on a
 * *state* is not a condition on presence, and a vocabulary that holds both is one a reader has to
 * ask which kind each word is. ADR 0171.
 */
export declare const MDY_PART_PRESENCES: readonly ["documentDeclaresIt", "fieldIsRequired", "fieldCanBeInvalid", "errorsAreVisible", "overlayIsOpen", "valueIsPresent", "valueIsAbsent", "kindOffersIt", "viewIsActive", "valuesOverflow", "inputWasRefused", "pointerIsOnAValue", "workIsInFlight"];
/**
 * Derived from the list above rather than written twice.
 *
 * A union restated beside the array it mirrors is a second declaration, and a check reading the
 * restatement passes while the array grows past it — which is how a vocabulary comes to have two
 * lengths. A test can only read the array, so the array is what everything reads.
 */
export type MdyPartPresence = (typeof MDY_PART_PRESENCES)[number];
/**
 * Who decides each presence condition, and where a consumer goes to ask.
 *
 * A condition with no way to decide it is a declaration each renderer interprets for itself, which is
 * how one of these came to mean one thing where chips are drawn and another where they are not. The
 * three the package answers today carry 85 of the 185 declarations, and that is the direction of the
 * causation rather than a coincidence: a condition a consumer can ask about is the one consumers read.
 *
 * Three will never have a resolver, and saying so here is the point of the table. A condition whose
 * answer restates an input the renderer already holds cannot be got wrong by anybody, and a function
 * over it would put a call between a consumer and a fact in their hand. Left as a blank they read as
 * gaps, and the next person counting resolvers reports three findings that are decisions.
 *
 * `owed` is the third state, and there is nothing in it today. It is kept in the shape because a
 * condition added to the contract arrives owed, and the table has to be able to say so rather than
 * force whoever adds it to invent an answer on the spot. ADR 0169.
 */
/**
 * Which message names a part that no relation points at.
 *
 * Most parts are named by being pointed at: a caption's `for`, an opener's `aria-controls`. Five are
 * not, and they are not machinery — a person types in a panel's search box, in the second date of a
 * range, in each half of a time. Nothing declared what those are called, so each renderer chose, and
 * they chose differently: one built `"<caption> — end"` by hand where another read `daterangeEndLabel`
 * from the message table, and a page in Italian said "end".
 *
 * The words already existed in the table for every one of them. What was missing was the sentence
 * saying which word belongs to which part — so this is a binding rather than a vocabulary, and the
 * translation of a control's name stops being a decision a renderer takes on its own.
 *
 * Keyed `kind.part`. A part named by a relation is not here and must not be: two ways to name one
 * element is the divergence this removes.
 */
export declare const MDY_PART_NAMES: Readonly<Record<string, string>>;
export declare const MDY_PRESENCE_RESOLUTION: Readonly<Record<MdyPartPresence, {
    /** The published name that answers it, or `null` where nothing does. */
    readonly resolver: string | null;
    /** Why nothing answers it — `"owed"`, or the reason no answer is possible or needed. */
    readonly because: string;
}>>;
/**
 * When each optional part is on the page, by part name.
 *
 * Keyed by name because the anatomy is declared twice — derived per kind, and written out once for
 * the shell every field shares — and a table is the only shape in which the two cannot disagree. A part
 * called
 * `supportingText` is the same part wherever it appears, and a table is the only shape in which
 * seventeen kinds cannot disagree about it.
 *
 * A name missing from here is a part whose condition has not been decided. That is a gap, and the
 * audit records it — but a *wrong* entry is worse than a missing one, because it tells a renderer to
 * build something at a moment when it is not wanted and nothing notices until it is on the page.
 */
/**
 * What a part needs the kind to have been *given* before its presence question applies at all.
 *
 * `presentWhen` says when a part is on the page. This says whether the question is asked — a reorder
 * grip is present when there is a value, and only where a document asked for reordering, which is not
 * a state the widget is in but something the page decided before it existed.
 *
 * One entry today, and it is a correction rather than an addition: read without it the contract owed
 * a drag handle to every multiselect holding a value, and all three renderers drew it only where
 * reordering was asked for. Three adapters agreeing against a declaration is the evidence that the
 * declaration is what is wrong.
 */
/**
 * Three that were here and are not any more, and the reason is one rule.
 *
 * A control that is part of a field's design is always present, and disabled where it cannot act.
 * Absence is for what is not part of *this* field — a box a configuration left out. Removing a
 * control when it has nothing to do collapses two facts that change at different rates: whether it
 * exists, which is fixed, and whether it can act, which changes as somebody works. The tab stops
 * then move under their hands, and the one who has never used the field learns what it can do only
 * after filling it in.
 *
 * `clearAll`, `wayBackAction` and `file.clear` were declared present-when-there-is-something, and
 * all three renderers drew them always — right about the presence, and none of them said *dimmed*,
 * so an empty field carried two buttons that looked live and did nothing. A button that lies is
 * worse than one that says it is unavailable.
 *
 * `chipMove` and `chipRemove` stay conditional and are not exceptions: they belong to a chip, and
 * exist exactly when the chip does. The chip is the state. `overflowCount` stays too — it reports a
 * state rather than offering an act, and "+0" is noise where absence is legible.
 */
/**
 * Parts whose unavailability is announced rather than set, and why that is not the usual defect.
 *
 * `aria-disabled` on a control the platform could disable natively is normally a lie: the reader is
 * told one thing and the pointer and keyboard do another, and the inspector says so. These are the
 * exception, and the reason is the tab order.
 *
 * The native property takes a control out of the tab order. For a control that is part of a field's
 * design — always there, unavailable only sometimes — that means the number of stops changes as
 * somebody works, and it changes *under their focus* at the one moment they have just pressed the
 * button: they clear a field, the button becomes unavailable, and their focus is on the document.
 * Announced instead, the button keeps focus and they hear the state change, which is the confirmation
 * that it worked.
 *
 * What neither this declaration nor the inspector can see is whether the handler actually refuses.
 * That is a question about an act rather than about markup, and the check that would settle it presses
 * the control and reads the value. ADR 0171 records that, and records that this list is the narrow
 * form on purpose: twenty-one parts declare `disabled` among their states and most of them are
 * natively disabled, so keying the exemption on that would give the whole contract away.
 */
export declare const MDY_ARIA_DISABLED_PARTS: readonly string[];
/**
 * Capabilities that decide whether a part's presence question applies at all.
 *
 * Keyed by `kind.part` where the gate belongs to one kind, and by the bare part name where it
 * belongs to the part wherever it appears — a slider's `value` is not a select's. Read through
 * {@link partIsOwed} so that neither half of the question can be taken without the other.
 *
 * `chipMove` — a reorder grip is owed only where a document asked for reordering. Read without this,
 * the contract owes one to every multiselect holding a value, which all three renderers correctly
 * disobey.
 *
 * A select's `value` is the same shape of question and is deliberately **not** here: the element
 * showing what was chosen exists in the custom chooser and not in the platform's own `<select>`,
 * which two renderers draw when a select does not filter. That is a difference between two
 * presentations of one kind, which this contract expresses as a variant rather than as a capability —
 * and a capability word invented for it would be a second vocabulary for an idea the catalogue
 * already has. It is owed a decision and a batch of its own.
 */
export declare const MDY_PART_REQUIRES: Readonly<Record<string, string>>;
export declare const MDY_PART_PRESENCE: Readonly<Record<string, MdyPartPresence>>;
/** One node in a widget's framework-independent structural anatomy. */
export interface MdyWidgetStructureNode<TPart extends string = string> {
    readonly part: TPart;
    readonly element: MdyWidgetSemanticElement;
    readonly parent?: TPart;
    readonly order: number;
    /**
     * Whether a renderer may leave this part out **while its parent is on the page**.
     *
     * Required is a statement about the part's place, not about the whole widget's lifetime: six kinds
     * declare a required part inside an optional `popup` — `select.listbox`, `datepicker.calendar`,
     * `colors.presets` and their siblings — and read as "always present" that is a contradiction with
     * `overlayOnlyParts`, which names those same parts as ones a closed widget has no reason to build.
     *
     * Both are true under this reading and neither is under the other: a closed select need not build
     * its listbox because the popup that would hold it is absent, and a select whose popup *is* on the
     * page must have one. So a renderer that builds an overlay's contents only when it opens is
     * conformant, and so is one that builds them eagerly — the difference between them is a rendering
     * choice, which is what `overlayOnlyParts` exists to say — in its own words, *"a closed widget is
     * not required to render any of them … what both must do is render them when open"*. This is the
     * same sentence from the part's side, where a reader deciding what to build actually looks.
     */
    readonly optional?: boolean;
    /**
     * What has to be true for an optional part to be on the page.
     *
     * `optional` says a renderer *may* leave a part out and stops there, so three renderers decided
     * three times when to build it and conformance had nothing to ask. A part that is present under a
     * condition nobody wrote is a part each adapter invents a rule for.
     *
     * Named `presentWhen` rather than `when` because `when` already means the overlay phase on a key
     * binding, and one word carrying two meanings is how a declaration comes to be read two ways.
     */
    readonly presentWhen?: MdyPartPresence;
    /**
     * A capability the kind must have been given before the part is owed at all.
     *
     * `presentWhen` says *when* a part is on the page; this says *whether the question applies*. A
     * multiselect's reorder grip is present when there is a value — and only where a document asked
     * for reordering, which no condition can express because it is not a state the widget is in, it is
     * something the page decided before the widget existed.
     *
     * Read literally without it, the contract owed a drag handle to every multiselect holding a value.
     * All three renderers drew it only where reordering was asked for, which is right and was a rule
     * none of them could point at — the shape where three adapters agree against the declaration and
     * the declaration is what is wrong.
     *
     * The same word a key binding uses, deliberately: `requires` there gates a gesture on the same
     * facts, and one vocabulary for one idea is what keeps a reader from checking whether they differ.
     */
    readonly requires?: string;
    readonly repeated?: boolean;
}
/**
 * Whether a part is owed on the page right now.
 *
 * Two facts decide it and they are easy to read as one: **whether the question applies at all** —
 * a capability the document asked for before the widget existed — and **whether the condition
 * holds** — a state the widget is in. A reader who takes only the second owes a reorder grip to
 * every multiselect holding a value, which is a rule all three renderers correctly disobey.
 *
 * One door so that neither can be read without the other. A checker asking "is this part missing
 * when it should be there" asks here; asking the node's `presentWhen` directly is asking half of a
 * two-part question and getting a confident wrong answer.
 *
 * `holds` is asked only when the gate is open, so a caller that cannot resolve a condition for a
 * capability the field does not have is never asked to.
 */
export declare function partIsOwed(node: MdyWidgetStructureNode, facts: {
    /** Whether the widget is in the state the condition names. */
    readonly holds: (condition: MdyPartPresence) => boolean;
    /** Whether the field was given the capability the part is gated on. */
    readonly offers: (capability: string) => boolean;
}): boolean;
/**
 * Which shape a document asks a kind to be drawn in.
 *
 * A kind with two anatomies is only half declared while nothing says *which one a given field
 * selects*: the catalogue named the select's two shapes and published no way to ask which one a
 * document picks, so a renderer drawing one of them and ignoring the property was violating nothing
 * stated, and a checker had to guess or hard-code the rule.
 *
 * The two axes, and both are the document's own words rather than a translation:
 *
 * - a **multiselect** is drawn by its `mode` — a toggle set or a bag;
 * - a **select** is drawn by whether it `searchable`: filtering is the combobox, not filtering is the
 *   platform's own chooser, which is a different control to anyone not using a pointer.
 *
 * `undefined` for a kind with one anatomy, which is every other kind: a variant asked of a kind that
 * has none is a question about a shape that does not exist.
 */
export declare function variantOf(kind: string, spec?: {
    readonly mode?: string;
    readonly searchable?: boolean;
}): string | undefined;
/** Ordered structural anatomy for a widget. This is metadata, not a virtual DOM. */
export interface MdyWidgetStructure<TPart extends string = string> {
    readonly kind: string;
    readonly nodes: readonly MdyWidgetStructureNode<TPart>[];
}
/** Canonical shell parts shared by field-like controls. */
export type MdyFieldShellPart = "root" | "label" | "requiredMarker" | "inputWrapper" | "prefix" | "control" | "suffix" | "inlineError" | "supportingText" | "errors" | "errorItem";
/** Canonical class vocabulary. Presenters must not invent adapter-specific equivalents. */
export declare const MDY_FIELD_SHELL_CLASSES: Readonly<{
    root: string;
    label: string;
    requiredMarker: string;
    inputWrapper: string;
    prefix: string;
    control: string;
    suffix: string;
    inlineError: string;
    supportingText: string;
    errors: string;
    errorItem: string;
}>;
/**
 * States every field-like widget's shell parts share.
 *
 * The shell is the same shell whatever it wraps, so its states are declared once rather than
 * seventeen times: a wrapper is disabled or in error, a label is filled or has an error to make room
 * for, a root is open or has been touched.
 *
 * Beside the shell's classes rather than in the catalogue, because a shell part's name and the
 * states it may be in are one fact, and {@link MDY_FIELD_STATE_CLASSES} is derived from both.
 */
export declare const MDY_SHELL_PART_STATES: Readonly<Record<string, readonly MdyStateName[]>>;
export declare const MDY_FIELD_STATE_CLASSES: Readonly<{
    /** Base the field root's state modifiers hang from. */
    field: string;
    /** States the field root reflects. */
    fieldStates: readonly string[];
    /** Base the wrapper holding the control, which is where a field shows it is unusable or wrong. */
    control: string;
    /** States that wrapper reflects. */
    controlStates: readonly string[];
    /** Base the label's own modifiers hang from. */
    label: string;
    /** States the label reflects: whether the field has a value, and whether it is failing. */
    labelStates: readonly string[];
    /** The root modifier an overlay widget carries while its popup is showing. */
    rendererOpen: string;
}>;
/**
 * Classes that belong to no single widget: the shared button, the overlay machinery, the surface
 * treatments a theme applies wherever it likes.
 *
 * Contract data, published through `@modyra/widgets/vocabulary`. They are not a kind's anatomy and
 * belong to no catalogue entry, which is why they are declared here rather than in one — but a theme
 * selects on them, so they are names this package promises to keep.
 *
 * Seven of the eight are already selected on by the themes shipped in this repository, so the
 * promise is not hypothetical. It was, however, unguarded: `contract:diff` reaches class names
 * through a kind's parts, so a name outside every kind was invisible to it and a rename would have
 * been reported as an internal change while breaking every stylesheet that used one. The snapshot
 * now records them alongside the scale, for the same reason and in the same shape.
 */
export declare const MDY_SHARED_UI_CLASSES: readonly string[];
/** Base field anatomy. Widget-specific contracts extend this ordered tree. */
export declare const MDY_FIELD_SHELL_STRUCTURE: {
    kind: string;
    nodes: readonly MdyWidgetStructureNode<"control" | "errorItem" | "errors" | "inlineError" | "inputWrapper" | "label" | "prefix" | "requiredMarker" | "root" | "suffix" | "supportingText">[];
};
/**
 * Canonical parts of the form itself, as against a field's shell.
 *
 * Not every refusal belongs to a field. A failed network call, a service that is down, a cross-field
 * rule only a server can check: they arrive with no path, the engine keeps them in
 * `state.lastSubmitErrors()`, and until this part existed there was nowhere in any renderer's markup
 * to put them — so a person pressed Send while the server said no and saw their fields exactly as
 * they had left them.
 *
 * The region is a `status`, not a field's error list: it speaks for the form, it appears after an
 * action the person took, and it is announced when it arrives rather than when it is reached.
 */
export type MdyFormShellPart = "formErrors" | "formErrorItem";
/** Canonical class vocabulary for the form's own parts. */
export declare const MDY_FORM_SHELL_CLASSES: Readonly<{
    formErrors: string;
    formErrorItem: string;
}>;
/**
 * Where the form's own refusals sit: first, before the fields.
 *
 * A summary a person has to scroll past their whole form to find is a summary they do not read, and
 * a refusal about the submission as a whole belongs where the submission was answered.
 */
export declare const MDY_FORM_SHELL_STRUCTURE: MdyWidgetStructure<MdyFormShellPart>;
/**
 * The same derivation over a bare node list, so it can be exercised on anatomies the catalogue does
 * not contain — in particular ones whose nodes are not listed parent-before-child.
 *
 * The catalogue's are, today, which is exactly why this exists: a derivation that only works on
 * sorted input would pass every test in this repository and put a part that lives inside a popup
 * into the half a server is told to emit.
 */
export declare function dynamicPartsOf(nodes: readonly MdyWidgetStructureNode[]): readonly string[];
/**
 * Which shell classes a field's state puts on, derived from the table that declares them.
 *
 * `MDY_FIELD_STATE_CLASSES` has always said which base each shell part carries and which states it
 * admits. What it never said is the answer — *given these flags, which classes are on* — so every
 * renderer wrote that out, and wrote the class names as string literals beside lines that read the
 * vocabulary properly. One of them spells the same state raw in one place and derives it in another.
 *
 * One state, two spellings, which is the part a renderer gets wrong: a failing field takes `--error`
 * on its wrapper and `--has-error` on its label. Both were declared and nothing composed them.
 *
 * **Every class is named, on or off.** A list of only the ones that are on tells a renderer what to
 * add and not what to take away, so a field that stops failing keeps the class that says it is —
 * which is the shape of a control stuck looking wrong after it was corrected. Returned per part
 * because they land on three elements, and a flat list makes the caller work out which is which.
 */
export declare function shellStateClasses(state: {
    readonly open?: boolean;
    readonly touched?: boolean;
    readonly disabled?: boolean;
    readonly readonly?: boolean;
    /** Failing: `--error` on the wrapper, `--has-error` on the label. One state, two names. */
    readonly error?: boolean;
    readonly filled?: boolean;
    /** The label stands in for a name the document never wrote. */
    readonly unwritten?: boolean;
}): {
    readonly field: Readonly<Record<string, boolean>>;
    readonly control: Readonly<Record<string, boolean>>;
    readonly label: Readonly<Record<string, boolean>>;
};