praxis-kit 7.0.0 → 7.4.0

package/dist/_shared/diagnostics.d.ts

@@ -98,7 +98,13 @@ declare enum DiagnosticCode {
     InternalError = "INTERNAL9000"
 }
 
+/**
+ * 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>;
 
 declare enum Severity {

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

@@ -1,9 +1,26 @@
 import { Diagnostics as Diagnostics$1, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
 
+/**
+ * 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>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -233,6 +250,12 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
      * `@praxis-kit/diagnostics`.
      */
     readonly diagnostics?: Diagnostics$1 | 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 +267,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 +284,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,17 +335,51 @@ type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
 }['normalize'];
 type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
 type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
+    /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
     readonly tag?: TDefault;
+    /** Display name used in diagnostics, dev tools, and generated component naming. */
     readonly name?: string;
+    /** Values used for the component's own (non-variant) props when the consumer omits them. */
     readonly defaults?: Partial<NoInfer<Props>>;
+    /**
+     * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
+     * normalizers see the same input. Use this for component-specific prop shaping — anything
+     * that depends on live instance state or the real DOM element belongs in `onElement` instead.
+     */
     readonly normalize?: NormalizeFn<NoInfer<Props>>;
+    /** Variant groups, base classes, presets, and the optional class-resolution plugin. */
     readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+    /** ARIA rules, child-content contracts, and other runtime validation for this component. */
     readonly enforcement?: EnforcementOptions<TAllowed>;
     /**
      * Adapter-resolved diagnostics default, spread in by `resolveAdapterCommonOptions`. Not meant to
      * be set directly by component authors — use `enforcement.diagnostics` to override per component.
      */
     readonly diagnostics?: Diagnostics$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.d.ts

@@ -1,4 +1,10 @@
+/**
+ * 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>;
 
 /**

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/html/index.d.ts

@@ -1,7 +1,13 @@
 import { ReadonlyDeep } from 'type-fest';
 import { DiagnosticInput } 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>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;