praxis-kit 3.1.0 → 4.0.0

package/dist/web/index.d.ts

@@ -1,236 +1,8 @@
-import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
-
-type AnyRecord = Record<string, unknown>;
-
-type IntrinsicTag = keyof HTMLElementTagNameMap;
-
-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 IntrinsicProps = AnyRecord & {
-    role?: AriaRole;
-};
-
-type NonEmptyArray<T> = [T, ...T[]];
-
-type Numberish = number | `${number}`;
-
-type Primitive = string | number | boolean;
-
-type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
-
-type StrictMode = boolean | 'warn' | 'async-warn' | 'throw';
-
-type CardinalityInput = {
-    min?: number;
-    max?: number;
-};
-
-type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
-
-type ChildRulePosition = 'first' | 'last' | 'any';
-
-type ChildRuleInput<T = unknown, U extends T = T> = {
-    name: string;
-    match: ChildRuleMatch<T, U>;
-    cardinality?: CardinalityInput;
-    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;
-};
-
-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<{
-    [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$1;
-};
-
-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>;
-}
-
-interface CVAVariants<V extends VariantMap> {
-    variants?: V;
-}
-
-/**
- * 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];
-};
-
-/**
- * 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<Record<string, VariantSelection<V>>>;
-
-type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
-
-interface BaseClassOptions {
-    baseClassName?: ClassName;
-}
-
-type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string;
-
-interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
-    recipeMap?: Record<string, RecipeTarget<TVariants>>;
-}
-
-interface TagMapOptions {
-    tagMap?: TagMap;
-}
-
-type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
-
-type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
-
-type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
-
-type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
-
-type OwnedPropKeys = ReadonlySet<string>;
-
-type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
-    pipeline: ClassPipelineFn;
-    ownedKeys?: OwnedPropKeys;
-    readonly _pluginProps?: TProps;
-}>;
-
-type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, strict: StrictMode) => ClassPlugin<TProps>;
-
-type AriaContext = {
-    readonly tag: IntrinsicTag;
-    readonly implicitRole: AriaRole | undefined;
-    readonly effectiveRole: string | undefined;
-    readonly props: ReadonlyDeep<IntrinsicProps>;
-};
-
-type RemoveAttributeFixKind = `removeAttribute:${string}`;
-type InjectLiveFixKind = `injectLive:${string}`;
-type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
-
-type AriaFixResult = {
-    applied: false;
-    next: ReadonlyDeep<IntrinsicProps>;
-} | {
-    applied: true;
-    next: ReadonlyDeep<IntrinsicProps>;
-    previous: ReadonlyDeep<IntrinsicProps>;
-};
-type AriaFix = {
-    readonly kind: FixKind;
-    readonly priority?: number;
-    readonly source?: string;
-    readonly apply: (context: AriaContext) => AriaFixResult;
-};
-
-type Severity = 'error' | 'warning' | (string & {});
-
-type AriaInvalidBase<M extends string = string> = {
-    valid: false;
-    severity: Severity;
-    message: M;
-    attribute?: string;
-};
-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;
-
-type AriaRule<C extends AriaContext = AriaContext> = (context: C) => readonly AriaResult[];
-
-type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
-
-type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
-    readonly strict?: StrictMode;
-    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. */
-    readonly allowedAs?: readonly TAllowed[];
-};
-
-type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = {
-    readonly base?: ClassName;
-    readonly variants?: V;
-    readonly defaults?: Partial<DefaultVariants<V>>;
-    readonly compounds?: readonly CompoundVariant<V>[];
-    readonly presets?: TPreset;
-    readonly tags?: Readonly<TagMap>;
-    readonly plugin?: ClassPluginFactory<TPluginProps>;
-    readonly precomputedClasses?: Readonly<Record<string, string>>;
-};
-
-type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
-    normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
-}['normalize'];
-type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyRecord>;
-type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord, TAllowed extends ElementType = ElementType> = {
-    readonly tag?: TDefault;
-    readonly name?: string;
-    readonly defaults?: Partial<NoInfer<Props>>;
-    readonly normalize?: NormalizeFn<NoInfer<Props>>;
-    readonly styling?: StylingOptions<V, TPreset, TPluginProps>;
-    readonly enforcement?: EnforcementOptions<TAllowed>;
-};
-
-type FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
-
-declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+import { ElementType, AnyRecord, EmptyRecord, VariantMap, RecipeMap, ClassPluginFactory, FactoryOptions, ExtractPluginProps } from '@praxis-kit/core';
+export { AnyFactoryOptions } from '@praxis-kit/core';
+import { FilterPredicate } from '@praxis-kit/adapter-utils';
+export { defineContractComponent } from '@praxis-kit/adapter-utils';
+import { Diagnostics } from '@praxis-kit/diagnostics';
 
 /**
  * Options accepted by createContractComponent in the web adapter.
@@ -238,7 +10,7 @@ declare function defineContractComponent<O extends FactoryOptions>(options: O):
  * 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> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPluginProps> & {
+type WebFactoryOptions<TDefault extends ElementType = ElementType, TProps extends AnyRecord = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined> = FactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin> & {
     readonly filterProps?: FilterPredicate;
 };
 
@@ -249,7 +21,7 @@ type UnknownProps = Record<string, unknown>;
  * Describes the public contract without exposing HTMLElement's internal members.
  * Variant key instance properties are typed via TVariants.
  */
-type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>> = {
+type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = {
     new (): HTMLElement & {
         as: string | undefined;
         recipe: string | undefined;
@@ -258,9 +30,9 @@ type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
         update(): void;
     } & {
         [K in Extract<keyof TVariants, string>]?: string | null;
-    };
-    /** The resolved strict mode for this component — usable by subclasses for custom enforcement. */
-    readonly strict: Exclude<StrictMode, undefined>;
+    } & TPluginProps;
+    /** The resolved diagnostics for this component — usable by subclasses for custom enforcement. */
+    readonly diagnostics: Diagnostics;
 };
 
 /**
@@ -277,7 +49,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)
@@ -290,7 +62,7 @@ type WebContractComponent<TVariants extends Readonly<VariantMap> = Readonly<Empt
  * For non-reactive attributes (`aria-*`, `role`, `data-*`) call `element.update()`
  * after setting them to trigger an explicit pipeline re-run.
  */
-declare function createContractComponent<TDefault extends ElementType, TProps extends UnknownProps = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord>(options: WebFactoryOptions<TDefault, TProps, TVariants, TPreset, TPluginProps>): WebContractComponent<TVariants>;
+declare function createContractComponent<TDefault extends ElementType, TProps extends UnknownProps = EmptyRecord, TVariants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<TVariants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined>(options: WebFactoryOptions<TDefault, TProps, TVariants, TPreset, TPlugin>): WebContractComponent<TVariants, ExtractPluginProps<TPlugin>>;
 
 /**
  * Renders a praxis-kit web component to an HTML string without requiring a DOM.
@@ -303,4 +75,4 @@ declare function createContractComponent<TDefault extends ElementType, TProps ex
  */
 declare function renderToString(component: WebContractComponent, props?: UnknownProps, innerHTML?: string): string;
 
-export { type AnyFactoryOptions, type WebContractComponent, type WebFactoryOptions, createContractComponent, defineContractComponent, renderToString };
+export { type WebContractComponent, type WebFactoryOptions, createContractComponent, renderToString };