praxis-kit 7.0.0 → 7.4.0

package/dist/preact/index.d.ts

@@ -2,9 +2,72 @@ import { RequireAtLeastOne, Simplify, ReadonlyDeep, OmitIndexSignature } from 't
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 import { ComponentChildren, VNode, ComponentType, JSX, Ref } from 'preact';
 
+/**
+ * A string-keyed object whose values are of type `T`.
+ */
 type StringMap<T = unknown> = Record<string, T>;
+/**
+ * A string-keyed object with values of unknown type.
+ */
 type AnyRecord = StringMap<unknown>;
+/**
+ * An object type with no named properties.
+ *
+ * Unlike `{}`, this excludes arbitrary properties during type operations while
+ * still satisfying `extends object`.
+ */
 type EmptyRecord = Record<never, never>;
+/**
+ * A compound component's named sub-components, for example
+ * `{ Header, Content, Footer }`.
+ */
+type SubComponentMap = Readonly<AnyRecord>;
+/**
+ * Default `Variants` type for components that declare no variants.
+ *
+ * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
+ * editor hovers remain self-descriptive.
+ */
+type NoVariants = Readonly<EmptyRecord>;
+/**
+ * Default `TPreset` type for components that declare no named presets.
+ *
+ * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
+ * editor hovers remain self-descriptive.
+ */
+type NoPreset = Readonly<EmptyRecord>;
+/**
+ * Fallback for `ExtractPluginProps<TPlugin>` when a plugin contributes no
+ * props, including the no-plugin case.
+ *
+ * Structurally identical to `EmptyRecord`, but named separately so editor
+ * hovers remain self-descriptive.
+ */
+type NoPluginProps = EmptyRecord;
+/**
+ * Determines whether an object type should be treated as empty.
+ *
+ * `keyof T` ignores call and construct signatures...
+ */
+type IsEmptyRecord<T extends object> = T extends (...args: never[]) => unknown ? false : T extends new (...args: never[]) => unknown ? false : keyof T extends never ? true : false;
+/**
+ * Merges two object types while eliding empty operands.
+ *
+ * If either operand is {@link EmptyRecord}, the other operand is returned
+ * directly instead of producing intersections such as
+ * `Component & EmptyRecord` in editor hovers.
+ *
+ * Unlike a homomorphic mapped type (for example `Simplify<T>`), this preserves
+ * call and construct signatures. Many component types are callable objects,
+ * and mapped types silently discard those signatures.
+ *
+ * @remarks
+ * Instantiate `MergeRecords` directly. Introducing an intermediate alias for
+ * one operand (for example `type C = PolymorphicComponent<G>`) can prevent
+ * `IsEmptyRecord` from evaluating eagerly, which breaks assignability under
+ * `exactOptionalPropertyTypes`.
+ */
+type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends true ? B : IsEmptyRecord<B> extends true ? A : A & B;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -187,7 +250,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 ? EmptyRecord : T : EmptyRecord;
+type ExtractPluginProps<TPlugin extends AnyClassPluginFactory> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? NoPluginProps : T : NoPluginProps;
 
 type AriaContext = {
     readonly tag: IntrinsicTag;
@@ -251,6 +314,12 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
      * `@praxis-kit/diagnostics`.
      */
     readonly diagnostics?: Diagnostics | DiagnosticsMode;
+    /**
+     * ARIA/accessibility rules evaluated against the resolved tag and props on every render.
+     * Each rule is a function receiving the current context and returning zero or more
+     * violations, some of which can carry an auto-applicable fix (see `createRemoveAttributeRule`
+     * and friends in `praxis-kit/contract`).
+     */
     readonly aria?: readonly AriaRule[];
     /**
      * Rules that need `AriaPolicyEngine`'s fix-application/caching machinery
@@ -262,6 +331,11 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
      * misleading `aria` name to get the machinery it needs.
      */
     readonly rules?: readonly AriaRule[];
+    /**
+     * Declares which children are valid, by name, match predicate, and cardinality (e.g. "at
+     * least 1, at most 4 `Button` children"). Open by default — children matching no rule are
+     * still allowed unless `exclusiveChildren` is set.
+     */
     readonly children?: readonly ChildRuleInput[];
     /**
      * When true, only children matching a `children` rule (or text, per `allowText`)
@@ -274,19 +348,49 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
      * or any listed rule. Default: true.
      */
     readonly allowText?: boolean;
+    /**
+     * Prop transforms composed with the component's own `normalize` (from `FactoryOptions`) and
+     * run before it. Unlike `normalize`, these live in the enforcement bucket because they
+     * typically encode a built-in HTML/ARIA fact rather than component-specific behavior.
+     */
     readonly props?: readonly PropNormalizer[];
     /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
     readonly allowedAs?: readonly TAllowed[];
 };
 
 type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = {
+    /** Class applied to every instance regardless of variant selection. */
     readonly base?: ClassName;
+    /**
+     * Named variant groups (e.g. `intent`, `size`), each mapping its possible values to a
+     * class string. A consumer selects a value per group as a prop (`<Button intent="primary">`).
+     */
     readonly variants?: V;
+    /** Value used for a variant group when the consumer doesn't pass one explicitly. */
     readonly defaults?: Partial<DefaultVariants<V>>;
+    /**
+     * Applies an extra class only when a specific *combination* of variant selections matches —
+     * for cases `variants` alone can't express (e.g. `intent: 'primary'` + `size: 'lg'` together
+     * need a class neither variant would add on its own).
+     */
     readonly compounds?: readonly CompoundVariant<V>[];
+    /**
+     * Named bundles of variant values, selectable as a single unit via the `recipe` prop (e.g.
+     * `<Button recipe="cta">` instead of setting `intent`/`size` individually).
+     */
     readonly presets?: TPreset;
+    /** Maps a resolved tag directly to a raw class string, independent of the variant system. */
     readonly tags?: Readonly<TagMap>;
+    /**
+     * A `ClassPluginFactory` (e.g. the Tailwind layout pipeline) that extends class resolution
+     * with its own owned props, layered on top of `variants`/`presets`/`tags`.
+     */
     readonly plugin?: TPlugin;
+    /**
+     * A cache-key → resolved-class-string lookup for every statically-known variant
+     * combination, skipping runtime class computation entirely when a match is found. Normally
+     * generated by a build-time class-extraction plugin rather than hand-authored.
+     */
     readonly precomputedClasses?: Readonly<Record<string, string>>;
 };
 
