praxis-kit 3.1.1 → 4.0.1

package/dist/{merge-refs-BKyE8h8M.d.ts → merge-refs-CEpa0zK1.d.ts}

@@ -1,7 +1,8 @@
-import { RequireAtLeastOne, Simplify, ReadonlyDeep, NonEmptyTuple } from 'type-fest';
 import { ComponentType, PropsWithChildren, ReactElement, JSX, Ref, ReactNode } from 'react';
+import { Except, RequireAtLeastOne, Simplify, ReadonlyDeep, NonEmptyTuple } from 'type-fest';
 
-type AnyRecord = Record<string, unknown>;
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -10,32 +11,176 @@ type ElementType = IntrinsicTag | (string & {});
 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];
 
-type AriaRole = KnownAriaRole | (string & {});
-
 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;
+type AriaRole = KnownAriaRole | (string & {});
 type IntrinsicProps = AnyRecord & {
     role?: AriaRole;
 };
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
 
-type NonEmptyArray<T> = [T, ...T[]];
+declare enum DiagnosticCategory {
+    Contract = 0,
+    HTML = 1,
+    ARIA = 2,
+    Composition = 3,
+    Rendering = 4,
+    Accessibility = 5,
+    Performance = 6,
+    Internal = 7,
+    Deprecation = 8,
+    Lint = 9
+}
 
-type Numberish = number | `${number}`;
+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"
+}
 
-type Primitive = string | number | boolean;
+type MetadataMap = AnyRecord;
+type NodeId = string;
 
-type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+interface Diagnostic$1 {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+}
+
+type CapabilityMap = StringMap<boolean>;
+
+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;
+}
 
-type StrictMode = boolean | 'warn' | 'async-warn' | 'throw';
+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 CardinalityInput = {
-    min?: number;
-    max?: number;
+type MinMax = {
+    min: number;
+    max: number;
 };
+type CardinalityInput = Partial<MinMax>;
 
 type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
 
@@ -58,16 +203,6 @@ type ValidResult = {
     valid: true;
 };
 
-type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
-
-type VariantValue$1 = string | string[];
-
-type VariantStates<K extends string = string> = Record<K, VariantValue$1>;
-
-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>;
-
 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<{
@@ -76,22 +211,13 @@ type CompoundVariantConditions<V extends VariantMap> = Simplify<{
 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$1;
+    class: VariantValue;
 };
 
 interface CVACompounds<V extends VariantMap> {
     compoundVariants?: readonly CompoundVariant<V>[];
 }
 
-/** 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>;
-};
-type VariantValue<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]?: VariantValue<keyof V[K] & string>;
-};
-
 interface CVADefaults<V extends VariantMap> {
     defaultVariants?: DefaultVariants<V>;
 }
@@ -100,6 +226,11 @@ 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.
  *
@@ -109,7 +240,14 @@ interface CVAVariants<V extends VariantMap> {
 type VariantSelection<V extends VariantMap> = {
     [K in keyof V]?: keyof V[K];
 };
-
+/** 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>;
+};
+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.
  *
@@ -117,7 +255,7 @@ type VariantSelection<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;
@@ -128,8 +266,8 @@ interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props
 type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
 type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
 type AllowedOf<T extends PolymorphicGenerics> = T['allowed'];
-
-type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
 interface BaseClassOptions {
     baseClassName?: ClassName;
@@ -161,7 +299,7 @@ type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
     readonly _pluginProps?: TProps;
 }>;
 
-type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, strict: StrictMode) => ClassPlugin<TProps>;
+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 AriaContext = {
@@ -195,8 +333,9 @@ type Severity = 'error' | 'warning' | (string & {});
 type AriaInvalidBase<M extends string = string> = {
     valid: false;
     severity: Severity;
-    message: M;
+    message?: M;
     attribute?: string;
+    diagnostic?: DiagnosticInput;
 };
 type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
     fixable: true;
@@ -213,11 +352,11 @@ type AriaRule<C extends AriaContext = AriaContext> = (context: C) => readonly Ar
 type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
 
 type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
-    readonly strict?: StrictMode;
+    readonly diagnostics?: Diagnostics;
     readonly aria?: readonly AriaRule[];
     readonly children?: readonly ChildRuleInput[];
     readonly props?: readonly PropNormalizer[];
-    /** Restricts the `as` prop to this set of tags. Violations route through strict mode. */
+    /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
     readonly allowedAs?: readonly TAllowed[];
 };
 
@@ -245,11 +384,21 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
     readonly enforcement?: EnforcementOptions<TAllowed>;
 };
 
-type DefaultOf<T extends PolymorphicGenerics> = T['default'];
-type PropsOf<T extends PolymorphicGenerics> = T['props'];
-
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
+interface ComponentIdentity {
+    id: NodeId;
+    name: string;
+    tag: string;
+}
+
+interface ComponentDefinition {
+    identity: ComponentIdentity;
+    capabilities: CapabilityMap;
+    metadata: MetadataMap;
+    diagnostics: Diagnostic$1[];
+}
+
 type UnknownProps = Record<string, unknown>;
 type SlotComponent = ComponentType<UnknownProps>;
 
@@ -261,6 +410,16 @@ type SlotComponent = ComponentType<UnknownProps>;
  */
 type RenderCallbackProps = Readonly<Record<string, unknown>>;
 
+type SlottableProps = PropsWithChildren;
+declare function Slottable({ children }: SlottableProps): ReactElement;
+
+/** Structural subset of `CompiledComponentArtifact` consumed by the React adapter. */
+interface CompiledArtifact {
+    readonly definition: ComponentDefinition;
+    readonly precomputed?: {
+        readonly variantLookup?: Record<string, string>;
+    };
+}
 /**
  * Extends FactoryOptions with React-specific configuration.
  * slotComponent is intentionally not in core — it is a React rendering concern.
@@ -274,11 +433,11 @@ type ReactFactoryOptions<TDefault extends ElementType, Props extends UnknownProp
      * Receives `runtime.options.variantKeys` as a convenience if needed.
      */
     filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
+    /** Pre-compiled artifact from `@praxis-kit/runtime`'s compiler. When provided, replaces the stub
+     *  definition and enables the precomputed variant lookup fast path. */
+    artifact?: CompiledArtifact;
 };
 
-type SlottableProps = PropsWithChildren;
-declare function Slottable({ children }: SlottableProps): ReactElement;
-
 /** Maps a core ElementType to its DOM instance type for ref inference. */
 type ElementRef<T extends ElementType> = T extends IntrinsicTag ? HTMLElementTagNameMap[T] : unknown;
 /** @internal React JSX intrinsic props for a given element type. */