praxis-kit 0.1.0

package/dist/solid/index.d.ts

@@ -0,0 +1,728 @@
+import "clsx";
+import { DiagnosticCode, DiagnosticInput, Diagnostics, DiagnosticsMode } from "../_shared/diagnostics.js";
+import { JSX } from "solid-js";
+import { OmitIndexSignature, ReadonlyDeep, RequireAtLeastOne, Simplify } from "type-fest";
+//#region ../../lib/foundation/src/string-map.d.ts
+/**
+ * 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>;
+//#endregion
+//#region ../../lib/primitive/src/types/any-record.d.ts
+/**
+ * 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;
+//#endregion
+//#region ../../lib/primitive/src/types/intrinsic-tag.d.ts
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+//#endregion
+//#region ../../lib/primitive/src/types/element-type.d.ts
+type ElementType = IntrinsicTag | (string & {});
+/**
+ * Resolves a component's default tag to its real DOM interface — `HTMLDialogElement` for
+ * `'dialog'`, `HTMLDetailsElement` for `'details'`, and so on — falling back to `HTMLElement`
+ * for custom-element tags or anything not in `HTMLElementTagNameMap`. Used to type
+ * `FactoryOptions.onElement`'s `element` param so component authors get direct, correctly-typed
+ * access to tag-specific native members (`dialogEl.showModal()`) without an unsafe cast.
+ *
+ * The fallback is `HTMLElement`, not the more generic `Element` — every tag reachable through
+ * `IntrinsicTag` extends it, and so does every custom element per spec, so members `HTMLElement`
+ * itself declares (`showPopover()`/`hidePopover()`/`togglePopover()`, the `popover` attribute)
+ * stay directly accessible even for tags with no dedicated entry in `HTMLElementTagNameMap`.
+ */
+type ElementForTag<TDefault extends ElementType> = TDefault extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TDefault] : HTMLElement;
+//#endregion
+//#region ../../lib/primitive/src/constants/aria/known-aria-roles.d.ts
+declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
+//#endregion
+//#region ../../lib/primitive/src/types/primitives/index.d.ts
+type Booleanish = boolean | 'true' | 'false';
+type ClassName = string | string[];
+type NonEmptyArray<T> = [T, ...T[]];
+type Numberish = number | `${number}`;
+type Primitive = string | number | boolean;
+type AriaRole = KnownAriaRole | (string & {});
+type IntrinsicProps = AnyRecord & {
+  role?: AriaRole;
+};
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/cardinality.d.ts
+type MinMax = {
+  min: number;
+  max: number;
+};
+type CardinalityInput = Partial<MinMax>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-context.d.ts
+/**
+ * Resolved per-instance state available to a dynamic (`dynamic(...)`) child
+ * rule field — the same tag/props every adapter already computes before
+ * evaluating children, exposed so a rule can vary by them (e.g. cardinality
+ * that depends on the resolved `as` tag).
+ */
+type ChildRuleContext = {
+  readonly tag: unknown;
+  readonly props: Readonly<AnyRecord>;
+};
+//#endregion
+//#region ../../lib/primitive/src/rule/rule-brand.d.ts
+declare const RULE_BRAND: unique symbol;
+//#endregion
+//#region ../../lib/primitive/src/types/rule/dynamic-rule.d.ts
+type DynamicRule<T, C = unknown> = {
+  readonly [RULE_BRAND]: true;
+  resolve(context: C): T;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/rule/rule.d.ts
+type Rule<T, C = unknown> = T | DynamicRule<T, C>;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-match.d.ts
+type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-position.d.ts
+type ChildRulePosition = 'first' | 'last' | 'any';
+//#endregion
+//#region ../../lib/primitive/src/types/contracts/child-rule-input.d.ts
+type ChildRuleInput<T = unknown, U extends T = T> = {
+  name: string;
+  match: ChildRuleMatch<T, U>;
+  /**
+   * Either a static cardinality, or `dynamic((ctx) => ...)` to derive it from
+   * the resolved tag/props (e.g. a different max depending on `as`). `match`
+   * stays static-only — it's already a function, so a dynamic wrapper would
+   * be indistinguishable from the predicate itself without one.
+   */
+  cardinality?: Rule<CardinalityInput, ChildRuleContext>;
+  position?: ChildRulePosition;
+  /**
+   * Optional component-type reference for O(1) dispatch index.
+   * When provided for every rule, the matcher reads child.type instead of
+   * calling every match function on every child (O(n×m) → O(n+m)).
+   */
+  type?: unknown;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/validation/valid-result.d.ts
+type ValidResult = {
+  valid: true;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/variants/string-to-boolean.d.ts
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-value.d.ts
+type VariantValue = string | string[];
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-states.d.ts
+type VariantStates<K extends string = string> = Record<K, VariantValue>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-map.d.ts
+type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-key.d.ts
+type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-selection.d.ts
+/**
+ * A partial selection of variant states authored at factory definition time.
+ *
+ * Uses `keyof V[K]` directly (not `VariantKey`) so TypeScript can eagerly
+ * resolve the union at constraint-check time without deferred conditional types.
+ */
+type VariantSelection<V extends VariantMap> = { [K in keyof V]?: keyof V[K]; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-props.d.ts
+/** The full optional prop surface exposed to callers for a given variant map. */
+type VariantProps<V extends VariantMap> = { [K in keyof V]?: VariantKey<V, K>; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/default-variants.d.ts
+type NormalizedVariantValue<K extends string> = string extends K ? Primitive : K extends 'true' | 'false' ? Booleanish : K extends `${number}` ? Numberish : K;
+type DefaultVariants<V extends VariantMap> = { [K in keyof V]?: NormalizedVariantValue<keyof V[K] & string>; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/recipe-map.d.ts
+/**
+ * A static, immutable map of named presets to partial variant selections.
+ *
+ * Presets are named bundles of variant props that callers activate by key,
+ * avoiding the need to repeat variant combinations at each call site.
+ */
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<VariantSelection<V>>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/recipe-target.d.ts
+type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/polymorphic-generics.d.ts
+/**
+ * The framework-neutral descriptor for a single praxis-kit component's contract — every render
+ * mechanism (tag resolution, prop merging, classes, ARIA) and every framework adapter's
+ * component type is built from this one shape. Deliberately just data: five type parameters and
+ * their corresponding properties, with no notion of JSX, call signatures, refs, or any
+ * framework-specific rendering concern. Each adapter (React, Vue, Svelte, Solid, Lit, Web) builds
+ * its own idiomatic component type on top of a `PolymorphicGenerics<...>` instantiation — see
+ * `PolymorphicComponent<G>` (`adapters/react/src/shared/types/polymorphic-props.ts`) for the
+ * React example — rather than this interface knowing anything about any of them.
+ *
+ * Use the `*Of<T>` accessor aliases below (`DefaultOf<G>`, `PropsOf<G>`, etc.) to read a single
+ * field back out of an already-resolved `G`, instead of indexing `G['default']` etc. directly at
+ * call sites — same rationale as any accessor: the property name stays an implementation detail,
+ * and every reader benefits together if it ever needs to change.
+ */
+interface PolymorphicGenerics<
+/**
+ * The element/tag this component renders as when the consumer doesn't override it via `as`
+ * (`AllowedOf<G>` permitting) — e.g. `'button'`, `'div'`. Defaults to the widest `ElementType`
+ * so a generic `PolymorphicGenerics` reference (with nothing else specified) still compiles.
+ */
+TDefault extends ElementType = ElementType,
+/**
+ * The props this specific component declares — its own contract, before variants are mixed
+ * in. Defaults to `AnyRecord` for the same "still compiles unspecified" reason as `TDefault`.
+ */
+Props extends AnyRecord = AnyRecord,
+/**
+ * This component's variant definitions (e.g. `{ intent: { primary: ..., ghost: ... } }`).
+ * Constrained to `Readonly<VariantMap>` — not the wider `AnyRecord` — specifically so `TPreset`
+ * below can be expressed as `RecipeMap<Variants>` and get real per-variant-key checking,
+ * instead of falling back to an unconstrained `RecipeMap<VariantMap>`.
+ */
+Variants extends Readonly<VariantMap> = Readonly<VariantMap>,
+/**
+ * Named presets (`RecipeMap<Variants>`) — bundles of variant selections a consumer activates
+ * by key instead of repeating the same variant combination at every call site. Tied to
+ * `Variants`, not `AnyRecord`, precisely so a preset can only ever select keys/values that
+ * `Variants` actually defines — an invalid preset is a type error, not a silent no-op.
+ * Defaults to `Readonly<EmptyRecord>` (no presets), which is the common case: a component can
+ * have variants without necessarily defining any named presets over them, and most don't.
+ */
+TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>,
+/**
+ * The set of elements/tags a consumer is allowed to switch to via `as`. Defaults to the widest
+ * `ElementType`, under which `AllowedOf<G>` imposes no restriction at all (see
+ * `PolymorphicControlProps.as`'s own comment in the React adapter for the concrete effect this
+ * has at a component's actual call site).
+ */
+TAllowed extends ElementType = ElementType> {
+  default: TDefault;
+  props: Props;
+  variants: Variants;
+  preset: TPreset;
+  allowed: TAllowed;
+}
+/** This component's variant definitions. See `PolymorphicGenerics`'s `Variants` parameter. */
+type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
+/** This component's named presets. See `PolymorphicGenerics`'s `TPreset` parameter. */
+type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
+/** The element/tag this component renders as by default. See `PolymorphicGenerics`'s `TDefault`
+ *  parameter. */
+type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+/** This component's own declared props, before variants are mixed in. See `PolymorphicGenerics`'s
+ *  `Props` parameter. */
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/compound-variant.d.ts
+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>>;
+type CompoundVariantConditions<V extends VariantMap> = Simplify<{ [K in keyof V]: CompoundVariantConditionValue<V, K>; }>;
+type CompoundVariantRequiredConditions<V extends VariantMap> = RequireAtLeastOneIfNotEmpty<CompoundVariantConditions<V>>;
+type CompoundVariantBase<V extends VariantMap> = keyof V extends never ? EmptyRecord : CompoundVariantRequiredConditions<V>;
+type CompoundVariant<V extends VariantMap> = CompoundVariantBase<V> & {
+  class: VariantValue;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-compounds.d.ts
+interface CVACompounds<V extends VariantMap> {
+  compoundVariants?: readonly CompoundVariant<V>[];
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-defaults.d.ts
+interface CVADefaults<V extends VariantMap> {
+  defaultVariants?: DefaultVariants<V>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-variants.d.ts
+interface CVAVariants<V extends VariantMap> {
+  variants?: V;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/base-class-options.d.ts
+interface BaseClassOptions {
+  baseClassName?: ClassName;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-fn.d.ts
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/recipe-options.d.ts
+interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
+  recipeMap?: StringMap<RecipeTarget<TVariants>>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/tag-map-options.d.ts
+interface TagMapOptions {
+  tagMap?: TagMap;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/composition-options.d.ts
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/cva-system-options.d.ts
+type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/style-options.d.ts
+type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-options.d.ts
+type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/owned-prop-keys.d.ts
+type OwnedPropKeys = ReadonlySet<string>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/class-plugin.d.ts
+type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
+  pipeline: ClassPipelineFn;
+  ownedKeys?: OwnedPropKeys;
+  readonly _pluginProps?: TProps;
+}>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/class-plugin-factory.d.ts
+type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics) => ClassPlugin<TProps>;
+/** `ClassPluginFactory` with its plugin-owned-props generic erased — the common form used
+ *  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 ? NoPluginProps : T : NoPluginProps;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-context.d.ts
+type AriaContext = {
+  /**
+   * The intrinsic HTML tag being evaluated.
+   */
+  readonly tag: IntrinsicTag;
+  /**
+   * The implicit ARIA role associated with the intrinsic tag.
+   */
+  readonly implicitRole: AriaRole | undefined;
+  /**
+   * The effective ARIA role after considering the element's explicit
+   * `role` attribute or component-provided role.
+   */
+  readonly effectiveRole: string | undefined;
+  /**
+   * The component's props available to the ARIA policy engine.
+   */
+  readonly props: ReadonlyDeep<IntrinsicProps>;
+  /**
+   * Variant prop names declared by the component.
+   *
+   * The adapter uses these names to determine which props are intercepted
+   * before reaching the DOM. A rule asserting a fact about a real HTML
+   * attribute should therefore treat a key present here as a component
+   * variant rather than a DOM attribute.
+   *
+   * An empty set indicates no variant props are declared — the case for
+   * evaluations with no factory context, such as `AriaPolicyEngine.evaluate`.
+   */
+  readonly variantKeys: ReadonlySet<string>;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/fix-kind.d.ts
+type RemoveAttributeFixKind = 'removeAttribute';
+type InjectLiveFixKind = 'injectLive';
+type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-fix.d.ts
+type AriaFixResult = {
+  applied: false;
+  next: ReadonlyDeep<IntrinsicProps>;
+} | {
+  applied: true;
+  next: ReadonlyDeep<IntrinsicProps>;
+  previous: ReadonlyDeep<IntrinsicProps>;
+};
+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;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/severity.d.ts
+type Severity = 'error' | 'warning' | (string & {});
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-result.d.ts
+type AriaInvalidBase<M extends string = string> = {
+  valid: false;
+  severity: Severity;
+  message?: M;
+  attribute?: string;
+  diagnostic?: DiagnosticInput;
+};
+type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: true;
+  fix: AriaFix;
+};
+type AriaInvalidWithoutFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: false;
+};
+type AriaInvalidResult<M extends string = string> = AriaInvalidWithFix<M> | AriaInvalidWithoutFix<M>;
+type AriaResult = ValidResult | AriaInvalidResult;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-rule.d.ts
+type AriaRule<C extends AriaContext = AriaContext> = ((context: C) => readonly AriaResult[]) & {
+  readonly readsProps?: readonly string[];
+  readonly tags?: readonly string[];
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/prop-normalizer.d.ts
+type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/enforcement-options.d.ts
+type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
+  /**
+   * Accepts a preset name (`'warn'`, `'throw'`, `'silent'`) or a full `Diagnostics`
+   * instance for custom reporting/policy. The string form needs no import from
+   * `@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
+   * (`AriaRule`'s `readsProps`, fixable `AriaFix` results) but have no
+   * relationship to ARIA semantics — an HTML fact or a security check like a
+   * dangerous-URL-scheme guard, for example. Evaluated together with `aria`
+   * (both run through the same engine, merged into one rule set) — this is a
+   * separate bucket purely so a non-ARIA rule doesn't have to sit under the
+   * 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`)
+   * are valid — anything else is rejected. Default: false (open — children not
+   * matching any rule are allowed).
+   */
+  readonly exclusiveChildren?: boolean;
+  /**
+   * When false, text/number child nodes are rejected regardless of exclusiveChildren
+   * 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[];
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/styling-options.d.ts
+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 a component defines up front. A caller activates one by name
+   * through the `recipe` prop (e.g. `<Button recipe="cta">` instead of setting `intent`/`size`
+   * individually) — `presets` is the store, `recipe` is the selector, which is why the field and
+   * the prop read differently. Explicit props always win over the activated bundle. The value type
+   * is `RecipeMap` (see `lib/primitive/src/types/variants/recipe-map.ts`).
+   */
+  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<StringMap<string>>;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/factory/factory-options.d.ts
+type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
+  normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
+}['normalize'];
+/**
+ * The type-erased shape of {@link FactoryOptions} — every generic parameter widened to its bound.
+ *
+ * Use it for a value that must hold *any* factory config (a registry, a generic wrapper). It
+ * cannot check `styling.compounds` conditions against the real variant keys/values, because it
+ * has forgotten what they are — for that, annotate against `FactoryOptions<...>` with the concrete
+ * generics (or `satisfies FactoryOptions<'button', Props, typeof variants>`), which keeps an
+ * invalid compound condition a type error rather than a silent no-op.
+ */
+type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
+/**
+ * The framework-neutral component-authoring config passed to `createContractComponent` in every
+ * adapter: default tag + name, own-prop defaults, a `normalize` transform, `styling` (variants,
+ * base classes, presets, class plugin), `enforcement` (ARIA + children contracts), `subComponents`,
+ * and `onElement`.
+ *
+ * `satisfies FactoryOptions<TDefault, Props, typeof variants, ...>` on a config object narrows
+ * `styling.compounds` conditions to the real per-variant-key shape — including resolving a
+ * boolean-shaped axis (`{ true, false }`) to a real `boolean` — so a condition naming a variant or
+ * value that does not exist is a compile error. `AnyFactoryOptions` cannot do this.
+ */
+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.
+   *
+   * Accepts either a single transform or an array of them, mirroring the `enforcement.props`
+   * array convention. An array is composed left to right — each entry receives the previous
+   * entry's *complete* output, not a merged patch — so unlike an `enforcement.props` normalizer
+   * (which returns a partial patch), a later `normalize` entry can also remove a key an earlier
+   * one added. An empty array is treated as no transform.
+   */
+  readonly normalize?: NormalizeFn<NoInfer<Props>> | ReadonlyArray<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.
+   *
+   * `element` is typed to the real DOM interface of every tag the rendered
+   * element could actually be — `TDefault` plus whatever `enforcement.allowed`
+   * permits via `as` (`HTMLDialogElement` for `tag: 'dialog'`,
+   * `HTMLDetailsElement` for `tag: 'details'`, and so on) — no cast needed to
+   * reach tag-specific members. A component that leaves `allowed`
+   * unconstrained (any tag reachable via `as`) falls back to `HTMLElement`,
+   * which still covers members every element shares (`showPopover()` and
+   * friends); restrict `enforcement.allowed` to the tags `onElement`
+   * actually knows how to handle to get real narrowing.
+   *
+   * `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: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
+};
+//#endregion
+//#region ../../lib/adapter-utils/src/runtime/define-component.d.ts
+export declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+//#endregion
+//#region ../../adapters/solid/src/types/primitives.d.ts
+type UnknownProps = AnyRecord;
+type SolidElement = JSX.Element;
+//#endregion
+//#region ../../adapters/solid/src/solid-options.d.ts
+type SolidFactoryOptions<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.
+   * Receives `runtime.options.variantKeys` as a convenience if needed.
+   */
+  filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
+};
+//#endregion
+//#region ../../adapters/solid/src/types/polymorphic-props.d.ts
+type ElementRef<T extends ElementType> = T extends IntrinsicTag ? HTMLElementTagNameMap[T] : unknown;
+type IntrinsicJSXProps<T extends ElementType> = T extends IntrinsicTag ? JSX.IntrinsicElements[T] : UnknownProps;
+type ControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = OmitIndexSignature<PropsOf<G>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
+  as?: TAs;
+  class?: ClassName | undefined;
+  recipe?: keyof RecipeOf<G>;
+  ref?: (el: ElementRef<TAs>) => void;
+};
+type SharedProps<G extends PolymorphicGenerics, TAs extends ElementType> = Omit<IntrinsicJSXProps<TAs>, keyof ControlProps<G, TAs> | 'children' | 'ref'> & ControlProps<G, TAs>;
+/**
+ * Props an `asChild` render function receives once defaults, variant classes, and ARIA role
+ * resolution have all run (see `buildSlotProps` in `render.tsx`). `class` is narrowed to a
+ * resolved `string`, not the wider `ClassName` a caller may pass in. `ref` is typed for spreading
+ * straight onto a concrete element, unlike `AsChildProps.ref`'s bare `unknown`. `role` is
+ * intentionally left off the type entirely — a render function that needs it casts locally.
+ *
+ * The `ref`/`role` reasoning (contravariance, why every representation of `role` fails to spread
+ * onto Solid's per-element JSX types) is real design intent, not obvious from the type alone — see
+ * `DECISIONS.md` → "`adapters/solid` — `ResolvedSlotProps`'s `ref`/`role` typing" for the full case.
+ */
+type ResolvedSlotProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignature<PropsOf<G>>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
+  class?: string | undefined;
+  ref?: (el: Element) => void;
+};
+/** An `asChild` render function, receiving the fully-resolved `ResolvedSlotProps<G>`. */
+type SlotRenderFn<G extends PolymorphicGenerics> = (props: ResolvedSlotProps<G>) => SolidElement;
+type AsChildProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignature<PropsOf<G>>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
+  as?: never;
+  asChild: true;
+  children: SlotRenderFn<G>;
+  class?: ClassName | undefined;
+  recipe?: keyof RecipeOf<G>;
+  ref?: unknown;
+};
+type PolymorphicProps<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<(SharedProps<G, TAs> & {
+  asChild?: false;
+  children?: unknown;
+}) | AsChildProps<G>>;
+type PolymorphicComponent<G extends PolymorphicGenerics> = {
+  <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicProps<G, TAs>): JSX.Element;
+  /**
+   * Non-generic fallback overload used for type extraction.
+   *
+   * TypeScript resolves conditional types such as
+   * `ComponentProps<typeof Component>` against only the final overload.
+   * Anchoring that overload to the default element preserves correct prop
+   * inference for tools such as Storybook and `ComponentProps`.
+   */
+  (props: PolymorphicProps<G, DefaultOf<G>>): JSX.Element;
+  displayName?: string;
+};
+/**
+ * A component's full prop contract — naming symmetry with React's/Preact's `ContractProps<T,
+ * Mode>`, not a fix for a gap: Solid has no version of the
+ * overload-resolution ceiling those two adapters need a marker to work around. `PolymorphicProps<G,
+ * TAs>` already folds both render modes into one unioned type (rather than two separate types the
+ * way React/Preact split them), and `PolymorphicComponent<G>`'s fallback overload already returns
+ * that whole union — so this alias is just `PolymorphicProps<G>` under a familiar name.
+ */
+type ContractProps<G extends PolymorphicGenerics> = PolymorphicProps<G>;
+//#endregion
+//#region ../../adapters/solid/src/create-contract-component.d.ts
+/**
+ * Creates a polymorphic Solid component with praxis-kit contracts applied.
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * `ref` is forwarded as an ordinary Solid ref callback. Pass `subComponents` to attach named
+ * sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ */
+export 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: SolidFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+  readonly subComponents?: TSubComponents;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>, TSubComponents>;
+//#endregion
+export type { AnyFactoryOptions, ContractProps, ElementRef, ElementType, EmptyRecord, FactoryOptions, PolymorphicComponent, PolymorphicGenerics, PolymorphicProps, ResolvedSlotProps, SlotRenderFn, SolidFactoryOptions };