praxis-kit 7.4.0 → 7.8.0

package/dist/react/index.d.ts

@@ -1,8 +1,9 @@
-import { U as UnknownProps, E as ElementType, a as EmptyRecord, V as VariantMap, N as NoVariants, R as RecipeMap, b as NoPreset, A as AnyClassPluginFactory, c as AnyRecord, d as ReactFactoryOptions, M as MergeRecords, P as PolymorphicComponent, e as PolymorphicGenerics, f as ExtractPluginProps } from '../react-options-BnjZpdVh.js';
-export { g as AnyFactoryOptions, h as ElementRef, F as FactoryOptions, i as PolymorphicProps, j as PolymorphicWithAsChild, k as PolymorphicWithRender, l as RenderCallbackProps, S as Slottable, m as SlottableProps, n as composeRefs, o as defineContractComponent, n as mergeRefs } from '../react-options-BnjZpdVh.js';
+import { U as UnknownProps, E as ElementType, a as EmptyRecord, V as VariantMap, N as NoVariants, R as RecipeMap, b as NoPreset, A as AnyClassPluginFactory, c as AnyRecord, d as ReactFactoryOptions, M as MergeRecords, P as PolymorphicComponent, e as PolymorphicGenerics, f as ExtractPluginProps } from '../react-options-DU3EdFOv.js';
+export { g as AnyFactoryOptions, C as ContractProps, h as ElementRef, F as FactoryOptions, i as PolymorphicProps, j as PolymorphicWithAsChild, k as PolymorphicWithRender, l as RenderCallbackProps, S as Slottable, m as SlottableProps, n as composeRefs, o as defineContractComponent, n as mergeRefs } from '../react-options-DU3EdFOv.js';
 import * as react from 'react';
 import { ReactElement, Ref } from 'react';
 import 'type-fest';
+import '@praxis-kit/contract-props';
 import '../_shared/diagnostics.js';
 
 /**

package/dist/react/index.js

@@ -15,7 +15,7 @@ import {
   makeCloneSlotChild,
   mergeRefs,
   render
-} from "../chunk-EIKPSL26.js";
+} from "../chunk-QYP7KLRE.js";
 
 // ../../adapters/react/src/current/create-contract-component.ts
 import { useCallback, useRef } from "react";
@@ -59,7 +59,12 @@ function createContractComponent(options) {
     const onElementRef = useCallback((el) => {
       if (!onElement) return;
       if (el) {
-        cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+        cleanupRef.current?.();
+        cleanupRef.current = void 0;
+        cleanupRef.current = onElement(
+          el,
+          () => propsRef.current
+        ) ?? void 0;
       } else {
         cleanupRef.current?.();
         cleanupRef.current = void 0;

package/dist/react/legacy.d.ts

@@ -1,7 +1,8 @@
-import { E as ElementType, U as UnknownProps, a as EmptyRecord, V as VariantMap, N as NoVariants, R as RecipeMap, b as NoPreset, A as AnyClassPluginFactory, d as ReactFactoryOptions, P as PolymorphicComponent, e as PolymorphicGenerics, M as MergeRecords, f as ExtractPluginProps } from '../react-options-BnjZpdVh.js';
-export { g as AnyFactoryOptions, h as ElementRef, F as FactoryOptions, i as PolymorphicProps, j as PolymorphicWithAsChild, k as PolymorphicWithRender, l as RenderCallbackProps, S as Slottable, m as SlottableProps, o as defineContractComponent, n as mergeRefs } from '../react-options-BnjZpdVh.js';
+import { E as ElementType, U as UnknownProps, a as EmptyRecord, V as VariantMap, N as NoVariants, R as RecipeMap, b as NoPreset, A as AnyClassPluginFactory, c as AnyRecord, d as ReactFactoryOptions, M as MergeRecords, P as PolymorphicComponent, e as PolymorphicGenerics, f as ExtractPluginProps } from '../react-options-DU3EdFOv.js';
+export { g as AnyFactoryOptions, C as ContractProps, h as ElementRef, F as FactoryOptions, i as PolymorphicProps, j as PolymorphicWithAsChild, k as PolymorphicWithRender, l as RenderCallbackProps, S as Slottable, m as SlottableProps, o as defineContractComponent, n as mergeRefs } from '../react-options-DU3EdFOv.js';
 import * as react from 'react';
 import 'type-fest';
+import '@praxis-kit/contract-props';
 import '../_shared/diagnostics.js';
 
 /**
@@ -23,10 +24,12 @@ import '../_shared/diagnostics.js';
  * ```
  *
  * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element the same
- * way it works in `praxis-kit/react`. Pass `onElement` to run setup once the real DOM element
- * exists; this adapter doesn't support `subComponents`.
+ * way it works in `praxis-kit/react`. Pass `subComponents` to attach named sub-components
+ * (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
  */
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed>): PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>;
+declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+    readonly subComponents?: TSubComponents;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>, TSubComponents>;
 
 type SlotProps = {
     [key: string]: unknown;

package/dist/react/legacy.js

@@ -1,19 +1,18 @@
 import {
-  COMPONENT_DEFAULT_TAG,
   SLOT_NAME,
   Slottable,
   applyDisplayName,
   applySlot,
   buildRuntime,
   defineContractComponent,
+  finalizeComponent,
   getElementRef,
   getPropsRef,
   hasWarningGetter,
-  isString,
   makeCloneSlotChild,
   mergeRefs,
   render
-} from "../chunk-EIKPSL26.js";
+} from "../chunk-QYP7KLRE.js";
 
 // ../../adapters/react/src/legacy/create-contract-component.ts
 import { forwardRef as forwardRef2, useCallback, useRef } from "react";
@@ -57,7 +56,11 @@ function createContractComponent(options) {
     const onElementRef = useCallback((el) => {
       if (!onElement) return;
       if (el) {
-        cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+        cleanupRef.current?.();
+        cleanupRef.current = onElement(
+          el,
+          () => propsRef.current
+        ) ?? void 0;
       } else {
         cleanupRef.current?.();
         cleanupRef.current = void 0;
@@ -67,11 +70,12 @@ function createContractComponent(options) {
     return render({ ...bundle, props, ref: mergedRef });
   });
   applyDisplayName(Component, options.name);
-  const defaultTag = bundle.runtime.options.defaultTag;
-  if (isString(defaultTag)) {
-    Object.assign(Component, { [COMPONENT_DEFAULT_TAG]: defaultTag });
-  }
-  return Component;
+  const assembled = finalizeComponent(
+    Component,
+    bundle.runtime.options.defaultTag,
+    options.subComponents
+  );
+  return assembled;
 }
 export {
   Slot,

package/dist/{react-options-BnjZpdVh.d.ts → react-options-DU3EdFOv.d.ts}

@@ -1,5 +1,6 @@
 import { Ref, PropsWithChildren, ReactElement, ComponentType, JSX, ReactNode } from 'react';
 import { RequireAtLeastOne, Simplify, ReadonlyDeep, NonEmptyTuple } from 'type-fest';
+import { HasGenerics, Mode, PickMode } from '@praxis-kit/contract-props';
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from './_shared/diagnostics.js';
 
 /**
@@ -72,6 +73,19 @@ type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
 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;
 
 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];
@@ -176,21 +190,78 @@ type DefaultVariants<V extends VariantMap> = {
  * 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<Record<string, VariantSelection<V>>>;
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSelection<V>>>;
 
 type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
 
-interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
+/**
+ * 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'];
+/** The set of elements/tags this component may render as via `as`. See `PolymorphicGenerics`'s
+ *  `TAllowed` parameter. */
 type AllowedOf<T extends PolymorphicGenerics> = T['allowed'];
+/** The element/tag this component renders as by default. See `PolymorphicGenerics`'s `TDefault`
+ *  parameter. */
 type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+/** This component's own declared props, before variants are mixed in. See `PolymorphicGenerics`'s
+ *  `Props` parameter. */
 type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
 type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
@@ -223,7 +294,7 @@ interface BaseClassOptions {
 type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
 
 interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
-    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+    recipeMap?: StringMap<RecipeTarget<TVariants>>;
 }
 
 interface TagMapOptions {
@@ -392,7 +463,7 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
      * 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<Record<string, string>>;
+    readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
@@ -438,13 +509,23 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * 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: Element, getProps: () => Readonly<Props>) => void | (() => void);
+    readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
 type MetadataMap = AnyRecord;
@@ -631,14 +712,52 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
      * `React.ComponentProps`.
      */
     (props: PolymorphicProps<G, DefaultOf<G>>): ReactElement;
+    /**
+     * Type-only; never assigned at runtime. See `HasGenerics<G>` (`@praxis-kit/contract-props`) for
+     * the full rationale — kept as an inline field rather than `HasGenerics<G> & {...}` because
+     * intersecting it onto this callable type changes how `PolymorphicComponent<any>` (used by
+     * test helpers like `box()`) resolves against concrete instantiations; structurally identical
+     * to `HasGenerics<G>` either way, which is what lets `ContractProps` constrain against it.
+     */
+    readonly __generics?: G;
     displayName?: string;
 };
+/**
+ * Recovers a built `PolymorphicComponent<G>`'s prop shape for a specific render mode, from
+ * outside the file that built it — the missing piece `React.ComponentProps<typeof Component>`
+ * can't provide, since it always resolves against `PolymorphicComponent`'s normal-mode fallback
+ * overload (see that type's own doc comment).
+ *
+ * ```tsx
+ * const Container = createContractComponent({ tag: 'div', name: 'Container', /* ... *\/ })
+ *
+ * // Normal-mode props (equivalent to ComponentProps<typeof Container>, but works for every mode):
+ * type ContainerProps = ContractProps<typeof Container>
+ *
+ * // A wrapper that always renders Container with asChild — ComponentProps<typeof Container>
+ * // fails here ("Type 'true' is not assignable to type 'false'"); ContractProps doesn't.
+ * type ContainerAsChildProps = ContractProps<typeof Container, 'asChild'>
+ * ```
+ *
+ * `T` accepts any built component value (`PolymorphicComponent<G>` or `CompoundComponent<G, S>` —
+ * the latter's sub-component intersection doesn't disturb `__generics`, which lives on the root
+ * call signature) via its own `__generics` marker; the `never` branch below only fires for a
+ * non-praxis-kit component, which has no `__generics` field to infer from at all.
+ *
+ * Always resolves against the component's *default* element (`PolymorphicWithAsChild<G,
+ * DefaultOf<G>>`, etc.) — the same ceiling `React.ComponentProps<typeof Component>` already has
+ * for its one mode, not a new limitation `ContractProps` introduces. `ContractProps<typeof
+ * Button>` is "`Button`'s contract for its default element," not a substitute for
+ * `PolymorphicProps<G, 'a'>` when a caller needs a specific non-default `as` — those remain two
+ * different questions with two different answers.
+ */
+type ContractProps<T extends HasGenerics<PolymorphicGenerics>, M extends Mode = 'normal'> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? PickMode<M, PolymorphicProps<G, DefaultOf<G>>, PolymorphicWithAsChild<G, DefaultOf<G>>, PolymorphicWithRender<G, DefaultOf<G>>> : never;
 
 /** Structural subset of `CompiledComponentArtifact` consumed by the React adapter. */
 interface CompiledArtifact {
     readonly definition: ComponentDefinition;
     readonly precomputed?: {
-        readonly variantLookup?: Record<string, string>;
+        readonly variantLookup?: StringMap<string>;
     };
 }
 /**
@@ -659,4 +778,4 @@ type ReactFactoryOptions<TDefault extends ElementType, Props extends UnknownProp
     artifact?: CompiledArtifact;
 };
 
-export { type AnyClassPluginFactory as A, type ElementType as E, type FactoryOptions as F, type MergeRecords as M, type NoVariants as N, type PolymorphicComponent as P, type RecipeMap as R, Slottable as S, type UnknownProps as U, type VariantMap as V, type EmptyRecord as a, type NoPreset as b, type AnyRecord as c, type ReactFactoryOptions as d, type PolymorphicGenerics as e, type ExtractPluginProps as f, type AnyFactoryOptions as g, type ElementRef as h, type PolymorphicProps as i, type PolymorphicWithAsChild as j, type PolymorphicWithRender as k, type RenderCallbackProps as l, type SlottableProps as m, mergeRefs as n, defineContractComponent as o };
+export { type AnyClassPluginFactory as A, type ContractProps as C, type ElementType as E, type FactoryOptions as F, type MergeRecords as M, type NoVariants as N, type PolymorphicComponent as P, type RecipeMap as R, Slottable as S, type UnknownProps as U, type VariantMap as V, type EmptyRecord as a, type NoPreset as b, type AnyRecord as c, type ReactFactoryOptions as d, type PolymorphicGenerics as e, type ExtractPluginProps as f, type AnyFactoryOptions as g, type ElementRef as h, type PolymorphicProps as i, type PolymorphicWithAsChild as j, type PolymorphicWithRender as k, type RenderCallbackProps as l, type SlottableProps as m, mergeRefs as n, defineContractComponent as o };

package/dist/solid/index.d.ts

@@ -72,6 +72,19 @@ type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
 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;
 
 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];
@@ -176,20 +189,75 @@ type DefaultVariants<V extends VariantMap> = {
  * 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<Record<string, VariantSelection<V>>>;
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSelection<V>>>;
 
 type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
 
-interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
+/**
+ * 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'];
+/** The element/tag this component renders as by default. See `PolymorphicGenerics`'s `TDefault`
+ *  parameter. */
 type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+/** This component's own declared props, before variants are mixed in. See `PolymorphicGenerics`'s
+ *  `Props` parameter. */
 type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
 type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
@@ -222,7 +290,7 @@ interface BaseClassOptions {
 type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
 
 interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
-    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+    recipeMap?: StringMap<RecipeTarget<TVariants>>;
 }
 
 interface TagMapOptions {
@@ -391,7 +459,7 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
      * 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<Record<string, string>>;
+    readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
@@ -437,20 +505,29 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * 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: Element, getProps: () => Readonly<Props>) => void | (() => void);
+    readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
 type UnknownProps = AnyRecord;
 type SolidElement = JSX.Element;
-type SlotRenderFn = (props: UnknownProps) => SolidElement;
 
 type SolidFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
     /**
@@ -469,10 +546,43 @@ type ControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = Omit
     ref?: (el: ElementRef<TAs>) => void;
 };
 type SharedProps<G extends PolymorphicGenerics, TAs extends ElementType> = Omit<IntrinsicJSXProps<TAs>, keyof ControlProps<G, TAs> | 'children' | 'ref'> & ControlProps<G, TAs>;
+/**
+ * The exact props object an `asChild` render function receives at runtime, once defaults,
+ * variant classes, and ARIA role resolution have all run — see `buildSlotProps` in `render.tsx`.
+ * `PropsOf<G>` stays `Partial` for the same reason `AsChildProps` below does: the type system
+ * can't prove every prop actually received a default, only that the runtime *tried*. `class` is
+ * narrowed to a plain resolved `string` (not the wider `ClassName` a caller may pass in).
+ *
+ * `ref` is `(el: Element) => void` rather than `AsChildProps.ref`'s bare `unknown` — a render
+ * function's own job is spreading this object directly onto a concrete element (`(props) => <a
+ * {...props} />`), so it needs a callback-ref shape assignable to that element's own `ref` prop
+ * type; contravariance makes an `Element`-typed callback assignable to any more specific one
+ * (`(el: HTMLAnchorElement) => void`, etc.) without knowing `TAs` in advance. `AsChildProps.ref`
+ * itself stays `unknown` on purpose — that field types what a *caller* hands in before the render
+ * function has even run, not what the render function receives back out.
+ *
+ * `role` (the value `buildSlotProps` adds only when `isKnownAriaRole` narrows it) is deliberately
+ * left OFF this type entirely, rather than given any explicit type. Every candidate representation
+ * fails the same way `ref` almost did: Solid's own per-element JSX types (`AnchorHTMLAttributes
+ * ['role']`, etc.) each narrow `role` to only the ARIA roles valid for *that* element, a strict
+ * subset of the full ARIA vocabulary — so a `KnownAriaRole`-typed field fails to spread onto any
+ * of them, and unlike `ref`, there's no contravariance trick available for a plain string-literal
+ * property (`unknown` fails the same assignability check `KnownAriaRole` does; only `any` would
+ * satisfy every per-element union, and this codebase doesn't use `any`). Omitting the key entirely
+ * keeps `{...props}` spreads honest and compiling; a render function that specifically needs to
+ * read `role` off this object needs an explicit, locally-scoped cast to do so. Previously this
+ * whole parameter was bare `UnknownProps`, giving the render function no type checking at all.
+ */
+type ResolvedSlotProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignature<PropsOf<G>>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
+    class?: string | undefined;
+    ref?: (el: Element) => void;
+};
+/** An `asChild` render function, receiving the fully-resolved `ResolvedSlotProps<G>`. */
+type SlotRenderFn<G extends PolymorphicGenerics> = (props: ResolvedSlotProps<G>) => SolidElement;
 type AsChildProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignature<PropsOf<G>>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
     as?: never;
     asChild: true;
-    children: SlotRenderFn;
+    children: SlotRenderFn<G>;
     class?: ClassName | undefined;
     recipe?: keyof RecipeOf<G>;
     ref?: unknown;
@@ -494,6 +604,15 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
     (props: PolymorphicProps<G, DefaultOf<G>>): JSX.Element;
     displayName?: string;
 };
+/**
+ * A component's full prop contract — naming symmetry with React's/Preact's `ContractProps<T,
+ * Mode>` (`@praxis-kit/contract-props`), not a fix for a gap: Solid has no version of the
+ * overload-resolution ceiling those two adapters need a marker to work around. `PolymorphicProps<G,
+ * TAs>` already folds both render modes into one unioned type (rather than two separate types the
+ * way React/Preact split them), and `PolymorphicComponent<G>`'s fallback overload already returns
+ * that whole union — so this alias is just `PolymorphicProps<G>` under a familiar name.
+ */
+type ContractProps<G extends PolymorphicGenerics> = PolymorphicProps<G>;
 
 /**
  * Creates a polymorphic Solid component with praxis-kit contracts applied.
@@ -519,4 +638,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
     readonly subComponents?: TSubComponents;
 }): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>, TSubComponents>;
 
-export { type AnyFactoryOptions, type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type SolidFactoryOptions, createContractComponent, defineContractComponent };
+export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type ResolvedSlotProps, type SlotRenderFn, type SolidFactoryOptions, createContractComponent, defineContractComponent };