praxis-kit 7.0.0 → 7.4.0

package/dist/vue/index.d.ts

@@ -3,9 +3,72 @@ import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagno
 import * as vue from 'vue';
 import { AllowedComponentProps } from 'vue';
 
+/**
+ * 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;
+/**
+ * Determines whether an object type should be treated as empty.
+ *
+ * `keyof T` ignores call and construct signatures...
+ */
+type IsEmptyRecord<T extends object> = T extends (...args: never[]) => unknown ? false : T extends new (...args: never[]) => unknown ? false : keyof T extends never ? true : false;
+/**
+ * Merges two object types while eliding empty operands.
+ *
+ * If either operand is {@link EmptyRecord}, the other operand is returned
+ * directly instead of producing intersections such as
+ * `Component & EmptyRecord` in editor hovers.
+ *
+ * Unlike a homomorphic mapped type (for example `Simplify<T>`), this preserves
+ * call and construct signatures. Many component types are callable objects,
+ * and mapped types silently discard those signatures.
+ *
+ * @remarks
+ * Instantiate `MergeRecords` directly. Introducing an intermediate alias for
+ * one operand (for example `type C = PolymorphicComponent<G>`) can prevent
+ * `IsEmptyRecord` from evaluating eagerly, which breaks assignability under
+ * `exactOptionalPropertyTypes`.
+ */
+type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends true ? B : IsEmptyRecord<B> extends true ? A : A & B;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -188,7 +251,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;
@@ -252,6 +315,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
@@ -263,6 +332,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`)
@@ -275,19 +349,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>>;
 };
 
@@ -296,17 +400,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;
+    /**
+     * Sub-components to attach to the generated root component, producing a
+     * compound component API (for example, `Card.Header`, `Card.Content`,
+     * and `Card.Footer`). Purely additive — has no effect on
+     * `enforcement.children`; author child rules explicitly if the component
+     * needs to validate its children.
+     */
+    readonly subComponents?: SubComponentMap;
+    /**
+     * Called once per instance, when the real underlying DOM element first
+     * exists, in every adapter — via that adapter's own native mount
+     * lifecycle, never through the props/attribute pipeline. Use this for
+     * wiring that needs the actual element (native imperative methods like
+     * `dialogEl.showModal()`, native events like `close`/`cancel` that have
+     * no prop-based equivalent), not for anything expressible as a plain
+     * prop.
+     *
+     * `getProps` returns the instance's *current* resolved props at call
+     * time — read it from inside a listener registered once at mount, rather
+     * than re-subscribing on every prop change.
+     *
+     * Return a cleanup function to run when the instance unmounts.
+     */
+    readonly onElement?: (element: Element, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
@@ -324,7 +462,7 @@ declare const Slottable: vue.DefineComponent<{}, () => vue.VNode<vue.RendererNod
 
 type UnknownProps = AnyRecord;
 
-type VueFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+type VueFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
     /**
      * Return true for any prop key that should be consumed but not forwarded to
      * the DOM. Variant keys are always stripped automatically.
@@ -370,6 +508,31 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
     displayName?: string;
 };
 
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory>(options: VueFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>;
+/**
+ * Creates a polymorphic Vue component with praxis-kit contracts applied.
+ *
+ * ```ts
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ * ```
+ *
+ * ```vue
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * Pass `subComponents` to attach named sub-components (`Card.Header`) and `onElement` to run
+ * setup once the real DOM element exists — both purely additive on top of the generated
+ * component.
+ */
+declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: VueFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>, TSubComponents>;
 
 export { type AnyFactoryOptions, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, Slottable, type SlottableProps, type VueFactoryOptions, createContractComponent, defineContractComponent };

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,