praxis-kit 7.0.0 → 7.3.0

package/dist/{chunk-35CJAOJW.js → chunk-EIKPSL26.js}

@@ -3,6 +3,12 @@ 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) {
@@ -59,7 +65,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
@@ -722,17 +728,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;
   }
@@ -752,6 +758,36 @@ function isTag(...args) {
   return tag !== void 0 && set2.has(tag);
 }
 
+// ../../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
 function getImplicitRole(tag, props) {
   if (tag in IMPLICIT_ROLE_RECORD) return IMPLICIT_ROLE_RECORD[tag];
@@ -2902,7 +2938,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
@@ -3725,6 +3761,23 @@ function applySlot(children, slotProps, ref, cloneSlotChild) {
   return cloneSlotChild({ child: children, slotProps, ref });
 }
 
+// ../../adapters/react/src/shared/to-react-factory-options.ts
+var REACT_FIELD_VALIDATORS = {
+  slotComponent: (v) => v === void 0 || isFunction(v) || isObject(v),
+  filterProps: (v) => v === void 0 || isFunction(v),
+  artifact: (v) => v === void 0 || isObject(v)
+};
+function isReactFactoryOptions(options) {
+  return isFactoryOptionsLike(options, REACT_FIELD_VALIDATORS);
+}
+
+// ../../adapters/react/src/shared/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/react/src/shared/apply-display-name.ts
 function applyDisplayName(component, name) {
   const displayName = name ?? "PolymorphicComponent";
@@ -3901,10 +3954,14 @@ function buildRuntime(options, defaultSlotComponent, normalizeChildren) {
 }
 
 export {
+  invariant,
   defineContractComponent,
   isString,
   SLOT_NAME,
   COMPONENT_DEFAULT_TAG,
+  finalizeComponent,
+  isReactFactoryOptions,
+  isPolymorphicComponent,
   mergeRefs,
   applyDisplayName,
   Slottable,

package/dist/codemod/index.js

@@ -211608,12 +211608,12 @@ var require_commonjs = __commonJS({
   }
 });
 
-// ../../node_modules/.pnpm/brace-expansion@5.0.7/node_modules/brace-expansion/dist/commonjs/index.js
+// ../../node_modules/.pnpm/brace-expansion@5.0.9/node_modules/brace-expansion/dist/commonjs/index.js
 var require_commonjs2 = __commonJS({
-  "../../node_modules/.pnpm/brace-expansion@5.0.7/node_modules/brace-expansion/dist/commonjs/index.js"(exports) {
+  "../../node_modules/.pnpm/brace-expansion@5.0.9/node_modules/brace-expansion/dist/commonjs/index.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.EXPANSION_MAX = void 0;
+    exports.EXPANSION_MAX_LENGTH = exports.EXPANSION_MAX = void 0;
     exports.expand = expand;
     var balanced_match_1 = require_commonjs();
     var escSlash = "\0SLASH" + Math.random() + "\0";
@@ -211632,6 +211632,7 @@ var require_commonjs2 = __commonJS({
     var commaPattern = /\\,/g;
     var periodPattern = /\\\./g;
     exports.EXPANSION_MAX = 1e5;
+    exports.EXPANSION_MAX_LENGTH = 4e6;
     function numeric(str) {
       return !isNaN(str) ? parseInt(str, 10) : str.charCodeAt(0);
     }
@@ -211666,11 +211667,11 @@ var require_commonjs2 = __commonJS({
       if (!str) {
         return [];
       }
-      const { max = exports.EXPANSION_MAX } = options;
+      const { max = exports.EXPANSION_MAX, maxLength = exports.EXPANSION_MAX_LENGTH } = options;
       if (str.slice(0, 2) === "{}") {
         str = "\\{\\}" + str.slice(2);
       }
-      return expand_(escapeBraces(str), max, true).map(unescapeBraces);
+      return expand_(escapeBraces(str), max, maxLength, true).map(unescapeBraces);
     }
     function embrace(str) {
       return "{" + str + "}";
@@ -211684,20 +211685,87 @@ var require_commonjs2 = __commonJS({
     function gte(i, y) {
       return i >= y;
     }
-    function expand_(str, max, isTop) {
-      const expansions = [];
+    function combine(acc, pre, values, max, maxLength, dropEmpties) {
+      const out = [];
+      let length = 0;
+      for (let a = 0; a < acc.length; a++) {
+        for (let v = 0; v < values.length; v++) {
+          if (out.length >= max)
+            return out;
+          const expansion = acc[a] + pre + values[v];
+          if (dropEmpties && !expansion)
+            continue;
+          if (length + expansion.length > maxLength)
+            return out;
+          out.push(expansion);
+          length += expansion.length;
+        }
+      }
+      return out;
+    }
+    function expandSequence(body, isAlphaSequence, max, maxLength) {
+      const n = body.split(/\.\./);
+      const N = [];
+      if (n[0] === void 0 || n[1] === void 0) {
+        return N;
+      }
+      const x = numeric(n[0]);
+      const y = numeric(n[1]);
+      const width = Math.max(n[0].length, n[1].length);
+      let incr = n.length === 3 && n[2] !== void 0 ? Math.max(Math.abs(numeric(n[2])), 1) : 1;
+      let test = lte;
+      const reverse = y < x;
+      if (reverse) {
+        incr *= -1;
+        test = gte;
+      }
+      const pad = n.some(isPadded);
+      let length = 0;
+      for (let i = x; test(i, y) && N.length < max; i += incr) {
+        let c;
+        if (isAlphaSequence) {
+          c = String.fromCharCode(i);
+          if (c === "\\") {
+            c = "";
+          }
+        } else {
+          c = String(i);
+          if (pad) {
+            const need = width - c.length;
+            if (need > 0) {
+              const z = new Array(need + 1).join("0");
+              if (i < 0) {
+                c = "-" + z + c.slice(1);
+              } else {
+                c = z + c;
+              }
+            }
+          }
+        }
+        if (length + c.length > maxLength)
+          break;
+        N.push(c);
+        length += c.length;
+      }
+      return N;
+    }
+    function expand_(str, max, maxLength, isTop) {
+      let acc = [""];
+      let dropEmpties = false;
+      let firstGroup = true;
       for (; ; ) {
         const m = (0, balanced_match_1.balanced)("{", "}", str);
-        if (!m)
-          return [str];
+        if (!m) {
+          return combine(acc, str, [""], max, maxLength, dropEmpties);
+        }
         const pre = m.pre;
-        if (/\$$/.test(m.pre)) {
-          const post2 = m.post.length ? expand_(m.post, max, false) : [""];
-          for (let k = 0; k < post2.length && k < max; k++) {
-            const expansion = pre + "{" + m.body + "}" + post2[k];
-            expansions.push(expansion);
-          }
-          return expansions;
+        if (/\$$/.test(pre)) {
+          acc = combine(acc, pre + "{" + m.body + "}", [""], max, maxLength, dropEmpties && !m.post.length);
+          firstGroup = false;
+          if (!m.post.length)
+            break;
+          str = m.post;
+          continue;
         }
         const isNumericSequence = /^-?\d+\.\.-?\d+(?:\.\.-?\d+)?$/.test(m.body);
         const isAlphaSequence = /^[a-zA-Z]\.\.[a-zA-Z](?:\.\.-?\d+)?$/.test(m.body);
@@ -211709,74 +211777,55 @@ var require_commonjs2 = __commonJS({
             isTop = true;
             continue;
           }
-          return [str];
+          return combine(acc, pre + "{" + m.body + "}" + m.post, [""], max, maxLength, dropEmpties);
         }
-        const post = m.post.length ? expand_(m.post, max, false) : [""];
-        let n;
+        if (firstGroup) {
+          dropEmpties = isTop && !isSequence;
+          firstGroup = false;
+        }
+        let values;
         if (isSequence) {
-          n = m.body.split(/\.\./);
+          values = expandSequence(m.body, isAlphaSequence, max, maxLength);
         } else {
-          n = parseCommaParts(m.body);
+          let n = parseCommaParts(m.body);
           if (n.length === 1 && n[0] !== void 0) {
-            n = expand_(n[0], max, false).map(embrace);
+            n = expand_(n[0], max, maxLength, false).map(embrace);
             if (n.length === 1) {
-              return post.map((p) => m.pre + n[0] + p);
-            }
-          }
-        }
-        let N;
-        if (isSequence && n[0] !== void 0 && n[1] !== void 0) {
-          const x = numeric(n[0]);
-          const y = numeric(n[1]);
-          const width = Math.max(n[0].length, n[1].length);
-          let incr = n.length === 3 && n[2] !== void 0 ? Math.max(Math.abs(numeric(n[2])), 1) : 1;
-          let test = lte;
-          const reverse = y < x;
-          if (reverse) {
-            incr *= -1;
-            test = gte;
-          }
-          const pad = n.some(isPadded);
-          N = [];
-          for (let i = x; test(i, y) && N.length < max; i += incr) {
-            let c;
-            if (isAlphaSequence) {
-              c = String.fromCharCode(i);
-              if (c === "\\") {
-                c = "";
-              }
-            } else {
-              c = String(i);
-              if (pad) {
-                const need = width - c.length;
-                if (need > 0) {
-                  const z = new Array(need + 1).join("0");
-                  if (i < 0) {
-                    c = "-" + z + c.slice(1);
-                  } else {
-                    c = z + c;
-                  }
-                }
-              }
+              acc = combine(acc, pre + n[0], [""], max, maxLength, dropEmpties && !m.post.length);
+              if (!m.post.length)
+                break;
+              str = m.post;
+              continue;
             }
-            N.push(c);
           }
-        } else {
-          N = [];
-          for (let j = 0; j < n.length; j++) {
-            N.push.apply(N, expand_(n[j], max, false));
+          let dropsEmpties = dropEmpties && !m.post.length && !pre;
+          for (let d = 0; dropsEmpties && d < acc.length; d++) {
+            if (acc[d]) {
+              dropsEmpties = false;
+            }
           }
-        }
-        for (let j = 0; j < N.length; j++) {
-          for (let k = 0; k < post.length && expansions.length < max; k++) {
-            const expansion = pre + N[j] + post[k];
-            if (!isTop || isSequence || expansion) {
-              expansions.push(expansion);
+          values = [];
+          let valuesLength = 0;
+          outer: for (let j = 0; j < n.length; j++) {
+            const expanded = expand_(n[j], max, maxLength, false);
+            for (let k = 0; k < expanded.length; k++) {
+              const v = expanded[k];
+              if (dropsEmpties && !v)
+                continue;
+              if (values.length >= max || valuesLength + v.length > maxLength) {
+                break outer;
+              }
+              values.push(v);
+              valuesLength += v.length;
             }
           }
         }
-        return expansions;
+        acc = combine(acc, pre, values, max, maxLength, dropEmpties && !m.post.length);
+        if (!m.post.length)
+          break;
+        str = m.post;
       }
+      return acc;
     }
   }
 });

package/dist/contract/index.d.ts

@@ -4,6 +4,8 @@ import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
 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$1;
+    /**
+     * 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);
 };
 
 /** Shared input shape for `invalidWithFix`/`invalidWithoutFix`. */

package/dist/guards/index.js

@@ -41,17 +41,17 @@ function getComponentDefaultTag(component) {
 // ../../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;
   }

package/dist/lit/index.d.ts

@@ -5,6 +5,8 @@ import { LitElement } from 'lit';
 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;
 
@@ -289,6 +291,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;
@@ -348,7 +374,9 @@ type LitContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
  * customElements.define('praxis-button', Button)
  * ```
  */
-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: LitFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin>): LitContractComponent<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: LitFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): LitContractComponent<TVariants, ExtractPluginProps<TPlugin>> & TSubComponents;
 
 /**
  * Renders a praxis-kit Lit component to an HTML string without requiring a DOM.

package/dist/lit/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
@@ -3503,7 +3542,7 @@ function diffAndApplyAttributes(host, state, prevPipelineAttrs, incomingProps) {
 }
 
 // ../../adapters/lit/src/create-contract-component.ts
-import { LitElement, html } from "lit";
+import { LitElement as LitElement2, html } from "lit";
 
 // ../../adapters/lit/src/build-runtime.ts
 import { silentDiagnostics as silentDiagnostics4 } from "../_shared/diagnostics.js";
@@ -3531,6 +3570,12 @@ function buildRuntime(options) {
   };
 }
 
+// ../../adapters/lit/src/is-lit-contract-component.ts
+import { LitElement } from "lit";
+function isLitContractComponent(value) {
+  return isFunction(value) && value.prototype instanceof LitElement;
+}
+
 // ../../adapters/lit/src/render-to-string.ts
 var ssrRegistry = /* @__PURE__ */ new WeakMap();
 function registerForSsr(cls, bundle) {
@@ -3547,8 +3592,17 @@ function renderToString(component, props = {}, innerHTML = "") {
   return renderBundleToString(entry.bundle, props, innerHTML);
 }
 
+// ../../adapters/lit/src/to-lit-factory-options.ts
+var LIT_FIELD_VALIDATORS = {
+  filterProps: (v) => v === void 0 || isFunction(v)
+};
+function isLitFactoryOptions(options) {
+  return isFactoryOptionsLike(options, LIT_FIELD_VALIDATORS);
+}
+
 // ../../adapters/lit/src/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isLitFactoryOptions(options), "options is not a valid LitFactoryOptions object");
   const bundle = buildRuntime(options);
   const looseBundle = toLooseBundle(bundle);
   const variantKeys = options.styling?.variants ? Object.keys(options.styling.variants) : [];
@@ -3573,7 +3627,7 @@ function createContractComponent(options) {
   iterate.forEach(pluginKeys, (key) => {
     staticProps[key] = { type: String, attribute: key };
   });
-  class PolymorphicLitElement extends LitElement {
+  class PolymorphicLitElement extends LitElement2 {
     // Tracks keys set by the pipeline last render so stale attrs are removed.
     _pipelineAttrs = /* @__PURE__ */ new Set();
     // Starts true so the first update always runs the pipeline regardless of
@@ -3635,6 +3689,21 @@ function createContractComponent(options) {
       const props = this._buildProps();
       diffAndApplyAttributes(this, resolveHostState(looseBundle, props), this._pipelineAttrs, props);
     }
+    // Light DOM means `this` already is the real host element — no ref/indirection needed.
+    // connectedCallback/disconnectedCallback are the native mount/unmount lifecycle, called
+    // once per instance regardless of how many pipeline re-runs `_applyPraxis` does.
+    _onElementCleanup;
+    connectedCallback() {
+      super.connectedCallback();
+      if (options.onElement) {
+        this._onElementCleanup = options.onElement(this, () => this._buildProps()) ?? void 0;
+      }
+    }
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      this._onElementCleanup?.();
+      this._onElementCleanup = void 0;
+    }
     render() {
       const children = Array.from(this.childNodes);
       const { tag, normalizedProps } = resolveTagAndNormalizedProps(looseBundle, this._buildProps());
@@ -3648,8 +3717,13 @@ function createContractComponent(options) {
   if (options.name) {
     Object.defineProperty(PolymorphicLitElement, "name", { value: options.name });
   }
+  invariant(
+    isLitContractComponent(PolymorphicLitElement),
+    "Generated class failed to satisfy the LitContractComponent shape"
+  );
   registerForSsr(PolymorphicLitElement, looseBundle);
-  return PolymorphicLitElement;
+  const assembled = assembleCompoundComponent(PolymorphicLitElement, options.subComponents);
+  return assembled;
 }
 export {
   createContractComponent,