praxis-kit 7.5.0 → 7.8.0

package/dist/svelte/Polymorphic.svelte

@@ -80,6 +80,14 @@
     return bundle.runtime.resolveAria(tag, ep).props as ResolvedAttributes
   }
 
+  // Unlike buildDomProps above, this intentionally skips normalizeEventKeys and style
+  // serialization — the asChild path hands props straight to a caller-authored snippet, which
+  // spreads them onto its own element via ordinary JSX/attribute semantics, not through
+  // <svelte:element>'s own attribute application; event-handler keys keep their caller-authored
+  // casing (`onClick`, not lowercased to `onclick`), and `style` passes through however the
+  // caller wrote it (object or string), unserialized. See `ResolvedSlotProps<G>`
+  // (types/resolved-slot-props.ts) for the type this produces — it deliberately omits `style`
+  // rather than asserting either shape, for this exact reason.
   function buildSlotProps(props: UnknownProps, classStr: string | undefined): UnknownProps {
     const { role, ...r } = props
     return {

package/dist/svelte/index.d.ts

@@ -1,5 +1,6 @@
-import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
+import { RequireAtLeastOne, Simplify, ReadonlyDeep, OmitIndexSignature } from 'type-fest';
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
+import { Snippet } from 'svelte';
 
 /**
  * A string-keyed object whose values are of type `T`.
@@ -185,6 +186,11 @@ 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>;
@@ -196,19 +202,78 @@ type DefaultVariants<V extends VariantMap> = {
  * 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 RecipeMap<V extends VariantMap = VariantMap> = Readonly<StringMap<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> {
+/**
+ * The framework-neutral descriptor for a single praxis-kit component's contract — every render
+ * mechanism (tag resolution, prop merging, classes, ARIA) and every framework adapter's
+ * component type is built from this one shape. Deliberately just data: five type parameters and
+ * their corresponding properties, with no notion of JSX, call signatures, refs, or any
+ * framework-specific rendering concern. Each adapter (React, Vue, Svelte, Solid, Lit, Web) builds
+ * its own idiomatic component type on top of a `PolymorphicGenerics<...>` instantiation — see
+ * `PolymorphicComponent<G>` (`adapters/react/src/shared/types/polymorphic-props.ts`) for the
+ * React example — rather than this interface knowing anything about any of them.
+ *
+ * Use the `*Of<T>` accessor aliases below (`DefaultOf<G>`, `PropsOf<G>`, etc.) to read a single
+ * field back out of an already-resolved `G`, instead of indexing `G['default']` etc. directly at
+ * call sites — same rationale as any accessor: the property name stays an implementation detail,
+ * and every reader benefits together if it ever needs to change.
+ */
+interface PolymorphicGenerics<
+/**
+ * The element/tag this component renders as when the consumer doesn't override it via `as`
+ * (`AllowedOf<G>` permitting) — e.g. `'button'`, `'div'`. Defaults to the widest `ElementType`
+ * so a generic `PolymorphicGenerics` reference (with nothing else specified) still compiles.
+ */
+TDefault extends ElementType = ElementType, 
+/**
+ * The props this specific component declares — its own contract, before variants are mixed
+ * in. Defaults to `AnyRecord` for the same "still compiles unspecified" reason as `TDefault`.
+ */
+Props extends AnyRecord = AnyRecord, 
+/**
+ * This component's variant definitions (e.g. `{ intent: { primary: ..., ghost: ... } }`).
+ * Constrained to `Readonly<VariantMap>` — not the wider `AnyRecord` — specifically so `TPreset`
+ * below can be expressed as `RecipeMap<Variants>` and get real per-variant-key checking,
+ * instead of falling back to an unconstrained `RecipeMap<VariantMap>`.
+ */
+Variants extends Readonly<VariantMap> = Readonly<VariantMap>, 
+/**
+ * Named presets (`RecipeMap<Variants>`) — bundles of variant selections a consumer activates
+ * by key instead of repeating the same variant combination at every call site. Tied to
+ * `Variants`, not `AnyRecord`, precisely so a preset can only ever select keys/values that
+ * `Variants` actually defines — an invalid preset is a type error, not a silent no-op.
+ * Defaults to `Readonly<EmptyRecord>` (no presets), which is the common case: a component can
+ * have variants without necessarily defining any named presets over them, and most don't.
+ */
+TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, 
+/**
+ * The set of elements/tags a consumer is allowed to switch to via `as`. Defaults to the widest
+ * `ElementType`, under which `AllowedOf<G>` imposes no restriction at all (see
+ * `PolymorphicControlProps.as`'s own comment in the React adapter for the concrete effect this
+ * has at a component's actual call site).
+ */
+TAllowed extends ElementType = ElementType> {
     default: TDefault;
     props: Props;
     variants: Variants;
     preset: TPreset;
     allowed: TAllowed;
 }
+/** This component's variant definitions. See `PolymorphicGenerics`'s `Variants` parameter. */
+type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
+/** This component's named presets. See `PolymorphicGenerics`'s `TPreset` parameter. */
+type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
+/** The set of elements/tags this component may render as via `as`. See `PolymorphicGenerics`'s
+ *  `TAllowed` parameter. */
 type AllowedOf<T extends PolymorphicGenerics> = T['allowed'];
+/** The element/tag this component renders as by default. See `PolymorphicGenerics`'s `TDefault`
+ *  parameter. */
 type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+/** This component's own declared props, before variants are mixed in. See `PolymorphicGenerics`'s
+ *  `Props` parameter. */
 type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
 type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
@@ -241,7 +306,7 @@ interface BaseClassOptions {
 type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
 
 interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
-    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+    recipeMap?: StringMap<RecipeTarget<TVariants>>;
 }
 
 interface TagMapOptions {
@@ -411,7 +476,7 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
      * combination, skipping runtime class computation entirely when a match is found. Normally
      * generated by a build-time class-extraction plugin rather than hand-authored.
      */
-    readonly precomputedClasses?: Readonly<Record<string, string>>;
+    readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
@@ -496,7 +561,7 @@ type ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props ex
     readonly allowText?: boolean;
     readonly ariaRules?: readonly AriaRule[];
     readonly allowedAs?: readonly ElementType[];
-    readonly precomputedClasses?: Readonly<Record<string, string>>;
+    readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 
 type ResolveAriaFn = <P extends IntrinsicProps>(tag: ElementType, props: P) => {
@@ -514,7 +579,7 @@ type RuntimePluginField<TPlugin extends ClassPlugin | undefined> = TPlugin exten
     readonly hasStyling: true;
 } : EmptyRecord;
 
-type PolymorphicRuntime<TDefault extends ElementType, Props extends AnyRecord, Variants extends VariantMap, TSlot extends string = never, TPreset extends RecipeMap<Variants> = Readonly<Record<string, VariantSelection<Variants>>>, TPlugin extends ClassPlugin | undefined = ClassPlugin | undefined> = RuntimePluginField<TPlugin> & {
+type PolymorphicRuntime<TDefault extends ElementType, Props extends AnyRecord, Variants extends VariantMap, TSlot extends string = never, TPreset extends RecipeMap<Variants> = Readonly<StringMap<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>;
@@ -554,7 +619,7 @@ declare class ChildrenEvaluator extends InvariantBase {
     evaluate(children: unknown[], context?: ChildRuleContext): void;
 }
 
-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 function createPolymorphic<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>>;
 
 /**
  * Matches option types that declare child enforcement rules.
@@ -618,6 +683,10 @@ declare class SlotValidator extends InvariantBase {
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
 type UnknownProps = AnyRecord;
+type ResolvedProps = Readonly<UnknownProps>;
+type ResolvedAttributes = AnyRecord;
+type StyleValue = string | number;
+type StyleObject = Partial<StringMap<StyleValue | null | undefined>>;
 
 type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
     /**
@@ -627,7 +696,25 @@ type SvelteFactoryOptions<TDefault extends ElementType, Props extends UnknownPro
     filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
 };
 
-type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic2<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>>>;
+type RuntimeOptions = Readonly<Pick<ResolvedFactoryOptions, 'displayName' | 'diagnostics' | 'variantKeys' | 'childRules' | 'allowedAs' | 'normalizeFn' | 'htmlPropNormalizersFn' | 'htmlChildrenEvaluatorFn'>>;
+type TagResolver = Readonly<{
+    resolveTag(as?: ElementType): ElementType;
+}>;
+type PropsResolver = Readonly<{
+    resolveProps(props: UnknownProps): ResolvedProps;
+}>;
+type ClassResolver = Readonly<{
+    resolveClasses(tag: ElementType, props: ResolvedProps, className?: ClassName, recipe?: string): string | undefined;
+}>;
+type AriaResolver = Readonly<{
+    resolveAria<P extends IntrinsicProps>(tag: ElementType, props: P): {
+        props: P;
+    };
+}>;
+type Runtime = Readonly<TagResolver & PropsResolver & ClassResolver & AriaResolver & {
+    options: RuntimeOptions;
+}>;
+type TypedRuntime<G extends PolymorphicGenerics> = ReturnType<typeof createPolymorphic<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>>>;
 
 type OnElementFn<G extends PolymorphicGenerics = PolymorphicGenerics> = (element: ElementForTag<DefaultOf<G> | AllowedOf<G>>, getProps: () => Readonly<PropsOf<G>>) => void | (() => void);
 type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions extends WithChildRules = WithChildRules> = BuiltChildrenEvaluator<TOptions> & {
@@ -636,6 +723,105 @@ type BuiltRuntime<G extends PolymorphicGenerics = PolymorphicGenerics, TOptions
     slotValidator: SlotValidator;
     onElement?: OnElementFn<G>;
 };
+type AnyBuiltRuntime = {
+    runtime: Runtime;
+    filterProps: FilterPredicate;
+    slotValidator: SlotValidator;
+    childrenEvaluator?: ChildrenEvaluator;
+    onElement?: OnElementFn;
+};
+
+type AsProp = Readonly<{
+    as?: string;
+}>;
+type AsChildProp = Readonly<{
+    asChild?: boolean;
+}>;
+type PolymorphicPropsBase = Readonly<Simplify<{
+    children?: unknown;
+    class?: ClassName;
+    recipe?: string;
+} & AsProp & AsChildProp>>;
+type KnownProps = Readonly<PolymorphicPropsBase & UnknownProps>;
+/**
+ * Props accepted by `<Polymorphic>`, the component every `createContractComponent` bundle
+ * renders through in the Svelte adapter — distinct from `KnownProps` above, which describes
+ * the abstract polymorphic-prop contract rather than this specific component's props (it also
+ * carries the runtime bundle).
+ */
+interface PolymorphicComponentProps {
+    /** The contract bundle to render, from `createContractComponent`. */
+    bundle: AnyBuiltRuntime;
+    /** Overrides the default tag. String-only: `<svelte:element>` only accepts string tags. */
+    as?: string;
+    /** Renders `children` as a snippet receiving the resolved props, instead of the host element. */
+    asChild?: boolean;
+    /** Caller class, merged with the resolved variant classes. */
+    class?: string;
+    /** Selects a named preset from `styling.presets`. */
+    recipe?: string;
+    children?: Snippet | Snippet<[UnknownProps]>;
+    [key: string]: unknown;
+}
+
+type NormalizedOptions<G extends PolymorphicGenerics> = SvelteFactoryOptions<DefaultOf<G>, PropsOf<G>, VariantsOf<G>, RecipeOf<G>> & {
+    readonly name: string;
+    readonly diagnostics: Diagnostics;
+};
+
+/**
+ * Recovers a bundle's `PolymorphicGenerics` descriptor from its own value type — the Svelte
+ * analog of React's/Preact's `__generics` marker recovery (`@praxis-kit/contract-props`), but
+ * needs no marker at all: `createContractComponent` already returns `BuiltRuntime<G, TOptions>`
+ * directly (not an erased type), so `G` is a plain, ordinary type parameter to `infer` back out.
+ * The second type argument is fixed to `WithChildRules` (its own upper bound) rather than
+ * `infer`'d, since nothing here needs `TOptions` itself, only `G`. Falls back to the widest
+ * `PolymorphicGenerics` for any non-praxis-kit bundle, the same "no marker, nothing to recover"
+ * case `HasGenerics<G>`'s own `never` branch covers for React/Preact — a caller annotation, not an
+ * internal assertion, so a mismatched bundle should degrade gracefully rather than poison the
+ * whole expression with `never`.
+ */
+type GenericsOf<T extends AnyBuiltRuntime> = T extends BuiltRuntime<infer G, WithChildRules> ? G : PolymorphicGenerics;
+/**
+ * The exact props object an `asChild` snippet receives at runtime, once defaults, variant
+ * classes, and ARIA role resolution have all run — see `buildSlotProps` in `Polymorphic.svelte`
+ * (whose own doc comment covers the runtime-only asymmetries with the non-asChild path, such as
+ * skipped event-key normalization, that don't change this type's contract). `<Polymorphic>` itself
+ * can't be typed against this directly (its own `children` prop must stay `Snippet<[UnknownProps]>`,
+ * erased, since one `.svelte` file/`.d.ts` serves every bundle's `G`) — this type exists for a
+ * caller to annotate their own snippet parameter with instead:
+ *
+ * ```svelte
+ * <Polymorphic bundle={buttonBundle} asChild>
+ *   {#snippet children(props: ResolvedSlotProps<GenericsOf<typeof buttonBundle>>)}
+ *     <a {...props} href="/foo">Go</a>
+ *   {/snippet}
+ * </Polymorphic>
+ * ```
+ *
+ * `PropsOf<G>` stays `Partial` for the same reason it does in every other adapter's asChild-mode
+ * type: the type system can't prove every prop actually received a default, only that the runtime
+ * *tried*. `VariantProps<VariantsOf<G>>` needs no extra `Partial` wrapper — it's already fully
+ * optional at its own definition (`{ [K in keyof V]?: ... }`). `class` is narrowed to a plain
+ * resolved `string`.
+ *
+ * Three fields other adapters' `ResolvedSlotProps<G>` carry, or a caller might expect, are
+ * deliberately absent here rather than given an explicit (and unsafe) type — omitting a key
+ * entirely keeps `{...props}` spreads onto a real element honest and compiling; reading one of
+ * these off the object directly needs an explicit, locally-scoped cast instead:
+ * - `ref` — Svelte has no `ref` prop concept (DOM access is via `bind:this`/`onElement`); a caller
+ *   who writes a literal `ref` key gets it forwarded like any other unknown prop, untyped.
+ * - `role` — same reasoning Solid's `ResolvedSlotProps<G>` documents: every candidate type is
+ *   either too wide to spread onto an unknown target element's own narrower per-element `role`
+ *   union, or (`unknown`) fails that same assignability check outright, the same way `unknown`
+ *   would for `style` below.
+ * - `style` — unlike the non-asChild `<svelte:element>` path (`buildDomProps`), the asChild path
+ *   skips `style`-object serialization entirely: a caller's `style` prop passes through however
+ *   they wrote it (object or string), so there's no one shape to assert here either.
+ */
+type ResolvedSlotProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignature<PropsOf<G>>> & OmitIndexSignature<VariantProps<VariantsOf<G>>> & {
+    class?: string | undefined;
+};
 
 /**
  * Creates a praxis-kit contract bundle for use with Svelte's `<Polymorphic>` component.
@@ -675,4 +861,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
     readonly subComponents?: TSubComponents;
 }): MergeRecords<BuiltRuntime<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>, TOptions>, TSubComponents>;
 
-export { type AnyFactoryOptions, type BuiltRuntime, type ElementType, type EmptyRecord, type FilterPredicate, type PolymorphicGenerics, type SvelteFactoryOptions, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent };
+export { type AnyBuiltRuntime, type AnyFactoryOptions, type AsProp, type BuiltChildrenEvaluator, type BuiltRuntime, type ClassResolver, type ElementType, type EmptyRecord, type FilterPredicate, type GenericsOf, type KnownProps, type NormalizedOptions, type PolymorphicComponentProps, type PolymorphicGenerics, type PolymorphicPropsBase, type PropsResolver, type ResolvedAttributes, type ResolvedProps, type ResolvedSlotProps, type Runtime, type RuntimeOptions, type StyleObject, type StyleValue, type SvelteFactoryOptions, type TagResolver, type TypedRuntime, type UnknownProps, type WithChildRules, createContractComponent, defineContractComponent };