praxis-kit 0.1.0

package/dist/lit/index.d.ts

@@ -0,0 +1,862 @@
+import "clsx";
+import { DiagnosticCode, DiagnosticInput, Diagnostics, DiagnosticsMode } from "../_shared/diagnostics.js";
+import { LitElement } from "lit";
+import { OmitIndexSignature, ReadonlyDeep, RequireAtLeastOne, Simplify } from "type-fest";
+//#region ../../lib/foundation/src/string-map.d.ts
+/**
+ * A string-keyed object whose values are of type `T`.
+ */
+type StringMap<T = unknown> = Record<string, T>;
+/**
+ * A string-keyed object with values of unknown type.
+ */
+type AnyRecord = StringMap<unknown>;
+//#endregion
+//#region ../../lib/primitive/src/types/any-record.d.ts
+/**
+ * An object type with no named properties.
+ *
+ * Unlike `{}`, this excludes arbitrary properties during type operations while
+ * still satisfying `extends object`.
+ */
+type EmptyRecord = Record<never, never>;
+/**
+ * A compound component's named sub-components, for example
+ * `{ Header, Content, Footer }`.
+ */
+type SubComponentMap = Readonly<AnyRecord>;
+/**
+ * Default `Variants` type for components that declare no variants.
+ *
+ * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
+ * editor hovers remain self-descriptive.
+ */
+type NoVariants = Readonly<EmptyRecord>;
+/**
+ * Default `TPreset` type for components that declare no named presets.
+ *
+ * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
+ * editor hovers remain self-descriptive.
+ */
+type NoPreset = Readonly<EmptyRecord>;
+/**
+ * Fallback for `ExtractPluginProps<TPlugin>` when a plugin contributes no
+ * props, including the no-plugin case.
+ *
+ * Structurally identical to `EmptyRecord`, but named separately so editor
+ * hovers remain self-descriptive.
+ */
+type NoPluginProps = EmptyRecord;
+/**
+ * Determines whether an object type should be treated as empty.
+ *
+ * `keyof T` ignores call and construct signatures...
+ */
+type IsEmptyRecord<T extends object> = T extends ((...args: never[]) => unknown) ? false : T extends (new (...args: never[]) => unknown) ? false : keyof T extends never ? true : false;
+/**
+ * Merges two object types while eliding empty operands.
+ *
+ * If either operand is {@link EmptyRecord}, the other operand is returned
+ * directly instead of producing intersections such as
+ * `Component & EmptyRecord` in editor hovers.
+ *
+ * Unlike a homomorphic mapped type (for example `Simplify<T>`), this preserves
+ * call and construct signatures. Many component types are callable objects,
+ * and mapped types silently discard those signatures.
+ *
+ * @remarks
+ * Instantiate `MergeRecords` directly. Introducing an intermediate alias for
+ * one operand (for example `type C = PolymorphicComponent<G>`) can prevent
+ * `IsEmptyRecord` from evaluating eagerly, which breaks assignability under
+ * `exactOptionalPropertyTypes`.
+ */
+type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends true ? B : IsEmptyRecord<B> extends true ? A : A & B;
+//#endregion
+//#region ../../lib/primitive/src/types/intrinsic-tag.d.ts
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+//#endregion
+//#region ../../lib/primitive/src/types/element-type.d.ts
+type ElementType = IntrinsicTag | (string & {});
+/**
+ * Resolves a component's default tag to its real DOM interface — `HTMLDialogElement` for
+ * `'dialog'`, `HTMLDetailsElement` for `'details'`, and so on — falling back to `HTMLElement`
+ * for custom-element tags or anything not in `HTMLElementTagNameMap`. Used to type
+ * `FactoryOptions.onElement`'s `element` param so component authors get direct, correctly-typed
+ * access to tag-specific native members (`dialogEl.showModal()`) without an unsafe cast.
+ *
+ * The fallback is `HTMLElement`, not the more generic `Element` — every tag reachable through
+ * `IntrinsicTag` extends it, and so does every custom element per spec, so members `HTMLElement`
+ * itself declares (`showPopover()`/`hidePopover()`/`togglePopover()`, the `popover` attribute)
+ * stay directly accessible even for tags with no dedicated entry in `HTMLElementTagNameMap`.
+ */
+type ElementForTag<TDefault extends ElementType> = TDefault extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TDefault] : HTMLElement;
+//#endregion
+//#region ../../lib/primitive/src/constants/aria/known-aria-roles.d.ts
+declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
+//#endregion
+//#region ../../lib/primitive/src/types/primitives/index.d.ts
+type Booleanish = boolean | 'true' | 'false';
+type ClassName = string | string[];
+type NonEmptyArray<T> = [T, ...T[]];
+type Numberish = number | `${number}`;
+type Primitive = string | number | boolean;
+type AriaRole = KnownAriaRole | (string & {});
+type IntrinsicProps = AnyRecord & {
+  role?: AriaRole;
+};
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/cardinality.d.ts
+type MinMax = {
+  min: number;
+  max: number;
+};
+type CardinalityInput = Partial<MinMax>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-context.d.ts
+/**
+ * Resolved per-instance state available to a dynamic (`dynamic(...)`) child
+ * rule field — the same tag/props every adapter already computes before
+ * evaluating children, exposed so a rule can vary by them (e.g. cardinality
+ * that depends on the resolved `as` tag).
+ */
+type ChildRuleContext = {
+  readonly tag: unknown;
+  readonly props: Readonly<AnyRecord>;
+};
+//#endregion
+//#region ../../lib/primitive/src/rule/rule-brand.d.ts
+declare const RULE_BRAND: unique symbol;
+//#endregion
+//#region ../../lib/primitive/src/types/rule/dynamic-rule.d.ts
+type DynamicRule<T, C = unknown> = {
+  readonly [RULE_BRAND]: true;
+  resolve(context: C): T;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/rule/rule.d.ts
+type Rule<T, C = unknown> = T | DynamicRule<T, C>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-match.d.ts
+type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-position.d.ts
+type ChildRulePosition = 'first' | 'last' | 'any';
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-input.d.ts
+type ChildRuleInput<T = unknown, U extends T = T> = {
+  name: string;
+  match: ChildRuleMatch<T, U>;
+  /**
+   * Either a static cardinality, or `dynamic((ctx) => ...)` to derive it from
+   * the resolved tag/props (e.g. a different max depending on `as`). `match`
+   * stays static-only — it's already a function, so a dynamic wrapper would
+   * be indistinguishable from the predicate itself without one.
+   */
+  cardinality?: Rule<CardinalityInput, ChildRuleContext>;
+  position?: ChildRulePosition;
+  /**
+   * Optional component-type reference for O(1) dispatch index.
+   * When provided for every rule, the matcher reads child.type instead of
+   * calling every match function on every child (O(n×m) → O(n+m)).
+   */
+  type?: unknown;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/validation/valid-result.d.ts
+type ValidResult = {
+  valid: true;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/variants/string-to-boolean.d.ts
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-value.d.ts
+type VariantValue = string | string[];
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-states.d.ts
+type VariantStates<K extends string = string> = Record<K, VariantValue>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-map.d.ts
+type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-key.d.ts
+type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-selection.d.ts
+/**
+ * A partial selection of variant states authored at factory definition time.
+ *
+ * Uses `keyof V[K]` directly (not `VariantKey`) so TypeScript can eagerly
+ * resolve the union at constraint-check time without deferred conditional types.
+ */
+type VariantSelection<V extends VariantMap> = { [K in keyof V]?: keyof V[K]; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-props.d.ts
+/** The full optional prop surface exposed to callers for a given variant map. */
+type VariantProps<V extends VariantMap> = { [K in keyof V]?: VariantKey<V, K>; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/default-variants.d.ts
+type NormalizedVariantValue<K extends string> = string extends K ? Primitive : K extends 'true' | 'false' ? Booleanish : K extends `${number}` ? Numberish : K;
+type DefaultVariants<V extends VariantMap> = { [K in keyof V]?: NormalizedVariantValue<keyof V[K] & string>; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/recipe-map.d.ts
+/**
+ * A static, immutable map of named presets to partial variant selections.
+ *
+ * Presets are named bundles of variant props that callers activate by key,
+ * avoiding the need to repeat variant combinations at each call site.
+ */
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSelection<V>>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/recipe-target.d.ts
+type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/polymorphic-generics.d.ts
+/**
+ * The framework-neutral descriptor for a single praxis-kit component's contract — every render
+ * mechanism (tag resolution, prop merging, classes, ARIA) and every framework adapter's
+ * component type is built from this one shape. Deliberately just data: five type parameters and
+ * their corresponding properties, with no notion of JSX, call signatures, refs, or any
+ * framework-specific rendering concern. Each adapter (React, Vue, Svelte, Solid, Lit, Web) builds
+ * its own idiomatic component type on top of a `PolymorphicGenerics<...>` instantiation — see
+ * `PolymorphicComponent<G>` (`adapters/react/src/shared/types/polymorphic-props.ts`) for the
+ * React example — rather than this interface knowing anything about any of them.
+ *
+ * Use the `*Of<T>` accessor aliases below (`DefaultOf<G>`, `PropsOf<G>`, etc.) to read a single
+ * field back out of an already-resolved `G`, instead of indexing `G['default']` etc. directly at
+ * call sites — same rationale as any accessor: the property name stays an implementation detail,
+ * and every reader benefits together if it ever needs to change.
+ */
+interface PolymorphicGenerics<
+/**
+ * The element/tag this component renders as when the consumer doesn't override it via `as`
+ * (`AllowedOf<G>` permitting) — e.g. `'button'`, `'div'`. Defaults to the widest `ElementType`
+ * so a generic `PolymorphicGenerics` reference (with nothing else specified) still compiles.
+ */
+TDefault extends ElementType = ElementType,
+/**
+ * The props this specific component declares — its own contract, before variants are mixed
+ * in. Defaults to `AnyRecord` for the same "still compiles unspecified" reason as `TDefault`.
+ */
+Props extends AnyRecord = AnyRecord,
+/**
+ * This component's variant definitions (e.g. `{ intent: { primary: ..., ghost: ... } }`).
+ * Constrained to `Readonly<VariantMap>` — not the wider `AnyRecord` — specifically so `TPreset`
+ * below can be expressed as `RecipeMap<Variants>` and get real per-variant-key checking,
+ * instead of falling back to an unconstrained `RecipeMap<VariantMap>`.
+ */
+Variants extends Readonly<VariantMap> = Readonly<VariantMap>,
+/**
+ * Named presets (`RecipeMap<Variants>`) — bundles of variant selections a consumer activates
+ * by key instead of repeating the same variant combination at every call site. Tied to
+ * `Variants`, not `AnyRecord`, precisely so a preset can only ever select keys/values that
+ * `Variants` actually defines — an invalid preset is a type error, not a silent no-op.
+ * Defaults to `Readonly<EmptyRecord>` (no presets), which is the common case: a component can
+ * have variants without necessarily defining any named presets over them, and most don't.
+ */
+TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>,
+/**
+ * The set of elements/tags a consumer is allowed to switch to via `as`. Defaults to the widest
+ * `ElementType`, under which `AllowedOf<G>` imposes no restriction at all (see
+ * `PolymorphicControlProps.as`'s own comment in the React adapter for the concrete effect this
+ * has at a component's actual call site).
+ */
+TAllowed extends ElementType = ElementType> {
+  default: TDefault;
+  props: Props;
+  variants: Variants;
+  preset: TPreset;
+  allowed: TAllowed;
+}
+/** This component's variant definitions. See `PolymorphicGenerics`'s `Variants` parameter. */
+type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
+/** This component's named presets. See `PolymorphicGenerics`'s `TPreset` parameter. */
+type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
+/** This component's own declared props, before variants are mixed in. See `PolymorphicGenerics`'s
+ *  `Props` parameter. */
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/compound-variant.d.ts
+type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
+type CompoundVariantConditionValue<V extends VariantMap, K extends keyof V> = VariantKey<V, K> | NonEmptyArray<VariantKey<V, K>>;
+type CompoundVariantConditions<V extends VariantMap> = Simplify<{ [K in keyof V]: CompoundVariantConditionValue<V, K>; }>;
+type CompoundVariantRequiredConditions<V extends VariantMap> = RequireAtLeastOneIfNotEmpty<CompoundVariantConditions<V>>;
+type CompoundVariantBase<V extends VariantMap> = keyof V extends never ? EmptyRecord : CompoundVariantRequiredConditions<V>;
+type CompoundVariant<V extends VariantMap> = CompoundVariantBase<V> & {
+  class: VariantValue;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-compounds.d.ts
+interface CVACompounds<V extends VariantMap> {
+  compoundVariants?: readonly CompoundVariant<V>[];
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-defaults.d.ts
+interface CVADefaults<V extends VariantMap> {
+  defaultVariants?: DefaultVariants<V>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-variants.d.ts
+interface CVAVariants<V extends VariantMap> {
+  variants?: V;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/base-class-options.d.ts
+interface BaseClassOptions {
+  baseClassName?: ClassName;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-fn.d.ts
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/recipe-options.d.ts
+interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
+  recipeMap?: StringMap<RecipeTarget<TVariants>>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/tag-map-options.d.ts
+interface TagMapOptions {
+  tagMap?: TagMap;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/composition-options.d.ts
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/cva-system-options.d.ts
+type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/style-options.d.ts
+type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-options.d.ts
+type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/owned-prop-keys.d.ts
+type OwnedPropKeys = ReadonlySet<string>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/class-plugin.d.ts
+type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
+  pipeline: ClassPipelineFn;
+  ownedKeys?: OwnedPropKeys;
+  readonly _pluginProps?: TProps;
+}>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/class-plugin-factory.d.ts
+type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics) => ClassPlugin<TProps>;
+/** `ClassPluginFactory` with its plugin-owned-props generic erased — the common form used
+ *  wherever a factory's concrete plugin-props shape isn't tracked (factory generics,
+ *  capability wiring). */
+type AnyClassPluginFactory = ClassPluginFactory<AnyRecord> | undefined;
+type ExtractPluginProps<TPlugin extends AnyClassPluginFactory> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? NoPluginProps : T : NoPluginProps;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-context.d.ts
+type AriaContext = {
+  /**
+   * The intrinsic HTML tag being evaluated.
+   */
+  readonly tag: IntrinsicTag;
+  /**
+   * The implicit ARIA role associated with the intrinsic tag.
+   */
+  readonly implicitRole: AriaRole | undefined;
+  /**
+   * The effective ARIA role after considering the element's explicit
+   * `role` attribute or component-provided role.
+   */
+  readonly effectiveRole: string | undefined;
+  /**
+   * The component's props available to the ARIA policy engine.
+   */
+  readonly props: ReadonlyDeep<IntrinsicProps>;
+  /**
+   * Variant prop names declared by the component.
+   *
+   * The adapter uses these names to determine which props are intercepted
+   * before reaching the DOM. A rule asserting a fact about a real HTML
+   * attribute should therefore treat a key present here as a component
+   * variant rather than a DOM attribute.
+   *
+   * An empty set indicates no variant props are declared — the case for
+   * evaluations with no factory context, such as `AriaPolicyEngine.evaluate`.
+   */
+  readonly variantKeys: ReadonlySet<string>;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/fix-kind.d.ts
+type RemoveAttributeFixKind = 'removeAttribute';
+type InjectLiveFixKind = 'injectLive';
+type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-fix.d.ts
+type AriaFixResult = {
+  applied: false;
+  next: ReadonlyDeep<IntrinsicProps>;
+} | {
+  applied: true;
+  next: ReadonlyDeep<IntrinsicProps>;
+  previous: ReadonlyDeep<IntrinsicProps>;
+};
+type AriaFix = {
+  readonly kind: FixKind;
+  /** The attribute a `'removeAttribute'`/`'injectLive'` fix targets — always set for those
+   *  kinds, absent for kinds with no single-attribute target (`'removeRole'`, etc.). */
+  readonly attribute?: string;
+  readonly priority?: number;
+  readonly source?: string;
+  readonly apply: (context: AriaContext) => AriaFixResult;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/severity.d.ts
+type Severity = 'error' | 'warning' | (string & {});
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-result.d.ts
+type AriaInvalidBase<M extends string = string> = {
+  valid: false;
+  severity: Severity;
+  message?: M;
+  attribute?: string;
+  diagnostic?: DiagnosticInput;
+};
+type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: true;
+  fix: AriaFix;
+};
+type AriaInvalidWithoutFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: false;
+};
+type AriaInvalidResult<M extends string = string> = AriaInvalidWithFix<M> | AriaInvalidWithoutFix<M>;
+type AriaResult = ValidResult | AriaInvalidResult;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-rule.d.ts
+type AriaRule<C extends AriaContext = AriaContext> = ((context: C) => readonly AriaResult[]) & {
+  readonly readsProps?: readonly string[];
+  readonly tags?: readonly string[];
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/prop-normalizer.d.ts
+type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/enforcement-options.d.ts
+type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
+  /**
+   * Accepts a preset name (`'warn'`, `'throw'`, `'silent'`) or a full `Diagnostics`
+   * instance for custom reporting/policy. The string form needs no import from
+   * `@praxis-kit/diagnostics`.
+   */
+  readonly diagnostics?: Diagnostics | DiagnosticsMode;
+  /**
+   * ARIA/accessibility rules evaluated against the resolved tag and props on every render.
+   * Each rule is a function receiving the current context and returning zero or more
+   * violations, some of which can carry an auto-applicable fix (see `createRemoveAttributeRule`
+   * and friends in `praxis-kit/contract`).
+   */
+  readonly aria?: readonly AriaRule[];
+  /**
+   * Rules that need `AriaPolicyEngine`'s fix-application/caching machinery
+   * (`AriaRule`'s `readsProps`, fixable `AriaFix` results) but have no
+   * relationship to ARIA semantics — an HTML fact or a security check like a
+   * dangerous-URL-scheme guard, for example. Evaluated together with `aria`
+   * (both run through the same engine, merged into one rule set) — this is a
+   * separate bucket purely so a non-ARIA rule doesn't have to sit under the
+   * misleading `aria` name to get the machinery it needs.
+   */
+  readonly rules?: readonly AriaRule[];
+  /**
+   * Declares which children are valid, by name, match predicate, and cardinality (e.g. "at
+   * least 1, at most 4 `Button` children"). Open by default — children matching no rule are
+   * still allowed unless `exclusiveChildren` is set.
+   */
+  readonly children?: readonly ChildRuleInput[];
+  /**
+   * When true, only children matching a `children` rule (or text, per `allowText`)
+   * are valid — anything else is rejected. Default: false (open — children not
+   * matching any rule are allowed).
+   */
+  readonly exclusiveChildren?: boolean;
+  /**
+   * When false, text/number child nodes are rejected regardless of exclusiveChildren
+   * or any listed rule. Default: true.
+   */
+  readonly allowText?: boolean;
+  /**
+   * Prop transforms composed with the component's own `normalize` (from `FactoryOptions`) and
+   * run before it. Unlike `normalize`, these live in the enforcement bucket because they
+   * typically encode a built-in HTML/ARIA fact rather than component-specific behavior.
+   */
+  readonly props?: readonly PropNormalizer[];
+  /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
+  readonly allowedAs?: readonly TAllowed[];
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/styling-options.d.ts
+type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = {
+  /** Class applied to every instance regardless of variant selection. */
+  readonly base?: ClassName;
+  /**
+   * Named variant groups (e.g. `intent`, `size`), each mapping its possible values to a
+   * class string. A consumer selects a value per group as a prop (`<Button intent="primary">`).
+   */
+  readonly variants?: V;
+  /** Value used for a variant group when the consumer doesn't pass one explicitly. */
+  readonly defaults?: Partial<DefaultVariants<V>>;
+  /**
+   * Applies an extra class only when a specific *combination* of variant selections matches —
+   * for cases `variants` alone can't express (e.g. `intent: 'primary'` + `size: 'lg'` together
+   * need a class neither variant would add on its own).
+   */
+  readonly compounds?: readonly CompoundVariant<V>[];
+  /**
+   * Named bundles of variant values a component defines up front. A caller activates one by name
+   * through the `recipe` prop (e.g. `<Button recipe="cta">` instead of setting `intent`/`size`
+   * individually) — `presets` is the store, `recipe` is the selector, which is why the field and
+   * the prop read differently. Explicit props always win over the activated bundle. The value type
+   * is `RecipeMap` (see `lib/primitive/src/types/variants/recipe-map.ts`).
+   */
+  readonly presets?: TPreset;
+  /** Maps a resolved tag directly to a raw class string, independent of the variant system. */
+  readonly tags?: Readonly<TagMap>;
+  /**
+   * A `ClassPluginFactory` (e.g. the Tailwind layout pipeline) that extends class resolution
+   * with its own owned props, layered on top of `variants`/`presets`/`tags`.
+   */
+  readonly plugin?: TPlugin;
+  /**
+   * A cache-key → resolved-class-string lookup for every statically-known variant
+   * combination, skipping runtime class computation entirely when a match is found. Normally
+   * generated by a build-time class-extraction plugin rather than hand-authored.
+   */
+  readonly precomputedClasses?: Readonly<StringMap<string>>;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/factory-options.d.ts
+type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
+  normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
+}['normalize'];
+/**
+ * The type-erased shape of {@link FactoryOptions} — every generic parameter widened to its bound.
+ *
+ * Use it for a value that must hold *any* factory config (a registry, a generic wrapper). It
+ * cannot check `styling.compounds` conditions against the real variant keys/values, because it
+ * has forgotten what they are — for that, annotate against `FactoryOptions<...>` with the concrete
+ * generics (or `satisfies FactoryOptions<'button', Props, typeof variants>`), which keeps an
+ * invalid compound condition a type error rather than a silent no-op.
+ */
+type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
+/**
+ * The framework-neutral component-authoring config passed to `createContractComponent` in every
+ * adapter: default tag + name, own-prop defaults, a `normalize` transform, `styling` (variants,
+ * base classes, presets, class plugin), `enforcement` (ARIA + children contracts), `subComponents`,
+ * and `onElement`.
+ *
+ * `satisfies FactoryOptions<TDefault, Props, typeof variants, ...>` on a config object narrows
+ * `styling.compounds` conditions to the real per-variant-key shape — including resolving a
+ * boolean-shaped axis (`{ true, false }`) to a real `boolean` — so a condition naming a variant or
+ * value that does not exist is a compile error. `AnyFactoryOptions` cannot do this.
+ */
+type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
+  /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
+  readonly tag?: TDefault;
+  /** Display name used in diagnostics, dev tools, and generated component naming. */
+  readonly name?: string;
+  /** Values used for the component's own (non-variant) props when the consumer omits them. */
+  readonly defaults?: Partial<NoInfer<Props>>;
+  /**
+   * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
+   * normalizers see the same input. Use this for component-specific prop shaping — anything
+   * that depends on live instance state or the real DOM element belongs in `onElement` instead.
+   *
+   * Accepts either a single transform or an array of them, mirroring the `enforcement.props`
+   * array convention. An array is composed left to right — each entry receives the previous
+   * entry's *complete* output, not a merged patch — so unlike an `enforcement.props` normalizer
+   * (which returns a partial patch), a later `normalize` entry can also remove a key an earlier
+   * one added. An empty array is treated as no transform.
+   */
+  readonly normalize?: NormalizeFn<NoInfer<Props>> | ReadonlyArray<NormalizeFn<NoInfer<Props>>>;
+  /** Variant groups, base classes, presets, and the optional class-resolution plugin. */
+  readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+  /** ARIA rules, child-content contracts, and other runtime validation for this component. */
+  readonly enforcement?: EnforcementOptions<TAllowed>;
+  /**
+   * Adapter-resolved diagnostics default, spread in by `resolveAdapterCommonOptions`. Not meant to
+   * be set directly by component authors — use `enforcement.diagnostics` to override per component.
+   */
+  readonly diagnostics?: Diagnostics;
+  /**
+   * Sub-components to attach to the generated root component, producing a
+   * compound component API (for example, `Card.Header`, `Card.Content`,
+   * and `Card.Footer`). Purely additive — has no effect on
+   * `enforcement.children`; author child rules explicitly if the component
+   * needs to validate its children.
+   */
+  readonly subComponents?: SubComponentMap;
+  /**
+   * Called once per instance, when the real underlying DOM element first
+   * exists, in every adapter — via that adapter's own native mount
+   * lifecycle, never through the props/attribute pipeline. Use this for
+   * wiring that needs the actual element (native imperative methods like
+   * `dialogEl.showModal()`, native events like `close`/`cancel` that have
+   * no prop-based equivalent), not for anything expressible as a plain
+   * prop.
+   *
+   * `element` is typed to the real DOM interface of every tag the rendered
+   * element could actually be — `TDefault` plus whatever `enforcement.allowed`
+   * permits via `as` (`HTMLDialogElement` for `tag: 'dialog'`,
+   * `HTMLDetailsElement` for `tag: 'details'`, and so on) — no cast needed to
+   * reach tag-specific members. A component that leaves `allowed`
+   * unconstrained (any tag reachable via `as`) falls back to `HTMLElement`,
+   * which still covers members every element shares (`showPopover()` and
+   * friends); restrict `enforcement.allowed` to the tags `onElement`
+   * actually knows how to handle to get real narrowing.
+   *
+   * `getProps` returns the instance's *current* resolved props at call
+   * time — read it from inside a listener registered once at mount, rather
+   * than re-subscribing on every prop change.
+   *
+   * Return a cleanup function to run when the instance unmounts.
+   */
+  readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
+};
+//#endregion
+//#region ../../lib/adapter-utils/src/types/filter-predicate.d.ts
+/**
+ * Determines whether a prop should be stripped before forwarding to the
+ * rendered element.
+ *
+ * Returning `true` excludes the prop from the output; returning `false`
+ * keeps it. This is the inverse polarity of `shouldForwardProp`-style
+ * predicates (Emotion/styled-components), where `true` means include.
+ *
+ * @param key - The prop name being evaluated.
+ * @param variantKeys - The set of configured variant prop names.
+ * @returns `true` to strip the prop; `false` to forward it.
+ */
+type FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
+//#endregion
+//#region ../../lib/adapter-utils/src/runtime/define-component.d.ts
+export declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+//#endregion
+//#region ../../adapters/lit/src/types/lit-options.d.ts
+/**
+ * Options accepted by createContractComponent in the Lit adapter.
+ *
+ * Extends FactoryOptions with one Lit-specific field:
+ * - filterProps: determines whether a prop should be omitted before it is
+ *   reflected as a DOM attribute. Variant keys and plugin-owned keys are
+ *   always omitted; this predicate extends that set.
+ *
+ * Note: this adapter targets Light DOM composition only. Shadow DOM slot
+ * protocol is intentionally out of scope.
+ */
+type LitFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+  readonly filterProps?: FilterPredicate;
+};
+//#endregion
+//#region ../../adapters/lit/src/types/generics.d.ts
+type RuntimeG<TDefault extends ElementType, Props extends AnyRecord, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants>> = PolymorphicGenerics<TDefault, Props, Variants, TPreset>;
+//#endregion
+//#region ../../adapters/lit/src/types/primitives.d.ts
+type UnknownProps = AnyRecord;
+/**
+ * Constructor type returned by createContractComponent.
+ *
+ * Describes the class contract without exposing LitElement's private members
+ * (which would trigger TS4094 in declaration emit). Variant key instance
+ * properties are typed via the TVariants parameter.
+ *
+ * `G` is a phantom marker only — see `__generics` below — and defaults to the
+ * widest `PolymorphicGenerics` so existing two-argument usages of this type
+ * (every call site inside this adapter) keep resolving exactly as before.
+ */
+type LitContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord, G extends PolymorphicGenerics = PolymorphicGenerics> = {
+  new (): MergeRecords<LitElement & {
+    recipe: string | undefined;
+    praxisClass: string | undefined;
+  } & { [K in Extract<keyof TVariants, string>]?: string | null; }, TPluginProps>;
+  /**
+   * Type-only; never assigned at runtime. `createContractComponent` erases
+   * `TDefault`/`Props`/`TPreset` entirely from its return type — only
+   * `TVariants` and `TPluginProps` survive as real instance-shape information,
+   * since those are the two that show up as actual constructor properties.
+   * This field is the Lit adapter's `HasGenerics<G>` counterpart: it carries
+   * the full `PolymorphicGenerics` the component was built from so
+   * `GenericsOf`/`ContractProps` (./contract-props) can recover
+   * it from outside the file that built it, the same recovery React/Preact do
+   * for their own erased overload-based component types. Inline rather than
+   * intersected for the same reason those adapters keep it inline — untested
+   * here since Lit's type has a single construct signature, not an overload
+   * set, but kept consistent with the established shape regardless.
+   */
+  readonly __generics?: G;
+};
+//#endregion
+//#region ../../lib/contract-props/src/has-generics.d.ts
+/**
+ * The phantom-marker shape read back via `T extends HasGenerics<infer G> ? G : never`. See the
+ * README for why this exists.
+ *
+ * Type-only: never assigned at runtime. In React's `PolymorphicComponent<G>`, declaring `readonly
+ * __generics?: G` inline (structurally matching this shape) rather than writing `HasGenerics<G> &
+ * { ...call signatures... }` was necessary to keep `PolymorphicComponent<any>`-typed test helpers
+ * assignable — confirmed directly against that adapter's own real component type (see
+ * `adapters/react/src/shared/types/polymorphic-props.test.ts`), not reproducible in an isolated
+ * minimal mock (see this file's own `has-generics.test.ts`), so treat "inline, not intersected"
+ * as an adapter-level implementation detail this package's marker shape must stay compatible
+ * with, not a property `HasGenerics<G>` itself enforces.
+ *
+ * Do **not** "harden" this with a `unique symbol` or other nominal brand: the whole point is that
+ * an adapter's real callable component type structurally satisfies this shape by declaring the
+ * same optional string-keyed field inline. Nominal purity here would break that compatibility.
+ */
+interface HasGenerics<G> {
+  readonly __generics?: G;
+}
+//#endregion
+//#region ../../adapters/lit/src/types/contract-props.d.ts
+/**
+ * Recovers a `LitContractComponent`'s `PolymorphicGenerics` descriptor from its own value type —
+ * the Lit analog of React's/Preact's `__generics` marker recovery.
+ * Needs the marker (unlike Svelte's `GenericsOf<T>`,
+ * `adapters/svelte/src/types/resolved-slot-props.ts`) because `createContractComponent` here
+ * returns `LitContractComponent<TVariants, TPluginProps, G>`, not `BuiltRuntime<G, TOptions>`
+ * directly — `TDefault`/`Props`/`TPreset` are genuinely erased from the return type, not merely
+ * hidden, so there is no ordinary type parameter left to `infer` them back out of.
+ * `LitContractComponent`'s own `__generics` field (`./primitives`) exists purely to make this
+ * recovery possible. Falls back to the widest `PolymorphicGenerics` for any non-praxis-kit value,
+ * the same "no marker, nothing to recover" case `HasGenerics<G>`'s own `never` branch covers for
+ * React/Preact.
+ */
+type GenericsOf<T extends HasGenerics<PolymorphicGenerics>> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? G : PolymorphicGenerics;
+/**
+ * A component's full prop contract — the attributes a caller can set on the custom element,
+ * recovered from outside the file that built it. Lit has exactly one render mode (no
+ * `asChild`/`render` — see the "known limitations" note atop `conformance.test.ts`), so unlike
+ * React's/Preact's `ContractProps<T, Mode>` this takes no `Mode` parameter: there is only ever one
+ * prop shape to pick.
+ *
+ * `as?: never` — deliberately absent, not merely undocumented. Every other adapter's `as` is real
+ * tag polymorphism (it changes the rendered host element); Lit's custom-element tag is fixed at
+ * `customElements.define()` time, so there is nothing for `as` to do here. `createContractComponent`
+ * strips it from the prop pipeline entirely (see that function's own doc comment) — this `never`
+ * makes that a type-level fact too, so `{ as: 'a' }` written against `ContractProps<T>` is a compile
+ * error, not a silently-ignored no-op a caller could believe was doing something.
+ *
+ * ```ts
+ * const Button = createContractComponent({ tag: 'button', name: 'Button', /* ... *\/ })
+ *
+ * type ButtonProps = ContractProps<typeof Button>
+ * ```
+ */
+type ContractProps<T extends HasGenerics<PolymorphicGenerics>> = Simplify<OmitIndexSignature<PropsOf<GenericsOf<T>>> & OmitIndexSignature<VariantProps<VariantsOf<GenericsOf<T>>>> & {
+  as?: never;
+  recipe?: keyof RecipeOf<GenericsOf<T>>;
+}>;
+//#endregion
+//#region ../../adapters/lit/src/create-contract-component.d.ts
+/**
+ * Creates a Lit custom element class with praxis-kit contracts applied.
+ *
+ * Returns a LitElement subclass. Register it with customElements.define():
+ *
+ * ```ts
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ *   enforcement: { strict: 'warn' },
+ * })
+ *
+ * customElements.define('praxis-button', Button)
+ * ```
+ *
+ * **This adapter is a Custom Element host carrying a Praxis semantic contract — not a
+ * reimplementation of native HTML element behavior.** `options.tag` (`'button'` above) names the
+ * _intrinsic model_ Praxis resolves ARIA roles, content-model rules, and built-in prop
+ * normalizers (`disabledProps`, etc.) against — it is not, and was never meant to be, the tag
+ * actually written to the DOM. The DOM tag is whatever name a caller later passes to
+ * `customElements.define(name, Button)`, entirely separate from `options.tag` and not knowable by
+ * this function at all (registration happens externally, after this returns, possibly under
+ * multiple names or never). So for the example above:
+ *
+ * ```text
+ * Praxis intrinsic model:  button   (options.tag — drives ARIA/content-model/normalizers)
+ * DOM host:                praxis-button   (customElements.define()'s name — the actual element)
+ * ```
+ *
+ * A concrete consequence worth internalizing: `<praxis-button disabled>` gets `aria-disabled` from
+ * the `disabledProps` normalizer (correctly, since `disabled`'s HTML-boolean-attribute semantics
+ * are honored in `_buildProps()` below), but the browser does **not** make the custom element
+ * keyboard-inert, form-participating, or otherwise behave like a real `HTMLButtonElement` — that
+ * gap isn't a bug, it's the direct consequence of `class X extends HTMLElement`, and no ARIA
+ * attribute on any element, custom or not, ever supplies real interactive behavior. The contract
+ * layer (styling, variants, ARIA policy, child enforcement, attribute management, lifecycle hooks,
+ * diagnostics) and the host's actual interactive behavior are — and have to stay — conceptually
+ * separate; a caller who needs real button/link/input behavior supplies it themselves (`onElement`
+ * is the wiring point), the same way any `role="button"` `<div>` would require it. (Customized
+ * built-ins — `class X extends HTMLButtonElement` + `{ extends: 'button' }` — were considered and
+ * rejected for solving this: a real platform mechanism, but a different consumer-facing API
+ * (`<button is="…">` instead of `<praxis-button>`) with its own platform constraints, not worth the
+ * complexity it would add here.)
+ *
+ * **No `as` prop, unlike every VDOM adapter.** React/Vue/Preact/Solid/Svelte's `as` genuinely
+ * changes the rendered host element — real tag polymorphism. Once the model/host distinction above
+ * is explicit, this becomes easy: a custom element's DOM tag is fixed at `customElements.define()`
+ * time, so there is no tag for `as` to switch — this adapter never accepted `as` as a semantic-only
+ * override either (an earlier design did — resolving ARIA/content-model rules as if the element
+ * were a different tag while the real DOM node stayed put). That was worse than not having it: it
+ * let a caller produce `role="link"`-shaped output with none of an anchor's actual
+ * keyboard/click/middle-click behavior — a real accessibility footgun regardless of what the
+ * option was named — and it made `renderContractToString`'s output disagree with the live client
+ * (SSR had no live DOM to constrain it to `options.tag`, so it rendered the *chosen* tag as a
+ * literal wrapper, e.g. `<a>…</a>`, while the browser could only ever produce
+ * `<praxis-button>…</praxis-button>`). `as` is filtered out unconditionally in `_buildProps()`
+ * below (including as a raw, undeclared HTML attribute — not just the removed Lit property)
+ * precisely so `resolveTag`/`renderBundleToString` — shared, unmodified, cross-adapter code —
+ * always resolve to `options.tag` for this adapter, on both the client and SSR paths alike.
+ * Matches `capabilities.tagPolymorphism: false` already declared in the conformance suite
+ * (`conformance.test.ts`), which this closes a real gap against: that flag already said Lit has no
+ * tag polymorphism, but SSR quietly provided a fake, DOM-inconsistent form of it until now. Need
+ * different semantics for one instance? Register a second component with a different `tag`, or
+ * set `role` directly — both already work today, unaffected by this.
+ */
+export declare function createContractComponent<TDefault extends ElementType, TProps extends UnknownProps = EmptyRecord, TVariants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: LitFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+  readonly subComponents?: TSubComponents;
+}): MergeRecords<LitContractComponent<TVariants, ExtractPluginProps<TPlugin>, RuntimeG<TDefault, TProps, TVariants, TPreset>>, TSubComponents>;
+//#endregion
+//#region ../../adapters/lit/src/render-to-string.d.ts
+/**
+ * Serializes a praxis-kit Lit component's **resolved contract** to an HTML string, without
+ * requiring a DOM — not Custom Element SSR, and not a hydration mechanism.
+ *
+ * This distinction matters and is easy to get wrong: the output element is `options.tag`
+ * (`<button>…</button>`, say), never the registered custom-element tag (`<praxis-button>`) —
+ * `createContractComponent`'s own doc comment covers why the two are different concepts ("the
+ * element Praxis models" vs. "the element actually in the DOM"). `customElements.define()` happens
+ * externally, after `createContractComponent()` returns, and this function has no way to know what
+ * name (if any) a caller eventually registers the class under, so there is no tag it could emit
+ * that's guaranteed to match. Even if it could, the browser's Custom Element upgrade mechanism only
+ * upgrades an exact tag-name match — a server-sent `<button>` can never become the live
+ * `<praxis-button>` no matter what the client bundle does, so this was never a viable
+ * SSR-then-upgrade path regardless of naming.
+ *
+ * Use this for what it actually is: previewing/testing the resolved styling + ARIA + attribute
+ * pipeline as plain HTML (static generation, snapshot tests, non-interactive contexts) — not for
+ * server-rendering markup you intend the live custom element to take over.
+ *
+ * `innerHTML` is treated as a pre-sanitized HTML string and inserted verbatim.
+ * Callers are responsible for escaping any untrusted content before passing it.
+ *
+ * ```ts
+ * // @vitest-environment node
+ * const html = renderContractToString(Button, { intent: 'primary', size: 'lg' })
+ * // => '<button class="btn btn-primary btn-lg"></button>'
+ * ```
+ */
+export declare function renderContractToString(component: LitContractComponent, props?: UnknownProps, innerHTML?: string): string;
+//#endregion
+export type { AnyFactoryOptions, ContractProps, ElementType, EmptyRecord, FactoryOptions, GenericsOf, LitContractComponent, LitFactoryOptions, PolymorphicGenerics };