praxis-kit 0.1.0

package/dist/web/index.d.ts

@@ -0,0 +1,832 @@
+import "clsx";
+import { DiagnosticCode, DiagnosticInput, Diagnostics, DiagnosticsMode } from "../_shared/diagnostics.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;
+//#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'];
+/** 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 ../../adapters/web/src/types/generics.d.ts
+type RuntimeG<TDefault extends ElementType, Props extends AnyRecord, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants>> = PolymorphicGenerics<TDefault, Props, Variants, TPreset>;
+//#endregion
+//#region ../../lib/adapter-utils/src/types/filter-predicate.d.ts
+/**
+ * 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;
+//#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/web/src/types/web-options.d.ts
+/**
+ * Options accepted by createContractComponent in the web adapter.
+ *
+ * Identical shape to LitFactoryOptions — a plain HTMLElement subclass with
+ * no framework dependency. Light DOM only; Shadow DOM is out of scope.
+ */
+type WebFactoryOptions<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;
+};
+//#endregion
+//#region ../../adapters/web/src/types/primitives.d.ts
+type UnknownProps = AnyRecord;
+/**
+ * Constructor type returned by createContractComponent.
+ *
+ * Describes the public contract without exposing HTMLElement's internal members.
+ * Variant key instance properties are typed via TVariants.
+ *
+ * No `as` field, unlike an earlier design — see the `as` note on
+ * `createContractComponent`'s own doc comment for why: a custom element's tag is
+ * fixed at `customElements.define()` time, so there is no tag for `as` to switch.
+ *
+ * `G` is a phantom marker only — see `__generics` below — and defaults to the
+ * widest `PolymorphicGenerics` so existing two-argument usages of this type keep
+ * resolving exactly as before. Mirrors the Lit adapter's `LitContractComponent`.
+ */
+type WebContractComponent<TVariants extends Readonly<VariantMap> = NoVariants, TPluginProps extends AnyRecord = EmptyRecord, G extends PolymorphicGenerics = PolymorphicGenerics> = {
+  new (): HTMLElement & {
+    recipe: string | undefined;
+    praxisClass: string | undefined;
+    /** Re-runs the pipeline — call after setting non-reactive attributes (aria-*, role, data-*)
+     *  or a praxis-owned property directly (property assignment doesn't trigger
+     *  attributeChangedCallback — see createContractComponent's own doc comment). */
+    update(): void;
+  } & { [K in Extract<keyof TVariants, string>]?: string | null; } & TPluginProps;
+  /** The resolved diagnostics for this component — usable by subclasses for custom enforcement. */
+  readonly diagnostics: Diagnostics;
+  /**
+   * Type-only; never assigned at runtime. `createContractComponent` erases
+   * `TDefault`/`TProps`/`TPreset` entirely from its return type — only `TVariants`
+   * and `TPluginProps` survive as real instance-shape information. This field
+   * carries the full `PolymorphicGenerics` the component was built from so
+   * `GenericsOf`/`ContractProps` (`./contract-props`) can recover it from outside
+   * the file that built it — identical to `LitContractComponent.__generics`.
+   */
+  readonly __generics?: G;
+};
+//#endregion
+//#region ../../lib/contract-props/src/has-generics.d.ts
+/**
+ * The phantom-marker shape read back via `T extends HasGenerics<infer G> ? G : never`. See the
+ * README for why this exists.
+ *
+ * Type-only: never assigned at runtime. In React's `PolymorphicComponent<G>`, declaring `readonly
+ * __generics?: G` inline (structurally matching this shape) rather than writing `HasGenerics<G> &
+ * { ...call signatures... }` was necessary to keep `PolymorphicComponent<any>`-typed test helpers
+ * assignable — confirmed directly against that adapter's own real component type (see
+ * `adapters/react/src/shared/types/polymorphic-props.test.ts`), not reproducible in an isolated
+ * minimal mock (see this file's own `has-generics.test.ts`), so treat "inline, not intersected"
+ * as an adapter-level implementation detail this package's marker shape must stay compatible
+ * with, not a property `HasGenerics<G>` itself enforces.
+ *
+ * Do **not** "harden" this with a `unique symbol` or other nominal brand: the whole point is that
+ * an adapter's real callable component type structurally satisfies this shape by declaring the
+ * same optional string-keyed field inline. Nominal purity here would break that compatibility.
+ */
+interface HasGenerics<G> {
+  readonly __generics?: G;
+}
+//#endregion
+//#region ../../adapters/web/src/types/contract-props.d.ts
+/**
+ * Recovers a `WebContractComponent`'s `PolymorphicGenerics` descriptor from its own value type —
+ * identical to the Lit adapter's `GenericsOf<T>` (`adapters/lit/src/types/contract-props.ts`),
+ * since both adapters build a fixed-identity custom element with the same erased return type.
+ * Needs the phantom `__generics` marker (unlike Svelte's `GenericsOf<T>`) because
+ * `createContractComponent` here returns `WebContractComponent<TVariants, TPluginProps, G>`, not a
+ * `BuiltRuntime<G, TOptions>` — `TDefault`/`TProps`/`TPreset` are genuinely erased from the return
+ * type, so there is no ordinary type parameter left to `infer` them back out of.
+ * `WebContractComponent`'s own `__generics` field (`./primitives`) exists purely to make this
+ * recovery possible. Falls back to the widest `PolymorphicGenerics` for any non-praxis-kit value.
+ */
+type GenericsOf<T extends HasGenerics<PolymorphicGenerics>> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? G : PolymorphicGenerics;
+/**
+ * A component's full prop contract — the attributes a caller can set on the custom element,
+ * recovered from outside the file that built it. The Web adapter has exactly one render mode (no
+ * `asChild`/`render` — see the "known limitations" note atop `conformance.test.ts`), so unlike
+ * React's/Preact's `ContractProps<T, Mode>` this takes no `Mode` parameter: there is only ever one
+ * prop shape to pick.
+ *
+ * `as?: never` — deliberately absent, not merely undocumented. Every VDOM adapter's `as` is real
+ * tag polymorphism (it changes the rendered host element); a custom element's tag is fixed at
+ * `customElements.define()` time, so there is nothing for `as` to do here. `createContractComponent`
+ * strips it from the prop pipeline entirely (see that function's own doc comment) — this `never`
+ * makes that a type-level fact too, so `{ as: 'a' }` written against `ContractProps<T>` is a compile
+ * error, not a silently-ignored no-op a caller could believe was doing something.
+ *
+ * ```ts
+ * const Button = createContractComponent({ tag: 'button', name: 'Button', /* ... *\/ })
+ *
+ * type ButtonProps = ContractProps<typeof Button>
+ * ```
+ */
+type ContractProps<T extends HasGenerics<PolymorphicGenerics>> = Simplify<OmitIndexSignature<PropsOf<GenericsOf<T>>> & OmitIndexSignature<VariantProps<VariantsOf<GenericsOf<T>>>> & {
+  as?: never;
+  recipe?: keyof RecipeOf<GenericsOf<T>>;
+}>;
+//#endregion
+//#region ../../adapters/web/src/create-contract-component.d.ts
+/**
+ * Creates a plain `HTMLElement` subclass with praxis-kit contracts applied.
+ *
+ * No framework dependency. Register with `customElements.define()`:
+ *
+ * ```ts
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ *   enforcement: { diagnostics: warnDiagnostics },
+ * })
+ *
+ * customElements.define('praxis-button', Button)
+ * ```
+ *
+ * The pipeline runs synchronously on `connectedCallback` and on every
+ * `attributeChangedCallback` for praxis-owned attributes (variant keys,
+ * `variant-key`, `praxis-class`).
+ *
+ * For non-reactive attributes (`aria-*`, `role`, `data-*`) — or a praxis-owned
+ * property set directly rather than via `setAttribute` (property assignment
+ * alone never fires `attributeChangedCallback`) — call `element.update()` after
+ * to trigger an explicit pipeline re-run.
+ *
+ * **This adapter is a Custom Element host carrying a Praxis semantic contract — not a
+ * reimplementation of native HTML element behavior.** `options.tag` (`'button'` above) names the
+ * _intrinsic model_ Praxis resolves ARIA roles, content-model rules, and built-in prop
+ * normalizers (`disabledProps`, etc.) against — it is not, and was never meant to be, the tag
+ * actually written to the DOM. The DOM tag is whatever name a caller later passes to
+ * `customElements.define(name, Button)`, entirely separate from `options.tag` and not knowable by
+ * this function at all (registration happens externally, after this returns, possibly under
+ * multiple names or never). So for the example above:
+ *
+ * ```text
+ * Praxis intrinsic model:  button   (options.tag — drives ARIA/content-model/normalizers)
+ * DOM host:                praxis-button   (customElements.define()'s name — the actual element)
+ * ```
+ *
+ * A concrete consequence worth internalizing: `<praxis-button disabled>` gets `aria-disabled` from
+ * the `disabledProps` normalizer (correctly, since `disabled`'s HTML-boolean-attribute semantics
+ * are honored in `_buildProps()` below), but the browser does **not** make the custom element
+ * keyboard-inert, form-participating, or otherwise behave like a real `HTMLButtonElement` — that
+ * gap isn't a bug, it's the direct consequence of `class X extends HTMLElement`, and no ARIA
+ * attribute on any element, custom or not, ever supplies real interactive behavior. The contract
+ * layer (styling, variants, ARIA policy, child enforcement, attribute management, lifecycle hooks,
+ * diagnostics) and the host's actual interactive behavior are — and have to stay — conceptually
+ * separate; a caller who needs real button/link/input behavior supplies it themselves (`onElement`
+ * is the wiring point), the same way any `role="button"` `<div>` would require it. (Customized
+ * built-ins — `class X extends HTMLButtonElement` + `{ extends: 'button' }` — were considered and
+ * rejected for solving this: a real platform mechanism, but a different consumer-facing API
+ * (`<button is="…">` instead of `<praxis-button>`) with its own platform constraints, not worth the
+ * complexity it would add here.)
+ *
+ * **No `as` prop.** Like the Lit adapter (this one's closest sibling — both are fixed-identity
+ * custom elements, sharing `resolveHostState`/`renderBundleToString` from the shared adapter runtime),
+ * a custom element's DOM tag is fixed at `customElements.define()` time — once the model/host
+ * distinction above is explicit, this becomes easy: there is no tag for `as` to switch. An earlier
+ * design accepted `as` as a semantic-only override (never changing the rendered element, but
+ * changing which ARIA/content-model rules applied, as if it really were a different tag). That was
+ * worse than not having it: it could produce `role="link"`-shaped output with none of an anchor's
+ * actual keyboard/click/middle-click behavior — a real accessibility footgun regardless of the
+ * option's name — and it made `renderContractToString`'s output disagree with itself across calls
+ * to the same component, which can only ever produce `<praxis-button>…</praxis-button>` on the live
+ * client regardless of what tag `as` named. `as` is filtered out unconditionally in `_buildProps()`
+ * below (including as a raw, undeclared HTML attribute, not just a declared property) so
+ * `resolveHostState`/`renderBundleToString` — shared, unmodified, cross-adapter code — always
+ * resolve to `options.tag` here, on both the client and SSR paths. Need different semantics for one
+ * instance? Register a second component with a different `tag`, or set `role` directly — both
+ * already work today, unaffected by this.
+ */
+export 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: WebFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
+  readonly subComponents?: TSubComponents;
+}): WebContractComponent<TVariants, ExtractPluginProps<TPlugin>, RuntimeG<TDefault, TProps, TVariants, TPreset>> & TSubComponents;
+//#endregion
+//#region ../../adapters/web/src/render-to-string.d.ts
+/**
+ * Serializes a praxis-kit web component's **resolved contract** to an HTML string, without
+ * requiring a DOM — not Custom Element SSR, and not a hydration mechanism.
+ *
+ * This distinction matters and is easy to get wrong: the output element is `options.tag`
+ * (`<button>…</button>`, say), never the registered custom-element tag (`<praxis-button>`) —
+ * `createContractComponent`'s own doc comment covers why the two are different concepts ("the
+ * element Praxis models" vs. "the element actually in the DOM"). `customElements.define()` happens
+ * externally, after `createContractComponent()` returns, and this function has no way to know what
+ * name (if any) a caller eventually registers the class under, so there is no tag it could emit
+ * that's guaranteed to match. Even if it could, the browser's Custom Element upgrade mechanism only
+ * upgrades an exact tag-name match — a server-sent `<button>` can never become the live
+ * `<praxis-button>` no matter what the client bundle does, so this was never a viable
+ * SSR-then-upgrade path regardless of naming.
+ *
+ * Use this for what it actually is: previewing/testing the resolved styling + ARIA + attribute
+ * pipeline as plain HTML (static generation, snapshot tests, non-interactive contexts) — not for
+ * server-rendering markup you intend the live custom element to take over.
+ *
+ * `innerHTML` is treated as a pre-sanitized HTML string and inserted verbatim.
+ * Callers are responsible for escaping any untrusted content before passing it.
+ */
+export declare function renderContractToString(component: WebContractComponent, props?: UnknownProps, innerHTML?: string): string;
+//#endregion
+export type { AnyFactoryOptions, ContractProps, ElementType, EmptyRecord, FactoryOptions, GenericsOf, PolymorphicGenerics, WebContractComponent, WebFactoryOptions };