praxis-kit 0.1.0 → 1.0.2

package/dist/svelte/index.d.ts

@@ -25,20 +25,6 @@ type EmptyRecord = Record<never, never>;
  * `{ Header, Content, Footer }`.
  */
 type SubComponentMap = Readonly<AnyRecord>;
-/**
- * Default `Variants` type for components that declare no variants.
- *
- * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
- * editor hovers remain self-descriptive.
- */
-type NoVariants = Readonly<EmptyRecord>;
-/**
- * Default `TPreset` type for components that declare no named presets.
- *
- * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
- * editor hovers remain self-descriptive.
- */
-type NoPreset = Readonly<EmptyRecord>;
 /**
  * Fallback for `ExtractPluginProps<TPlugin>` when a plugin contributes no
  * props, including the no-plugin case.
@@ -568,16 +554,6 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
   normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
 }['normalize'];
-/**
- * The type-erased shape of {@link FactoryOptions} — every generic parameter widened to its bound.
- *
- * Use it for a value that must hold *any* factory config (a registry, a generic wrapper). It
- * cannot check `styling.compounds` conditions against the real variant keys/values, because it
- * has forgotten what they are — for that, annotate against `FactoryOptions<...>` with the concrete
- * generics (or `satisfies FactoryOptions<'button', Props, typeof variants>`), which keeps an
- * invalid compound condition a type error rather than a silent no-op.
- */
-type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
 /**
  * The framework-neutral component-authoring config passed to `createContractComponent` in every
  * adapter: default tag + name, own-prop defaults, a `normalize` transform, `styling` (variants,
@@ -587,7 +563,9 @@ type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, Reci
  * `satisfies FactoryOptions<TDefault, Props, typeof variants, ...>` on a config object narrows
  * `styling.compounds` conditions to the real per-variant-key shape — including resolving a
  * boolean-shaped axis (`{ true, false }`) to a real `boolean` — so a condition naming a variant or
- * value that does not exist is a compile error. `AnyFactoryOptions` cannot do this.
+ * value that does not exist is a compile error. Leaving `V` at the bare `VariantMap` instead
+ * (whether via `FactoryOptions`'s own default or an explicit erased instantiation) forgets that
+ * shape entirely, so the same invalid condition becomes a silent no-op instead.
  */
 type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
   /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
@@ -596,6 +574,33 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
   readonly name?: string;
   /** Values used for the component's own (non-variant) props when the consumer omits them. */
   readonly defaults?: Partial<NoInfer<Props>>;
+  /**
+   * Optional, type-only declaration of this component's complete own-prop shape — present purely
+   * for type recovery, never read at runtime (see `declareProps` in `@praxis-kit/adapter-utils`).
+   *
+   * `defaults` alone can only prove a prop *has a default*, not that it's the complete prop model
+   * a component accepts — a `defaults: { size: 'md' }` component may still take `onClick`,
+   * `disabled`, and other props with no default at all, none of which a `defaults`-only recovery
+   * can see (see `ContractPropsFrom`'s own doc comment for the general shape of this problem).
+   * `props` closes that gap: when present, `ContractPropsOf<C>` / `ContractProps<typeof Component>`
+   * recover this declared type directly and exactly, in place of the necessarily-partial,
+   * literal-widened recovery `defaults` alone allows.
+   *
+   * Typed as `object | undefined`, not `NoInfer<Props> | undefined` like `defaults`/`onElement` —
+   * deliberately decoupled from this interface's own `Props` generic, unlike those two fields.
+   * `defaults`/`onElement` are tied to `Props` because real runtime code reads them against a
+   * concretely-resolved `Props` for a real call; `props` is never read at runtime at all (see
+   * above), so it has no such need, and tying it to `Props extends AnyRecord` would force every
+   * hand-declared prop `interface`/`type` an author passes through `declareProps<Props>()` to
+   * structurally satisfy `Record<string, unknown>` — a real TypeScript limitation (a named type
+   * without an index signature never satisfies that, even via plain assignment, only a fresh
+   * object literal does) that would make this field far more awkward to use for its one real job:
+   * carrying an author's own already-precise prop type through untouched. `ContractPropsFrom`
+   * (`contract-model.ts`) recovers the real value here structurally, straight off `O`'s own
+   * literal type — independent of this field's declared type, same as every other `Contract*From`
+   * derivation in that file.
+   */
+  readonly props?: object | undefined;
   /**
    * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
    * normalizers see the same input. Use this for component-specific prop shaping — anything
@@ -650,7 +655,9 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
    *
    * Return a cleanup function to run when the instance unmounts.
    */
-  readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
+  readonly onElement?: {
+    onElement(element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>): void | (() => void);
+  }['onElement'];
 };
 //#endregion
 //#region ../../lib/primitive/src/types/factory/resolved-factory-options.d.ts
@@ -687,6 +694,154 @@ type ResolvedFactoryOptions<TDefault extends ElementType = ElementType, Props ex
   readonly precomputedClasses?: Readonly<StringMap<string>>;
 };
 //#endregion
+//#region ../../lib/primitive/src/types/factory/contract-model.d.ts
+/**
+ * The pipeline this file implements:
+ *
+ * ```text
+ * O (a raw contract literal)
+ *   → Contract*From<O>        one derivation per dimension, straight off O's own shape
+ *   → ContractDimensions<O>   the six derivations, assembled
+ *   → ContractModel<...>      the same six values, as a required-field carrier
+ *   → ContractModelOf<C>      resolves an already-`defineContract`-ed C's real model,
+ *                             or reconstructs one from a raw C via ContractModelFrom
+ * ```
+ *
+ * See `DECISIONS.md`'s `defineContract` entry for the TypeScript limitations that shaped the
+ * derivations below.
+ */
+/**
+ * Canonical type-level representation of a contract's dimensions — the contract-level counterpart
+ * to `PolymorphicGenerics`. Every field is required, so a field's presence is never ambiguous the
+ * way it is on an optional `FactoryOptions` field.
+ */
+interface ContractModel<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, V extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<VariantMap> = RecipeMap<VariantMap>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> {
+  readonly tag: TDefault;
+  readonly props: Props;
+  readonly variants: V;
+  readonly preset: TPreset;
+  readonly plugin: TPlugin;
+  readonly allowed: TAllowed;
+}
+/**
+ * The phantom-marker shape read back via `T extends HasContractModel<infer M> ? M : ...` — the
+ * contract-level counterpart to `lib/contract-props`'s `HasGenerics<G>`. Type-only: never assigned
+ * at runtime.
+ *
+ * `__model` is **required**, not optional like `HasGenerics<G>`'s `__generics?` — an optional field
+ * would make `C extends HasContractModel<infer M>` trivially succeed for any `C`, defeating the
+ * one thing this marker exists to answer: did `C` really go through `defineContract`?
+ */
+interface HasContractModel<M extends ContractModel = ContractModel> {
+  readonly __model: M;
+}
+type ContractTagFrom<O> = O extends {
+  tag: infer TDefault extends ElementType;
+} ? TDefault : ElementType;
+/** `'img'` → `string`, `1` → `number`, `true` → `boolean` — undoes `defineContract`'s `const O`
+ *  literal narrowing so a `defaults` value doesn't become the only value a caller may pass. */
+type WidenLiteral<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type WidenShallow<T> = { [K in keyof T]: WidenLiteral<T[K]>; };
+/** What the author explicitly declared, via `props: declareProps<Props>()`
+ *  (`@praxis-kit/adapter-utils`) — used exactly as declared, no `Partial`/widening/`data-*`
+ *  stripping (see `DefaultPropsFrom` for why those exist there but not here). */
+type DeclaredPropsFrom<O> = O extends {
+  props: infer Props extends object | undefined;
+} ? [NonNullable<Props>] extends [never] ? never : NonNullable<Props> & AnyRecord : never;
+/** What can be inferred from `defaults` — partial at best, since a default only proves a prop
+ *  *has* one, not that it's the complete prop set. `Partial`: a defaulted prop is optional to the
+ *  caller by definition. `data-*` keys are dropped — every adapter has its own passthrough for
+ *  those already (finding #43). */
+type DefaultPropsFrom<O> = O extends {
+  defaults: infer Props extends AnyRecord;
+} ? Partial<WidenShallow<Omit<Props, Extract<keyof Props, `data-${string}`>>>> : never;
+/** Declared beats defaulted beats nothing. `[X] extends [never]`, not bare `X extends never` —
+ *  tuple-wrapped so the check doesn't distribute if `X` is ever a union containing `never`. */
+type ContractPropsFrom<O> = [DeclaredPropsFrom<O>] extends [never] ? [DefaultPropsFrom<O>] extends [never] ? EmptyRecord : DefaultPropsFrom<O> : DeclaredPropsFrom<O>;
+type ContractVariantsFrom<O> = O extends {
+  styling: {
+    variants: infer V extends Readonly<VariantMap>;
+  };
+} ? V : Readonly<EmptyRecord>;
+type ContractPresetFrom<O> = O extends {
+  styling: {
+    presets: infer TPreset extends RecipeMap<VariantMap>;
+  };
+} ? TPreset : Readonly<EmptyRecord>;
+type ContractPluginFrom<O> = O extends {
+  styling: {
+    plugin: infer TPlugin extends AnyClassPluginFactory;
+  };
+} ? TPlugin : AnyClassPluginFactory;
+type ContractAllowedFrom<O> = O extends {
+  enforcement: {
+    allowedAs: readonly (infer TAllowed extends ElementType)[];
+  };
+} ? TAllowed : ElementType;
+/** The six derivations above, assembled — the direct input to `ContractModel`. */
+type ContractDimensions<O> = {
+  readonly tag: ContractTagFrom<O>;
+  readonly props: ContractPropsFrom<O>;
+  readonly variants: ContractVariantsFrom<O>;
+  readonly preset: ContractPresetFrom<O>;
+  readonly plugin: ContractPluginFrom<O>;
+  readonly allowed: ContractAllowedFrom<O>;
+};
+/**
+ * Builds a `ContractModel` from a raw literal `O` — the fallback path `ContractModelOf<C>` uses
+ * when `C` never went through `defineContract` (no `__model` marker to read directly), and what
+ * `defineContract` itself attaches as that marker for a `C` that did.
+ */
+type ContractModelFrom<O> = ContractDimensions<O> extends (infer D extends ContractDimensions<O>) ? ContractModel<D['tag'], D['props'], D['variants'], D['preset'], D['plugin'], D['allowed']> : never;
+/**
+ * Resolves "does `C` carry a real `ContractModel` already, or do we need to build one from its raw
+ * shape" — every `Contract*Of` accessor (`contract-of.ts`) is a one-line projection off this.
+ */
+type ContractModelOf<C> = C extends HasContractModel<infer M> ? M : ContractModelFrom<C>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-of.d.ts
+/**
+ * `FactoryOptions`-level accessor family, mirroring `polymorphic-generics.ts`'s `*Of<T>`
+ * convention (`DefaultOf<G>`, `PropsOf<G>`, etc.) but applied one layer up, to a contract itself
+ * rather than to the `PolymorphicGenerics` an adapter derives from it.
+ *
+ * Named with a `Contract` prefix specifically to avoid colliding with `polymorphic-generics.ts`'s
+ * own `PropsOf`/`VariantsOf`/`RecipeOf`/`AllowedOf`/`DefaultOf` — both families are re-exported
+ * from `@praxis-kit/core`, so a name clash would be a real conflict, not a style nit.
+ *
+ * Each accessor is a trivial projection off `ContractModelOf<C>` (`contract-model.ts`) — the one
+ * place that resolves "does `C` carry a real `ContractModel` (via `defineContract`) or does one
+ * need reconstructing from `C`'s raw shape," so every accessor shares one implementation of that
+ * resolution rather than repeating it. See `contract-model.ts`'s own doc comments for the
+ * `ContractXFrom<O>` derivation each of these ultimately reads through, and `DECISIONS.md`'s
+ * `defineContract` entry for the design history behind the required-pattern-match technique.
+ */
+type ContractTagOf<C extends FactoryOptions> = ContractModelOf<C>['tag'];
+/** See this file's own doc comment. Best-effort when `C` has no `ContractModel` marker — see
+ *  `ContractPropsFrom`'s own doc comment for why. */
+type ContractPropsOf<C extends FactoryOptions> = ContractModelOf<C>['props'];
+/** See this file's own doc comment. */
+type ContractVariantsOf<C extends FactoryOptions> = ContractModelOf<C>['variants'];
+/** See this file's own doc comment. */
+type ContractPresetOf<C extends FactoryOptions> = ContractModelOf<C>['preset'];
+/** See this file's own doc comment. */
+type ContractPluginOf<C extends FactoryOptions> = ContractModelOf<C>['plugin'];
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-generics.d.ts
+/**
+ * The canonical projection from a defined contract `C` to the `PolymorphicGenerics` shape every
+ * adapter's prop types are built from — the one place "G" gets computed, so it can no longer
+ * silently drift per adapter the way today's hand-assembled `PolymorphicGenerics<...>` instantiation
+ * at each `createContractComponent` call site can (see `ContractGenericsWithAllowedOf` below for
+ * the one confirmed instance of that drift).
+ *
+ * Folds the class-resolution plugin's own contributed props (`ExtractPluginProps<TPlugin>`) into
+ * `props` here, once, rather than leaving each adapter's `ContractProps` to re-derive that merge
+ * via its own distributive conditional type on every read — the root cause of the ~22-member
+ * layout-union bug PR #95 patched per-adapter (see `DECISIONS.md`'s `defineContract` entry).
+ */
+type ContractGenericsOf<C extends FactoryOptions> = PolymorphicGenerics<ContractTagOf<C>, MergeRecords<ContractPropsOf<C>, ExtractPluginProps<ContractPluginOf<C>>>, ContractVariantsOf<C>, ContractPresetOf<C>>;
+//#endregion
 //#region ../../lib/primitive/src/types/polymorphic-runtime/resolve-aria-fn.d.ts
 type ResolveAriaFn = <P extends IntrinsicProps>(tag: ElementType, props: P, extraProps?: IntrinsicProps) => {
   props: P;
@@ -829,15 +984,21 @@ declare class SlotValidator extends InvariantBase {
   assertSingleChild(count: number): void;
 }
 //#endregion
-//#region ../../lib/adapter-utils/src/runtime/define-component.d.ts
-export declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
-//#endregion
 //#region ../../adapters/svelte/src/types/primitives.d.ts
 type UnknownProps = AnyRecord;
 type ResolvedProps = Readonly<UnknownProps>;
 //#endregion
 //#region ../../adapters/svelte/src/svelte-options.d.ts
-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> & {
+/**
+ * Every generic parameter has a default (widened to that parameter's own *bound*, matching
+ * a wide-bound, type-erased philosophy, not `FactoryOptions`'s own narrower `EmptyRecord`-style
+ * defaults) so `SvelteFactoryOptions` can be used bare, as `createContractComponent`'s single
+ * `C extends SvelteFactoryOptions` constraint — see `ReactFactoryOptions`'s identical fix for the
+ * same reason. Unlike every other adapter's `*FactoryOptions`, none of these five had a default at
+ * all before this — `createContractComponent`'s old 7-generic signature always supplied them
+ * itself, so nothing here needed to compile bare until Phase 2 of the `defineContract` refactor.
+ */
+type SvelteFactoryOptions<TDefault extends ElementType = ElementType, Props extends UnknownProps = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = RecipeMap<Variants>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
   /**
    * 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.
@@ -986,9 +1147,18 @@ type ResolvedSlotProps<G extends PolymorphicGenerics> = Partial<OmitIndexSignatu
  * the same way on a plain bundle as on a component function/class, so `Card.Header` is itself
  * just another bundle, passed to its own `<Polymorphic bundle={Card.Header}>`. Pass `onElement`
  * to run setup once the real DOM element exists.
+ *
+ * `TDefault`/`Props`/`Variants`/`TPreset` are each `ContractXOf<C>`-derived *defaults* on this
+ * function's own type parameter list, mirroring every other adapter's identical fix — see
+ * `@praxis-kit/react`'s own doc comment for why. The biggest reduction of any adapter (7 generics
+ * down to `C` + `TSubComponents`): the old `TOptions extends WithChildRules` parameter — needed by
+ * `BuiltRuntime<G, TOptions>` to conditionally include `childrenEvaluator` based on the *literal*
+ * `enforcement.children`/`exclusiveChildren`/`allowText` shape — was never anything but a
+ * self-referential reconstruction of the same options type `C` now *is* directly, so it's simply
+ * `C` itself below, not a separate parameter.
  */
-export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord, TOptions extends WithChildRules = SvelteFactoryOptions<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>(options: SvelteFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & TOptions & {
+export declare function createContractComponent<C extends SvelteFactoryOptions, TDefault extends ElementType = ContractTagOf<C>, Props extends UnknownProps = ContractPropsOf<C>, Variants extends Readonly<VariantMap> = ContractVariantsOf<C>, TPreset extends RecipeMap<VariantMap> = ContractPresetOf<C>, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: C & {
   readonly subComponents?: TSubComponents;
-}): MergeRecords<BuiltRuntime<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>, TOptions>, TSubComponents>;
+}): MergeRecords<BuiltRuntime<ContractGenericsOf<C>, C>, TSubComponents>;
 //#endregion
-export type { AnyBuiltRuntime, AnyFactoryOptions, BuiltRuntime, ElementType, EmptyRecord, FactoryOptions, GenericsOf, PolymorphicComponentProps, PolymorphicGenerics, ResolvedSlotProps, SvelteFactoryOptions };
+export type { AnyBuiltRuntime, BuiltRuntime, ElementType, EmptyRecord, FactoryOptions, GenericsOf, PolymorphicComponentProps, PolymorphicGenerics, ResolvedSlotProps, SvelteFactoryOptions };