praxis-kit 4.0.1 → 4.1.0

package/dist/svelte/index.d.ts

@@ -1,7 +1,9 @@
-import { Except, RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
+import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
+import { Diagnostics, DiagnosticInput } from '../_shared/diagnostics.js';
 
 type StringMap<T = unknown> = Record<string, T>;
 type AnyRecord = StringMap<unknown>;
+type EmptyRecord = Record<never, never>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -12,7 +14,6 @@ type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
 
 type Booleanish = boolean | 'true' | 'false';
 type ClassName = string | string[];
-type EmptyRecord = Record<never, never>;
 type NonEmptyArray<T> = [T, ...T[]];
 type Numberish = number | `${number}`;
 type Primitive = string | number | boolean;
@@ -22,154 +23,19 @@ type IntrinsicProps = AnyRecord & {
 };
 type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
 
-declare enum DiagnosticCategory {
-    Contract = 0,
-    HTML = 1,
-    ARIA = 2,
-    Composition = 3,
-    Rendering = 4,
-    Accessibility = 5,
-    Performance = 6,
-    Internal = 7,
-    Deprecation = 8,
-    Lint = 9
-}
-
-declare enum DiagnosticCode {
-    MissingRequiredChild = "COMP1001",
-    InvalidParent = "COMP1002",
-    InvalidChild = "COMP1003",
-    UnexpectedChild = "COMP1004",
-    AmbiguousChild = "COMP1005",
-    CardinalityMin = "COMP1006",
-    CardinalityMax = "COMP1007",
-    PositionViolation = "COMP1008",
-    AllowedAsViolation = "COMP1009",
-    SlotExclusive = "SLOT1001",
-    SlotSingleChild = "SLOT1002",
-    SlotDiscardedChildren = "SLOT1003",
-    SlotRenderFn = "SLOT1004",
-    MissingAriaRelationship = "ARIA2001",
-    AriaViolation = "ARIA2002",
-    AriaAttributeInvalid = "ARIA2003",
-    AriaMissingLiveRegion = "ARIA2004",
-    AriaMissingAtomic = "ARIA2005",
-    AriaRelevantInvalidToken = "ARIA2006",
-    AriaRelevantSuperseded = "ARIA2007",
-    AriaInvalidRole = "ARIA2008",
-    AriaMissingAccessibleName = "ARIA2009",
-    AriaAttributeOnPresentational = "ARIA2010",
-    AriaHiddenOnFocusable = "ARIA2011",
-    AriaRequiredProperty = "ARIA2012",
-    AriaInvalidAttributeValue = "ARIA2013",
-    AriaRedundantLevelAttribute = "ARIA2014",
-    InvalidHeadingHierarchy = "HTML3001",
-    HtmlEmptyRole = "HTML3002",
-    HtmlImplicitRoleRedundant = "HTML3003",
-    HtmlImplicitRoleOverride = "HTML3004",
-    HtmlStandaloneRegionOverride = "HTML3005",
-    HtmlLandmarkRoleOverride = "HTML3006",
-    HtmlInvalidChild = "HTML3007",
-    InvalidRenderingTarget = "RENDER4001",
-    LintDeadCompoundKey = "LINT5001",
-    LintDeadCompoundValue = "LINT5002",
-    LintDeadCompoundNonLiteral = "LINT5003",
-    LintMissingStrict = "LINT5004",
-    LintInvalidDefaultKey = "LINT5005",
-    LintInvalidDefaultValue = "LINT5006",
-    LintInvalidDefaultNonLiteral = "LINT5007",
-    LintNegativeMin = "LINT5008",
-    LintNegativeMax = "LINT5009",
-    LintMaxLessThanMin = "LINT5010",
-    LintZeroMax = "LINT5011",
-    LintMultipleFirst = "LINT5012",
-    LintMultipleLast = "LINT5013",
-    LintMinSumExceedsCapacity = "LINT5014",
-    LintCardinalityViolation = "LINT5015",
-    LintAriaTagOverride = "LINT5016",
-    ContractUnknownVariantDim = "COMP1010",
-    ContractUnknownVariantValue = "COMP1011",
-    ContractUnknownRecipeKey = "COMP1012",
-    ContractInvalidVariantValue = "COMP1013",
-    TailwindMultipleDisplayProps = "CSS6001",
-    TailwindReservedLayoutLiteral = "CSS6002",
-    TailwindDeadVariantClass = "CSS6003",
-    PluginInvalidShape = "PLUGIN7001",
-    PluginPipelineReturnType = "PLUGIN7002",
-    InternalError = "INTERNAL9000"
-}
-
-interface SourcePosition {
-    line: number;
-    col: number;
-}
-interface SourceLocation {
-    file: string;
-    start: SourcePosition;
-    end?: SourcePosition;
-}
-
-declare enum Severity$1 {
-    Debug = 0,
-    Info = 1,
-    Warning = 2,
-    Error = 3,
-    Fatal = 4
-}
-
-interface DiagnosticSuggestion {
-    title: string;
-    description?: string;
-    fix?: string;
-}
-
-type Context = AnyRecord;
-type Metadata = AnyRecord;
-interface Diagnostic {
-    code: DiagnosticCode;
-    severity: Severity$1;
-    category: DiagnosticCategory;
-    message: string;
-    rationale?: string;
-    component?: string;
-    contract?: string;
-    location?: SourceLocation;
-    suggestions?: DiagnosticSuggestion[];
-    context?: Context;
-    metadata?: Metadata;
-}
-
-declare enum Enforcement {
-    Ignore = 0,
-    Report = 1,
-    Throw = 2
-}
-interface DiagnosticPolicy {
-    resolve(diagnostic: Diagnostic): Enforcement;
-}
-
-interface DiagnosticReporter {
-    report(diagnostic: Diagnostic): void;
-}
-
-type DiagnosticInput = Except<Diagnostic, 'severity'>;
-declare class Diagnostics {
-    private readonly reporter;
-    private readonly policy;
-    readonly active: boolean;
-    constructor(reporter: DiagnosticReporter, policy?: DiagnosticPolicy);
-    report(diagnostic: Diagnostic): Diagnostic;
-    warn(input: DiagnosticInput): Diagnostic;
-    error(input: DiagnosticInput): Diagnostic;
-    info(input: DiagnosticInput): Diagnostic;
-}
-
 type MinMax = {
     min: number;
     max: number;
 };
 type CardinalityInput = Partial<MinMax>;
 
+/** Structural counterpart to `@praxis-kit/contract`'s `ChildrenEvaluator` class — `lib/primitive`
+ *  may not depend on `lib/contract` (see `primitive-no-upper-layers` in .dependency-cruiser.cjs),
+ *  so this describes only the shape consumers actually call. Mirrors `AriaEngine`'s pattern. */
+type ChildrenEvaluator$1 = {
+    evaluate: (children: unknown[]) => void;
+};
+
 type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
 
 type ChildRulePosition = 'first' | 'last' | 'any';
@@ -197,34 +63,16 @@ type ValidResult = {
     valid: true;
 };
 
-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;
-};
-
-interface CVACompounds<V extends VariantMap> {
-    compoundVariants?: readonly CompoundVariant<V>[];
-}
-
-interface CVADefaults<V extends VariantMap> {
-    defaultVariants?: DefaultVariants<V>;
-}
-
-interface CVAVariants<V extends VariantMap> {
-    variants?: V;
-}
-
 type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+
 type VariantValue = string | string[];
