praxis-kit 7.0.0 → 7.3.0

package/dist/vue/index.js

@@ -1,6 +1,30 @@
 // ../../adapters/vue/src/create-contract-component.ts
 import { computed, defineComponent as defineComponent2 } from "vue";
 
+// ../../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) {
@@ -43,10 +67,13 @@ function isString(value) {
 function isNumber(value) {
   return typeof value === "number";
 }
+function isFunction(value) {
+  return typeof value === "function";
+}
 
 // ../../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
@@ -676,17 +703,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;
   }
@@ -706,22 +733,34 @@ function isTag(...args) {
   return tag !== void 0 && set2.has(tag);
 }
 
-// ../../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
@@ -2874,7 +2913,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
@@ -3571,6 +3610,13 @@ function buildRuntime(options) {
   return built;
 }
 
+// ../../adapters/vue/src/is-polymorphic-component.ts
+function isPolymorphicComponent(value) {
+  if (!isObject(value)) return false;
+  if (!("displayName" in value)) return true;
+  return value.displayName === void 0 || isString(value.displayName);
+}
+
 // ../../adapters/vue/src/render.ts
 import { cloneVNode, h as h3 } from "vue";
 
@@ -3669,7 +3715,7 @@ function prepareRenderState(runtime, attrs, filterProps) {
     className
   };
 }
-function buildElementProps(props, className) {
+function buildElementProps(props, className, elementRef) {
   const { role, ...rest } = props;
   return {
     ...normalizeListenerKeys(rest),
@@ -3677,11 +3723,17 @@ function buildElementProps(props, className) {
     // normalizeClass turns it into '' and still emits class="", while the client patcher
     // removes the attribute outright. Omitting the key entirely keeps both paths consistent.
     ...className !== void 0 && { class: className },
-    ...isKnownAriaRole(role) && { role }
+    ...isKnownAriaRole(role) && { role },
+    // Vue calls a function-ref with the element on mount and with null on unmount, same
+    // contract as React/Preact's callback refs — a natural fit for FactoryOptions.onElement.
+    // Cast: Vue's own VNodeRef type also accepts a resolved *component* instance, since refs
+    // can target components as well as elements — irrelevant here, this is only ever attached
+    // to an intrinsic host tag, which always resolves to a real Element.
+    ...elementRef !== void 0 && { ref: elementRef }
   };
 }
-function renderIntrinsic(state, runtime, slots) {
-  const elementProps = buildElementProps(state.props, state.className);
+function renderIntrinsic(state, runtime, slots, elementRef) {
+  const elementProps = buildElementProps(state.props, state.className, elementRef);
   const domProps = runtime.resolveAria(state.tag, elementProps).props;
   return h3(state.tag, domProps, slots.default ? { default: slots.default } : void 0);
 }
@@ -3694,12 +3746,13 @@ function validateSlotDirectives(directives, validator) {
   }
   return true;
 }
-function tryRenderAsChild(state, children, discarded, validator) {
+function tryRenderAsChild(state, children, discarded, validator, elementRef) {
   if (!validateSlotDirectives(state.directives, validator)) return null;
   if (discarded > 0) validator.warnDiscardedChildren(discarded);
   const attrs = {
     ...pickAttributes(state.props),
-    ...state.className !== void 0 && { class: state.className }
+    ...state.className !== void 0 && { class: state.className },
+    ...elementRef !== void 0 && { ref: elementRef }
   };
   const slottable = extractSlottable(children);
   if (slottable) return slottable.rebuild(cloneVNode(slottable.child, attrs));
@@ -3714,20 +3767,31 @@ function render({
   state,
   slots,
   slotValidator,
-  childrenEvaluator
+  childrenEvaluator,
+  elementRef
 }) {
   const { vnodes: children, discarded } = normalizeChildren(slots);
   if (process.env.NODE_ENV !== "production") {
     childrenEvaluator?.evaluate(children, { tag: state.tag, props: state.normalizedProps });
     runtime.options.htmlChildrenEvaluatorFn?.(state.tag)?.evaluate(children, { tag: state.tag, props: state.normalizedProps });
   }
-  const slotResult = tryRenderAsChild(state, children, discarded, slotValidator);
-  return slotResult ?? renderIntrinsic(state, runtime, slots);
+  const slotResult = tryRenderAsChild(state, children, discarded, slotValidator, elementRef);
+  return slotResult ?? renderIntrinsic(state, runtime, slots, elementRef);
+}
+
+// ../../adapters/vue/src/to-vue-factory-options.ts
+var VUE_FIELD_VALIDATORS = {
+  filterProps: (v) => v === void 0 || isFunction(v)
+};
+function isVueFactoryOptions(options) {
+  return isFactoryOptionsLike(options, VUE_FIELD_VALIDATORS);
 }
 
 // ../../adapters/vue/src/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isVueFactoryOptions(options), "options is not a valid VueFactoryOptions object");
   const bundle = buildRuntime(options);
+  const { onElement } = options;
   const Component = defineComponent2({
     // normalizeOptions always supplies `name`, so displayName is always defined here —
     // the fallback only satisfies the type, which allows it to be absent in general.
@@ -3737,15 +3801,33 @@ function createContractComponent(options) {
       const state = computed(
         () => prepareRenderState(bundle.runtime, attrs, bundle.filterProps)
       );
-      return () => render({ ...bundle, state: state.value, slots });
+      let cleanup;
+      let boundElement = null;
+      const onElementRef = onElement ? (element) => {
+        if (element === boundElement) return;
+        if (boundElement) {
+          cleanup?.();
+          cleanup = void 0;
+        }
+        boundElement = element;
+        if (element) {
+          cleanup = onElement(element, () => attrs) ?? void 0;
+        }
+      } : void 0;
+      return () => render({ ...bundle, state: state.value, slots, elementRef: onElementRef });
     }
   });
   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/web/index.d.ts

@@ -4,6 +4,8 @@ import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagno
 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;
 
@@ -288,6 +290,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 FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
@@ -352,7 +378,9 @@ type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
  * For non-reactive attributes (`aria-*`, `role`, `data-*`) call `element.update()`
  * after setting them to trigger an explicit pipeline re-run.
  */
-declare function createContractComponent<TDefault extends ElementType, TProps extends UnknownProps = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory>(options: WebFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin>): WebContractComponent<TVariants, ExtractPluginProps<TPlugin>>;
+declare function createContractComponent<TDefault extends ElementType, TProps extends UnknownProps = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: WebFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): WebContractComponent<TVariants, ExtractPluginProps<TPlugin>> & TSubComponents;
 
 /**
  * Renders a praxis-kit web component to an HTML string without requiring a DOM.

package/dist/web/index.js

@@ -1,8 +1,22 @@
+// ../../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/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) {
@@ -45,10 +59,13 @@ function isString(value) {
 function isNumber(value) {
   return typeof value === "number";
 }
+function isFunction(value) {
+  return typeof value === "function";
+}
 
 // ../../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
@@ -587,17 +604,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;
   }
@@ -617,6 +634,28 @@ function isTag(...args) {
   return tag !== void 0 && set2.has(tag);
 }
 
+// ../../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
 function getImplicitRole(tag, props) {
   if (tag in IMPLICIT_ROLE_RECORD) return IMPLICIT_ROLE_RECORD[tag];
@@ -2721,7 +2760,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
@@ -3526,6 +3565,14 @@ function buildRuntime(options) {
   };
 }
 
+// ../../adapters/web/src/is-web-contract-component.ts
+function isWebContractComponent(value) {
+  if (!isFunction(value)) return false;
+  if (typeof HTMLElement !== "undefined" && !(value.prototype instanceof HTMLElement)) return false;
+  if (!("diagnostics" in value)) return false;
+  return isObject(value.diagnostics);
+}
+
 // ../../adapters/web/src/render-to-string.ts
 var ssrRegistry = /* @__PURE__ */ new WeakMap();
 function registerForSsr(cls, bundle) {
@@ -3542,8 +3589,17 @@ function renderToString(component, props = {}, innerHTML = "") {
   return renderBundleToString(entry.bundle, props, innerHTML);
 }
 
+// ../../adapters/web/src/to-web-factory-options.ts
+var WEB_FIELD_VALIDATORS = {
+  filterProps: (v) => v === void 0 || isFunction(v)
+};
+function isWebFactoryOptions(options) {
+  return isFactoryOptionsLike(options, WEB_FIELD_VALIDATORS);
+}
+
 // ../../adapters/web/src/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isWebFactoryOptions(options), "options is not a valid WebFactoryOptions object");
   const bundle = buildRuntime(options);
   const looseBundle = toLooseBundle(bundle);
   const variantKeys = options.styling?.variants ? Object.keys(options.styling.variants) : [];
@@ -3557,8 +3613,20 @@ function createContractComponent(options) {
     static get observedAttributes() {
       return observedAttrNames;
     }
+    // Tag registered by the consumer's own customElements.define() call is never literally
+    // `dialog` (custom-element names must be hyphenated), so native `<dialog>`-specific methods
+    // like showModal() won't exist on this class unless the consumer opts into "customized
+    // built-ins" (`{ extends: 'dialog' }`) themselves — not something this adapter special-cases.
+    _onElementCleanup;
     connectedCallback() {
       this._applyPraxis();
+      if (options.onElement) {
+        this._onElementCleanup = options.onElement(this, () => this._buildProps()) ?? void 0;
+      }
+    }
+    disconnectedCallback() {
+      this._onElementCleanup?.();
+      this._onElementCleanup = void 0;
     }
     // Fires synchronously for every observed attribute change — no microtask
     // scheduling needed. The guard is implicit: this only fires for
@@ -3575,12 +3643,11 @@ function createContractComponent(options) {
     get _self() {
       return this;
     }
-    _applyPraxis() {
+    // Shared by _applyPraxis and the onElement getProps accessor — both need the same
+    // attribute-derived prop snapshot, just for different purposes (pipeline input vs.
+    // exposing "current props" to author-supplied element wiring).
+    _buildProps() {
       const self = this._self;
-      const {
-        childrenEvaluator,
-        runtime: { options: options2 }
-      } = bundle;
       const observedSet = new Set(
         this.constructor.observedAttributes ?? []
       );
@@ -3596,6 +3663,14 @@ function createContractComponent(options) {
         const val = self[key] ?? this.getAttribute(key);
         if (val != null) props[key] = val;
       }
+      return props;
+    }
+    _applyPraxis() {
+      const {
+        childrenEvaluator,
+        runtime: { options: options2 }
+      } = bundle;
+      const props = this._buildProps();
       const hostState = resolveHostState(looseBundle, props);
       const children = Array.from(this.childNodes);
       if (childrenEvaluator) {
@@ -3612,8 +3687,14 @@ function createContractComponent(options) {
     Object.defineProperty(PolymorphicWebElement, "name", { value: options.name });
   }
   Object.defineProperty(PolymorphicWebElement, "diagnostics", { value: bundle.diagnostics });
-  registerForSsr(PolymorphicWebElement, looseBundle);
-  return PolymorphicWebElement;
+  const contractClass = PolymorphicWebElement;
+  invariant(
+    isWebContractComponent(contractClass),
+    "Generated class failed to satisfy the WebContractComponent shape"
+  );
+  registerForSsr(contractClass, looseBundle);
+  const assembled = assembleCompoundComponent(contractClass, options.subComponents);
+  return assembled;
 }
 export {
   createContractComponent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-kit",
-  "version": "7.0.0",
+  "version": "7.3.0",
   "type": "module",
   "exports": {
     "./react": {
@@ -187,7 +187,7 @@
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "esbuild": "^0.28.1",
     "esbuild-plugin-solid": "^0.6.0",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.0.0",
     "@typescript-eslint/utils": "8.65.0",
@@ -204,8 +204,8 @@
     "vite": "^8.1.5",
     "vue": "^3.5.40",
     "@praxis-kit/adapter-utils": "0.0.0",
-    "@praxis-kit/diagnostics": "0.0.0",
     "@praxis-kit/core": "0.0.0",
+    "@praxis-kit/diagnostics": "0.0.0",
     "@praxis-kit/pipeline": "0.0.0",
     "@praxis-kit/primitive": "0.0.0",
     "@praxis-kit/vite-plugin": "0.0.0"