praxis-kit 7.0.0 → 7.3.0

package/dist/preact/index.d.ts

@@ -5,6 +5,8 @@ import { ComponentChildren, VNode, ComponentType, JSX, Ref } from 'preact';
 type StringMap<T = unknown> = Record<string, T>;
 type AnyRecord = StringMap<unknown>;
 type EmptyRecord = Record<never, never>;
+/** A compound component's named sub-components, e.g. `{ Header, Content, Footer }`. */
+type SubComponentMap = Readonly<AnyRecord>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -306,6 +308,30 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * 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;
@@ -362,6 +388,8 @@ 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>>;
+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, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: PreactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): PolymorphicComponent<PolymorphicGenerics<TDefault, 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, R as RecipeMap, A as AnyClassPluginFactory, b as AnyRecord, c as ReactFactoryOptions, P as PolymorphicComponent, d as PolymorphicGenerics, e as ExtractPluginProps } from '../react-options-DLDsA4Tn.js';
+export { f as AnyFactoryOptions, g as ElementRef, F as FactoryOptions, h as PolymorphicProps, i as PolymorphicWithAsChild, j as PolymorphicWithRender, k as RenderCallbackProps, S as Slottable, l as SlottableProps, m as composeRefs, n as defineContractComponent, m as mergeRefs } from '../react-options-DLDsA4Tn.js';
 import * as react from 'react';
 import { ReactElement, Ref } from 'react';
 import 'type-fest';
@@ -22,7 +22,9 @@ 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>>;
+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, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+    readonly subComponents?: TSubComponents;
+}): PolymorphicComponent<PolymorphicGenerics<TDefault, 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,5 +1,5 @@
-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, R as RecipeMap, A as AnyClassPluginFactory, c as ReactFactoryOptions, P as PolymorphicComponent, d as PolymorphicGenerics, e as ExtractPluginProps } from '../react-options-DLDsA4Tn.js';
+export { f as AnyFactoryOptions, g as ElementRef, F as FactoryOptions, h as PolymorphicProps, i as PolymorphicWithAsChild, j as PolymorphicWithRender, k as RenderCallbackProps, S as Slottable, l as SlottableProps, n as defineContractComponent, m as mergeRefs } from '../react-options-DLDsA4Tn.js';
 import * as react from 'react';
 import 'type-fest';
 import '../_shared/diagnostics.js';

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;

package/dist/{react-options-Cm99IE5J.d.ts → react-options-DLDsA4Tn.d.ts}

@@ -5,6 +5,8 @@ import { Diagnostics, DiagnosticInput, DiagnosticsMode } from './_shared/diagnos
 type StringMap<T = unknown> = Record<string, T>;
 type AnyRecord = StringMap<unknown>;
 type EmptyRecord = Record<never, never>;
+/** A compound component's named sub-components, e.g. `{ Header, Content, Footer }`. */
+type SubComponentMap = Readonly<AnyRecord>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -307,6 +309,30 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * 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);
 };
 
 type MetadataMap = AnyRecord;
@@ -521,4 +547,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 PolymorphicComponent as P, type RecipeMap as R, Slottable as S, type UnknownProps as U, type VariantMap as V, type EmptyRecord as a, type ReactFactoryOptions as b, type PolymorphicGenerics as c, type ExtractPluginProps as d, type AnyFactoryOptions as e, type ElementRef as f, type PolymorphicProps as g, type PolymorphicWithAsChild as h, type PolymorphicWithRender as i, type RenderCallbackProps as j, type SlottableProps as k, defineContractComponent as l, mergeRefs as m };
+export { type AnyClassPluginFactory as A, type ElementType as E, type FactoryOptions as F, type PolymorphicComponent as P, type RecipeMap as R, Slottable as S, type UnknownProps as U, type VariantMap as V, type EmptyRecord as a, type AnyRecord as b, type ReactFactoryOptions as c, type PolymorphicGenerics as d, type ExtractPluginProps as e, type AnyFactoryOptions as f, type ElementRef as g, type PolymorphicProps as h, type PolymorphicWithAsChild as i, type PolymorphicWithRender as j, type RenderCallbackProps as k, type SlottableProps as l, mergeRefs as m, defineContractComponent as n };

package/dist/solid/index.d.ts

@@ -5,6 +5,8 @@ import { JSX } from 'solid-js';
 type StringMap<T = unknown> = Record<string, T>;
 type AnyRecord = StringMap<unknown>;
 type EmptyRecord = Record<never, never>;
+/** A compound component's named sub-components, e.g. `{ Header, Content, Footer }`. */
+type SubComponentMap = Readonly<AnyRecord>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -306,6 +308,30 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * 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;
@@ -357,6 +383,8 @@ 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: SolidFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>;
+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, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: SolidFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): PolymorphicComponent<PolymorphicGenerics<TDefault, 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 };