praxis-kit 0.1.0 → 1.0.2

package/dist/contract/index.d.ts

@@ -1,6 +1,6 @@
 import "clsx";
 import { Diagnostic, DiagnosticInput, Diagnostics as Diagnostics$1, DiagnosticsMode } from "../_shared/diagnostics.js";
-import { ReadonlyDeep, RequireAtLeastOne, Simplify } from "type-fest";
+import { Except, ReadonlyDeep, RequireAtLeastOne, SetRequired, Simplify } from "type-fest";
 //#region ../../lib/foundation/src/string-map.d.ts
 /**
  * A string-keyed object whose values are of type `T`.
@@ -24,6 +24,38 @@ type EmptyRecord = Record<never, never>;
  * `{ Header, Content, Footer }`.
  */
 type SubComponentMap = Readonly<AnyRecord>;
+/**
+ * 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;
@@ -171,6 +203,64 @@ type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSe
 //#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;
+}
+//#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>>;
@@ -242,6 +332,7 @@ type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends Var
  *  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 = {
@@ -427,16 +518,6 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
 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,
@@ -446,7 +527,9 @@ type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, Reci
  * `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.
+ * value that does not exist is a compile error. Leaving `V` at the bare `VariantMap` instead
+ * (whether via `FactoryOptions`'s own default or an explicit erased instantiation) forgets that
+ * shape entirely, so the same invalid condition becomes a silent no-op instead.
  */
 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`. */
@@ -455,6 +538,33 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
   readonly name?: string;
   /** Values used for the component's own (non-variant) props when the consumer omits them. */
   readonly defaults?: Partial<NoInfer<Props>>;
+  /**
+   * Optional, type-only declaration of this component's complete own-prop shape — present purely
+   * for type recovery, never read at runtime (see `declareProps` in `@praxis-kit/adapter-utils`).
+   *
+   * `defaults` alone can only prove a prop *has a default*, not that it's the complete prop model
+   * a component accepts — a `defaults: { size: 'md' }` component may still take `onClick`,
+   * `disabled`, and other props with no default at all, none of which a `defaults`-only recovery
+   * can see (see `ContractPropsFrom`'s own doc comment for the general shape of this problem).
+   * `props` closes that gap: when present, `ContractPropsOf<C>` / `ContractProps<typeof Component>`
+   * recover this declared type directly and exactly, in place of the necessarily-partial,
+   * literal-widened recovery `defaults` alone allows.
+   *
+   * Typed as `object | undefined`, not `NoInfer<Props> | undefined` like `defaults`/`onElement` —
+   * deliberately decoupled from this interface's own `Props` generic, unlike those two fields.
+   * `defaults`/`onElement` are tied to `Props` because real runtime code reads them against a
+   * concretely-resolved `Props` for a real call; `props` is never read at runtime at all (see
+   * above), so it has no such need, and tying it to `Props extends AnyRecord` would force every
+   * hand-declared prop `interface`/`type` an author passes through `declareProps<Props>()` to
+   * structurally satisfy `Record<string, unknown>` — a real TypeScript limitation (a named type
+   * without an index signature never satisfies that, even via plain assignment, only a fresh
+   * object literal does) that would make this field far more awkward to use for its one real job:
+   * carrying an author's own already-precise prop type through untouched. `ContractPropsFrom`
+   * (`contract-model.ts`) recovers the real value here structurally, straight off `O`'s own
+   * literal type — independent of this field's declared type, same as every other `Contract*From`
+   * derivation in that file.
+   */
+  readonly props?: object | undefined;
   /**
    * 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
@@ -509,7 +619,9 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
    *
    * Return a cleanup function to run when the instance unmounts.
    */
-  readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
+  readonly onElement?: {
+    onElement(element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>): void | (() => void);
+  }['onElement'];
 };
 //#endregion
 //#region ../../lib/primitive/src/types/factory/resolved-factory-options.d.ts
@@ -546,6 +658,210 @@ type ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props ex
   readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 //#endregion
+//#region ../../lib/primitive/src/types/factory/contract-input.d.ts
+/**
+ * The author-facing input constraint for `defineContract` (`@praxis-kit/adapter-utils`) —
+ * `FactoryOptions` with `tag` and `name` promoted from optional to required, and `diagnostics`
+ * removed entirely.
+ *
+ * `tag`/`name` are required here, not just conventionally recommended, because nothing in
+ * `FactoryOptions` itself enforces either: today `{}` satisfies `FactoryOptions`, and an absent
+ * `tag` silently resolves to `'div'` inside `resolveFactoryOptions` — a contract author who forgets
+ * `tag` gets no signal at all. Requiring both here, at the one boundary every contract passes
+ * through before construction, closes that gap without touching `FactoryOptions` itself (which
+ * stays permissive, since it's also the type any type-erased context still needs to describe).
+ *
+ * `diagnostics` is omitted, not just left optional: per `FactoryOptions.diagnostics`'s own doc
+ * comment, it's adapter-resolved only ("spread in by `resolveAdapterCommonOptions`") — a contract
+ * author overrides diagnostics behavior through `enforcement.diagnostics` instead, never this
+ * field directly, so there's nothing for an author to supply here in the first place.
+ *
+ * `Props` is `ContractInput`'s first type parameter (matching `FactoryOptions`'s own field-order
+ * intuition, even though `FactoryOptions` itself puts `TDefault` first) purely for readability as a
+ * standalone type annotation — `defineContract` itself constrains its own `const O` against the
+ * bare, all-defaulted `ContractInput` (see that function's own doc comment), never
+ * `ContractInput<Props>` with `Props` given explicitly.
+ *
+ * Every other parameter's default widens to that parameter's own *bound* (`Readonly<VariantMap>`,
+ * `RecipeMap<V>`, `AnyClassPluginFactory`, `ElementType`), not `FactoryOptions`'s narrower
+ * `EmptyRecord`-style defaults — deliberate and load-bearing: a real author's contract (real
+ * variants, a real preset, a real plugin) must structurally satisfy whatever bound this type
+ * presents, and a narrow bound would only accept an empty-variants, no-preset, no-plugin contract.
+ * See `DECISIONS.md`'s `defineContract` entry for the concrete bug this bound choice fixes.
+ */
+type ContractInput<Props extends AnyRecord = AnyRecord, TDefault extends ElementType = ElementType, V extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<V> = RecipeMap<V>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = SetRequired<Except<FactoryOptions<TDefault, Props, V, TPreset, TPlugin, TAllowed>, 'diagnostics'>, 'tag' | 'name'>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-model.d.ts
+/**
+ * The pipeline this file implements:
+ *
+ * ```text
+ * O (a raw contract literal)
+ *   → Contract*From<O>        one derivation per dimension, straight off O's own shape
+ *   → ContractDimensions<O>   the six derivations, assembled
+ *   → ContractModel<...>      the same six values, as a required-field carrier
+ *   → ContractModelOf<C>      resolves an already-`defineContract`-ed C's real model,
+ *                             or reconstructs one from a raw C via ContractModelFrom
+ * ```
+ *
+ * See `DECISIONS.md`'s `defineContract` entry for the TypeScript limitations that shaped the
+ * derivations below.
+ */
+/**
+ * Canonical type-level representation of a contract's dimensions — the contract-level counterpart
+ * to `PolymorphicGenerics`. Every field is required, so a field's presence is never ambiguous the
+ * way it is on an optional `FactoryOptions` field.
+ */
+interface ContractModel<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, V extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<VariantMap> = RecipeMap<VariantMap>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> {
+  readonly tag: TDefault;
+  readonly props: Props;
+  readonly variants: V;
+  readonly preset: TPreset;
+  readonly plugin: TPlugin;
+  readonly allowed: TAllowed;
+}
+/**
+ * The phantom-marker shape read back via `T extends HasContractModel<infer M> ? M : ...` — the
+ * contract-level counterpart to `lib/contract-props`'s `HasGenerics<G>`. Type-only: never assigned
+ * at runtime.
+ *
+ * `__model` is **required**, not optional like `HasGenerics<G>`'s `__generics?` — an optional field
+ * would make `C extends HasContractModel<infer M>` trivially succeed for any `C`, defeating the
+ * one thing this marker exists to answer: did `C` really go through `defineContract`?
+ */
+interface HasContractModel<M extends ContractModel = ContractModel> {
+  readonly __model: M;
+}
+type ContractTagFrom<O> = O extends {
+  tag: infer TDefault extends ElementType;
+} ? TDefault : ElementType;
+/** `'img'` → `string`, `1` → `number`, `true` → `boolean` — undoes `defineContract`'s `const O`
+ *  literal narrowing so a `defaults` value doesn't become the only value a caller may pass. */
+type WidenLiteral<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type WidenShallow<T> = { [K in keyof T]: WidenLiteral<T[K]>; };
+/** What the author explicitly declared, via `props: declareProps<Props>()`
+ *  (`@praxis-kit/adapter-utils`) — used exactly as declared, no `Partial`/widening/`data-*`
+ *  stripping (see `DefaultPropsFrom` for why those exist there but not here). */
+type DeclaredPropsFrom<O> = O extends {
+  props: infer Props extends object | undefined;
+} ? [NonNullable<Props>] extends [never] ? never : NonNullable<Props> & AnyRecord : never;
+/** What can be inferred from `defaults` — partial at best, since a default only proves a prop
+ *  *has* one, not that it's the complete prop set. `Partial`: a defaulted prop is optional to the
+ *  caller by definition. `data-*` keys are dropped — every adapter has its own passthrough for
+ *  those already (finding #43). */
+type DefaultPropsFrom<O> = O extends {
+  defaults: infer Props extends AnyRecord;
+} ? Partial<WidenShallow<Omit<Props, Extract<keyof Props, `data-${string}`>>>> : never;
+/** Declared beats defaulted beats nothing. `[X] extends [never]`, not bare `X extends never` —
+ *  tuple-wrapped so the check doesn't distribute if `X` is ever a union containing `never`. */
+type ContractPropsFrom<O> = [DeclaredPropsFrom<O>] extends [never] ? [DefaultPropsFrom<O>] extends [never] ? EmptyRecord : DefaultPropsFrom<O> : DeclaredPropsFrom<O>;
+type ContractVariantsFrom<O> = O extends {
+  styling: {
+    variants: infer V extends Readonly<VariantMap>;
+  };
+} ? V : Readonly<EmptyRecord>;
+type ContractPresetFrom<O> = O extends {
+  styling: {
+    presets: infer TPreset extends RecipeMap<VariantMap>;
+  };
+} ? TPreset : Readonly<EmptyRecord>;
+type ContractPluginFrom<O> = O extends {
+  styling: {
+    plugin: infer TPlugin extends AnyClassPluginFactory;
+  };
+} ? TPlugin : AnyClassPluginFactory;
+type ContractAllowedFrom<O> = O extends {
+  enforcement: {
+    allowedAs: readonly (infer TAllowed extends ElementType)[];
+  };
+} ? TAllowed : ElementType;
+/** The six derivations above, assembled — the direct input to `ContractModel`. */
+type ContractDimensions<O> = {
+  readonly tag: ContractTagFrom<O>;
+  readonly props: ContractPropsFrom<O>;
+  readonly variants: ContractVariantsFrom<O>;
+  readonly preset: ContractPresetFrom<O>;
+  readonly plugin: ContractPluginFrom<O>;
+  readonly allowed: ContractAllowedFrom<O>;
+};
+/**
+ * Builds a `ContractModel` from a raw literal `O` — the fallback path `ContractModelOf<C>` uses
+ * when `C` never went through `defineContract` (no `__model` marker to read directly), and what
+ * `defineContract` itself attaches as that marker for a `C` that did.
+ */
+type ContractModelFrom<O> = ContractDimensions<O> extends (infer D extends ContractDimensions<O>) ? ContractModel<D['tag'], D['props'], D['variants'], D['preset'], D['plugin'], D['allowed']> : never;
+/**
+ * Resolves "does `C` carry a real `ContractModel` already, or do we need to build one from its raw
+ * shape" — every `Contract*Of` accessor (`contract-of.ts`) is a one-line projection off this.
+ */
+type ContractModelOf<C> = C extends HasContractModel<infer M> ? M : ContractModelFrom<C>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/defined-contract.d.ts
+/**
+ * `defineContract`'s return type — `O` itself (the pure-identity return value, see that function's
+ * own doc comment for why no defaults are injected), intersected with the `ContractModel` phantom
+ * marker `defineContract` established from `O` at its own call site. Per the `defineContract`
+ * proposal (`DECISIONS.md`): "the semantic distinction that matters is `FactoryOptions` describes
+ * *acceptable* structure, `DefinedContract<O>` represents a *concrete, established* contract" —
+ * `M` is exactly that establishment, made concrete and inspectable rather than left implicit in
+ * `O`'s own nested optional fields.
+ */
+type DefinedContract<O extends ContractInput, M extends ContractModel = ContractModel> = O & HasContractModel<M>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-of.d.ts
+/**
+ * `FactoryOptions`-level accessor family, mirroring `polymorphic-generics.ts`'s `*Of<T>`
+ * convention (`DefaultOf<G>`, `PropsOf<G>`, etc.) but applied one layer up, to a contract itself
+ * rather than to the `PolymorphicGenerics` an adapter derives from it.
+ *
+ * Named with a `Contract` prefix specifically to avoid colliding with `polymorphic-generics.ts`'s
+ * own `PropsOf`/`VariantsOf`/`RecipeOf`/`AllowedOf`/`DefaultOf` — both families are re-exported
+ * from `@praxis-kit/core`, so a name clash would be a real conflict, not a style nit.
+ *
+ * Each accessor is a trivial projection off `ContractModelOf<C>` (`contract-model.ts`) — the one
+ * place that resolves "does `C` carry a real `ContractModel` (via `defineContract`) or does one
+ * need reconstructing from `C`'s raw shape," so every accessor shares one implementation of that
+ * resolution rather than repeating it. See `contract-model.ts`'s own doc comments for the
+ * `ContractXFrom<O>` derivation each of these ultimately reads through, and `DECISIONS.md`'s
+ * `defineContract` entry for the design history behind the required-pattern-match technique.
+ */
+type ContractTagOf<C extends FactoryOptions> = ContractModelOf<C>['tag'];
+/** See this file's own doc comment. Best-effort when `C` has no `ContractModel` marker — see
+ *  `ContractPropsFrom`'s own doc comment for why. */
+type ContractPropsOf<C extends FactoryOptions> = ContractModelOf<C>['props'];
+/** See this file's own doc comment. */
+type ContractVariantsOf<C extends FactoryOptions> = ContractModelOf<C>['variants'];
+/** See this file's own doc comment. */
+type ContractPresetOf<C extends FactoryOptions> = ContractModelOf<C>['preset'];
+/** See this file's own doc comment. */
+type ContractPluginOf<C extends FactoryOptions> = ContractModelOf<C>['plugin'];
+/** See this file's own doc comment. */
+type ContractAllowedOf<C extends FactoryOptions> = ContractModelOf<C>['allowed'];
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-generics.d.ts
+/**
+ * The canonical projection from a defined contract `C` to the `PolymorphicGenerics` shape every
+ * adapter's prop types are built from — the one place "G" gets computed, so it can no longer
+ * silently drift per adapter the way today's hand-assembled `PolymorphicGenerics<...>` instantiation
+ * at each `createContractComponent` call site can (see `ContractGenericsWithAllowedOf` below for
+ * the one confirmed instance of that drift).
+ *
+ * Folds the class-resolution plugin's own contributed props (`ExtractPluginProps<TPlugin>`) into
+ * `props` here, once, rather than leaving each adapter's `ContractProps` to re-derive that merge
+ * via its own distributive conditional type on every read — the root cause of the ~22-member
+ * layout-union bug PR #95 patched per-adapter (see `DECISIONS.md`'s `defineContract` entry).
+ */
+type ContractGenericsOf<C extends FactoryOptions> = PolymorphicGenerics<ContractTagOf<C>, MergeRecords<ContractPropsOf<C>, ExtractPluginProps<ContractPluginOf<C>>>, ContractVariantsOf<C>, ContractPresetOf<C>>;
+/**
+ * Same projection as `ContractGenericsOf`, additionally threading `TAllowed` through to
+ * `PolymorphicGenerics`'s own `TAllowed` parameter. Only React's `createContractComponent`
+ * currently uses this variant — every other adapter uses the plain `ContractGenericsOf` above,
+ * matching their current behavior of not narrowing `as` via `enforcement.allowedAs` at the type
+ * level (the ARIA/tag-resolution engine still enforces `allowedAs` identically at runtime for all
+ * adapters regardless of which projection their types use).
+ */
+type ContractGenericsWithAllowedOf<C extends FactoryOptions> = PolymorphicGenerics<ContractTagOf<C>, MergeRecords<ContractPropsOf<C>, ExtractPluginProps<ContractPluginOf<C>>>, ContractVariantsOf<C>, ContractPresetOf<C>, ContractAllowedOf<C>>;
+//#endregion
 //#region ../../lib/contract/src/types/aria/invalid-result-input.d.ts
 /** Shared input shape for `invalidWithFix`/`invalidWithoutFix`. */
 type InvalidResultInput = {
@@ -674,4 +990,70 @@ interface Diagnostics {
   report(diagnostic: Diagnostic): Diagnostic;
 }
 //#endregion
-export type { AnyFactoryOptions, AriaContext, AriaFix, AriaFixResult, AriaPhase, AriaResult, AriaRule, Diagnostics, EnforcementOptions, FactoryOptions, FixKind, IntrinsicProps, AriaInvalidResult as InvalidResult, AriaInvalidWithFix as InvalidWithFix, AriaInvalidWithoutFix as InvalidWithoutFix, NormalizeFn, PropNormalizer, RemoveAttributeFixKind, ResolvedFactoryOptions, Severity, StateNormalizerConfig, StylingOptions, ValidResult };
+//#region ../../lib/adapter-utils/src/runtime/define-contract.d.ts
+/**
+ * Takes a concrete contract input and establishes its canonical `ContractModel` from it — the
+ * contract-definition boundary every adapter's `createContractComponent` builds on.
+ *
+ * Deliberately a typed identity function at runtime, not a normalizer — no defaults are injected,
+ * no fields are added or removed. `O` is inferred once, from the literal argument, and
+ * `ContractModelFrom<O>` (`contract-model.ts`) does the rest — the model's six dimensions are its
+ * properties, not something this function's own signature has to think about individually.
+ * `ContractInput`'s bound requires `tag` and `name`, each a non-empty string; `tag`/`name`
+ * additionally reject the empty-string literal specifically, via a self-referential constraint on
+ * `O` itself, since a field type alone can't express "reject this one specific literal."
+ *
+ * ```ts
+ * export const boxContract = defineContract({ tag: 'div', name: 'Box' })
+ * export const buttonContract = defineContract({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: { variants: { intent: { primary: 'btn--primary' } } },
+ * })
+ * ```
+ */
+export declare function defineContract<const O extends ContractInput & {
+  readonly tag: O['tag'] extends '' ? never : ElementType;
+  readonly name: O['name'] extends '' ? never : string;
+}>(options: O): DefinedContract<O, ContractModelFrom<O>>;
+//#endregion
+//#region ../../lib/adapter-utils/src/runtime/declare-props.d.ts
+/**
+ * Type-only prop declaration helper for a `defineContract` config's `props` field
+ * (`FactoryOptions.props`, `lib/primitive`) — never called for its return value (always
+ * `undefined` at runtime), only for its type. Exists so an author can declare a component's
+ * complete prop shape inline, in the same object literal `defineContract`'s single `const O`
+ * parameter already infers from, without a separate generic argument at the
+ * `defineContract`/`createContractComponent` call site itself — the fix for the gap
+ * `ContractPropsFrom` (`lib/primitive`) documents: `defaults` alone can only prove a prop *has
+ * a default*, not that it's the complete prop model.
+ *
+ * ```ts
+ * interface ButtonProps {
+ *   onClick?: () => void
+ *   disabled?: boolean
+ * }
+ *
+ * const buttonContract = defineContract({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   props: declareProps<ButtonProps>(),
+ *   defaults: { type: 'button' },
+ * })
+ * ```
+ *
+ * Optional — most contracts still don't need this. Only reach for it when `defaults` doesn't
+ * already capture every prop the component accepts.
+ *
+ * Bounded by `object`, not `AnyRecord` (`Record<string, unknown>`) like `Props` is everywhere else
+ * in this pipeline — deliberately. A hand-declared `interface`/`type` prop shape (the overwhelmingly
+ * common case an author reaches for here) has no index signature, and TypeScript's generic
+ * *constraint* satisfaction (unlike plain value assignment) requires one to satisfy
+ * `Record<string, unknown>` — a real, well-known TypeScript limitation, not a design choice this
+ * file is working around loosely. `object` has no such requirement and accepts the same real
+ * interfaces plain assignment already does; `ContractPropsFrom` (`lib/primitive`) matches this
+ * field back out with the identical `object`-bounded pattern for the same reason.
+ */
+export declare function declareProps<Props extends object>(): Props | undefined;
+//#endregion
+export type { AriaContext, AriaFix, AriaFixResult, AriaPhase, AriaResult, AriaRule, ContractAllowedOf, ContractDimensions, ContractGenericsOf, ContractGenericsWithAllowedOf, ContractInput, ContractModel, ContractModelFrom, ContractModelOf, ContractPluginOf, ContractPresetOf, ContractPropsOf, ContractTagOf, ContractVariantsOf, DefinedContract, Diagnostics, EnforcementOptions, FactoryOptions, FixKind, HasContractModel, IntrinsicProps, AriaInvalidResult as InvalidResult, AriaInvalidWithFix as InvalidWithFix, AriaInvalidWithoutFix as InvalidWithoutFix, NormalizeFn, PropNormalizer, RemoveAttributeFixKind, ResolvedFactoryOptions, Severity, StateNormalizerConfig, StylingOptions, ValidResult };

package/dist/contract/index.js

@@ -208,6 +208,71 @@ const selectedProps = makeStateNormalizer({
 	falseState: "synthesize"
 });
 //#endregion
+//#region ../../lib/adapter-utils/src/runtime/define-contract.ts
+/**
+* Takes a concrete contract input and establishes its canonical `ContractModel` from it — the
+* contract-definition boundary every adapter's `createContractComponent` builds on.
+*
+* Deliberately a typed identity function at runtime, not a normalizer — no defaults are injected,
+* no fields are added or removed. `O` is inferred once, from the literal argument, and
+* `ContractModelFrom<O>` (`contract-model.ts`) does the rest — the model's six dimensions are its
+* properties, not something this function's own signature has to think about individually.
+* `ContractInput`'s bound requires `tag` and `name`, each a non-empty string; `tag`/`name`
+* additionally reject the empty-string literal specifically, via a self-referential constraint on
+* `O` itself, since a field type alone can't express "reject this one specific literal."
+*
+* ```ts
+* export const boxContract = defineContract({ tag: 'div', name: 'Box' })
+* export const buttonContract = defineContract({
+*   tag: 'button',
+*   name: 'Button',
+*   styling: { variants: { intent: { primary: 'btn--primary' } } },
+* })
+* ```
+*/
+function defineContract(options) {
+	return options;
+}
+//#endregion
+//#region ../../lib/adapter-utils/src/runtime/declare-props.ts
+/**
+* Type-only prop declaration helper for a `defineContract` config's `props` field
+* (`FactoryOptions.props`, `lib/primitive`) — never called for its return value (always
+* `undefined` at runtime), only for its type. Exists so an author can declare a component's
+* complete prop shape inline, in the same object literal `defineContract`'s single `const O`
+* parameter already infers from, without a separate generic argument at the
+* `defineContract`/`createContractComponent` call site itself — the fix for the gap
+* `ContractPropsFrom` (`lib/primitive`) documents: `defaults` alone can only prove a prop *has
+* a default*, not that it's the complete prop model.
+*
+* ```ts
+* interface ButtonProps {
+*   onClick?: () => void
+*   disabled?: boolean
+* }
+*
+* const buttonContract = defineContract({
+*   tag: 'button',
+*   name: 'Button',
+*   props: declareProps<ButtonProps>(),
+*   defaults: { type: 'button' },
+* })
+* ```
+*
+* Optional — most contracts still don't need this. Only reach for it when `defaults` doesn't
+* already capture every prop the component accepts.
+*
+* Bounded by `object`, not `AnyRecord` (`Record<string, unknown>`) like `Props` is everywhere else
+* in this pipeline — deliberately. A hand-declared `interface`/`type` prop shape (the overwhelmingly
+* common case an author reaches for here) has no index signature, and TypeScript's generic
+* *constraint* satisfaction (unlike plain value assignment) requires one to satisfy
+* `Record<string, unknown>` — a real, well-known TypeScript limitation, not a design choice this
+* file is working around loosely. `object` has no such requirement and accepts the same real
+* interfaces plain assignment already does; `ContractPropsFrom` (`lib/primitive`) matches this
+* field back out with the identical `object`-bounded pattern for the same reason.
+*/
+function declareProps() {}
+//#endregion
 //#region ../../lib/contract/src/aria/factories.ts
 /**
 * Builds a correctly-literal-typed `fixable: false` `AriaResult`. Exists so a rule author can
@@ -338,4 +403,4 @@ function mergeContracts(...contracts) {
 	};
 }
 //#endregion
-export { activeContract, activeProps, createRemoveAttributeRule, disabledContract, disabledProps, expandedContract, expandedProps, invalidContract, invalidProps, invalidWithFix, invalidWithoutFix, loadingContract, loadingProps, makeStateNormalizer, mergeContracts, pressedContract, pressedProps, readonlyContract, readonlyProps, removeAttributeFix, selectedContract, selectedProps };
+export { activeContract, activeProps, createRemoveAttributeRule, declareProps, defineContract, disabledContract, disabledProps, expandedContract, expandedProps, invalidContract, invalidProps, invalidWithFix, invalidWithoutFix, loadingContract, loadingProps, makeStateNormalizer, mergeContracts, pressedContract, pressedProps, readonlyContract, readonlyProps, removeAttributeFix, selectedContract, selectedProps };

package/dist/eslint/index.js

@@ -138,10 +138,16 @@ const iterate = Object.freeze({
 function isString(value) {
 	return typeof value === "string";
 }
+function isNumber(value) {
+	return typeof value === "number";
+}
 function isObject(value, excludeArrays = false) {
 	if (value === null || typeof value !== "object") return false;
 	return excludeArrays ? !Array.isArray(value) : true;
 }
+function isUndefined(value) {
+	return value === void 0;
+}
 //#endregion
 //#region ../../plugins/eslint/src/utils/ast.ts
 /** Narrows any node-shaped value to one whose `value` property is a string — the common check
@@ -158,7 +164,7 @@ function asArrayExpression(node) {
 function asNumericLiteral(node) {
 	if (node?.type === "Literal") {
 		const { value } = node;
-		if (typeof value === "number") return value;
+		if (isNumber(value)) return value;
 	}
 	if (node?.type === "UnaryExpression") {
 		const { operator, argument } = node;
@@ -195,7 +201,7 @@ function isFactoryCall(node, calleeNames) {
 }
 function extractVariantValues(node) {
 	const valuesObj = asObjectExpression(node);
-	if (!valuesObj) return void 0;
+	if (isUndefined(valuesObj)) return void 0;
 	const values = /* @__PURE__ */ new Set();
 	iterate.forEach(valuesObj.properties, (prop) => {
 		if (prop.type !== "Property") return;
@@ -206,14 +212,14 @@ function extractVariantValues(node) {
 }
 function extractVariantMap(variantsNode) {
 	const variantsObj = asObjectExpression(variantsNode);
-	if (!variantsObj) return void 0;
+	if (isUndefined(variantsObj)) return void 0;
 	const map = /* @__PURE__ */ new Map();
 	iterate.forEach(variantsObj.properties, (prop) => {
 		if (prop.type !== "Property") return;
 		const key = getPropertyKey(prop);
-		if (!key) return;
+		if (isUndefined(key)) return;
 		const values = extractVariantValues(prop.value);
-		if (!values) return;
+		if (isUndefined(values)) return;
 		map.set(key, values);
 	});
 	return map;