praxis-kit 7.0.0 → 7.4.0

package/dist/lit/index.d.ts

@@ -2,9 +2,72 @@ import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 import { LitElement } from 'lit';
 
+/**
+ * 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;
 
@@ -170,7 +233,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;
@@ -234,6 +297,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
@@ -245,6 +314,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`)
@@ -257,19 +331,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>>;
 };
 
@@ -278,19 +382,65 @@ type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
 }['normalize'];
 type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
 type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
+    /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
     readonly tag?: TDefault;
+    /** Display name used in diagnostics, dev tools, and generated component naming. */
     readonly name?: string;
+    /** Values used for the component's own (non-variant) props when the consumer omits them. */
     readonly defaults?: Partial<NoInfer<Props>>;
+    /**
+     * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
+     * normalizers see the same input. Use this for component-specific prop shaping — anything
+     * that depends on live instance state or the real DOM element belongs in `onElement` instead.
+     */
     readonly normalize?: NormalizeFn<NoInfer<Props>>;
+    /** Variant groups, base classes, presets, and the optional class-resolution plugin. */
     readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+    /** ARIA rules, child-content contracts, and other runtime validation for this component. */
     readonly enforcement?: EnforcementOptions<TAllowed>;
     /**
      * Adapter-resolved diagnostics default, spread in by `resolveAdapterCommonOptions`. Not meant to
      * be set directly by component authors — use `enforcement.diagnostics` to override per component.
      */
     readonly diagnostics?: Diagnostics;
+    /**
+     * Sub-components to attach to the generated root component, producing a
+     * compound component API (for example, `Card.Header`, `Card.Content`,
+     * and `Card.Footer`). Purely additive — has no effect on
+     * `enforcement.children`; author child rules explicitly if the component
+     * needs to validate its children.
+     */
+    readonly subComponents?: SubComponentMap;
+    /**
+     * Called once per instance, when the real underlying DOM element first
+     * exists, in every adapter — via that adapter's own native mount
+     * lifecycle, never through the props/attribute pipeline. Use this for
+     * wiring that needs the actual element (native imperative methods like
+     * `dialogEl.showModal()`, native events like `close`/`cancel` that have
+     * no prop-based equivalent), not for anything expressible as a plain
+     * prop.
+     *
+     * `getProps` returns the instance's *current* resolved props at call
+     * time — read it from inside a listener registered once at mount, rather
+     * than re-subscribing on every prop change.
+     *
+     * Return a cleanup function to run when the instance unmounts.
+     */
+    readonly onElement?: (element: Element, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
+/**
+ * Determines whether a prop should be stripped before forwarding to the
+ * rendered element.
+ *
+ * Returning `true` excludes the prop from the output; returning `false`
+ * keeps it. This is the inverse polarity of `shouldForwardProp`-style
+ * predicates (Emotion/styled-components), where `true` means include.
+ *
+ * @param key - The prop name being evaluated.
+ * @param variantKeys - The set of configured variant prop names.
+ * @returns `true` to strip the prop; `false` to forward it.
+ */
 type FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
@@ -306,7 +456,7 @@ declare function defineContractComponent<O extends FactoryOptions>(options: O):
  * Note: this adapter targets Light DOM composition only. Shadow DOM slot
  * protocol is intentionally out of scope.
  */
-type LitFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+type LitFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
     readonly filterProps?: FilterPredicate;
 };
 
@@ -318,14 +468,14 @@ type UnknownProps = AnyRecord;
  * (which would trigger TS4094 in declaration emit). Variant key instance
  * properties are typed via the TVariants parameter.
  */
-type LitContractComponent<TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = {
-    new (): LitElement & {
+type LitContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord> = {
+    new (): MergeRecords<LitElement & {
         as: string | undefined;
         recipe: string | undefined;
         praxisClass: string | undefined;
     } & {
         [K in Extract<keyof TVariants, string>]?: string | null;
-    } & TPluginProps;
+    }, TPluginProps>;
 };
 
 /**
@@ -348,7 +498,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> = NoVariants, TPreset extends RecipeMap<TVariants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: LitFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+    readonly subComponents?: TSubComponents;
+}): MergeRecords<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,