praxis-kit 7.0.0 → 7.4.0

package/dist/web/index.d.ts

@@ -1,9 +1,48 @@
 import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 
+/**
+ * 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;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -169,7 +208,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;
@@ -233,6 +272,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
@@ -244,6 +289,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`)
@@ -256,19 +306,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>>;
 };
 
@@ -277,19 +357,65 @@ 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);
 };
 
+/**
+ * Determines whether a prop should be stripped before forwarding to the
+ * rendered element.
+ *
+ * Returning `true` excludes the prop from the output; returning `false`
+ * keeps it. This is the inverse polarity of `shouldForwardProp`-style
+ * predicates (Emotion/styled-components), where `true` means include.
+ *
+ * @param key - The prop name being evaluated.
+ * @param variantKeys - The set of configured variant prop names.
+ * @returns `true` to strip the prop; `false` to forward it.
+ */
 type FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
@@ -300,7 +426,7 @@ declare function defineContractComponent<O extends FactoryOptions>(options: O):
  * Identical shape to LitFactoryOptions — a plain HTMLElement subclass with
  * no framework dependency. Light DOM only; Shadow DOM is out of scope.
  */
-type WebFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+type WebFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
     readonly filterProps?: FilterPredicate;
 };
 
@@ -311,7 +437,7 @@ type UnknownProps = AnyRecord;
  * Describes the public contract without exposing HTMLElement's internal members.
  * Variant key instance properties are typed via TVariants.
  */
-type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = {
+type WebContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord> = {
     new (): HTMLElement & {
         as: string | undefined;
         recipe: string | undefined;
@@ -352,7 +478,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> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, 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.4.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,10 +204,10 @@
     "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/pipeline": "0.0.0",
     "@praxis-kit/primitive": "0.0.0",
+    "@praxis-kit/pipeline": "0.0.0",
+    "@praxis-kit/diagnostics": "0.0.0",
     "@praxis-kit/vite-plugin": "0.0.0"
   },
   "publishConfig": {