praxis-kit 7.5.0 → 7.8.0

package/dist/preact/index.d.ts

@@ -1,6 +1,7 @@
 import { RequireAtLeastOne, Simplify, ReadonlyDeep, OmitIndexSignature } from 'type-fest';
 import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 import { ComponentChildren, VNode, ComponentType, JSX, Ref } from 'preact';
+import { HasGenerics, Mode, PickMode } from '@praxis-kit/contract-props';
 
 /**
  * A string-keyed object whose values are of type `T`.
@@ -189,20 +190,75 @@ 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 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>;
@@ -235,7 +291,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 {
@@ -404,7 +460,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> = {
@@ -520,8 +576,37 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
      * inference for tools such as Storybook and `ComponentProps`.
      */
     (props: PolymorphicProps<G, DefaultOf<G>>): AnyVNode;
+    /**
+     * Type-only; never assigned at runtime. See `HasGenerics<G>` (`@praxis-kit/contract-props`) for
+     * the full rationale — kept as an inline field rather than `HasGenerics<G> & {...}` because
+     * intersecting it onto this callable type changes how `PolymorphicComponent<any>` resolves
+     * against concrete instantiations (confirmed for React's identical shape,
+     * `adapters/react/src/shared/types/polymorphic-props.test.ts`); structurally identical to
+     * `HasGenerics<G>` either way, which is what lets `ContractProps` constrain against it.
+     */
+    readonly __generics?: G;
     displayName?: string;
 };
+/**
+ * Recovers a built `PolymorphicComponent<G>`'s prop shape for a specific render mode, from
+ * outside the file that built it — the missing piece `ComponentProps<typeof Component>` can't
+ * provide, since it always resolves against `PolymorphicComponent`'s normal-mode fallback
+ * overload (see that type's own doc comment).
+ *
+ * No `'render'` mode — Preact has no render-callback render strategy, unlike React.
+ *
+ * ```tsx
+ * const Container = createContractComponent({ tag: 'div', name: 'Container', /* ... *\/ })
+ *
+ * // Normal-mode props (equivalent to ComponentProps<typeof Container>, but works for asChild too):
+ * type ContainerProps = ContractProps<typeof Container>
+ *
+ * // A wrapper that always renders Container with asChild — ComponentProps<typeof Container>
+ * // fails here ("Type 'true' is not assignable to type 'false'"); ContractProps doesn't.
+ * type ContainerAsChildProps = ContractProps<typeof Container, 'asChild'>
+ * ```
+ */
+type ContractProps<T extends HasGenerics<PolymorphicGenerics>, M extends Exclude<Mode, 'render'> = 'normal'> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? PickMode<M, PolymorphicProps<G, DefaultOf<G>>, PolymorphicWithAsChild<G, DefaultOf<G>>, never> : never;
 
 /**
  * Creates a polymorphic Preact component with praxis-kit contracts applied.
@@ -548,4 +633,4 @@ declare function createContractComponent<TDefault extends ElementType, Props ext
     readonly subComponents?: TSubComponents;
 }): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>, TSubComponents>;
 
-export { type AnyFactoryOptions, type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent };
+export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent };