praxis-kit 6.6.1 → 7.3.0

package/dist/solid/index.js

@@ -1,3 +1,27 @@
+// ../../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) {
@@ -8,6 +32,11 @@ function makeResolveTag(defaultTag) {
 // ../../lib/primitive/src/rule/rule-brand.ts
 var RULE_BRAND = /* @__PURE__ */ Symbol("praxis-kit/dynamic-rule");
 
+// ../../lib/primitive/src/rule/dynamic.ts
+function dynamic(resolve) {
+  return { [RULE_BRAND]: true, resolve };
+}
+
 // ../../lib/primitive/src/guards/foundational/is-defined.ts
 function isUndefined(value) {
   return value === void 0;
@@ -21,7 +50,7 @@ function isNonNull(value) {
   return value != null;
 }
 function isNullish(value) {
-  return isNull(value) || value === void 0;
+  return isNull(value) || isUndefined(value);
 }
 
 // ../../lib/primitive/src/utils/type-guards.ts
@@ -35,10 +64,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
@@ -598,6 +630,24 @@ var ROLE_RESTRICTED_ATTRIBUTES = /* @__PURE__ */ new Map([
   ]
 ]);
 
+// ../../lib/primitive/src/constants/html/void-tags.ts
+var VOID_TAGS = [
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+];
+
 // ../../lib/primitive/src/guards/aria/is-aria-attribute.ts
 function isGlobalAriaAttribute(attr) {
   return GLOBAL_ARIA_ATTRIBUTES.has(attr);
@@ -650,17 +700,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;
   }
@@ -680,14 +730,34 @@ function isTag(...args) {
   return tag !== void 0 && set2.has(tag);
 }
 
-// ../../lib/adapter-utils/src/runtime/apply-display-name.ts
-function applyDisplayName(component, name) {
-  Object.assign(component, { displayName: name ?? "PolymorphicComponent" });
+// ../../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/define-component.ts
-function defineContractComponent(options) {
-  return (factory) => factory(options);
+// ../../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
@@ -1588,7 +1658,8 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
     const cached = _AriaPolicyEngine.#removeAttributeFixCache.get(attr);
     if (cached) return cached;
     const fix = {
-      kind: `removeAttribute:${attr}`,
+      kind: "removeAttribute",
+      attribute: attr,
       apply: ({ props }) => {
         if (!(attr in props)) return { applied: false, next: props };
         return { applied: true, next: omitProp(props, attr), previous: props };
@@ -1859,7 +1930,8 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
     if (!impliedLive) return NO_VIOLATIONS2;
     if ("aria-live" in props) return NO_VIOLATIONS2;
     const injectLive = {
-      kind: `injectLive:${effectiveRole}`,
+      kind: "injectLive",
+      attribute: "aria-live",
       apply: (ctx) => ({
         applied: true,
         next: { ...ctx.props, "aria-live": impliedLive },
@@ -1928,6 +2000,23 @@ var AriaPolicyEngine = class _AriaPolicyEngine extends InvariantBase {
   }
 };
 
+// ../../lib/contract/src/aria/factories.ts
+function removeProp(props, key) {
+  const next = { ...props };
+  delete next[key];
+  return next;
+}
+function removeAttributeFix(attribute) {
+  return Object.freeze({
+    kind: "removeAttribute",
+    attribute,
+    apply: ({ props }) => {
+      if (!(attribute in props)) return { applied: false, next: props };
+      return { applied: true, next: removeProp(props, attribute), previous: props };
+    }
+  });
+}
+
 // ../../lib/contract/src/children/get-type-name.ts
 function getTypeName(value) {
   if (value === null) return "null";
@@ -2246,22 +2335,6 @@ import { warnDiagnostics as warnDiagnostics2 } from "../_shared/diagnostics.js";
 
 // ../core/src/html/contracts/categories.ts
 var METADATA_TAGS = ["script", "template"];
-var VOID_TAGS = [
-  "area",
-  "base",
-  "br",
-  "col",
-  "embed",
-  "hr",
-  "img",
-  "input",
-  "link",
-  "meta",
-  "param",
-  "source",
-  "track",
-  "wbr"
-];
 var TEXT_ONLY_TAGS = [
   "option",
   "script",
@@ -2385,20 +2458,6 @@ var INPUT_MUTUALLY_EXCLUSIVE_POLICIES = [
 
 // ../core/src/html/spec/validators/attribute-type-validator.ts
 var DEFAULT_INPUT_TYPE = "text";
-function omit(props, key) {
-  const next = { ...props };
-  delete next[key];
-  return next;
-}
-function removeAttributeFix(attribute) {
-  return {
-    kind: `removeAttribute:${attribute}`,
-    apply: ({ props }) => {
-      if (!(attribute in props)) return { applied: false, next: props };
-      return { applied: true, next: omit(props, attribute), previous: props };
-    }
-  };
-}
 function createInputAttributeTypeRule({
   attribute,
   allowedTypes
@@ -2851,7 +2910,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
@@ -2904,6 +2963,13 @@ function isLabelableControl(child) {
   const type = getChildProp(child, "type");
   return !isString(type) || type !== "hidden";
 }
+function hasAccessibleNameProp(props) {
+  return "aria-label" in props || "aria-labelledby" in props;
+}
+function isNonEmptyTextChild(child) {
+  if (isNumber(child)) return true;
+  return isString(child) && child.trim().length > 0;
+}
 var labelContract = contract([
   { name: "control", match: isLabelableControl, cardinality: { max: 1 } },
   { name: "nested-label", match: isTag("label"), cardinality: { max: 0 } },
@@ -2911,6 +2977,13 @@ var labelContract = contract([
     name: "other-interactive-content",
     match: isTag(...OTHER_INTERACTIVE_TAGS),
     cardinality: { max: 0 }
+  },
+  {
+    name: "accessible-name",
+    match: isNonEmptyTextChild,
+    cardinality: dynamic(
+      (ctx) => hasAccessibleNameProp(ctx.props) ? { min: 0 } : { min: 1 }
+    )
   }
 ]);
 
@@ -3486,6 +3559,9 @@ function composeFilter(ownedKeys, filterProps) {
   return (key, variantKeys) => defaultFilter(key, variantKeys) || filterProps(key, variantKeys);
 }
 
+// ../../adapters/solid/src/create-contract-component.ts
+import { mergeProps as mergeProps2, onCleanup } from "solid-js";
+
 // ../../adapters/solid/src/slot/slot-validator.ts
 var SlotValidator = class extends InvariantBase {
   #name;
@@ -3533,6 +3609,13 @@ function buildRuntime(options) {
   };
 }
 
+// ../../adapters/solid/src/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/solid/src/render.tsx
 import { createComponent as _$createComponent } from "solid-js/web";
 import { mergeProps as _$mergeProps } from "solid-js/web";
@@ -3629,7 +3712,10 @@ function render({
     }));
   }
   if (process.env.NODE_ENV !== "production") {
-    createEffect(() => runtime.options.htmlChildrenEvaluatorFn?.(tag())?.evaluate(toChildArray(known.children)));
+    createEffect(() => runtime.options.htmlChildrenEvaluatorFn?.(tag())?.evaluate(toChildArray(known.children), {
+      tag: tag(),
+      props: normalizedProps()
+    }));
   }
   const slotResult = tryRenderAsChild(known, filteredProps, resolvedClass, slotValidator);
   if (slotResult !== null) return slotResult;
@@ -3644,20 +3730,46 @@ function render({
   }, () => domProps()));
 }
 
+// ../../adapters/solid/src/to-solid-factory-options.ts
+var SOLID_FIELD_VALIDATORS = {
+  filterProps: (v) => v === void 0 || isFunction(v)
+};
+function isSolidFactoryOptions(options) {
+  return isFactoryOptionsLike(options, SOLID_FIELD_VALIDATORS);
+}
+
 // ../../adapters/solid/src/create-contract-component.ts
 function createContractComponent(options) {
+  invariant(isSolidFactoryOptions(options), "options is not a valid SolidFactoryOptions object");
   const bundle = buildRuntime(options);
+  const { onElement } = options;
   const Component = (props) => {
+    const propsWithRef = onElement ? mergeProps2(props, {
+      get ref() {
+        const consumerRef = props.ref;
+        return (el) => {
+          if (typeof consumerRef === "function") consumerRef(el);
+          const cleanup = onElement(el, () => props);
+          if (cleanup) onCleanup(cleanup);
+        };
+      }
+    }) : props;
     return render({
       ...bundle,
-      props
+      props: propsWithRef
     });
   };
   applyDisplayName(Component, options.name);
-  if (typeof bundle.runtime.options.defaultTag === "string") {
-    Object.assign(Component, { [COMPONENT_DEFAULT_TAG]: bundle.runtime.options.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 {
   createContractComponent,

package/dist/svelte/Polymorphic.svelte

@@ -130,7 +130,21 @@
       if (process.env.NODE_ENV === 'production' || !hostEl) return
       const childArray = Array.from(hostEl.childNodes)
       bundle.childrenEvaluator?.evaluate(childArray, { tag, props: normalizedProps })
-      bundle.runtime.options.htmlChildrenEvaluatorFn?.(tag)?.evaluate(childArray)
+      bundle.runtime.options.htmlChildrenEvaluatorFn
+        ?.(tag)
+        ?.evaluate(childArray, { tag, props: normalizedProps })
+    })
+
+    const onElement = $derived(bundle.onElement)
+
+    // Unlike the effect above, this runs in every environment (not dev-only) — onElement is a
+    // real runtime feature, not a diagnostic. Re-runs (cleaning up the previous call first, via
+    // the returned teardown) whenever hostEl changes identity, e.g. the resolved tag changes and
+    // Svelte mounts a new host element.
+    $effect(() => {
+      if (!hostEl) return
+      const cleanup = onElement?.(hostEl, () => normalizedProps)
+      return () => cleanup?.()
     })
   }
 </script>

package/dist/svelte/index.d.ts

@@ -4,6 +4,8 @@ import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagno
 type StringMap<T = unknown> = Record<string, T>;
 type AnyRecord = StringMap<unknown>;
 type EmptyRecord = Record<never, never>;
+/** A compound component's named sub-components, e.g. `{ Header, Content, Footer }`. */
+type SubComponentMap = Readonly<AnyRecord>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -29,13 +31,6 @@ type MinMax = {
 };
 type CardinalityInput = Partial<MinMax>;
 
-/** Structural counterpart to `@praxis-kit/contract`'s `ChildrenEvaluator` class — `lib/primitive`
- *  may not depend on `lib/contract` (see `primitive-no-upper-layers` in .dependency-cruiser.cjs),
- *  so this describes only the shape consumers actually call. Mirrors `AriaEngine`'s pattern. */
-type ChildrenEvaluator$1 = {
-    evaluate: (children: unknown[]) => void;
-};
-
 /**
  * Resolved per-instance state available to a dynamic (`dynamic(...)`) child
  * rule field — the same tag/props every adapter already computes before
@@ -47,6 +42,13 @@ type ChildRuleContext = {
     readonly props: Readonly<AnyRecord>;
 };
 
+/** Structural counterpart to `@praxis-kit/contract`'s `ChildrenEvaluator` class — `lib/primitive`
+ *  may not depend on `lib/contract` (see `primitive-no-upper-layers` in .dependency-cruiser.cjs),
+ *  so this describes only the shape consumers actually call. Mirrors `AriaEngine`'s pattern. */
+type ChildrenEvaluator$1 = {
+    evaluate: (children: unknown[], context?: ChildRuleContext) => void;
+};
+
 declare const RULE_BRAND: unique symbol;
 
 type DynamicRule<T, C = unknown> = {
@@ -131,6 +133,7 @@ interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props
     preset: TPreset;
     allowed: TAllowed;
 }
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
 type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
 type CompoundVariantConditionValue<V extends VariantMap, K extends keyof V> = VariantKey<V, K> | NonEmptyArray<VariantKey<V, K>>;
@@ -200,8 +203,8 @@ type AriaContext = {
     readonly props: ReadonlyDeep<IntrinsicProps>;
 };
 
-type RemoveAttributeFixKind = `removeAttribute:${string}`;
-type InjectLiveFixKind = `injectLive:${string}`;
+type RemoveAttributeFixKind = 'removeAttribute';
+type InjectLiveFixKind = 'injectLive';
 type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
 
 type AriaFixResult = {
@@ -214,6 +217,9 @@ type AriaFixResult = {
 };
 type AriaFix = {
     readonly kind: FixKind;
+    /** The attribute a `'removeAttribute'`/`'injectLive'` fix targets — always set for those
+     *  kinds, absent for kinds with no single-attribute target (`'removeRole'`, etc.). */
+    readonly attribute?: string;
     readonly priority?: number;
     readonly source?: string;
     readonly apply: (context: AriaContext) => AriaFixResult;
@@ -307,6 +313,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 ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>> = {
@@ -421,12 +451,16 @@ type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownPro
 
 type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic2<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>>>;
 
+type OnElementFn<Props = unknown> = (element: Element, getProps: () => Readonly<Props>) => void | (() => void);
 type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions extends WithChildRules = WithChildRules> = BuiltChildrenEvaluator<TOptions> & {
     runtime: TypedRuntime<G>;
     filterProps: FilterPredicate;
     slotValidator: SlotValidator;
+    onElement?: OnElementFn<PropsOf<G>>;
 };
 
-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, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & TOptions): BuiltRuntime<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>, TOptions>;
+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, TSubComponents extends Readonly<AnyRecord> = EmptyRecord, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & TOptions & {
+    readonly subComponents?: TSubComponents;
+}): BuiltRuntime<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>, TOptions> & TSubComponents;
 
 export { type AnyFactoryOptions, type BuiltRuntime, type ElementType, type EmptyRecord, type FilterPredicate, type PolymorphicGenerics, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent };