praxis-kit 1.1.0

package/dist/svelte/index.d.ts

@@ -0,0 +1,343 @@
+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 ClassName = string | string[];
+
+type EmptyRecord = Record<never, never>;
+
+type IntrinsicProps = AnyRecord & {
+    role?: AriaRole;
+};
+
+type NonEmptyArray<T> = [T, ...T[]];
+
+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 WithChildRules = {
+    enforcement?: {
+        children?: readonly unknown[];
+    };
+};
+
+type ValidResult = {
+    valid: true;
+};
+
+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>;
+
+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>[];
+}
+
+/** 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 DefaultVariants<V extends VariantMap> = {
+    [K in keyof V]?: VariantKey<V, K>;
+};
+
+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 PresetMap<V extends VariantMap = VariantMap> = Readonly<Record<string, VariantSelection<V>>>;
+
+interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends PresetMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
+    default: TDefault;
+    props: Props;
+    variants: Variants;
+    preset: TPreset;
+    allowed: TAllowed;
+}
+
+type PresetTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+
+interface BaseClassOptions {
+    baseClassName?: ClassName;
+}
+
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, variantKey?: string) => string;
+
+interface PresetOptions<TVariants extends VariantMap = VariantMap> {
+    presetMap?: Record<string, PresetTarget<TVariants>>;
+}
+
+interface TagMapOptions {
+    tagMap?: TagMap;
+}
+
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & PresetOptions<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 PresetMap<V> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = {
+    readonly base?: ClassName;
+    readonly variants?: V;
+    readonly defaults?: Partial<VariantProps<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 FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends PresetMap<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 ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends PresetMap<V> = Readonly<EmptyRecord>> = {
+    readonly defaultTag: TDefault;
+    readonly baseClassName?: ClassName;
+    readonly defaultProps?: Partial<Props>;
+    readonly tagMap?: Readonly<TagMap>;
+    readonly presetMap?: TPreset;
+    readonly variants?: V;
+    readonly defaultVariants?: Partial<VariantProps<V>>;
+    readonly compoundVariants?: readonly CompoundVariant<V>[];
+    readonly displayName?: string;
+    readonly strict: StrictMode;
+    readonly variantKeys: ReadonlySet<string>;
+    readonly normalizeFn?: NormalizeFn<Props>;
+    readonly childRules?: readonly ChildRuleInput[];
+    readonly ariaRules?: readonly AriaRule[];
+    readonly allowedAs?: readonly ElementType[];
+    readonly precomputedClasses?: Readonly<Record<string, string>>;
+};
+
+type ResolveAriaFn = <P extends IntrinsicProps>(tag: ElementType, props: P) => {
+    props: P;
+};
+
+type ResolveClassNameFn<Props extends AnyRecord, TSlot extends string = never> = (tag: ElementType, props: Props, className?: ClassName, variantKey?: TSlot) => string;
+
+type ResolvePropsFn<Props extends AnyRecord> = <P extends Partial<Props>>(props: P) => Simplify<Omit<Props, keyof P> & P>;
+
+type ResolveTagFn<TDefault extends ElementType> = <T extends ElementType | undefined = undefined>(as?: T) => T extends ElementType ? T : TDefault;
+
+type RuntimePluginField<TPlugin extends ClassPlugin | undefined> = TPlugin extends ClassPlugin ? {
+    readonly classPlugin: TPlugin;
+    readonly hasStyling: true;
+} : EmptyRecord;
+
+type PolymorphicRuntime<TDefault extends ElementType, Props extends AnyRecord, Variants extends VariantMap, TSlot extends string = never, TPreset extends PresetMap<Variants> = Readonly<Record<string, VariantSelection<Variants>>>, TPlugin extends ClassPlugin | undefined = ClassPlugin | undefined> = RuntimePluginField<TPlugin> & {
+    readonly options: Readonly<ResolvedFactoryOptions<TDefault, Props, Variants, TPreset>>;
+    readonly resolveTag: ResolveTagFn<TDefault>;
+    readonly resolveProps: ResolvePropsFn<Props>;
+    readonly resolveClasses: ResolveClassNameFn<Props, TSlot>;
+    readonly resolveAria: ResolveAriaFn;
+};
+
+declare abstract class StrictBase {
+    protected readonly strict: StrictMode;
+    constructor(strict: StrictMode);
+    protected violate(message: string): void;
+    protected warn(message: string): void;
+    protected invariant(condition: unknown, message: string): void;
+}
+
+declare class ChildrenEvaluator extends StrictBase {
+    #private;
+    constructor(rules: readonly ChildRuleInput[], strict?: StrictMode, context?: string);
+    evaluate(children: unknown[]): void;
+}
+
+declare const disabledProps: PropNormalizer;
+
+declare const invalidProps: PropNormalizer;
+
+declare function createPolymorphic<TDefault extends ElementType, Props extends AnyRecord, Variants extends Readonly<VariantMap>, TPreset extends PresetMap<Variants> = Readonly<EmptyRecord>>(options?: FactoryOptions<TDefault, Props, Variants, TPreset>): PolymorphicRuntime<TDefault, Props, Variants, Extract<keyof TPreset, string>, TPreset>;
+
+declare class SlotValidator extends StrictBase {
+    #private;
+    constructor(name: string, strict: StrictMode, elementTerm: string);
+    assertExclusive(): void;
+    warnDiscardedChildren(count: number): void;
+    assertSingleChild(count: number): void;
+}
+
+type FilterPredicate = (key: string, variantKeys: ReadonlySet<string>) => boolean;
+
+type BuiltChildrenEvaluator<TOptions extends WithChildRules> = TOptions extends {
+    enforcement: {
+        children: readonly unknown[];
+    };
+} ? {
+    childrenEvaluator: ChildrenEvaluator;
+} : EmptyRecord;
+
+type UnknownProps = Record<string, unknown>;
+
+type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends PresetMap<Variants> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord> = FactoryOptions<TDefault, Props, Variants, TPreset, TPluginProps> & {
+    /**
+     * 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.
+     */
+    filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
+};
+
+type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, PresetOf<G>>>;
+
+type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions extends WithChildRules = WithChildRules> = BuiltChildrenEvaluator<TOptions> & {
+    runtime: TypedRuntime<G>;
+    filterProps: FilterPredicate;
+    slotValidator: SlotValidator;
+};
+
+declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends PresetMap<Variants> = Readonly<EmptyRecord>, TPluginProps extends AnyRecord = EmptyRecord, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, Props & TPluginProps, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPluginProps> & TOptions): BuiltRuntime<PolymorphicGenerics<TDefault, Props & TPluginProps, Variants, TPreset>, TOptions>;
+
+declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+
+export { type BuiltRuntime, type FilterPredicate, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent, disabledProps, invalidProps };