praxis-kit 3.1.1 → 4.0.1

package/dist/web/index.d.ts

@@ -1,6 +1,7 @@
-import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
+import { Except, RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
 
-type AnyRecord = Record<string, unknown>;
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -9,32 +10,165 @@ 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;
+interface SourcePosition {
+    line: number;
+    col: number;
+}
+interface SourceLocation {
+    file: string;
+    start: SourcePosition;
+    end?: SourcePosition;
+}
 
-type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+declare enum Severity$1 {
+    Debug = 0,
+    Info = 1,
+    Warning = 2,
+    Error = 3,
+    Fatal = 4
+}
+
+interface DiagnosticSuggestion {
+    title: string;
+    description?: string;
+    fix?: string;
+}
 
-type StrictMode = boolean | 'warn' | 'async-warn' | 'throw';
+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;
+}
 
-type CardinalityInput = {
-    min?: number;
-    max?: number;
+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>;
 
 type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
 
@@ -57,16 +191,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<{
@@ -75,18 +199,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>[];
 }
 
-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>;
 }
@@ -95,6 +214,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.
  *
@@ -104,7 +228,10 @@ interface CVAVariants<V extends VariantMap> {
 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.
  *
@@ -112,7 +239,6 @@ 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 BaseClassOptions {
@@ -145,7 +271,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 = {
@@ -179,8 +305,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;
@@ -197,11 +324,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[];
 };
 
@@ -260,8 +387,8 @@ type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
     } & {
         [K in Extract<keyof TVariants, string>]?: string | null;
     } & TPluginProps;
-    /** The resolved strict mode for this component — usable by subclasses for custom enforcement. */
-    readonly strict: Exclude<StrictMode, undefined>;
+    /** The resolved diagnostics for this component — usable by subclasses for custom enforcement. */
+    readonly diagnostics: Diagnostics;
 };
 
 /**
@@ -278,7 +405,7 @@ type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
  *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
  *     defaults: { intent: 'primary' },
  *   },
- *   enforcement: { strict: 'warn' },
+ *   enforcement: { diagnostics: warnDiagnostics },
  * })
  *
  * customElements.define('praxis-button', Button)