@@ -295,17 +399,51 @@ type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
 }['normalize'];
 type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
 type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
+    /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
     readonly tag?: TDefault;
+    /** Display name used in diagnostics, dev tools, and generated component naming. */
     readonly name?: string;
+    /** Values used for the component's own (non-variant) props when the consumer omits them. */
     readonly defaults?: Partial<NoInfer<Props>>;
+    /**
+     * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
+     * normalizers see the same input. Use this for component-specific prop shaping — anything
+     * that depends on live instance state or the real DOM element belongs in `onElement` instead.
+     */
     readonly normalize?: NormalizeFn<NoInfer<Props>>;
+    /** Variant groups, base classes, presets, and the optional class-resolution plugin. */
     readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+    /** ARIA rules, child-content contracts, and other runtime validation for this component. */
     readonly enforcement?: EnforcementOptions<TAllowed>;
     /**
      * Adapter-resolved diagnostics default, spread in by `resolveAdapterCommonOptions`. Not meant to
      * be set directly by component authors — use `enforcement.diagnostics` to override per component.
      */
     readonly diagnostics?: Diagnostics;
+    /**
+     * Sub-components to attach to the generated root component, producing a
+     * compound component API (for example, `Card.Header`, `Card.Content`,
+     * and `Card.Footer`). Purely additive — has no effect on
+     * `enforcement.children`; author child rules explicitly if the component
+     * needs to validate its children.
+     */
+    readonly subComponents?: SubComponentMap;
+    /**
+     * Called once per instance, when the real underlying DOM element first
+     * exists, in every adapter — via that adapter's own native mount
+     * lifecycle, never through the props/attribute pipeline. Use this for
+     * wiring that needs the actual element (native imperative methods like
+     * `dialogEl.showModal()`, native events like `close`/`cancel` that have
+     * no prop-based equivalent), not for anything expressible as a plain
+     * prop.
+     *
+     * `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);
 };
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
@@ -319,7 +457,7 @@ type UnknownProps = AnyRecord;
 type SlotComponent = ComponentType<UnknownProps>;
 type AnyVNode = VNode<any>;
 
-type PreactFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+type PreactFactoryOptions<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> & {
     /** Component used to render the asChild slot. Defaults to the built-in Slot. */
     slotComponent?: SlotComponent;
     /**
@@ -362,6 +500,29 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
     displayName?: string;
 };
 
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory>(options: PreactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>;
+/**
+ * Creates a polymorphic Preact component with praxis-kit contracts applied.
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element. 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, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: PreactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+    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 PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent };

package/dist/preact/index.js

@@ -1,3 +1,27 @@
+// ../../lib/adapter-utils/src/invariant.ts
+function panic(message) {
+  throw new Error(message);
+}
+function invariant(condition, message) {
+  if (!condition) panic(message);
+}
+
+// ../../lib/adapter-utils/src/runtime/apply-display-name.ts
+function applyDisplayName(component, name) {
+  Object.assign(component, { displayName: name ?? "PolymorphicComponent" });
+}
+
+// ../../lib/adapter-utils/src/runtime/define-component.ts
+function defineContractComponent(options) {
+  return (factory) => factory(options);
+}
+
+// ../../lib/adapter-utils/src/runtime/assemble-compound-component.ts
+function assembleCompoundComponent(root, subComponents) {
+  if (!subComponents) return root;
+  return Object.assign(root, subComponents);
+}
+
 // ../../lib/primitive/src/tag/resolve-tag.ts
 function makeResolveTag(defaultTag) {
   return function tag(as) {
@@ -54,7 +78,7 @@ function isPlainObject(value) {
 
 // ../../lib/primitive/src/rule/is-dynamic-rule.ts
 function isDynamicRule(rule) {
-  return isObject(rule, true) && rule[RULE_BRAND] === true;
+  return isObject(rule, true) && Reflect.get(rule, RULE_BRAND) === true;
 }
 
 // ../../lib/primitive/src/rule/resolve-rule.ts
@@ -703,17 +727,17 @@ var COMPONENT_DEFAULT_TAG = /* @__PURE__ */ Symbol.for("praxis.component-default
 // ../../lib/primitive/src/guards/children/is-tag.ts
 function getAsProp(child) {
   if (!isObject(child) || !("props" in child)) return void 0;
-  const props = child.props;
+  const { props } = child;
   if (!isObject(props)) return void 0;
-  const as = props.as;
+  const as = Reflect.get(props, "as");
   return isString(as) && as !== "" ? as : void 0;
 }
 function getTag(child) {
   if (!isObject(child) || !("type" in child)) return void 0;
-  const t = child.type;
+  const { type: t } = child;
   if (isString(t)) return t;
   if (typeof t === "function" || isObject(t)) {
-    const defaultTag = t[COMPONENT_DEFAULT_TAG];
+    const defaultTag = Reflect.get(t, COMPONENT_DEFAULT_TAG);
     if (!isString(defaultTag)) return void 0;
     return getAsProp(child) ?? defaultTag;
   }
@@ -733,25 +757,34 @@ function isTag(...args) {
   return tag !== void 0 && set2.has(tag);
 }
 
-// ../../adapters/preact/src/create-contract-component.ts
-import { forwardRef as forwardRef2 } from "preact/compat";
-
-// ../../lib/adapter-utils/src/invariant.ts
-function panic(message) {
-  throw new Error(message);
-}
-function invariant(condition, message) {
-  if (!condition) panic(message);
-}
-
-// ../../lib/adapter-utils/src/runtime/apply-display-name.ts
-function applyDisplayName(component, name) {
-  Object.assign(component, { displayName: name ?? "PolymorphicComponent" });
-}
-
-// ../../lib/adapter-utils/src/runtime/define-component.ts
-function defineContractComponent(options) {
-  return (factory) => factory(options);
+// ../../lib/adapter-utils/src/runtime/finalize-component.ts
+function finalizeComponent(component, defaultTag, subComponents) {
+  if (typeof defaultTag === "string") {
+    Object.assign(component, { [COMPONENT_DEFAULT_TAG]: defaultTag });
+  }
+  return assembleCompoundComponent(component, subComponents);
+}
+
+// ../../lib/adapter-utils/src/runtime/is-factory-options-like.ts
+var FACTORY_OPTIONS_FIELD_VALIDATORS = {
+  tag: (v) => v === void 0 || isString(v),
+  name: (v) => v === void 0 || isString(v),
+  defaults: (v) => v === void 0 || isObject(v),
+  normalize: (v) => v === void 0 || isFunction(v),
+  styling: (v) => v === void 0 || isObject(v),
+  enforcement: (v) => v === void 0 || isObject(v),
+  diagnostics: (v) => v === void 0 || isObject(v),
+  subComponents: (v) => v === void 0 || isObject(v),
+  onElement: (v) => v === void 0 || isFunction(v)
+};
+function isFactoryOptionsLike(options, extraFieldValidators) {
+  if (!isObject(options)) return false;
+  const validators = { ...FACTORY_OPTIONS_FIELD_VALIDATORS, ...extraFieldValidators };
+  for (const [key, value] of Object.entries(options)) {
+    const validate = validators[key];
+    if (!validate || !validate(value)) return false;
+  }
+  return true;
 }
 
 // ../../lib/contract/src/aria/aria-role-policy.ts
@@ -2904,7 +2937,7 @@ function getChildProp(child, key) {
   if (!isVNodeLike(child)) return void 0;
   const { props } = child;
   if (!isObject(props)) return void 0;
-  return props[key];
+  return Reflect.get(props, key);
 }
 
 // ../core/src/html/contracts/aria/landmarks.ts
@@ -3619,6 +3652,10 @@ function applyMergePolicy(key, slotVal, childVal) {
   return policyHandlers[classifyProp(key, slotVal, childVal)](slotVal, childVal);
 }
 
+// ../../adapters/preact/src/create-contract-component.ts
+import { forwardRef as forwardRef2 } from "preact/compat";
+import { useCallback, useRef } from "preact/hooks";
+
 // ../../adapters/preact/src/render.tsx
 import { h as h2 } from "preact";
 
@@ -3881,18 +3918,54 @@ function buildRuntime(options) {
   return built;
 }
 
+// ../../adapters/preact/src/is-polymorphic-component.ts
+function isPolymorphicComponent(value) {
+  if (!isFunction(value)) return false;
+  if (!("displayName" in value)) return true;
+  return value.displayName === void 0 || isString(value.displayName);
+}
+
+// ../../adapters/preact/src/to-preact-factory-options.ts
+var PREACT_FIELD_VALIDATORS = {
+  slotComponent: (v) => v === void 0 || isFunction(v) || isObject(v),
+  filterProps: (v) => v === void 0 || isFunction(v)
+};
+function isPreactFactoryOptions(options) {
+  return isFactoryOptionsLike(options, PREACT_FIELD_VALIDATORS);
+}
+
 // ../../adapters/preact/src/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isPreactFactoryOptions(options), "options is not a valid PreactFactoryOptions object");
   const bundle = buildRuntime(options);
+  const { onElement } = options;
   const Component = forwardRef2(function Component2(props, ref) {
-    return render({ ...bundle, props, ref: ref ?? null });
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const cleanupRef = useRef(void 0);
+    const onElementRef = useCallback((el) => {
+      if (!onElement) return;
+      if (el) {
+        cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+      } else {
+        cleanupRef.current?.();
+        cleanupRef.current = void 0;
+      }
+    }, []);
+    const mergedRef = onElement ? mergeRefs(ref, onElementRef) : ref;
+    return render({ ...bundle, props, ref: mergedRef });
   });
   applyDisplayName(Component, options.name);
-  const defaultTag = bundle.runtime.options.defaultTag;
-  if (typeof defaultTag === "string") {
-    Object.assign(Component, { [COMPONENT_DEFAULT_TAG]: defaultTag });
-  }
-  return Component;
+  const assembled = finalizeComponent(
+    Component,
+    bundle.runtime.options.defaultTag,
+    options.subComponents
+  );
+  invariant(
+    isPolymorphicComponent(assembled),
+    "Generated component failed to satisfy the PolymorphicComponent shape"
+  );
+  return assembled;
 }
 export {
   Slottable,

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import { U as UnknownProps, E as ElementType, a as EmptyRecord, V as VariantMap, R as RecipeMap, A as AnyClassPluginFactory, b as ReactFactoryOptions, P as PolymorphicComponent, c as PolymorphicGenerics, d as ExtractPluginProps } from '../react-options-Cm99IE5J.js';
-export { e as AnyFactoryOptions, f as ElementRef, F as FactoryOptions, g as PolymorphicProps, h as PolymorphicWithAsChild, i as PolymorphicWithRender, j as RenderCallbackProps, S as Slottable, k as SlottableProps, m as composeRefs, l as defineContractComponent, m as mergeRefs } from '../react-options-Cm99IE5J.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-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 * as react from 'react';
 import { ReactElement, Ref } from 'react';
 import 'type-fest';
@@ -22,7 +22,30 @@ type CloneInput = {
     ref: NormalizedRef;
 };
 
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset, TAllowed>>;
+/**
+ * Creates a polymorphic React 19 component with praxis-kit contracts applied.
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * `ref` is accepted as a plain prop (React 19) and forwarded to the rendered host element or,
+ * with `asChild`, to the consumer's own element. 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, 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 = {
     ref?: Ref<unknown> | null;

package/dist/react/index.js

@@ -1,18 +1,24 @@
 import {
-  COMPONENT_DEFAULT_TAG,
   SLOT_NAME,
   Slottable,
   applyDisplayName,
   applySlot,
   buildRuntime,
   defineContractComponent,
+  finalizeComponent,
   getElementRef,
   getPropsRef,
   hasWarningGetter,
+  invariant,
+  isPolymorphicComponent,
+  isReactFactoryOptions,
   makeCloneSlotChild,
   mergeRefs,
   render
-} from "../chunk-35CJAOJW.js";
+} from "../chunk-EIKPSL26.js";
+
+// ../../adapters/react/src/current/create-contract-component.ts
+import { useCallback, useRef } from "react";
 
 // ../../adapters/react/src/current/slot/composeRefs.ts
 function getChildRef(element) {
@@ -43,16 +49,36 @@ function buildRuntime2(options) {
 
 // ../../adapters/react/src/current/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isReactFactoryOptions(options), "options is not a valid ReactFactoryOptions object");
   const bundle = buildRuntime2(options);
+  const { onElement } = options;
   function Component({ ref, ...props }) {
-    return render({ ...bundle, props, ref: ref ?? null });
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const cleanupRef = useRef(void 0);
+    const onElementRef = useCallback((el) => {
+      if (!onElement) return;
+      if (el) {
+        cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+      } else {
+        cleanupRef.current?.();
+        cleanupRef.current = void 0;
+      }
+    }, []);
+    const mergedRef = onElement ? mergeRefs(ref, onElementRef) : ref;
+    return render({ ...bundle, props, ref: mergedRef ?? null });
   }
   applyDisplayName(Component, options.name);
-  const defaultTag = bundle.runtime.options.defaultTag;
-  if (typeof defaultTag === "string") {
-    Object.assign(Component, { [COMPONENT_DEFAULT_TAG]: defaultTag });
-  }
-  return Component;
+  const assembled = finalizeComponent(
+    Component,
+    bundle.runtime.options.defaultTag,
+    options.subComponents
+  );
+  invariant(
+    isPolymorphicComponent(assembled),
+    "Generated component failed to satisfy the PolymorphicComponent shape"
+  );
+  return assembled;
 }
 export {
   Slot,

package/dist/react/legacy.d.ts

@@ -1,10 +1,32 @@
-import { E as ElementType, U as UnknownProps, a as EmptyRecord, V as VariantMap, R as RecipeMap, A as AnyClassPluginFactory, b as ReactFactoryOptions, P as PolymorphicComponent, c as PolymorphicGenerics, d as ExtractPluginProps } from '../react-options-Cm99IE5J.js';
-export { e as AnyFactoryOptions, f as ElementRef, F as FactoryOptions, g as PolymorphicProps, h as PolymorphicWithAsChild, i as PolymorphicWithRender, j as RenderCallbackProps, S as Slottable, k as SlottableProps, l as defineContractComponent, m as mergeRefs } from '../react-options-Cm99IE5J.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, 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 * as react from 'react';
 import 'type-fest';
 import '../_shared/diagnostics.js';
 
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset, TAllowed>>;
+/**
+ * Creates a polymorphic React component with praxis-kit contracts applied, for React 18 and
+ * earlier (use `praxis-kit/react` instead on React 19, which accepts `ref` as a plain prop).
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * 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`.
+ */
+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>>;
 
 type SlotProps = {
     [key: string]: unknown;

package/dist/react/legacy.js

@@ -13,10 +13,10 @@ import {
   makeCloneSlotChild,
   mergeRefs,
   render
-} from "../chunk-35CJAOJW.js";
+} from "../chunk-EIKPSL26.js";
 
 // ../../adapters/react/src/legacy/create-contract-component.ts
-import { forwardRef as forwardRef2 } from "react";
+import { forwardRef as forwardRef2, useCallback, useRef } from "react";
 
 // ../../adapters/react/src/legacy/slot/Slot.tsx
 import { forwardRef } from "react";
@@ -49,8 +49,22 @@ function buildRuntime2(options) {
 // ../../adapters/react/src/legacy/create-contract-component.ts
 function createContractComponent(options) {
   const bundle = buildRuntime2(options);
+  const { onElement } = options;
   const Component = forwardRef2(function Component2(props, ref) {
-    return render({ ...bundle, props, ref });
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const cleanupRef = useRef(void 0);
+    const onElementRef = useCallback((el) => {
+      if (!onElement) return;
+      if (el) {
+        cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+      } else {
+        cleanupRef.current?.();
+        cleanupRef.current = void 0;
+      }
+    }, []);
+    const mergedRef = onElement ? mergeRefs(ref, onElementRef) : ref;
+    return render({ ...bundle, props, ref: mergedRef });
   });
   applyDisplayName(Component, options.name);
   const defaultTag = bundle.runtime.options.defaultTag;