+
 type VariantStates<K extends string = string> = Record<K, VariantValue>;
+
 type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+
 type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+
 /**
  * A partial selection of variant states authored at factory definition time.
  *
@@ -234,10 +82,12 @@ type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof
 type VariantSelection<V extends VariantMap> = {
     [K in keyof V]?: keyof V[K];
 };
+
 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>;
 };
+
 /**
  * A static, immutable map of named presets to partial variant selections.
  *
@@ -245,7 +95,9 @@ type DefaultVariants<V extends VariantMap> = {
  * avoiding the need to repeat variant combinations at each call site.
  */
 type RecipeMap<V extends VariantMap = VariantMap> = Readonly<Record<string, VariantSelection<V>>>;
+
 type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+
 interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
     default: TDefault;
     props: Props;
@@ -254,6 +106,29 @@ interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props
     allowed: TAllowed;
 }
 
+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;
+};
+
+interface CVACompounds<V extends VariantMap> {
+    compoundVariants?: readonly CompoundVariant<V>[];
+}
+
+interface CVADefaults<V extends VariantMap> {
+    defaultVariants?: DefaultVariants<V>;
+}
+
+interface CVAVariants<V extends VariantMap> {
+    variants?: V;
+}
+
 interface BaseClassOptions {
     baseClassName?: ClassName;
 }
@@ -285,8 +160,12 @@ type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
 }>;
 
 type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics) => ClassPlugin<TProps>;
-type ExtractPluginProps<TPlugin extends ClassPluginFactory<AnyRecord> | undefined> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? EmptyRecord : T : EmptyRecord;
-type PluginInstance<TPlugin extends ClassPluginFactory<AnyRecord> | undefined> = TPlugin extends ClassPluginFactory<infer TProps> ? ClassPlugin<TProps> : undefined;
+/** `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 ? EmptyRecord : T : EmptyRecord;
+type PluginInstance<TPlugin extends AnyClassPluginFactory> = TPlugin extends ClassPluginFactory<infer TProps> ? ClassPlugin<TProps> : undefined;
 
 type AriaContext = {
     readonly tag: IntrinsicTag;
@@ -346,7 +225,7 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
     readonly allowedAs?: readonly TAllowed[];
 };
 
-type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined> = {
+type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = {
     readonly base?: ClassName;
     readonly variants?: V;
     readonly defaults?: Partial<DefaultVariants<V>>;
@@ -360,8 +239,8 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
     normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
 }['normalize'];
-type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, ClassPluginFactory<AnyRecord> | undefined>;
-type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined, TAllowed extends ElementType = ElementType> = {
+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> = {
     readonly tag?: TDefault;
     readonly name?: string;
     readonly defaults?: Partial<NoInfer<Props>>;
@@ -384,6 +263,7 @@ type ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props ex
     readonly variantKeys: ReadonlySet<string>;
     readonly normalizeFn?: NormalizeFn<Props>;
     readonly htmlPropNormalizersFn?: (tag: unknown) => readonly PropNormalizer[] | undefined;
+    readonly htmlChildrenEvaluatorFn?: (tag: unknown) => ChildrenEvaluator$1 | undefined;
     readonly childRules?: readonly ChildRuleInput[];
     readonly ariaRules?: readonly AriaRule[];
     readonly allowedAs?: readonly ElementType[];
@@ -428,7 +308,7 @@ declare class ChildrenEvaluator extends InvariantBase {
     evaluate(children: unknown[]): void;
 }
 
-declare function createPolymorphic<TDefault extends ElementType, Props extends AnyRecord, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined>(options?: FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicRuntime<TDefault, Props, Variants, Extract<keyof TPreset, string>, TPreset, PluginInstance<TPlugin>>;
+declare function createPolymorphic2<TDefault extends ElementType, Props extends AnyRecord, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory>(options?: FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicRuntime<TDefault, Props, Variants, Extract<keyof TPreset, string>, TPreset, PluginInstance<TPlugin>>;
 
 declare class SlotValidator extends InvariantBase {
     #private;
@@ -450,9 +330,9 @@ type BuiltChildrenEvaluator<TOptions extends WithChildRules> = TOptions extends
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
-type UnknownProps = Record<string, unknown>;
+type UnknownProps = AnyRecord;
 
-type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
     /**
      * 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.
@@ -460,7 +340,7 @@ type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownPro
     filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
 };
 
-type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>>>;
+type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic2<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>>>;
 
 type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions extends WithChildRules = WithChildRules> = BuiltChildrenEvaluator<TOptions> & {
     runtime: TypedRuntime<G>;
@@ -468,6 +348,6 @@ type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions
     slotValidator: SlotValidator;
 };
 
-declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & TOptions): BuiltRuntime<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>, TOptions>;
+declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & TOptions): BuiltRuntime<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>, TOptions>;
 
 export { type AnyFactoryOptions, type BuiltRuntime, type ElementType, type EmptyRecord, type FilterPredicate, type PolymorphicGenerics, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent };