@skdx/react 0.26.0 → 0.28.0

package/dist/form/types.d.cts

@@ -1,6 +1,7 @@
 import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { SlotProps } from '../utils/slot.cjs';
+import type { FormErrors } from './serverErrors.cjs';
 /**
  * A plain-object mirror of the native `ValidityState` for one field, as
  * captured by {@link Form} after a `checkValidity()`/`invalid`/`blur`/`change`
@@ -20,17 +21,131 @@ export interface ValiditySnapshot {
     valueMissing: boolean;
     valid: boolean;
 }
-/** @internal Per-field validity snapshots distributed from {@link Form} to its descendants via context. Not part of the public API. */
+/** @internal Validity state distributed from Form to field descendants. */
 export interface FormContextValue {
     validities: Record<string, ValiditySnapshot | undefined>;
+    /** One field's server errors, already normalised and already cleared if the user has edited it since. */
+    serverErrors: (name: string) => string[];
 }
-/** Props for the {@link Form} root. */
-export interface FormProps extends Omit<PrimitivePropsWithRef<'form'>, 'onSubmit'> {
+/** When a {@link Form} refreshes a control's validity outside the submit pass. */
+export type FormValidationMode = 'submit' | 'blur' | 'change';
+/** Whether a {@link Form} refuses an invalid submit or only annotates it. */
+export type FormValidationBehavior = 'native' | 'aria';
+/** What one failing field reports through {@link FormProps.onFieldInvalid}. */
+export interface FormFieldInvalidDetail {
+    /** The `name` the failing control submits under — the key its snapshot is stored against. */
+    name: string;
+    /** The control's live `ValidityState`, so the consumer can log or branch on the reason. */
+    validity: ValidityState;
+}
+/**
+ * The imperative half of the Form contract, assigned onto the `<form>` node the
+ * forwarded ref already carries.
+ */
+export interface FormHandle {
+    /**
+     * Runs every control's native `checkValidity()` and every descendant
+     * `FormFieldRoot`'s own validation model, without short-circuiting, and resolves to
+     * whether the whole form passed. Populates the validity snapshots the
+     * messages render from, and deliberately moves no focus — a consumer may call
+     * it on every keystroke.
+     */
+    validate(): Promise<boolean>;
+}
+/** What {@link Form}'s forwarded ref carries: the `<form>` plus `validate()`. */
+export type FormElementHandle = HTMLFormElement & FormHandle;
+/** Props for {@link FormRoot}: {@link FormProps} minus the derived-anatomy-only props. */
+export type FormRootProps = Omit<FormProps, 'errorSummary' | 'submitLabel'> & Pick<PrimitivePropsWithRef<'form'>, 'asChild'>;
+/**
+ * Props for the {@link Form} recipe. No `asChild`: the recipe always wraps its
+ * children in the derived anatomy, so `Slot` would never receive the single
+ * element it needs. Reach for `primitives/form`'s headless `FormRoot` for that.
+ */
+export interface FormProps extends Omit<PrimitivePropsWithRef<'form'>, 'onSubmit' | 'onInvalid' | 'onReset' | 'asChild'> {
+    /**
+     * Heading for a derived `FormErrorSummary` ahead of the fields — the GOV.UK
+     * "There is a problem" pattern, a `role="alert"` list of one link per failing
+     * field, focused the first time it appears. The prop carries the copy rather
+     * than a flag, because that heading is the consumer's wording in the
+     * consumer's language and nothing in this library can invent it.
+     * @default undefined — no summary is derived, and nothing takes focus.
+     */
+    errorSummary?: string;
+    /**
+     * Label for a derived `FormSubmit` button, rendered after the fields. Same
+     * reasoning as `errorSummary`: the copy is the prop.
+     * @default undefined — no submit button is derived.
+     */
+    submitLabel?: string;
+    /**
+     * Errors the browser cannot derive, keyed by the `name` a {@link FormField}
+     * already carries: a server response, a cross-field rule, an async
+     * uniqueness check. Each entry is shown by that field's catch-all
+     * `FormMessage` (the one with no `match`) ahead of any native message, and
+     * marks its control `aria-invalid` so a `FormErrorSummary` lists it.
+     *
+     * Cleared per field on that field's next `change`, so an error the user has
+     * already acted on stops being announced without the consumer having to
+     * clear it themselves. Re-supply the prop to raise it again.
+     *
+     * The alternative was `FormMessage`'s `forceMatch` — a boolean threaded by
+     * hand into each individual message, with nothing tying it to the field's
+     * `name`.
+     * @default undefined — no server errors.
+     */
+    errors?: FormErrors;
     /**
-     * Fires on submit only once every field passes native constraint validation.
+     * Fires on submit only once every field passes native constraint validation
+     * — or, under `validationBehavior="aria"`, whether or not it does.
      * @default undefined — no-op if omitted.
      */
     onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    /**
+     * Fires when the native `<form>` is reset — a `<button type="reset">`, or
+     * `form.reset()`. The Form clears its per-field validity snapshots, its
+     * dismissed-server-error set, and every descendant `FormFieldRoot`'s touched/dirty
+     * and error state before calling this, because a native reset restores each
+     * control's *value* and nothing else: without it a reset form still shows
+     * what was wrong with values that no longer exist.
+     * @default undefined — no-op if omitted.
+     */
+    onReset?: (event: Event) => void;
+    /**
+     * Fires once per failing field during the submit pass, so a consumer can stop
+     * a spinner, log the failure, or scroll the page — a blocked submit
+     * otherwise returns without notifying anyone.
+     *
+     * Named `onFieldInvalid` rather than `onInvalid`: `invalid` is a native event
+     * with different semantics (it fires at the control, does not bubble, and
+     * this Form already listens for the real one capture-phase), and `onInvalid`
+     * on a `<form>` reaches nothing today, so overriding the native prop with a
+     * different payload would be the more confusing of the two.
+     * @default undefined — no-op if omitted.
+     */
+    onFieldInvalid?: (detail: FormFieldInvalidDetail) => void;
+    /**
+     * When a control's validity snapshot is refreshed, and therefore when its
+     * `FormMessage`s may start showing. `change` refreshes on both `change` and
+     * `blur`; `blur` on blur only; `submit` on nothing but the submit pass, which
+     * is what a form that must stay quiet until the user has finished wants.
+     *
+     * The submit-time pass is always captured whatever the mode — it is what
+     * snapshots the failure the submit was blocked on. A `FormFieldRoot` inside this Form
+     * is unaffected: it owns its own engine and its own `mode`.
+     * @default 'change'
+     */
+    validationMode?: FormValidationMode;
+    /**
+     * Whether a failed validation refuses the submit or only annotates it.
+     * `native` is the platform's behaviour. `aria` sets `noValidate` on the
+     * `<form>` and skips the gate, so the submit goes through with every failing
+     * control already marked `aria-invalid` and described by its message — what a
+     * client-routed or server-action form needs, where the server is the
+     * authority and the client's job is to annotate. The snapshots are still
+     * taken first, so the messages are on screen when `onSubmit` runs.
+     * @default 'native'
+     */
+    validationBehavior?: FormValidationBehavior;
 }
 /** @internal Field identity distributed from {@link FormField} to its descendants via context. Not part of the public API. */
 export interface FormFieldContextValue {
@@ -38,10 +153,32 @@ export interface FormFieldContextValue {
     id: string;
     messageId: string;
 }
-/** Props for {@link FormField}, a per-field grouping of label, control, and message. */
-export interface FormFieldProps extends PrimitivePropsWithRef<'div'> {
+/** Props for {@link FormFieldRoot}: {@link FormFieldProps} minus the derived-anatomy-only props. */
+export type FormFieldRootProps = Omit<FormFieldProps, 'label' | 'message'> & Pick<PrimitivePropsWithRef<'div'>, 'asChild'>;
+/**
+ * Props for {@link FormField}, a per-field grouping of label, control, and
+ * message. No `asChild`: the recipe always wraps its children in the derived
+ * anatomy, so `Slot` would never receive the single element it needs. Reach
+ * for `primitives/form`'s headless `FormFieldRoot` for that.
+ */
+export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /** Field name, matched against the `name` attribute of the native input rendered inside `FormControl`. */
     name: string;
+    /**
+     * The control's label, rendered into a derived `FormLabel` whose `htmlFor`
+     * points at the id this field injects onto the control.
+     * @default undefined — no label is rendered, and the control is unnamed.
+     */
+    label?: React.ReactNode;
+    /**
+     * The catch-all validation message, rendered into a derived `FormMessage` shown
+     * whenever the field is invalid at all. A server error keyed to this
+     * field's `name` in the `Form`'s `errors` replaces the text. For a message
+     * targeting one `ValidityState` reason, compose `FormMessage`s yourself from
+     * `@skdx/react/primitives/form`.
+     * @default undefined — the message element renders with no text of its own.
+     */
+    message?: React.ReactNode;
 }
 /** Props for {@link FormLabel}, a label wired to its `FormField`'s control. */
 export interface FormLabelProps extends PrimitivePropsWithRef<'label'> {
@@ -57,7 +194,9 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
      */
     match?: keyof ValiditySnapshot;
     /**
-     * Always render regardless of native validity — for async/server errors.
+     * Always render regardless of native validity — the per-message escape
+     * hatch. `Form`'s `errors` is the keyed version of the same idea and needs
+     * no per-message wiring.
      * @default false
      */
     forceMatch?: boolean;
@@ -65,7 +204,7 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
 /** Props for {@link FormSubmit}, a `type="submit"` button. */
 export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link FormErrorSummary}, the GOV.UK error summary for a form's `Field`s. */
+/** Props for {@link FormErrorSummary}, the GOV.UK error summary for a form's `FormFieldRoot`s. */
 export interface FormErrorSummaryProps extends Omit<PrimitivePropsWithRef<'div'>, 'autoFocus'> {
     /**
      * Focus the summary the first time it appears. Turn it off when your own

package/dist/form/types.d.ts

@@ -1,6 +1,7 @@
 import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { SlotProps } from '../utils/slot.js';
+import type { FormErrors } from './serverErrors.js';
 /**
  * A plain-object mirror of the native `ValidityState` for one field, as
  * captured by {@link Form} after a `checkValidity()`/`invalid`/`blur`/`change`
@@ -20,17 +21,131 @@ export interface ValiditySnapshot {
     valueMissing: boolean;
     valid: boolean;
 }
-/** @internal Per-field validity snapshots distributed from {@link Form} to its descendants via context. Not part of the public API. */
+/** @internal Validity state distributed from Form to field descendants. */
 export interface FormContextValue {
     validities: Record<string, ValiditySnapshot | undefined>;
+    /** One field's server errors, already normalised and already cleared if the user has edited it since. */
+    serverErrors: (name: string) => string[];
 }
-/** Props for the {@link Form} root. */
-export interface FormProps extends Omit<PrimitivePropsWithRef<'form'>, 'onSubmit'> {
+/** When a {@link Form} refreshes a control's validity outside the submit pass. */
+export type FormValidationMode = 'submit' | 'blur' | 'change';
+/** Whether a {@link Form} refuses an invalid submit or only annotates it. */
+export type FormValidationBehavior = 'native' | 'aria';
+/** What one failing field reports through {@link FormProps.onFieldInvalid}. */
+export interface FormFieldInvalidDetail {
+    /** The `name` the failing control submits under — the key its snapshot is stored against. */
+    name: string;
+    /** The control's live `ValidityState`, so the consumer can log or branch on the reason. */
+    validity: ValidityState;
+}
+/**
+ * The imperative half of the Form contract, assigned onto the `<form>` node the
+ * forwarded ref already carries.
+ */
+export interface FormHandle {
+    /**
+     * Runs every control's native `checkValidity()` and every descendant
+     * `FormFieldRoot`'s own validation model, without short-circuiting, and resolves to
+     * whether the whole form passed. Populates the validity snapshots the
+     * messages render from, and deliberately moves no focus — a consumer may call
+     * it on every keystroke.
+     */
+    validate(): Promise<boolean>;
+}
+/** What {@link Form}'s forwarded ref carries: the `<form>` plus `validate()`. */
+export type FormElementHandle = HTMLFormElement & FormHandle;
+/** Props for {@link FormRoot}: {@link FormProps} minus the derived-anatomy-only props. */
+export type FormRootProps = Omit<FormProps, 'errorSummary' | 'submitLabel'> & Pick<PrimitivePropsWithRef<'form'>, 'asChild'>;
+/**
+ * Props for the {@link Form} recipe. No `asChild`: the recipe always wraps its
+ * children in the derived anatomy, so `Slot` would never receive the single
+ * element it needs. Reach for `primitives/form`'s headless `FormRoot` for that.
+ */
+export interface FormProps extends Omit<PrimitivePropsWithRef<'form'>, 'onSubmit' | 'onInvalid' | 'onReset' | 'asChild'> {
+    /**
+     * Heading for a derived `FormErrorSummary` ahead of the fields — the GOV.UK
+     * "There is a problem" pattern, a `role="alert"` list of one link per failing
+     * field, focused the first time it appears. The prop carries the copy rather
+     * than a flag, because that heading is the consumer's wording in the
+     * consumer's language and nothing in this library can invent it.
+     * @default undefined — no summary is derived, and nothing takes focus.
+     */
+    errorSummary?: string;
+    /**
+     * Label for a derived `FormSubmit` button, rendered after the fields. Same
+     * reasoning as `errorSummary`: the copy is the prop.
+     * @default undefined — no submit button is derived.
+     */
+    submitLabel?: string;
+    /**
+     * Errors the browser cannot derive, keyed by the `name` a {@link FormField}
+     * already carries: a server response, a cross-field rule, an async
+     * uniqueness check. Each entry is shown by that field's catch-all
+     * `FormMessage` (the one with no `match`) ahead of any native message, and
+     * marks its control `aria-invalid` so a `FormErrorSummary` lists it.
+     *
+     * Cleared per field on that field's next `change`, so an error the user has
+     * already acted on stops being announced without the consumer having to
+     * clear it themselves. Re-supply the prop to raise it again.
+     *
+     * The alternative was `FormMessage`'s `forceMatch` — a boolean threaded by
+     * hand into each individual message, with nothing tying it to the field's
+     * `name`.
+     * @default undefined — no server errors.
+     */
+    errors?: FormErrors;
     /**
-     * Fires on submit only once every field passes native constraint validation.
+     * Fires on submit only once every field passes native constraint validation
+     * — or, under `validationBehavior="aria"`, whether or not it does.
      * @default undefined — no-op if omitted.
      */
     onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    /**
+     * Fires when the native `<form>` is reset — a `<button type="reset">`, or
+     * `form.reset()`. The Form clears its per-field validity snapshots, its
+     * dismissed-server-error set, and every descendant `FormFieldRoot`'s touched/dirty
+     * and error state before calling this, because a native reset restores each
+     * control's *value* and nothing else: without it a reset form still shows
+     * what was wrong with values that no longer exist.
+     * @default undefined — no-op if omitted.
+     */
+    onReset?: (event: Event) => void;
+    /**
+     * Fires once per failing field during the submit pass, so a consumer can stop
+     * a spinner, log the failure, or scroll the page — a blocked submit
+     * otherwise returns without notifying anyone.
+     *
+     * Named `onFieldInvalid` rather than `onInvalid`: `invalid` is a native event
+     * with different semantics (it fires at the control, does not bubble, and
+     * this Form already listens for the real one capture-phase), and `onInvalid`
+     * on a `<form>` reaches nothing today, so overriding the native prop with a
+     * different payload would be the more confusing of the two.
+     * @default undefined — no-op if omitted.
+     */
+    onFieldInvalid?: (detail: FormFieldInvalidDetail) => void;
+    /**
+     * When a control's validity snapshot is refreshed, and therefore when its
+     * `FormMessage`s may start showing. `change` refreshes on both `change` and
+     * `blur`; `blur` on blur only; `submit` on nothing but the submit pass, which
+     * is what a form that must stay quiet until the user has finished wants.
+     *
+     * The submit-time pass is always captured whatever the mode — it is what
+     * snapshots the failure the submit was blocked on. A `FormFieldRoot` inside this Form
+     * is unaffected: it owns its own engine and its own `mode`.
+     * @default 'change'
+     */
+    validationMode?: FormValidationMode;
+    /**
+     * Whether a failed validation refuses the submit or only annotates it.
+     * `native` is the platform's behaviour. `aria` sets `noValidate` on the
+     * `<form>` and skips the gate, so the submit goes through with every failing
+     * control already marked `aria-invalid` and described by its message — what a
+     * client-routed or server-action form needs, where the server is the
+     * authority and the client's job is to annotate. The snapshots are still
+     * taken first, so the messages are on screen when `onSubmit` runs.
+     * @default 'native'
+     */
+    validationBehavior?: FormValidationBehavior;
 }
 /** @internal Field identity distributed from {@link FormField} to its descendants via context. Not part of the public API. */
 export interface FormFieldContextValue {
@@ -38,10 +153,32 @@ export interface FormFieldContextValue {
     id: string;
     messageId: string;
 }
-/** Props for {@link FormField}, a per-field grouping of label, control, and message. */
-export interface FormFieldProps extends PrimitivePropsWithRef<'div'> {
+/** Props for {@link FormFieldRoot}: {@link FormFieldProps} minus the derived-anatomy-only props. */
+export type FormFieldRootProps = Omit<FormFieldProps, 'label' | 'message'> & Pick<PrimitivePropsWithRef<'div'>, 'asChild'>;
+/**
+ * Props for {@link FormField}, a per-field grouping of label, control, and
+ * message. No `asChild`: the recipe always wraps its children in the derived
+ * anatomy, so `Slot` would never receive the single element it needs. Reach
+ * for `primitives/form`'s headless `FormFieldRoot` for that.
+ */
+export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /** Field name, matched against the `name` attribute of the native input rendered inside `FormControl`. */
     name: string;
+    /**
+     * The control's label, rendered into a derived `FormLabel` whose `htmlFor`
+     * points at the id this field injects onto the control.
+     * @default undefined — no label is rendered, and the control is unnamed.
+     */
+    label?: React.ReactNode;
+    /**
+     * The catch-all validation message, rendered into a derived `FormMessage` shown
+     * whenever the field is invalid at all. A server error keyed to this
+     * field's `name` in the `Form`'s `errors` replaces the text. For a message
+     * targeting one `ValidityState` reason, compose `FormMessage`s yourself from
+     * `@skdx/react/primitives/form`.
+     * @default undefined — the message element renders with no text of its own.
+     */
+    message?: React.ReactNode;
 }
 /** Props for {@link FormLabel}, a label wired to its `FormField`'s control. */
 export interface FormLabelProps extends PrimitivePropsWithRef<'label'> {
@@ -57,7 +194,9 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
      */
     match?: keyof ValiditySnapshot;
     /**
-     * Always render regardless of native validity — for async/server errors.
+     * Always render regardless of native validity — the per-message escape
+     * hatch. `Form`'s `errors` is the keyed version of the same idea and needs
+     * no per-message wiring.
      * @default false
      */
     forceMatch?: boolean;
@@ -65,7 +204,7 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
 /** Props for {@link FormSubmit}, a `type="submit"` button. */
 export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link FormErrorSummary}, the GOV.UK error summary for a form's `Field`s. */
+/** Props for {@link FormErrorSummary}, the GOV.UK error summary for a form's `FormFieldRoot`s. */
 export interface FormErrorSummaryProps extends Omit<PrimitivePropsWithRef<'div'>, 'autoFocus'> {
     /**
      * Focus the summary the first time it appears. Turn it off when your own

package/dist/heading/Heading.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.create;var n=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var P=Object.getPrototypeOf,x=Object.prototype.hasOwnProperty;var L=(e,o)=>{for(var i in o)n(e,i,{get:o[i],enumerable:!0})},a=(e,o,i,t)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of c(o))!x.call(e,r)&&r!==i&&n(e,r,{get:()=>o[r],enumerable:!(t=y(o,r))||t.enumerable});return e};var h=(e,o,i)=>(i=e!=null?l(P(e)):{},a(o||!e||!e.__esModule?n(i,"default",{value:e,enumerable:!0}):i,e)),u=e=>a(n({},"__esModule",{value:!0}),e);var E={};L(E,{Heading:()=>d});module.exports=u(E);var p=h(require("react"),1),s=require("../utils/part.cjs"),m=require("../utils/primitive.cjs"),f=require("react/jsx-runtime"),v="skdx-visually-hidden",d=p.forwardRef(({as:e,visuallyHidden:o=!1,className:i,...t},r)=>{let H=m.Primitive[e],g=[i,o?v:void 0].filter(Boolean).join(" ");return(0,f.jsx)(H,{...t,...(0,s.skdxPart)("heading","root",g||void 0),ref:r})});d.displayName="Heading";0&&(module.exports={Heading});

package/dist/heading/Heading.d.cts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { HeadingProps } from './types.cjs';
+/**
+ * A section heading: `<h1>`–`<h6>` as `as` names. Outline level (`as`) and
+ * visual size (`data-size`) are separate. `as` has no default to prevent
+ * outline skips.
+ *
+ * @example
+ * ```tsx
+ * <Heading as="h2" data-size="lg">Revenue</Heading>
+ * <Heading as="h2" visuallyHidden>Filters</Heading>
+ * ```
+ */
+export declare const Heading: React.ForwardRefExoticComponent<Omit<HeadingProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/heading/Heading.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { HeadingProps } from './types.js';
+/**
+ * A section heading: `<h1>`–`<h6>` as `as` names. Outline level (`as`) and
+ * visual size (`data-size`) are separate. `as` has no default to prevent
+ * outline skips.
+ *
+ * @example
+ * ```tsx
+ * <Heading as="h2" data-size="lg">Revenue</Heading>
+ * <Heading as="h2" visuallyHidden>Filters</Heading>
+ * ```
+ */
+export declare const Heading: React.ForwardRefExoticComponent<Omit<HeadingProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/heading/Heading.js

@@ -0,0 +1 @@
+import*as e from"react";import{skdxPart as s}from"../utils/part.js";import{Primitive as m}from"../utils/primitive.js";import{jsx as H}from"react/jsx-runtime";var f="skdx-visually-hidden",o=e.forwardRef(({as:i,visuallyHidden:r=!1,className:t,...n},d)=>{let a=m[i],p=[t,r?f:void 0].filter(Boolean).join(" ");return H(a,{...n,...s("heading","root",p||void 0),ref:d})});o.displayName="Heading";export{o as Heading};

package/dist/heading/index.d.cts

@@ -0,0 +1,2 @@
+export { Heading } from './Heading.cjs';
+export type { HeadingProps } from './types.cjs';

package/dist/heading/index.d.ts

@@ -0,0 +1,2 @@
+export { Heading } from './Heading.js';
+export type { HeadingProps } from './types.js';

package/dist/heading/types.d.cts

@@ -0,0 +1,15 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** Props for {@link Heading}, a section heading whose level and visual size are separate. */
+export interface HeadingProps extends PrimitivePropsWithRef<'h2'> {
+    /**
+     * Which heading element to render. Required — the level belongs to your
+     * document outline, which this library does not place.
+     */
+    as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+    /**
+     * Remove the heading from view while leaving it in the accessibility tree,
+     * by composing the `.skdx-visually-hidden` utility.
+     * @default false
+     */
+    visuallyHidden?: boolean;
+}

package/dist/heading/types.d.ts

@@ -0,0 +1,15 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** Props for {@link Heading}, a section heading whose level and visual size are separate. */
+export interface HeadingProps extends PrimitivePropsWithRef<'h2'> {
+    /**
+     * Which heading element to render. Required — the level belongs to your
+     * document outline, which this library does not place.
+     */
+    as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+    /**
+     * Remove the heading from view while leaving it in the accessibility tree,
+     * by composing the `.skdx-visually-hidden` utility.
+     * @default false
+     */
+    visuallyHidden?: boolean;
+}

package/dist/hover-card/HoverCard.cjs

@@ -1 +1 @@
-"use strict";var _=Object.create;var R=Object.defineProperty;var $=Object.getOwnPropertyDescriptor;var j=Object.getOwnPropertyNames;var ee=Object.getPrototypeOf,oe=Object.prototype.hasOwnProperty;var re=(e,r)=>{for(var o in r)R(e,o,{get:r[o],enumerable:!0})},N=(e,r,o,p)=>{if(r&&typeof r=="object"||typeof r=="function")for(let s of j(r))!oe.call(e,s)&&s!==o&&R(e,s,{get:()=>r[s],enumerable:!(p=$(r,s))||p.enumerable});return e};var g=(e,r,o)=>(o=e!=null?_(ee(e)):{},N(r||!e||!e.__esModule?R(o,"default",{value:e,enumerable:!0}):o,e)),te=e=>N(R({},"__esModule",{value:!0}),e);var ne={};re(ne,{HoverCard:()=>M,HoverCardArrow:()=>I,HoverCardContent:()=>E,HoverCardPortal:()=>y,HoverCardRootProvider:()=>A,HoverCardTrigger:()=>x,useHoverCardContext:()=>f});module.exports=te(ne);var t=g(require("react"),1),b=require("../utils/createContext.cjs"),k=require("../utils/part.cjs"),H=require("../utils/popper.cjs"),F=require("../utils/useControllableState.cjs"),O=require("../utils/useOpenChangeComplete.cjs"),P=require("react/jsx-runtime"),[A,f]=(0,b.createSafeContext)("HoverCard");function M({children:e,open:r,defaultOpen:o=!1,onOpenChange:p,onOpenChangeComplete:s,openDelay:l=700,closeDelay:C=300}){let m=t.useRef(null),u=t.useRef(null),n=t.useRef(!1),v=t.useRef(0),a=t.useRef(0),[w=!1,c]=(0,F.useControllableState)({prop:r,defaultProp:o,onChange:p});(0,O.useOpenChangeComplete)(w,u,s);let i=t.useCallback(()=>{window.clearTimeout(v.current),window.clearTimeout(a.current)},[]);t.useEffect(()=>i,[i]);let X=t.useCallback(()=>{i(),c(!0)},[i,c]),Y=t.useCallback(()=>{i(),c(!1)},[i,c]),Z=t.useCallback(()=>{i(),v.current=window.setTimeout(()=>c(!0),l)},[i,c,l]),L=t.useCallback(()=>{i(),a.current=window.setTimeout(()=>c(!1),C)},[i,c,C]);return(0,P.jsx)(H.PopperRoot,{children:(0,P.jsx)(A,{contentId:t.useId(),open:w,triggerRef:m,contentRef:u,ignoreNextFocusRef:n,onOpen:X,onClose:Y,onTriggerEnter:Z,onTriggerLeave:L,onContentEnter:i,onContentLeave:L,children:e})})}M.displayName="HoverCard";var I=t.forwardRef((e,r)=>(0,P.jsx)(H.PopperArrow,{...e,...(0,k.skdxPart)("hover-card","arrow",e.className),ref:r}));I.displayName="HoverCardArrow";var D=g(require("react"),1),S=require("../utils/composeRefs.cjs"),B=require("../utils/part.cjs"),V=require("../utils/popper.cjs"),d=require("../utils/primitive.cjs");var T=require("react/jsx-runtime"),x=D.forwardRef((e,r)=>{let o=f("HoverCardTrigger"),p=(0,S.useComposedRefs)(r,o.triggerRef);return(0,T.jsx)(V.PopperAnchor,{asChild:!0,children:(0,T.jsx)(d.Primitive.a,{"aria-describedby":o.open?o.contentId:void 0,"data-state":o.open?"open":"closed",...e,...(0,B.skdxPart)("hover-card","trigger",e.className),ref:p,onPointerEnter:(0,d.composeEventHandlers)(e.onPointerEnter,s=>{s.pointerType!=="touch"&&o.onTriggerEnter()}),onPointerLeave:(0,d.composeEventHandlers)(e.onPointerLeave,s=>{s.pointerType!=="touch"&&o.onTriggerLeave()}),onFocus:(0,d.composeEventHandlers)(e.onFocus,()=>{if(o.ignoreNextFocusRef.current){o.ignoreNextFocusRef.current=!1;return}o.onOpen()}),onBlur:(0,d.composeEventHandlers)(e.onBlur,o.onClose)})})});x.displayName="HoverCardTrigger";var W=require("../utils/portal.cjs");var K=require("react/jsx-runtime"),y=({forceMount:e,children:r,...o})=>{let p=f("HoverCardPortal");return e||p.open?(0,K.jsx)(W.Portal,{...o,children:r}):null};y.displayName="HoverCardPortal";var q=g(require("react"),1),z=require("../utils/composeRefs.cjs"),G=require("../utils/part.cjs"),J=require("../utils/popper.cjs"),h=require("../utils/primitive.cjs"),Q=require("../utils/useDismiss.cjs");var U=require("react/jsx-runtime"),E=q.forwardRef(({forceMount:e,side:r="bottom",sideOffset:o=4,onEscapeKeyDown:p,onPointerDownOutside:s,onFocusOutside:l,onInteractOutside:C,...m},u)=>{let n=f("HoverCardContent"),v=(0,z.useComposedRefs)(u,n.contentRef);return(0,Q.useDismiss)({enabled:n.open,onEscapeKeyDown:a=>{p?.(a),a.defaultPrevented||(n.onClose(),n.ignoreNextFocusRef.current=!0,n.triggerRef.current?.focus())},onInteractOutside:C,onPointerDownOutside:a=>{s?.(a),a.defaultPrevented||n.onClose()},onFocusOutside:a=>{l?.(a),a.defaultPrevented||n.onClose()}},[n.triggerRef,n.contentRef]),e||n.open?(0,U.jsx)(J.PopperContent,{component:"hover-card",id:n.contentId,"data-state":n.open?"open":"closed",side:r,sideOffset:o,...m,...(0,G.skdxPart)("hover-card","content",m.className),ref:v,onPointerEnter:(0,h.composeEventHandlers)(m.onPointerEnter,a=>{a.pointerType!=="touch"&&n.onContentEnter()}),onPointerLeave:(0,h.composeEventHandlers)(m.onPointerLeave,a=>{a.pointerType!=="touch"&&n.onContentLeave()})}):null});E.displayName="HoverCardContent";0&&(module.exports={HoverCard,HoverCardArrow,HoverCardContent,HoverCardPortal,HoverCardRootProvider,HoverCardTrigger,useHoverCardContext});
+"use strict";var oe=Object.create;var P=Object.defineProperty;var re=Object.getOwnPropertyDescriptor;var te=Object.getOwnPropertyNames;var ne=Object.getPrototypeOf,ae=Object.prototype.hasOwnProperty;var ie=(e,o)=>{for(var r in o)P(e,r,{get:o[r],enumerable:!0})},k=(e,o,r,s)=>{if(o&&typeof o=="object"||typeof o=="function")for(let n of te(o))!ae.call(e,n)&&n!==r&&P(e,n,{get:()=>o[n],enumerable:!(s=re(o,n))||s.enumerable});return e};var E=(e,o,r)=>(r=e!=null?oe(ne(e)):{},k(o||!e||!e.__esModule?P(r,"default",{value:e,enumerable:!0}):r,e)),se=e=>k(P({},"__esModule",{value:!0}),e);var pe={};ie(pe,{HoverCard:()=>_,HoverCardArrow:()=>T,HoverCardContent:()=>g,HoverCardPortal:()=>y,HoverCardRoot:()=>b,HoverCardRootProvider:()=>Z,HoverCardTrigger:()=>h,useHoverCardContext:()=>c});module.exports=se(pe);var i=E(require("react"),1),Q=require("../utils/createContext.cjs"),U=require("../utils/part.cjs"),w=require("../utils/popper.cjs"),X=require("../utils/useControllableState.cjs"),Y=require("../utils/useOpenChangeComplete.cjs");var S=E(require("react"),1),D=require("../utils/composeRefs.cjs"),M=require("../utils/part.cjs"),I=require("../utils/popper.cjs"),A=require("../utils/primitive.cjs"),V=require("../utils/useDismiss.cjs");var W=require("react/jsx-runtime"),g=S.forwardRef(({forceMount:e,side:o="bottom",sideOffset:r=4,onEscapeKeyDown:s,onPointerDownOutside:n,onFocusOutside:m,onInteractOutside:l,...p},H)=>{let t=c("HoverCardContent"),v=(0,D.useComposedRefs)(H,t.contentRef);return(0,V.useDismiss)({enabled:t.open,onEscapeKeyDown:a=>{s?.(a),a.defaultPrevented||(t.onClose(),t.triggerRef.current?.focus())},onInteractOutside:l,onPointerDownOutside:a=>{n?.(a),a.defaultPrevented||t.onClose()},onFocusOutside:a=>{m?.(a),a.defaultPrevented||t.onClose()}},[t.triggerRef,t.contentRef]),e||t.open?(0,W.jsx)(I.PopperContent,{component:"hover-card",id:t.contentId,"data-state":t.open?"open":"closed",side:o,sideOffset:r,...p,...(0,M.skdxPart)("hover-card","content",p.className),ref:v,onPointerEnter:(0,A.composeEventHandlers)(p.onPointerEnter,a=>{a.pointerType!=="touch"&&t.onContentEnter()}),onPointerLeave:(0,A.composeEventHandlers)(p.onPointerLeave,a=>{a.pointerType!=="touch"&&t.onContentLeave()})}):null});g.displayName="HoverCardContent";var B=require("../utils/portal.cjs");var F=require("react/jsx-runtime"),y=({forceMount:e,children:o,...r})=>{let s=c("HoverCardPortal");return e||s.open?(0,F.jsx)(B.Portal,{...r,children:o}):null};y.displayName="HoverCardPortal";var K=E(require("react"),1),q=require("../utils/composeRefs.cjs"),z=require("../utils/part.cjs"),G=require("../utils/popper.cjs"),R=require("../utils/primitive.cjs");var L=require("react/jsx-runtime"),h=K.forwardRef((e,o)=>{let r=c("HoverCardTrigger"),s=(0,q.useComposedRefs)(o,r.triggerRef);return(0,L.jsx)(G.PopperAnchor,{asChild:!0,children:(0,L.jsx)(R.Primitive.a,{"aria-describedby":r.open?r.contentId:void 0,"data-state":r.open?"open":"closed",...e,...(0,z.skdxPart)("hover-card","trigger",e.className),ref:s,onPointerEnter:(0,R.composeEventHandlers)(e.onPointerEnter,n=>{n.pointerType!=="touch"&&r.onTriggerEnter()}),onPointerLeave:(0,R.composeEventHandlers)(e.onPointerLeave,n=>{n.pointerType!=="touch"&&r.onTriggerLeave()})})})});h.displayName="HoverCardTrigger";var f=require("react/jsx-runtime"),J=({trigger:e,side:o,align:r,showArrow:s,children:n,passThrough:m})=>{let{open:l}=c("HoverCardAnatomy"),p=l&&m?.id?{"aria-describedby":m.id}:{};return(0,f.jsxs)(f.Fragment,{children:[e?(0,f.jsx)(h,{asChild:!0,...p,children:e}):null,(0,f.jsx)(y,{children:(0,f.jsxs)(g,{...m,side:o,align:r,children:[n,s?(0,f.jsx)(T,{}):null]})})]})};var u=require("react/jsx-runtime"),[Z,c]=(0,Q.createSafeContext)("HoverCard");function b({children:e,open:o,defaultOpen:r=!1,onOpenChange:s,onOpenChangeComplete:n,openDelay:m=700,closeDelay:l=300,disabled:p=!1}){let H=i.useRef(null),t=i.useRef(null),v=i.useRef(0),a=i.useRef(0),[x=!1,C]=(0,X.useControllableState)({prop:o,defaultProp:r,onChange:s}),O=p?!1:x;(0,Y.useOpenChangeComplete)(O,t,n);let d=i.useCallback(()=>{window.clearTimeout(v.current),window.clearTimeout(a.current)},[]);i.useEffect(()=>d,[d]);let $=i.useCallback(()=>{p||(d(),C(!0))},[d,C,p]),j=i.useCallback(()=>{d(),C(!1)},[d,C]),ee=i.useCallback(()=>{p||(d(),v.current=window.setTimeout(()=>C(!0),m))},[d,C,m,p]),N=i.useCallback(()=>{d(),a.current=window.setTimeout(()=>C(!1),l)},[d,C,l]);return(0,u.jsx)(w.PopperRoot,{children:(0,u.jsx)(Z,{contentId:i.useId(),open:O,triggerRef:H,contentRef:t,onOpen:$,onClose:j,onTriggerEnter:ee,onTriggerLeave:N,onContentEnter:d,onContentLeave:N,children:e})})}b.displayName="HoverCardRoot";function _({children:e,open:o,defaultOpen:r,onOpenChange:s,onOpenChangeComplete:n,openDelay:m,closeDelay:l,disabled:p,trigger:H,side:t,align:v,showArrow:a=!1,...x}){return(0,u.jsx)(b,{open:o,defaultOpen:r,onOpenChange:s,onOpenChangeComplete:n,openDelay:m,closeDelay:l,disabled:p,children:(0,u.jsx)(J,{trigger:H,side:t,align:v,showArrow:a,passThrough:x,children:e})})}_.displayName="HoverCard";var T=i.forwardRef((e,o)=>(0,u.jsx)(w.PopperArrow,{...e,...(0,U.skdxPart)("hover-card","arrow",e.className),ref:o}));T.displayName="HoverCardArrow";0&&(module.exports={HoverCard,HoverCardArrow,HoverCardContent,HoverCardPortal,HoverCardRoot,HoverCardRootProvider,HoverCardTrigger,useHoverCardContext});

package/dist/hover-card/HoverCard.d.cts

@@ -7,6 +7,16 @@ export declare const HoverCardRootProvider: {
     }): React.JSX.Element;
     displayName: string;
 }, useHoverCardContext: (consumerName: string) => HoverCardContextValue;
+/** Props for {@link HoverCardRoot}: {@link HoverCardProps} minus the derived-anatomy-only props. */
+export type HoverCardRootProps = Omit<HoverCardProps, 'trigger' | 'side' | 'align' | 'showArrow'>;
+/**
+ * State/context root with independent open/close delays. Wraps children in
+ * popper root, renders no DOM. Use directly for full manual composition.
+ */
+export declare function HoverCardRoot({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, openDelay, closeDelay, disabled, }: HoverCardRootProps): React.JSX.Element;
+export declare namespace HoverCardRoot {
+    var displayName: string;
+}
 /**
  * Root of a hover-revealed preview card (e.g. a user profile preview behind
  * a link): owns open state with independent open/close delays and hands it
@@ -14,6 +24,13 @@ export declare const HoverCardRootProvider: {
  * `HoverCardArrow` via context. Wraps children in the shared popper
  * positioning root. Renders no DOM element itself.
  *
+ * Always draws the derived anatomy from `trigger`: the trigger (merged onto
+ * `trigger` via `asChild` — no extra wrapping `<a>`), the portal, and the
+ * floating card around the body (`children`). `children` is the card's
+ * body, never a switch — this component never inspects what it was given,
+ * only whether it exists. For full manual composition of the parts, use
+ * `HoverCardRoot` from `@skdx/react/primitives/hover-card` instead of this recipe.
+ *
  * Unlike `Tooltip`, the pointer can move from the trigger onto the content
  * itself without the card closing — `HoverCardContent` cancels the close
  * timer on pointer-enter. Escape closes the card and returns focus to the
@@ -22,9 +39,32 @@ export declare const HoverCardRootProvider: {
  * (WCAG 2.2 SC 1.4.13). Works controlled (`open` + `onOpenChange`) or
  * uncontrolled (`defaultOpen`).
  *
+ * The card is **pointer-only, and its content is not keyboard-reachable by
+ * design** — the same position Radix, Zag and Base UI take (Base UI renamed
+ * its family `PreviewCard`). Hover opens it, focus does not, no key does, and
+ * `Tab` moves through the page as if it were closed. **`HoverCardContent`
+ * must therefore hold nothing tabbable: use `Popover` when the content has to
+ * be operated** — a hover card whose content is interactive is a popover.
+ * Escape is the exception, and it is a dismissal rather than
+ * an activation.
+ *
+ * `disabled` suppresses the card in place: the pointer entering the trigger
+ * does nothing, `aria-describedby` never appears, `data-state` stays `closed`
+ * and `onOpenChange` never fires. Hover is the only activation there is, so
+ * suppressing it suppresses the card entirely.
+ *
  * @example
  * ```tsx
- * <HoverCard>
+ * <HoverCard trigger={<a href="/users/kent">@kentcdodds</a>}>
+ *   <p>Kent C. Dodds</p>
+ * </HoverCard>
+ * ```
+ *
+ * @example Full manual composition, for anything the derived anatomy can't express — `@skdx/react/primitives/hover-card`.
+ * ```tsx
+ * import { HoverCardArrow, HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from '@skdx/react/primitives/hover-card';
+ *
+ * <HoverCardRoot>
  *   <HoverCardTrigger href="/users/kent">@kentcdodds</HoverCardTrigger>
  *   <HoverCardPortal>
  *     <HoverCardContent>
@@ -32,10 +72,10 @@ export declare const HoverCardRootProvider: {
  *       <HoverCardArrow />
  *     </HoverCardContent>
  *   </HoverCardPortal>
- * </HoverCard>
+ * </HoverCardRoot>
  * ```
  */
-export declare function HoverCard({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, openDelay, closeDelay, }: HoverCardProps): React.JSX.Element;
+export declare function HoverCard({ children, open, defaultOpen, onOpenChange, onOpenChangeComplete, openDelay, closeDelay, disabled, trigger, side, align, showArrow, ...rest }: HoverCardProps): React.JSX.Element;
 export declare namespace HoverCard {
     var displayName: string;
 }