praxis-kit 0.1.0 → 1.0.2

package/dist/lit/index.d.ts

@@ -32,13 +32,6 @@ type SubComponentMap = Readonly<AnyRecord>;
  * 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.
@@ -534,16 +527,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,
@@ -553,7 +536,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`. */
@@ -562,6 +547,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
@@ -616,9 +628,159 @@ 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/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/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'];
+//#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>>;
+//#endregion
 //#region ../../lib/adapter-utils/src/types/filter-predicate.d.ts
 /**
  * Determines whether a prop should be stripped before forwarding to the
@@ -634,9 +796,6 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
  */
 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.
@@ -648,14 +807,17 @@ export declare function defineContractComponent<O extends FactoryOptions>(option
  *
  * Note: this adapter targets Light DOM composition only. Shadow DOM slot
  * protocol is intentionally out of scope.
+ *
+ * Every generic parameter has a default (widened to that parameter's own *bound*, matching
+ * a wide-bound, type-erased philosophy, not `FactoryOptions`'s own narrower `EmptyRecord`-style
+ * defaults) so `LitFactoryOptions` can be used bare, as `createContractComponent`'s single
+ * `C extends LitFactoryOptions` constraint — see `ReactFactoryOptions`'s identical fix for the
+ * same reason.
  */
-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> & {
+type LitFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = AnyRecord, TVariants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<TVariants> = RecipeMap<TVariants>, 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;
 /**
@@ -668,8 +830,12 @@ type UnknownProps = AnyRecord;
  * `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.
+ *
+ * `C` is a second phantom marker — see `__contract` below — added alongside `G`, not replacing
+ * it (Phase 3 of the `defineContract` refactor), defaulting to the widest `FactoryOptions` for the
+ * same reason.
  */
