praxis-kit 7.4.0 → 7.8.0

package/dist/tailwind/index.d.ts

@@ -99,7 +99,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 {

package/dist/vite-plugin/index.d.ts

@@ -75,10 +75,13 @@ declare enum DiagnosticCode {
     HtmlInputAltIgnoredForType = "HTML3113",
     HtmlInputHeightIgnoredForType = "HTML3114",
     HtmlInputWidthIgnoredForType = "HTML3115",
+    HtmlAnchorDangerousHref = "HTML3201",
     A11yInputMissingAccessibleName = "A11Y8100",
     A11yInputPlaceholderNotLabel = "A11Y8101",
     A11yInputPasswordAutocomplete = "A11Y8102",
     A11yInputRequiredReadOnlyConflict = "A11Y8103",
+    A11yAnchorRoleButtonWithHref = "A11Y8200",
+    A11yAnchorAriaDisabledInert = "A11Y8201",
     InvalidRenderingTarget = "RENDER4001",
     LintDeadCompoundKey = "LINT5001",
     LintDeadCompoundValue = "LINT5002",
@@ -294,7 +297,7 @@ declare function analyze(code: string, filename: string, options?: PluginOptions
  * Returns null when static extraction is not possible (non-literal values,
  * no variants, or combination count exceeds MAX_COMBINATIONS).
  */
-declare function buildPrecomputedClasses(stylingObj: ts.ObjectLiteralExpression): Record<string, string> | null;
+declare function buildPrecomputedClasses(stylingObj: ts.ObjectLiteralExpression): StringMap<string> | null;
 /**
  * Injects precomputed variant class maps into all factory calls in the given
  * source file that have fully-static `styling.variants` configurations.
@@ -334,7 +337,7 @@ type ComponentTokens = {
     tagClasses: string[];
 };
 type DesignTokenManifest = {
-    components: Record<string, ComponentTokens>;
+    components: StringMap<ComponentTokens>;
     allClasses: string[];
 };
 /**
@@ -440,7 +443,7 @@ declare function transformAsChild(source: ts.SourceFile): string | null;
 type StaticComponent = {
     readonly defaultTag: string;
     readonly variantKeys: ReadonlySet<string>;
-    readonly precomputedClasses: Readonly<Record<string, string>>;
+    readonly precomputedClasses: Readonly<StringMap<string>>;
 };
 /**
  * Walks the source file and extracts metadata for each same-file factory call

package/dist/vue/index.d.ts

@@ -73,6 +73,19 @@ type MergeRecords<A extends object, B extends object> = IsEmptyRecord<A> extends
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
 type ElementType = IntrinsicTag | (string & {});
+/**
+ * Resolves a component's default tag to its real DOM interface — `HTMLDialogElement` for
+ * `'dialog'`, `HTMLDetailsElement` for `'details'`, and so on — falling back to `HTMLElement`
+ * for custom-element tags or anything not in `HTMLElementTagNameMap`. Used to type
+ * `FactoryOptions.onElement`'s `element` param so component authors get direct, correctly-typed
+ * access to tag-specific native members (`dialogEl.showModal()`) without an unsafe cast.
+ *
+ * The fallback is `HTMLElement`, not the more generic `Element` — every tag reachable through
+ * `IntrinsicTag` extends it, and so does every custom element per spec, so members `HTMLElement`
+ * itself declares (`showPopover()`/`hidePopover()`/`togglePopover()`, the `popover` attribute)
+ * stay directly accessible even for tags with no dedicated entry in `HTMLElementTagNameMap`.
+ */
+type ElementForTag<TDefault extends ElementType> = TDefault extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TDefault] : HTMLElement;
 
 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];
@@ -177,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>;
@@ -223,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 {
@@ -392,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> = {
@@ -438,13 +506,23 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
      * no prop-based equivalent), not for anything expressible as a plain
      * prop.
      *
+     * `element` is typed to the real DOM interface of every tag the rendered
+     * element could actually be — `TDefault` plus whatever `enforcement.allowed`
+     * permits via `as` (`HTMLDialogElement` for `tag: 'dialog'`,
+     * `HTMLDetailsElement` for `tag: 'details'`, and so on) — no cast needed to
+     * reach tag-specific members. A component that leaves `allowed`
+     * unconstrained (any tag reachable via `as`) falls back to `HTMLElement`,
+     * which still covers members every element shares (`showPopover()` and
+     * friends); restrict `enforcement.allowed` to the tags `onElement`
+     * actually knows how to handle to get real narrowing.
+     *
      * `getProps` returns the instance's *current* resolved props at call
      * time — read it from inside a listener registered once at mount, rather
      * than re-subscribing on every prop change.
      *
      * Return a cleanup function to run when the instance unmounts.
      */
-    readonly onElement?: (element: Element, getProps: () => Readonly<Props>) => void | (() => void);
+    readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
 };
 
 declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
@@ -507,6 +585,16 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
     };
     displayName?: string;
 };
+/**
+ * A component's full prop contract, both render modes at once — naming symmetry with React's/
+ * Preact's `ContractProps<T, Mode>` (`@praxis-kit/contract-props`), not a fix for a gap: Vue has
+ * no version of the overload-resolution ceiling those two adapters need a marker to work around.
+ * `PolymorphicComponent<G>`'s single `new()` construct signature already exposes both modes
+ * unioned together (`$props: PolymorphicProps<G> | PolymorphicWithAsChild<G>`), so this alias is
+ * just that same union under a familiar name — no phantom marker involved, `G` is already an
+ * ordinary, ambient type parameter.
+ */
+type ContractProps<G extends PolymorphicGenerics> = PolymorphicProps<G> | PolymorphicWithAsChild<G>;
 
 /**
  * Creates a polymorphic Vue component with praxis-kit contracts applied.
@@ -535,4 +623,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 ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, Slottable, type SlottableProps, type VueFactoryOptions, createContractComponent, defineContractComponent };
+export { type AnyFactoryOptions, type ContractProps, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, Slottable, type SlottableProps, type VueFactoryOptions, createContractComponent, defineContractComponent };