@skdx/react 0.28.0 → 0.29.0

package/dist/form/types.d.cts

@@ -2,12 +2,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`
- * pass. Used by {@link FormMessage}'s `match` prop to target a specific
- * failure reason.
- */
+/** A plain-object mirror of the native `ValidityState` for one field, captured by {@link Form} after a validation pass. */
 export interface ValiditySnapshot {
     badInput: boolean;
     customError: boolean;
@@ -35,132 +30,82 @@ export type FormValidationBehavior = 'native' | 'aria';
 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;
+    /** A plain snapshot of the control's validity flags, so the consumer can branch on the reason. */
+    validity: ValiditySnapshot;
 }
-/**
- * The imperative half of the Form contract, assigned onto the `<form>` node the
- * forwarded ref already carries.
- */
+/** 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.
-     */
+    /** Runs every control's native `checkValidity()` and every descendant `FormFieldRoot`'s own validation model, resolving to whether the whole form passed. */
     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.
- */
+/** Props for the {@link Form} recipe. */
 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.
+     * Heading for a derived `FormErrorSummary` ahead of the fields, focused the first time it appears.
      * @default undefined — no summary is derived, and nothing takes focus.
      */
-    errorSummary?: string;
+    errorSummary?: string | undefined;
     /**
-     * Label for a derived `FormSubmit` button, rendered after the fields. Same
-     * reasoning as `errorSummary`: the copy is the prop.
+     * Label for a derived `FormSubmit` button, rendered after the fields.
      * @default undefined — no submit button is derived.
      */
-    submitLabel?: string;
+    submitLabel?: string | undefined;
     /**
-     * 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`.
+     * Errors the browser cannot derive, keyed by the `name` a {@link FormField} already carries, shown by that field's catch-all `FormMessage`.
      * @default undefined — no server errors.
      */
-    errors?: FormErrors;
+    errors?: FormErrors | undefined;
     /**
      * 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;
+    onSubmit?: ((event: React.SubmitEvent<HTMLFormElement>) => void) | undefined;
     /**
-     * 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.
+     * Fires when the native `<form>` is reset, after the Form clears its
+     * per-field validity snapshots and touched/dirty/error state.
      * @default undefined — no-op if omitted.
      */
-    onReset?: (event: Event) => void;
+    onReset?: ((event: Event) => void) | undefined;
     /**
-     * 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.
+     * Fires once per failing field during the submit pass, so a consumer can react before a blocked submit returns silently.
      * @default undefined — no-op if omitted.
      */
-    onFieldInvalid?: (detail: FormFieldInvalidDetail) => void;
+    onFieldInvalid?: ((detail: FormFieldInvalidDetail) => void) | undefined;
     /**
-     * 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`.
+     * When a control's validity snapshot refreshes, and therefore when its `FormMessage`s may start showing.
      * @default 'change'
      */
-    validationMode?: FormValidationMode;
+    validationMode?: FormValidationMode | undefined;
     /**
      * 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;
+    validationBehavior?: FormValidationBehavior | undefined;
+    /**
+     * Spacing rung the skin packs the form by, mirrored to `data-density`.
+     * @default undefined — the skin's own default spacing.
+     */
+    density?: 'compact' | (string & {}) | undefined;
 }
-/** @internal Field identity distributed from {@link FormField} to its descendants via context. Not part of the public API. */
+/** @internal Field identity distributed from {@link FormField} to its descendants via context. */
 export interface FormFieldContextValue {
     name: string;
     id: string;
     messageId: string;
+    /** Ids of the field's currently shown messages, in mount order. */
+    messageIds: readonly string[];
+    /** Returns the id owned by the message with this token: the bare `messageId` for the first, `${messageId}-n` after. */
+    claimMessageId: (token: string) => string;
+    setMessageVisible: (id: string, visible: boolean) => void;
 }
 /** 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.
- */
+/** Props for {@link FormField}, a per-field grouping of label, control, and message. */
 export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /** Field name, matched against the `name` attribute of the native input rendered inside `FormControl`. */
     name: string;
@@ -169,16 +114,12 @@ export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asCh
      * points at the id this field injects onto the control.
      * @default undefined — no label is rendered, and the control is unnamed.
      */
-    label?: React.ReactNode;
+    label?: React.ReactNode | undefined;
     /**
-     * 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`.
+     * The catch-all validation message, rendered into a derived `FormMessage` shown whenever the field is invalid at all.
      * @default undefined — the message element renders with no text of its own.
      */
-    message?: React.ReactNode;
+    message?: React.ReactNode | undefined;
 }
 /** Props for {@link FormLabel}, a label wired to its `FormField`'s control. */
 export interface FormLabelProps extends PrimitivePropsWithRef<'label'> {
@@ -192,14 +133,12 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
      * Which `ValidityState` flag to show this message for; omit to match any invalid state.
      * @default undefined — matches any invalid state.
      */
-    match?: keyof ValiditySnapshot;
+    match?: keyof ValiditySnapshot | undefined;
     /**
-     * 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.
+     * Always render regardless of native validity, the per-message escape hatch.
      * @default false
      */
-    forceMatch?: boolean;
+    forceMatch?: boolean | undefined;
 }
 /** Props for {@link FormSubmit}, a `type="submit"` button. */
 export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
@@ -207,9 +146,8 @@ export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
 /** 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
-     * routing or scroll restoration already moves focus.
+     * Focus the summary the first time it appears.
      * @default true
      */
-    autoFocus?: boolean;
+    autoFocus?: boolean | undefined;
 }

package/dist/form/types.d.ts

@@ -2,12 +2,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`
- * pass. Used by {@link FormMessage}'s `match` prop to target a specific
- * failure reason.
- */
+/** A plain-object mirror of the native `ValidityState` for one field, captured by {@link Form} after a validation pass. */
 export interface ValiditySnapshot {
     badInput: boolean;
     customError: boolean;
@@ -35,132 +30,82 @@ export type FormValidationBehavior = 'native' | 'aria';
 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;
+    /** A plain snapshot of the control's validity flags, so the consumer can branch on the reason. */
+    validity: ValiditySnapshot;
 }
-/**
- * The imperative half of the Form contract, assigned onto the `<form>` node the
- * forwarded ref already carries.
- */
+/** 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.
-     */
+    /** Runs every control's native `checkValidity()` and every descendant `FormFieldRoot`'s own validation model, resolving to whether the whole form passed. */
     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.
- */
+/** Props for the {@link Form} recipe. */
 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.
+     * Heading for a derived `FormErrorSummary` ahead of the fields, focused the first time it appears.
      * @default undefined — no summary is derived, and nothing takes focus.
      */
-    errorSummary?: string;
+    errorSummary?: string | undefined;
     /**
-     * Label for a derived `FormSubmit` button, rendered after the fields. Same
-     * reasoning as `errorSummary`: the copy is the prop.
+     * Label for a derived `FormSubmit` button, rendered after the fields.
      * @default undefined — no submit button is derived.
      */
-    submitLabel?: string;
+    submitLabel?: string | undefined;
     /**
-     * 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`.
+     * Errors the browser cannot derive, keyed by the `name` a {@link FormField} already carries, shown by that field's catch-all `FormMessage`.
      * @default undefined — no server errors.
      */
-    errors?: FormErrors;
+    errors?: FormErrors | undefined;
     /**
      * 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;
+    onSubmit?: ((event: React.SubmitEvent<HTMLFormElement>) => void) | undefined;
     /**
-     * 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.
+     * Fires when the native `<form>` is reset, after the Form clears its
+     * per-field validity snapshots and touched/dirty/error state.
      * @default undefined — no-op if omitted.
      */
-    onReset?: (event: Event) => void;
+    onReset?: ((event: Event) => void) | undefined;
     /**
-     * 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.
+     * Fires once per failing field during the submit pass, so a consumer can react before a blocked submit returns silently.
      * @default undefined — no-op if omitted.
      */
-    onFieldInvalid?: (detail: FormFieldInvalidDetail) => void;
+    onFieldInvalid?: ((detail: FormFieldInvalidDetail) => void) | undefined;
     /**
-     * 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`.
+     * When a control's validity snapshot refreshes, and therefore when its `FormMessage`s may start showing.
      * @default 'change'
      */
-    validationMode?: FormValidationMode;
+    validationMode?: FormValidationMode | undefined;
     /**
      * 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;
+    validationBehavior?: FormValidationBehavior | undefined;
+    /**
+     * Spacing rung the skin packs the form by, mirrored to `data-density`.
+     * @default undefined — the skin's own default spacing.
+     */
+    density?: 'compact' | (string & {}) | undefined;
 }
-/** @internal Field identity distributed from {@link FormField} to its descendants via context. Not part of the public API. */
+/** @internal Field identity distributed from {@link FormField} to its descendants via context. */
 export interface FormFieldContextValue {
     name: string;
     id: string;
     messageId: string;
+    /** Ids of the field's currently shown messages, in mount order. */
+    messageIds: readonly string[];
+    /** Returns the id owned by the message with this token: the bare `messageId` for the first, `${messageId}-n` after. */
+    claimMessageId: (token: string) => string;
+    setMessageVisible: (id: string, visible: boolean) => void;
 }
 /** 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.
- */
+/** Props for {@link FormField}, a per-field grouping of label, control, and message. */
 export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asChild'> {
     /** Field name, matched against the `name` attribute of the native input rendered inside `FormControl`. */
     name: string;
@@ -169,16 +114,12 @@ export interface FormFieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'asCh
      * points at the id this field injects onto the control.
      * @default undefined — no label is rendered, and the control is unnamed.
      */
-    label?: React.ReactNode;
+    label?: React.ReactNode | undefined;
     /**
-     * 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`.
+     * The catch-all validation message, rendered into a derived `FormMessage` shown whenever the field is invalid at all.
      * @default undefined — the message element renders with no text of its own.
      */
-    message?: React.ReactNode;
+    message?: React.ReactNode | undefined;
 }
 /** Props for {@link FormLabel}, a label wired to its `FormField`'s control. */
 export interface FormLabelProps extends PrimitivePropsWithRef<'label'> {
@@ -192,14 +133,12 @@ export interface FormMessageProps extends PrimitivePropsWithRef<'span'> {
      * Which `ValidityState` flag to show this message for; omit to match any invalid state.
      * @default undefined — matches any invalid state.
      */
-    match?: keyof ValiditySnapshot;
+    match?: keyof ValiditySnapshot | undefined;
     /**
-     * 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.
+     * Always render regardless of native validity, the per-message escape hatch.
      * @default false
      */
-    forceMatch?: boolean;
+    forceMatch?: boolean | undefined;
 }
 /** Props for {@link FormSubmit}, a `type="submit"` button. */
 export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
@@ -207,9 +146,8 @@ export interface FormSubmitProps extends PrimitivePropsWithRef<'button'> {
 /** 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
-     * routing or scroll restoration already moves focus.
+     * Focus the summary the first time it appears.
      * @default true
      */
-    autoFocus?: boolean;
+    autoFocus?: boolean | undefined;
 }

package/dist/heading/Heading.cjs

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

package/dist/heading/Heading.d.cts

@@ -1,9 +1,7 @@
-import * as React from 'react';
+import type * 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.
+ * A section heading (`<h1>`–`<h6>` via `as`) with outline level and visual size (`data-size`) kept separate.
  *
  * @example
  * ```tsx
@@ -11,4 +9,7 @@ import type { HeadingProps } from './types.cjs';
  * <Heading as="h2" visuallyHidden>Filters</Heading>
  * ```
  */
-export declare const Heading: React.ForwardRefExoticComponent<Omit<HeadingProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+export declare const Heading: {
+    ({ as, visuallyHidden, className, ref: forwardedRef, size, ...props }: HeadingProps): React.ReactNode;
+    displayName: string;
+};

package/dist/heading/Heading.d.ts

@@ -1,9 +1,7 @@
-import * as React from 'react';
+import type * 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.
+ * A section heading (`<h1>`–`<h6>` via `as`) with outline level and visual size (`data-size`) kept separate.
  *
  * @example
  * ```tsx
@@ -11,4 +9,7 @@ import type { HeadingProps } from './types.js';
  * <Heading as="h2" visuallyHidden>Filters</Heading>
  * ```
  */
-export declare const Heading: React.ForwardRefExoticComponent<Omit<HeadingProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+export declare const Heading: {
+    ({ as, visuallyHidden, className, ref: forwardedRef, size, ...props }: HeadingProps): React.ReactNode;
+    displayName: string;
+};

package/dist/heading/Heading.js

@@ -1 +1,2 @@
-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};
+'use client';
+import{appearanceAttrs as m}from"../utils/appearance.js";import{skdxPart as s}from"../utils/part.js";import{Primitive as f}from"../utils/primitive.js";import{jsx as y}from"react/jsx-runtime";var c="skdx-visually-hidden",o=({as:t,visuallyHidden:r=!1,className:i,ref:a,size:n,...e})=>{let p=f[t],d=[i,r?c:void 0].filter(Boolean).join(" ");return y(p,{...e,...m({size:n},e),...s("heading","root",d||void 0),ref:a})};o.displayName="Heading";export{o as Heading};

package/dist/heading/types.d.cts

@@ -1,15 +1,17 @@
 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.
-     */
+    /** Which heading element to render; required, since the level belongs to your document outline. */
     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;
+    visuallyHidden?: boolean | undefined;
+    /**
+     * Size rung the skin scales the heading by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | (string & {}) | undefined;
 }

package/dist/heading/types.d.ts

@@ -1,15 +1,17 @@
 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.
-     */
+    /** Which heading element to render; required, since the level belongs to your document outline. */
     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;
+    visuallyHidden?: boolean | undefined;
+    /**
+     * Size rung the skin scales the heading by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | (string & {}) | undefined;
 }

package/dist/image/Image.cjs

@@ -1 +1,2 @@
-"use strict";var z=Object.create;var l=Object.defineProperty;var F=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var q=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var B=(e,t)=>{for(var a in t)l(e,a,{get:t[a],enumerable:!0})},y=(e,t,a,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of W(t))!A.call(e,r)&&r!==a&&l(e,r,{get:()=>t[r],enumerable:!(i=F(t,r))||i.enumerable});return e};var D=(e,t,a)=>(a=e!=null?z(q(e)):{},y(t||!e||!e.__esModule?l(a,"default",{value:e,enumerable:!0}):a,e)),G=e=>y(l({},"__esModule",{value:!0}),e);var J={};B(J,{Image:()=>P});module.exports=G(J);var o=D(require("react"),1),I=require("../utils/composeRefs.cjs"),g=require("../utils/part.cjs"),n=require("../utils/primitive.cjs"),R=require("../utils/useCallbackRef.cjs"),f=require("react/jsx-runtime"),P=o.forwardRef(({onLoadingStatusChange:e=()=>{},src:t,srcSet:a,sizes:i,alt:r,loading:S="lazy",decoding:L="async",fetchPriority:h="auto",fit:E,position:C,fallback:u,style:b,onLoad:v,onError:H,...c},N)=>{let[d,k]=o.useState("idle"),s=(0,R.useCallbackRef)(m=>{k(m),e(m)}),p=o.useRef(null),x=(0,I.useComposedRefs)(N,p);o.useLayoutEffect(()=>{if(!t){s("idle");return}let m=p.current;if(m?.complete){s(m.naturalWidth>0?"loaded":"error");return}s("loading")},[t,a,i,s]);let M=(0,n.composeEventHandlers)(v,()=>{d!=="error"&&s("loaded")}),T=(0,n.composeEventHandlers)(H,()=>s("error")),j=(0,g.skdxPart)("image","root",c.className);if(d==="error"&&u!==void 0)return(0,f.jsx)(n.Primitive.span,{"data-loading-status":d,...(0,g.skdxPart)("image","fallback",c.className),children:u});let w={objectFit:E,objectPosition:C,...b};return(0,f.jsx)(n.Primitive.img,{src:t,srcSet:a,sizes:i,alt:r,loading:S,decoding:L,fetchPriority:h,"data-loading-status":d,...c,style:w,onLoad:M,onError:T,...j,ref:x})});P.displayName="Image";0&&(module.exports={Image});
+'use client';
+"use strict";var T=Object.create;var c=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var w=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var B=(e,t)=>{for(var a in t)c(e,a,{get:t[a],enumerable:!0})},y=(e,t,a,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of q(t))!A.call(e,o)&&o!==a&&c(e,o,{get:()=>t[o],enumerable:!(n=W(t,o))||n.enumerable});return e};var D=(e,t,a)=>(a=e!=null?T(w(e)):{},y(t||!e||!e.__esModule?c(a,"default",{value:e,enumerable:!0}):a,e)),G=e=>y(c({},"__esModule",{value:!0}),e);var J={};B(J,{Image:()=>P});module.exports=G(J);var i=D(require("react"),1),R=require("../utils/composeRefs.cjs"),g=require("../utils/part.cjs"),s=require("../utils/primitive.cjs"),I=require("../utils/useCallbackRef.cjs"),f=require("react/jsx-runtime"),P=({onLoadingStatusChange:e=()=>{},src:t,srcSet:a,sizes:n,alt:o,loading:S="lazy",decoding:L="async",fetchPriority:h="auto",fit:E,position:C,fallback:u,style:N,onLoad:b,onError:v,ref:k,...l})=>{let[d,x]=i.useState("idle"),r=(0,I.useCallbackRef)(m=>{x(m),e(m)}),p=i.useRef(null),H=(0,R.useComposedRefs)(k,p);i.useLayoutEffect(()=>{if(!t){r("idle");return}let m=p.current;if(m?.complete){r(m.naturalWidth>0?"loaded":"error");return}r("loading")},[t,a,n,r]);let j=(0,s.composeEventHandlers)(b,()=>{d!=="error"&&r("loaded")}),z=(0,s.composeEventHandlers)(v,()=>r("error")),F=(0,g.skdxPart)("image","root",l.className);if(d==="error"&&u!==void 0)return(0,f.jsx)(s.Primitive.span,{"data-loading-status":d,...(0,g.skdxPart)("image","fallback",l.className),children:u});let M={objectFit:E,objectPosition:C,...N};return(0,f.jsx)(s.Primitive.img,{src:t,srcSet:a,sizes:n,alt:o,loading:S,decoding:L,fetchPriority:h,"data-loading-status":d,...l,style:M,onLoad:j,onError:z,...F,ref:H})};P.displayName="Image";0&&(module.exports={Image});

package/dist/image/Image.d.cts

@@ -1,13 +1,14 @@
 import * as React from 'react';
 import type { ImageProps } from './types.cjs';
 /**
- * Renders `<img>` unconditionally and drives status off its own load/error
- * events — unlike `AvatarImage`'s off-DOM probe, which would trigger a
- * second fetch and defeat `loading="lazy"`.
+ * Renders an `<img>` unconditionally and derives loading status from its own load/error events.
  *
  * @example
  * ```tsx
  * <Image src="/hero.jpg" alt="Product hero shot" fit="cover" fallback={<Placeholder />} />
  * ```
  */
-export declare const Image: React.ForwardRefExoticComponent<Omit<ImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+export declare const Image: {
+    ({ onLoadingStatusChange, src, srcSet, sizes, alt, loading, decoding, fetchPriority, fit, position, fallback, style, onLoad, onError, ref: forwardedRef, ...props }: ImageProps): React.ReactNode;
+    displayName: string;
+};

package/dist/image/Image.d.ts

@@ -1,13 +1,14 @@
 import * as React from 'react';
 import type { ImageProps } from './types.js';
 /**
- * Renders `<img>` unconditionally and drives status off its own load/error
- * events — unlike `AvatarImage`'s off-DOM probe, which would trigger a
- * second fetch and defeat `loading="lazy"`.
+ * Renders an `<img>` unconditionally and derives loading status from its own load/error events.
  *
  * @example
  * ```tsx
  * <Image src="/hero.jpg" alt="Product hero shot" fit="cover" fallback={<Placeholder />} />
  * ```
  */
-export declare const Image: React.ForwardRefExoticComponent<Omit<ImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+export declare const Image: {
+    ({ onLoadingStatusChange, src, srcSet, sizes, alt, loading, decoding, fetchPriority, fit, position, fallback, style, onLoad, onError, ref: forwardedRef, ...props }: ImageProps): React.ReactNode;
+    displayName: string;
+};

package/dist/image/Image.js

@@ -1 +1,2 @@
-import*as e from"react";import{useComposedRefs as M}from"../utils/composeRefs.js";import{skdxPart as l}from"../utils/part.js";import{composeEventHandlers as c,Primitive as g}from"../utils/primitive.js";import{useCallbackRef as T}from"../utils/useCallbackRef.js";import{jsx as f}from"react/jsx-runtime";var j=e.forwardRef(({onLoadingStatusChange:u=()=>{},src:r,srcSet:n,sizes:i,alt:p,loading:y="lazy",decoding:I="async",fetchPriority:R="auto",fit:P,position:S,fallback:m,style:L,onLoad:h,onError:E,...s},C)=>{let[o,b]=e.useState("idle"),t=T(a=>{b(a),u(a)}),d=e.useRef(null),v=M(C,d);e.useLayoutEffect(()=>{if(!r){t("idle");return}let a=d.current;if(a?.complete){t(a.naturalWidth>0?"loaded":"error");return}t("loading")},[r,n,i,t]);let H=c(h,()=>{o!=="error"&&t("loaded")}),N=c(E,()=>t("error")),k=l("image","root",s.className);if(o==="error"&&m!==void 0)return f(g.span,{"data-loading-status":o,...l("image","fallback",s.className),children:m});let x={objectFit:P,objectPosition:S,...L};return f(g.img,{src:r,srcSet:n,sizes:i,alt:p,loading:y,decoding:I,fetchPriority:R,"data-loading-status":o,...s,style:x,onLoad:H,onError:N,...k,ref:v})});j.displayName="Image";export{j as Image};
+'use client';
+import*as t from"react";import{useComposedRefs as j}from"../utils/composeRefs.js";import{skdxPart as c}from"../utils/part.js";import{composeEventHandlers as l,Primitive as g}from"../utils/primitive.js";import{useCallbackRef as z}from"../utils/useCallbackRef.js";import{jsx as f}from"react/jsx-runtime";var F=({onLoadingStatusChange:u=()=>{},src:r,srcSet:i,sizes:n,alt:p,loading:y="lazy",decoding:R="async",fetchPriority:I="auto",fit:P,position:S,fallback:m,style:L,onLoad:h,onError:E,ref:C,...s})=>{let[o,N]=t.useState("idle"),e=z(a=>{N(a),u(a)}),d=t.useRef(null),b=j(C,d);t.useLayoutEffect(()=>{if(!r){e("idle");return}let a=d.current;if(a?.complete){e(a.naturalWidth>0?"loaded":"error");return}e("loading")},[r,i,n,e]);let v=l(h,()=>{o!=="error"&&e("loaded")}),k=l(E,()=>e("error")),x=c("image","root",s.className);if(o==="error"&&m!==void 0)return f(g.span,{"data-loading-status":o,...c("image","fallback",s.className),children:m});let H={objectFit:P,objectPosition:S,...L};return f(g.img,{src:r,srcSet:i,sizes:n,alt:p,loading:y,decoding:R,fetchPriority:I,"data-loading-status":o,...s,style:H,onLoad:v,onError:k,...x,ref:b})};F.displayName="Image";export{F as Image};