-type LitContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord, G extends PolymorphicGenerics = PolymorphicGenerics> = {
+type LitContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord, G extends PolymorphicGenerics = PolymorphicGenerics, C extends FactoryOptions = FactoryOptions> = {
   new (): MergeRecords<LitElement & {
     recipe: string | undefined;
     praxisClass: string | undefined;
@@ -689,45 +855,70 @@ type LitContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, T
    * set, but kept consistent with the established shape regardless.
    */
   readonly __generics?: G;
+  /**
+   * Type-only; never assigned at runtime — same rationale as `__generics` above and
+   * React's/Preact's `__contract` (see `HasContract<C>`, `@praxis-kit/contract-props`). Carries
+   * the *complete* contract this component was built from (`C`, the argument
+   * `createContractComponent<C extends LitFactoryOptions>` was actually called with), not just
+   * its `PolymorphicGenerics` projection. `GenericsOf`/`ContractProps` (./contract-props) recover
+   * `G` *through* this field now (`ContractGenericsOf<C>`), rather than from a separately-computed
+   * `G` that never carried plugin-contributed props — see that file's doc comment for the bug this
+   * closes.
+   */
+  readonly __contract?: C;
 };
 //#endregion
-//#region ../../lib/contract-props/src/has-generics.d.ts
+//#region ../../lib/contract-props/src/has-contract.d.ts
 /**
- * The phantom-marker shape read back via `T extends HasGenerics<infer G> ? G : never`. See the
- * README for why this exists.
+ * The phantom-marker shape read back via `T extends HasContract<infer C> ? C : never` — the
+ * contract-retention counterpart to `HasGenerics<G>` in this same package. Where `HasGenerics<G>`
+ * lets a built component recover the `PolymorphicGenerics` an adapter derived for it,
+ * `HasContract<C>` lets it recover the *complete, authoritative contract* (`C`, the argument
+ * `createContractComponent<C extends XFactoryOptions>` was actually called with) it was derived
+ * from — the two are deliberately separate markers, not one broadened to do both jobs: `G` is
+ * "what the adapter needs to implement the component," `C` is "what the component was configured
+ * with" (see `DECISIONS.md`'s `defineContract` entry). A component carries both.
  *
- * 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.
+ * Type-only: never assigned at runtime, same rationale as `HasGenerics<G>` (see that type's own
+ * doc comment) — a `createContractComponent` return value gets this shape via a type assertion,
+ * not a real property write.
  *
- * 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.
+ * Unconstrained (no `C extends FactoryOptions` bound), matching `HasGenerics<G>`'s own choice —
+ * this package has no dependency on `@praxis-kit/core`/`@praxis-kit/primitive`, and adding one
+ * just to write a bound here isn't worth it: the accessor types that actually consume `C`
+ * (`ContractTagOf<C>`, etc., in `@praxis-kit/primitive`) already declare their own constraint.
+ *
+ * Do **not** "harden" this with a `unique symbol` or other nominal brand, for the same reason
+ * `HasGenerics<G>` doesn't: a real component's callable type needs to structurally satisfy this
+ * shape by declaring the same inline optional field, not by importing a nominal brand.
  */
-interface HasGenerics<G> {
-  readonly __generics?: G;
+interface HasContract<C> {
+  readonly __contract?: C;
 }
 //#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>`,
+ * the Lit analog of React's/Preact's `ContractGenericsOf`-via-`__contract` recovery.
+ * Needs a 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>`
+ * returns `LitContractComponent<TVariants, TPluginProps, G, C>`, 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.
+ *
+ * Re-pointed at `__contract` (Phase 4 of the `defineContract` refactor) rather than the
+ * separately-computed `__generics` field it used to read: `__generics`'s own `G` was assembled
+ * from `TDefault`/`Props`/`TVariants`/`TPreset` alone, with **no plugin-contributed props folded
+ * in** — a real, previously-open gap (`findings.md` #44 — Lit/Web's `ContractProps` silently
+ * missing plugin props entirely, not just unionized like React/Preact's old bug). `ContractGenericsOf<C>`
+ * folds `ExtractPluginProps<TPlugin>` into `props` once, at the canonical projection point, so this
+ * fix comes for free from routing through it — no separate merge needed here. `__generics` itself
+ * is untouched (still assembled, still readable) — this file just no longer reads it.
+ *
+ * Falls back to the widest `PolymorphicGenerics` for any non-praxis-kit value, the same "no
+ * marker, nothing to recover" case `HasContract<C>`'s own `never` branch covers for React/Preact.
  */
-type GenericsOf<T extends HasGenerics<PolymorphicGenerics>> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? G : PolymorphicGenerics;
+type GenericsOf<T extends HasContract<FactoryOptions>> = T extends HasContract<infer C extends FactoryOptions> ? ContractGenericsOf<C> extends (infer G extends PolymorphicGenerics) ? G : PolymorphicGenerics : 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
@@ -742,16 +933,32 @@ type GenericsOf<T extends HasGenerics<PolymorphicGenerics>> = T extends HasGener
  * 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.
  *
+ * `data-*` attributes pass through (`DataAttributes` below). `_buildProps()` in
+ * `createContractComponent` scans every attribute set on the custom element into the pipeline, so
+ * `<praxis-button data-slot="…">` is real, forwarded input — a `data-*` a contract sets in
+ * `defaults` (`data-slot`, the near-universal styling hook) has to be a member of `ContractProps`
+ * for a consumer to type it. Other global/host attributes (`id`, `class`, `slot`, `aria-*`,
+ * `role`) are equally accepted on the element but are *not* part of this type: they are DOM
+ * globals a caller sets on the element directly, not part of a component's declared prop contract.
+ * `data-*` is the exception because contracts author it as an overridable prop.
+ *
  * ```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>>>> & {
+type ContractProps<T extends HasContract<FactoryOptions>> = Simplify<OmitIndexSignature<PropsOf<GenericsOf<T>>> & OmitIndexSignature<VariantProps<VariantsOf<GenericsOf<T>>>> & DataAttributes & {
   as?: never;
   recipe?: keyof RecipeOf<GenericsOf<T>>;
 }>;
+/**
+ * `data-*` attribute passthrough. The value type is `string | number | boolean | undefined` —
+ * what a `data-*` attribute serializes to (mirrors the React adapter's own `DataAttributes`).
+ */
+type DataAttributes = {
+  [key: `data-${string}`]: string | number | boolean | undefined;
+};
 //#endregion
 //#region ../../adapters/lit/src/create-contract-component.d.ts
 /**
@@ -823,10 +1030,15 @@ type ContractProps<T extends HasGenerics<PolymorphicGenerics>> = Simplify<OmitIn
  * 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.
+ *
+ * `TDefault`/`TProps`/`TVariants`/`TPreset`/`TPlugin` are each `ContractXOf<C>`-derived *defaults*
+ * on this function's own type parameter list, mirroring every other adapter's identical fix — see
+ * `@praxis-kit/react`'s own doc comment for why (computed as function type-parameter defaults, not
+ * inline body computations, which doesn't resolve for a still-abstract `C`).
  */
-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> & {
+export declare function createContractComponent<C extends LitFactoryOptions, TDefault extends ElementType = ContractTagOf<C>, TProps extends UnknownProps = ContractPropsOf<C>, TVariants extends Readonly<VariantMap> = ContractVariantsOf<C>, TPreset extends RecipeMap<VariantMap> = ContractPresetOf<C>, TPlugin extends AnyClassPluginFactory = ContractPluginOf<C>, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: C & {
   readonly subComponents?: TSubComponents;
-}): MergeRecords<LitContractComponent<TVariants, ExtractPluginProps<TPlugin>, RuntimeG<TDefault, TProps, TVariants, TPreset>>, TSubComponents>;
+}): MergeRecords<LitContractComponent<TVariants, ExtractPluginProps<TPlugin>, ContractGenericsOf<C>, C>, TSubComponents>;
 //#endregion
 //#region ../../adapters/lit/src/render-to-string.d.ts
 /**
@@ -859,4 +1071,4 @@ export declare function createContractComponent<TDefault extends ElementType, TP
  */
 export declare function renderContractToString(component: LitContractComponent, props?: UnknownProps, innerHTML?: string): string;
 //#endregion
-export type { AnyFactoryOptions, ContractProps, ElementType, EmptyRecord, FactoryOptions, GenericsOf, LitContractComponent, LitFactoryOptions, PolymorphicGenerics };
+export type { ContractProps, ElementType, EmptyRecord, FactoryOptions, GenericsOf, LitContractComponent, LitFactoryOptions, PolymorphicGenerics };