@skdx/react 0.26.0 → 0.28.0

package/dist/steps/types.d.ts

@@ -1,21 +1,22 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
-/** The four mutually exclusive statuses a single step can be in. */
-export type StepStatus = 'completed' | 'current' | 'incomplete' | 'disabled';
+/**
+ * Step status: completed, current, incomplete, error (announces form failures separately), or disabled.
+ */
+export type StepStatus = 'completed' | 'current' | 'error' | 'incomplete' | 'disabled';
 /** Layout axis of a {@link Steps} list. */
 export type StepsOrientation = 'horizontal' | 'vertical';
 /**
- * How far a `StepsTrigger` may jump. `'linear'` allows completed steps, the
- * current step, and the first not-yet-completed step (the frontier);
- * `'non-linear'` allows any step that is not itself disabled.
+ * Navigation mode: `'linear'` restricts to completed, current, and next incomplete steps; `'non-linear'` allows any non-disabled step.
  */
 export type StepsNavigationMode = 'linear' | 'non-linear';
-/** @internal One registered step, as {@link Steps} tracks it for navigation-mode decisions. Not part of the public API. */
+/** @internal One registered step tracked for navigation-mode decisions. */
 export interface StepsItemState {
     value: string;
     completed: boolean;
     disabled: boolean;
 }
-/** @internal Shared state distributed from {@link Steps} to its parts via context. Not part of the public API. */
+/** @internal Shared state distributed from Steps to its parts via context. */
 export interface StepsContextValue {
     value?: string;
     orientation: StepsOrientation;
@@ -31,8 +32,32 @@ export interface StepsContextValue {
     /** Activates `value` if {@link StepsContextValue.canActivate} allows it; a no-op otherwise. */
     activate: (value: string) => void;
 }
+/** One entry of {@link StepsProps.items} — a single step. */
+export interface StepsStep {
+    /** Rendered in the trigger; names the step. */
+    label: React.ReactNode;
+    /**
+     * Supporting copy rendered under the step trigger.
+     * @default undefined — no description is rendered.
+     */
+    description?: React.ReactNode;
+}
 /** Props for the {@link Steps} root. */
 export interface StepsProps extends PrimitivePropsWithRef<'ol'> {
+    /**
+     * Steps to render as derived `StepsItem`/`StepsTrigger` pairs. Step value is its
+     * positional index (string), used by `current` and `onValueChange`. Ignored if
+     * `children` is given for manual composition.
+     * @default undefined — nothing is derived; compose the steps as `children`.
+     */
+    items?: StepsStep[];
+    /**
+     * Index of the current step in `items`. Earlier steps derive as `completed`,
+     * enabling backward but not forward navigation in linear mode. Controlled prop:
+     * pair it with `onValueChange`.
+     * @default undefined — no step is current, and only the first is reachable.
+     */
+    current?: number;
     /**
      * Current step's value, for controlled usage. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own current step internally.
@@ -44,23 +69,20 @@ export interface StepsProps extends PrimitivePropsWithRef<'ol'> {
      */
     defaultValue?: string;
     /**
-     * Fires with the new value whenever the current step changes, controlled or
-     * not. Never fires for an activation the navigation mode or a disabled step
-     * blocked.
+     * Fires when the current step changes. Never fires for activations blocked by
+     * navigation mode or disabled steps.
      * @default undefined — no-op.
      */
     onValueChange?: (value: string) => void;
     /**
-     * Layout axis, exposed as `data-orientation`. Purely a styling hook — each
-     * trigger is an ordinary tab stop, so there is no ARIA orientation and no
-     * arrow-key handling.
+     * Layout axis, exposed as `data-orientation`. Purely a styling hook; no ARIA
+     * orientation or arrow-key handling.
      * @default 'horizontal'
      */
     orientation?: StepsOrientation;
     /**
-     * `'linear'` restricts triggers to completed steps, the current step, and
-     * the first not-yet-completed step. `'non-linear'` lets a trigger activate
-     * any step that is not itself disabled. Neither mode restricts programmatic
+     * `'linear'` restricts to completed, current, and next incomplete steps;
+     * `'non-linear'` allows any non-disabled step. Neither restricts programmatic
      * changes to `value`.
      * @default 'linear'
      */
@@ -85,30 +107,41 @@ export interface StepsProps extends PrimitivePropsWithRef<'ol'> {
      * @default 'Disabled'
      */
     disabledLabel?: string;
+    /**
+     * Visually-hidden status text for a step in an error state.
+     * @default 'Error'
+     */
+    errorLabel?: string;
 }
 /**
  * Props for a single {@link StepsItem}.
  *
- * `asChild` is deliberately unavailable: `StepsItem` injects its own
- * visually-hidden status element as a second child, which `Slot` (single
- * element child only) cannot merge onto a consumer's element.
+ * `asChild` is unavailable: `StepsItem` injects a visually-hidden status element
+ * as a second child, which `Slot` cannot merge.
  */
 export interface StepsItemProps extends Omit<PrimitivePropsWithRef<'li'>, 'asChild'> {
     /** Unique identifier matched against the root's `value` and a `StepsTrigger`'s `value`. */
     value: string;
     /**
-     * Whether this step has been completed. Drives `data-status` and, in linear
-     * mode, which steps a trigger may activate.
+     * Whether this step is completed. Drives `data-state` and, in linear mode,
+     * which steps a trigger may activate.
      * @default false
      */
     completed?: boolean;
     /**
-     * Whether this step can be activated at all. A disabled step's trigger
-     * leaves the tab order and refuses activation, but the step does not move
-     * the linear frontier.
+     * Whether this step can be activated. A disabled step's trigger leaves the tab
+     * order and refuses activation, without moving the linear frontier.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Whether this step is in an error state (form validation or upload failure).
+     * Drives `data-state="error"` and the `errorLabel` status text, announcing the
+     * failure separately. Ranks below `current`: the current step announces as
+     * current even while failing.
+     * @default false
+     */
+    error?: boolean;
 }
 /** Props for a single {@link StepsTrigger} button. */
 export interface StepsTriggerProps extends PrimitivePropsWithRef<'button'> {

package/dist/switch/Switch.cjs

@@ -1 +1 @@
-"use strict";var g=Object.create;var n=Object.defineProperty;var q=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var I=Object.getPrototypeOf,z=Object.prototype.hasOwnProperty;var A=(e,t)=>{for(var o in t)n(e,o,{get:t[o],enumerable:!0})},S=(e,t,o,c)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of F(t))!z.call(e,r)&&r!==o&&n(e,r,{get:()=>t[r],enumerable:!(c=q(t,r))||c.enumerable});return e};var b=(e,t,o)=>(o=e!=null?g(I(e)):{},S(t||!e||!e.__esModule?n(o,"default",{value:e,enumerable:!0}):o,e)),D=e=>S(n({},"__esModule",{value:!0}),e);var G={};A(G,{Switch:()=>v,SwitchProvider:()=>T,SwitchThumb:()=>f,useSwitchContext:()=>p});module.exports=D(G);var s=b(require("react"),1),k=require("../utils/composeRefs.cjs"),x=require("../utils/createContext.cjs"),P=require("../utils/formControl.cjs"),R=require("../utils/hiddenInput.cjs"),y=require("../utils/part.cjs"),d=require("../utils/primitive.cjs"),C=require("../utils/useControllableState.cjs"),a=require("react/jsx-runtime"),[T,p]=(0,x.createSafeContext)("Switch"),v=s.forwardRef(({checked:e,defaultChecked:t=!1,onCheckedChange:o,required:c,name:r,value:M="on",disabled:m=!1,invalid:u=!1,...h},B)=>{let[i=!1,l]=(0,C.useControllableState)({prop:e,defaultProp:t,onChange:o}),w=s.useRef(null),V=(0,k.useComposedRefs)(B,w);return(0,P.useFormReset)(w,()=>l(t)),(0,a.jsxs)(T,{checked:i,disabled:m,children:[(0,a.jsx)(d.Primitive.button,{type:"button",role:"switch","aria-checked":i,"aria-required":c||void 0,"aria-invalid":u?!0:void 0,"data-state":i?"checked":"unchecked","data-disabled":m?"":void 0,"data-invalid":u?"":void 0,disabled:m,...h,...(0,y.skdxPart)("switch","root",h.className),ref:V,onClick:(0,d.composeEventHandlers)(h.onClick,()=>l(!i))}),r&&(0,a.jsx)(R.HiddenInput,{type:"checkbox",name:r,value:M,checked:i,required:c,disabled:m})]})});v.displayName="Switch";var H=b(require("react"),1),E=require("../utils/part.cjs"),N=require("../utils/primitive.cjs");var L=require("react/jsx-runtime"),f=H.forwardRef((e,t)=>{let o=p("SwitchThumb");return(0,L.jsx)(N.Primitive.span,{"data-state":o.checked?"checked":"unchecked","data-disabled":o.disabled?"":void 0,...e,...(0,E.skdxPart)("switch","thumb",e.className),ref:t})});f.displayName="SwitchThumb";0&&(module.exports={Switch,SwitchProvider,SwitchThumb,useSwitchContext});
+"use strict";var U=Object.create;var f=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var X=Object.getOwnPropertyNames;var Y=Object.getPrototypeOf,Z=Object.prototype.hasOwnProperty;var _=(e,t)=>{for(var o in t)f(e,o,{get:t[o],enumerable:!0})},T=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of X(t))!Z.call(e,a)&&a!==o&&f(e,a,{get:()=>t[a],enumerable:!(r=W(t,a))||r.enumerable});return e};var k=(e,t,o)=>(o=e!=null?U(Y(e)):{},T(t||!e||!e.__esModule?f(o,"default",{value:e,enumerable:!0}):o,e)),$=e=>T(f({},"__esModule",{value:!0}),e);var O={};_(O,{Switch:()=>y,SwitchLabel:()=>h,SwitchProvider:()=>z,SwitchThumb:()=>p,useSwitchContext:()=>s});module.exports=$(O);var d=k(require("react"),1),V=require("../utils/createContext.cjs"),u=require("../utils/formControl.cjs"),q=require("../utils/hiddenInput.cjs"),B=require("../utils/part.cjs"),w=require("../utils/primitive.cjs"),F=require("../utils/useControllableState.cjs");var C=k(require("react"),1),v=require("../utils/part.cjs"),H=require("../utils/primitive.cjs");var N=require("react/jsx-runtime"),h=C.forwardRef((e,t)=>{let o=s("SwitchLabel");return(0,N.jsx)(H.Primitive.span,{"data-state":o.checked?"checked":"unchecked","data-disabled":o.disabled?"":void 0,...e,...(0,v.skdxPart)("switch","label",e.className),ref:t})});h.displayName="SwitchLabel";var E=k(require("react"),1),M=require("../utils/part.cjs"),g=require("../utils/primitive.cjs");var A=require("react/jsx-runtime"),p=E.forwardRef((e,t)=>{let o=s("SwitchThumb");return(0,A.jsx)(g.Primitive.span,{"data-state":o.checked?"checked":"unchecked","data-disabled":o.disabled?"":void 0,...e,...(0,M.skdxPart)("switch","thumb",e.className),ref:t})});p.displayName="SwitchThumb";var i=require("react/jsx-runtime");function I({label:e,labelPosition:t}){let o=(0,i.jsx)(p,{}),r=e?(0,i.jsx)(h,{children:e}):null;return t==="start"?(0,i.jsxs)(i.Fragment,{children:[r,o]}):(0,i.jsxs)(i.Fragment,{children:[o,r]})}var n=require("react/jsx-runtime"),[z,s]=(0,V.createSafeContext)("Switch"),y=d.forwardRef(({checked:e,defaultChecked:t=!1,onCheckedChange:o,required:r,name:a,value:D="on",disabled:m=!1,readOnly:l=!1,invalid:P=!1,form:x,label:G,labelPosition:J="end",children:K,...b},Q)=>{let[c=!1,R]=(0,F.useControllableState)({prop:e,defaultProp:t,onChange:o}),S=d.useRef(null),L=d.useRef(null);return(0,u.useFormValidityHandle)(Q,S,L),(0,u.useFormReset)(S,()=>R(t),x),(0,n.jsxs)(z,{checked:c,disabled:m,children:[(0,n.jsx)(w.Primitive.button,{type:"button",role:"switch","aria-checked":c,"aria-required":r||void 0,"aria-invalid":P?!0:void 0,"aria-readonly":l||void 0,"data-state":c?"checked":"unchecked","data-disabled":m?"":void 0,"data-readonly":l?"":void 0,"data-invalid":P?"":void 0,disabled:m,...b,...(0,B.skdxPart)("switch","root",b.className),ref:S,onClick:(0,w.composeEventHandlers)(b.onClick,()=>{l||R(!c)}),children:K??(0,n.jsx)(I,{label:G,labelPosition:J})}),a&&(0,n.jsx)(q.HiddenInput,{ref:L,type:"checkbox",name:a,value:D,checked:c,required:l?void 0:r,disabled:m,form:x})]})});y.displayName="Switch";0&&(module.exports={Switch,SwitchLabel,SwitchProvider,SwitchThumb,useSwitchContext});

package/dist/switch/Switch.d.cts

@@ -8,17 +8,38 @@ export declare const SwitchProvider: {
 }, useSwitchContext: (consumerName: string) => SwitchContextValue;
 /**
  * A boolean on/off switch button. Renders `role="switch"` with `aria-checked`,
- * `data-state` (`'checked'` / `'unchecked'`), `data-disabled`, and
- * `aria-invalid`/`data-invalid` when `invalid` is set. Toggles on click
- * (Space/Enter activation is native `<button>` behavior). When `name` is
- * set, also renders a visually-hidden native `<input type="checkbox">` so
- * the value participates in real form submission.
+ * `data-state`, `data-disabled`, and `aria-invalid`/`data-invalid` when
+ * `invalid` is set. Toggles on click. When `name` is set, also renders a
+ * visually-hidden native `<input type="checkbox">` for real form submission.
+ *
+ * The forwarded ref is that hidden input's owner as well as the button: it
+ * carries `checkValidity()`, `reportValidity()` and `setCustomValidity()`
+ * alongside everything an `HTMLButtonElement` ref already did. Type it with
+ * {@link SwitchHandle}. All three delegate to the hidden input; the two
+ * readable ones answer `true` when there is none.
+ *
+ * `role="switch"` takes its name from its content, but a `SwitchThumb` is the
+ * moving knob and renders no text — give it a visible label child, or an
+ * `aria-label` when the label lives elsewhere on screen.
  *
  * @example
  * ```tsx
+ * // Named from its own content: the text is the label a user hears and sees.
  * <Switch defaultChecked name="notifications">
  *   <SwitchThumb />
+ *   Notifications
  * </Switch>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Named by the author, for the icon-only form where no text sits inside.
+ * <Switch defaultChecked name="notifications" aria-label="Notifications">
+ *   <SwitchThumb />
+ * </Switch>
+ * ```
+ *
+ * Given no `children` draws the derived anatomy: Thumb plus Label from
+ * `label`/`labelPosition`. Given children, they render verbatim.
  */
 export declare const Switch: React.ForwardRefExoticComponent<Omit<SwitchProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/switch/Switch.d.ts

@@ -8,17 +8,38 @@ export declare const SwitchProvider: {
 }, useSwitchContext: (consumerName: string) => SwitchContextValue;
 /**
  * A boolean on/off switch button. Renders `role="switch"` with `aria-checked`,
- * `data-state` (`'checked'` / `'unchecked'`), `data-disabled`, and
- * `aria-invalid`/`data-invalid` when `invalid` is set. Toggles on click
- * (Space/Enter activation is native `<button>` behavior). When `name` is
- * set, also renders a visually-hidden native `<input type="checkbox">` so
- * the value participates in real form submission.
+ * `data-state`, `data-disabled`, and `aria-invalid`/`data-invalid` when
+ * `invalid` is set. Toggles on click. When `name` is set, also renders a
+ * visually-hidden native `<input type="checkbox">` for real form submission.
+ *
+ * The forwarded ref is that hidden input's owner as well as the button: it
+ * carries `checkValidity()`, `reportValidity()` and `setCustomValidity()`
+ * alongside everything an `HTMLButtonElement` ref already did. Type it with
+ * {@link SwitchHandle}. All three delegate to the hidden input; the two
+ * readable ones answer `true` when there is none.
+ *
+ * `role="switch"` takes its name from its content, but a `SwitchThumb` is the
+ * moving knob and renders no text — give it a visible label child, or an
+ * `aria-label` when the label lives elsewhere on screen.
  *
  * @example
  * ```tsx
+ * // Named from its own content: the text is the label a user hears and sees.
  * <Switch defaultChecked name="notifications">
  *   <SwitchThumb />
+ *   Notifications
  * </Switch>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Named by the author, for the icon-only form where no text sits inside.
+ * <Switch defaultChecked name="notifications" aria-label="Notifications">
+ *   <SwitchThumb />
+ * </Switch>
+ * ```
+ *
+ * Given no `children` draws the derived anatomy: Thumb plus Label from
+ * `label`/`labelPosition`. Given children, they render verbatim.
  */
 export declare const Switch: React.ForwardRefExoticComponent<Omit<SwitchProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/switch/Switch.js

@@ -1 +1 @@
-import*as i from"react";import{useComposedRefs as k}from"../utils/composeRefs.js";import{createSafeContext as x}from"../utils/createContext.js";import{useFormReset as P}from"../utils/formControl.js";import{HiddenInput as R}from"../utils/hiddenInput.js";import{skdxPart as y}from"../utils/part.js";import{composeEventHandlers as C,Primitive as T}from"../utils/primitive.js";import{useControllableState as v}from"../utils/useControllableState.js";import{jsx as p,jsxs as N}from"react/jsx-runtime";var[H,f]=x("Switch"),E=i.forwardRef(({checked:t,defaultChecked:o=!1,onCheckedChange:r,required:m,name:n,value:w="on",disabled:c=!1,invalid:s=!1,...a},S)=>{let[e=!1,d]=v({prop:t,defaultProp:o,onChange:r}),h=i.useRef(null),b=k(S,h);return P(h,()=>d(o)),N(H,{checked:e,disabled:c,children:[p(T.button,{type:"button",role:"switch","aria-checked":e,"aria-required":m||void 0,"aria-invalid":s?!0:void 0,"data-state":e?"checked":"unchecked","data-disabled":c?"":void 0,"data-invalid":s?"":void 0,disabled:c,...a,...y("switch","root",a.className),ref:b,onClick:C(a.onClick,()=>d(!e))}),n&&p(R,{type:"checkbox",name:n,value:w,checked:e,required:m,disabled:c})]})});E.displayName="Switch";import*as u from"react";import{skdxPart as L}from"../utils/part.js";import{Primitive as M}from"../utils/primitive.js";import{jsx as B}from"react/jsx-runtime";var l=u.forwardRef((t,o)=>{let r=f("SwitchThumb");return B(M.span,{"data-state":r.checked?"checked":"unchecked","data-disabled":r.disabled?"":void 0,...t,...L("switch","thumb",t.className),ref:o})});l.displayName="SwitchThumb";export{E as Switch,H as SwitchProvider,l as SwitchThumb,f as useSwitchContext};
+import*as a from"react";import{createSafeContext as B}from"../utils/createContext.js";import{useFormReset as F,useFormValidityHandle as z}from"../utils/formControl.js";import{HiddenInput as D}from"../utils/hiddenInput.js";import{skdxPart as G}from"../utils/part.js";import{composeEventHandlers as J,Primitive as K}from"../utils/primitive.js";import{useControllableState as Q}from"../utils/useControllableState.js";import*as k from"react";import{skdxPart as M}from"../utils/part.js";import{Primitive as g}from"../utils/primitive.js";import{jsx as A}from"react/jsx-runtime";var l=k.forwardRef((e,o)=>{let t=s("SwitchLabel");return A(g.span,{"data-state":t.checked?"checked":"unchecked","data-disabled":t.disabled?"":void 0,...e,...M("switch","label",e.className),ref:o})});l.displayName="SwitchLabel";import*as y from"react";import{skdxPart as I}from"../utils/part.js";import{Primitive as V}from"../utils/primitive.js";import{jsx as q}from"react/jsx-runtime";var f=y.forwardRef((e,o)=>{let t=s("SwitchThumb");return q(V.span,{"data-state":t.checked?"checked":"unchecked","data-disabled":t.disabled?"":void 0,...e,...I("switch","thumb",e.className),ref:o})});f.displayName="SwitchThumb";import{Fragment as x,jsx as P,jsxs as R}from"react/jsx-runtime";function L({label:e,labelPosition:o}){let t=P(f,{}),i=e?P(l,{children:e}):null;return o==="start"?R(x,{children:[i,t]}):R(x,{children:[t,i]})}import{jsx as h,jsxs as W}from"react/jsx-runtime";var[U,s]=B("Switch"),T=a.forwardRef(({checked:e,defaultChecked:o=!1,onCheckedChange:t,required:i,name:p,value:C="on",disabled:n=!1,readOnly:c=!1,invalid:u=!1,form:w,label:v,labelPosition:H="end",children:N,...d},E)=>{let[r=!1,b]=Q({prop:e,defaultProp:o,onChange:t}),m=a.useRef(null),S=a.useRef(null);return z(E,m,S),F(m,()=>b(o),w),W(U,{checked:r,disabled:n,children:[h(K.button,{type:"button",role:"switch","aria-checked":r,"aria-required":i||void 0,"aria-invalid":u?!0:void 0,"aria-readonly":c||void 0,"data-state":r?"checked":"unchecked","data-disabled":n?"":void 0,"data-readonly":c?"":void 0,"data-invalid":u?"":void 0,disabled:n,...d,...G("switch","root",d.className),ref:m,onClick:J(d.onClick,()=>{c||b(!r)}),children:N??h(L,{label:v,labelPosition:H})}),p&&h(D,{ref:S,type:"checkbox",name:p,value:C,checked:r,required:c?void 0:i,disabled:n,form:w})]})});T.displayName="Switch";export{T as Switch,l as SwitchLabel,U as SwitchProvider,f as SwitchThumb,s as useSwitchContext};

package/dist/switch/SwitchAnatomy.d.cts

@@ -0,0 +1,10 @@
+/**
+ * The anatomy a {@link Switch} draws when given no children: a Thumb, always,
+ * plus a Label on the side `labelPosition` names when `label` is given.
+ *
+ * @internal
+ */
+export declare function SwitchAnatomy({ label, labelPosition, }: {
+    label?: string;
+    labelPosition: 'start' | 'end';
+}): import("react").JSX.Element;

package/dist/switch/SwitchAnatomy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The anatomy a {@link Switch} draws when given no children: a Thumb, always,
+ * plus a Label on the side `labelPosition` names when `label` is given.
+ *
+ * @internal
+ */
+export declare function SwitchAnatomy({ label, labelPosition, }: {
+    label?: string;
+    labelPosition: 'start' | 'end';
+}): import("react").JSX.Element;

package/dist/switch/SwitchLabel.d.cts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import type { SwitchLabelProps } from './types.cjs';
+/**
+ * The visible text inside a {@link Switch}. Renders
+ * `<span data-state data-disabled>` carrying `skdx-switch__label`.
+ *
+ * It is a child of the switch's own `<button>`, not a sibling — the root *is*
+ * the track, so unlike Checkbox (whose label sits next to a small box) there is
+ * nowhere else for it to live. That also means it names the control:
+ * `role="switch"` takes its accessible name from content, so a `SwitchLabel` is
+ * the naming mechanism, and a switch whose only child is a {@link SwitchThumb}
+ * needs an `aria-label` instead.
+ *
+ * The class it emits is load-bearing. `packages/skins/src/components/switch.css`
+ * switches the labelled layout on `:has(.skdx-switch__label)`: it moves the
+ * track to a `::before` pill so the label sits *beside* the track rather than
+ * inside a fixed 32px box, which keeps the thumb — a flex item with no content
+ * of its own — from collapsing to nothing.
+ *
+ * @example
+ * ```tsx
+ * <Switch defaultChecked>
+ *   <SwitchThumb />
+ *   <SwitchLabel>Airplane mode</SwitchLabel>
+ * </Switch>
+ * ```
+ */
+export declare const SwitchLabel: React.ForwardRefExoticComponent<Omit<SwitchLabelProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/switch/SwitchLabel.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import type { SwitchLabelProps } from './types.js';
+/**
+ * The visible text inside a {@link Switch}. Renders
+ * `<span data-state data-disabled>` carrying `skdx-switch__label`.
+ *
+ * It is a child of the switch's own `<button>`, not a sibling — the root *is*
+ * the track, so unlike Checkbox (whose label sits next to a small box) there is
+ * nowhere else for it to live. That also means it names the control:
+ * `role="switch"` takes its accessible name from content, so a `SwitchLabel` is
+ * the naming mechanism, and a switch whose only child is a {@link SwitchThumb}
+ * needs an `aria-label` instead.
+ *
+ * The class it emits is load-bearing. `packages/skins/src/components/switch.css`
+ * switches the labelled layout on `:has(.skdx-switch__label)`: it moves the
+ * track to a `::before` pill so the label sits *beside* the track rather than
+ * inside a fixed 32px box, which keeps the thumb — a flex item with no content
+ * of its own — from collapsing to nothing.
+ *
+ * @example
+ * ```tsx
+ * <Switch defaultChecked>
+ *   <SwitchThumb />
+ *   <SwitchLabel>Airplane mode</SwitchLabel>
+ * </Switch>
+ * ```
+ */
+export declare const SwitchLabel: React.ForwardRefExoticComponent<Omit<SwitchLabelProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/switch/SwitchThumb.d.cts

@@ -1,14 +1,14 @@
 import * as React from 'react';
 import type { SwitchThumbProps } from './types.cjs';
 /**
- * The sliding handle inside a {@link Switch}, positioned by CSS off of its
- * `data-state`. Renders `<span data-state data-disabled>` mirroring the
- * parent switch's state.
+ * The sliding handle inside a {@link Switch}, positioned by CSS via `data-state`.
+ * Renders nothing to the accessible name; pair with a label or `aria-label`.
  *
  * @example
  * ```tsx
  * <Switch defaultChecked>
  *   <SwitchThumb />
+ *   Airplane mode
  * </Switch>
  * ```
  */

package/dist/switch/SwitchThumb.d.ts

@@ -1,14 +1,14 @@
 import * as React from 'react';
 import type { SwitchThumbProps } from './types.js';
 /**
- * The sliding handle inside a {@link Switch}, positioned by CSS off of its
- * `data-state`. Renders `<span data-state data-disabled>` mirroring the
- * parent switch's state.
+ * The sliding handle inside a {@link Switch}, positioned by CSS via `data-state`.
+ * Renders nothing to the accessible name; pair with a label or `aria-label`.
  *
  * @example
  * ```tsx
  * <Switch defaultChecked>
  *   <SwitchThumb />
+ *   Airplane mode
  * </Switch>
  * ```
  */

package/dist/switch/index.d.cts

@@ -1,3 +1,2 @@
-export * from './Switch.cjs';
-export { SwitchThumb } from './SwitchThumb.cjs';
-export type { SwitchProps, SwitchThumbProps } from './types.cjs';
+export { Switch } from './Switch.cjs';
+export type { SwitchHandle, SwitchProps } from './types.cjs';

package/dist/switch/index.d.ts

@@ -1,3 +1,2 @@
-export * from './Switch.js';
-export { SwitchThumb } from './SwitchThumb.js';
-export type { SwitchProps, SwitchThumbProps } from './types.js';
+export { Switch } from './Switch.js';
+export type { SwitchHandle, SwitchProps } from './types.js';

package/dist/switch/primitives.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Advanced primitives for `Switch` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { Switch, SwitchLabel, SwitchThumb } from '@skdx/react/primitives/switch';
+ *
+ * <Switch defaultChecked>
+ *   <SwitchThumb />
+ *   <SwitchLabel>Airplane mode</SwitchLabel>
+ * </Switch>
+ * ```
+ */
+export { Switch } from './Switch.cjs';
+export { SwitchLabel } from './SwitchLabel.cjs';
+export { SwitchThumb } from './SwitchThumb.cjs';
+export type { SwitchProps, SwitchHandle, SwitchLabelProps, SwitchThumbProps } from './types.cjs';

package/dist/switch/primitives.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Advanced primitives for `Switch` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { Switch, SwitchLabel, SwitchThumb } from '@skdx/react/primitives/switch';
+ *
+ * <Switch defaultChecked>
+ *   <SwitchThumb />
+ *   <SwitchLabel>Airplane mode</SwitchLabel>
+ * </Switch>
+ * ```
+ */
+export { Switch } from './Switch.js';
+export { SwitchLabel } from './SwitchLabel.js';
+export { SwitchThumb } from './SwitchThumb.js';
+export type { SwitchProps, SwitchHandle, SwitchLabelProps, SwitchThumbProps } from './types.js';

package/dist/switch/types.d.cts

@@ -1,4 +1,13 @@
+import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/**
+ * What `Switch`'s forwarded ref actually is: the root `<button>` plus the
+ * constraint-validation methods, which are assigned onto that node rather than
+ * replacing it — so this is additive, and everything an `HTMLButtonElement`
+ * ref already did still works. Type a ref with
+ * `React.useRef<SwitchHandle>(null)`.
+ */
+export type SwitchHandle = HTMLButtonElement & FormValidityHandle;
 /** @internal Shared state distributed from {@link Switch} to its {@link SwitchThumb} via context. Not part of the public API. */
 export interface SwitchContextValue {
     checked: boolean;
@@ -37,11 +46,39 @@ export interface SwitchProps extends Omit<PrimitivePropsWithRef<'button'>, 'defa
      */
     value?: string;
     /**
-     * Marks the switch as invalid, exposed as `aria-invalid`/`data-invalid`.
+     * Displays a state the user may not change. The switch keeps its tab stop, focus ring, `role="switch"`, adds `aria-readonly="true"` and `data-readonly`, and refuses the flip. A read-only switch submits its value.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Marks the switch as invalid, exposed as `aria-invalid`/`data-invalid`. Presentational only. Use `setCustomValidity()` on the ref for errors submission must block on.
      * @default false
      */
     invalid?: boolean;
+    /**
+     * Disables the switch and excludes it from the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The `id` of the `<form>` this switch submits with, for a switch that is not a DOM descendant of it. Mirrors the native `form` attribute onto the hidden input.
+     * @default undefined — the nearest ancestor `<form>`, as for a native input.
+     */
+    form?: string;
+    /**
+     * Visible caption, rendered into a derived `SwitchLabel` inside the button — the accessible name, since `role="switch"` takes its name from content. Ignored when `children` is given.
+     * @default undefined — no label rendered.
+     */
+    label?: string;
+    /**
+     * Which side of the derived `SwitchThumb` the derived `SwitchLabel` sits on. Only meaningful with `label`. Ignored when `children` is given.
+     * @default 'end'
+     */
+    labelPosition?: 'start' | 'end';
 }
 /** Props for the {@link SwitchThumb}, the sliding handle inside a {@link Switch}. */
 export interface SwitchThumbProps extends PrimitivePropsWithRef<'span'> {
 }
+/** Props for the {@link SwitchLabel}, the switch's visible text. */
+export interface SwitchLabelProps extends PrimitivePropsWithRef<'span'> {
+}

package/dist/switch/types.d.ts

@@ -1,4 +1,13 @@
+import type { FormValidityHandle } from '../utils/formControl.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/**
+ * What `Switch`'s forwarded ref actually is: the root `<button>` plus the
+ * constraint-validation methods, which are assigned onto that node rather than
+ * replacing it — so this is additive, and everything an `HTMLButtonElement`
+ * ref already did still works. Type a ref with
+ * `React.useRef<SwitchHandle>(null)`.
+ */
+export type SwitchHandle = HTMLButtonElement & FormValidityHandle;
 /** @internal Shared state distributed from {@link Switch} to its {@link SwitchThumb} via context. Not part of the public API. */
 export interface SwitchContextValue {
     checked: boolean;
@@ -37,11 +46,39 @@ export interface SwitchProps extends Omit<PrimitivePropsWithRef<'button'>, 'defa
      */
     value?: string;
     /**
-     * Marks the switch as invalid, exposed as `aria-invalid`/`data-invalid`.
+     * Displays a state the user may not change. The switch keeps its tab stop, focus ring, `role="switch"`, adds `aria-readonly="true"` and `data-readonly`, and refuses the flip. A read-only switch submits its value.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Marks the switch as invalid, exposed as `aria-invalid`/`data-invalid`. Presentational only. Use `setCustomValidity()` on the ref for errors submission must block on.
      * @default false
      */
     invalid?: boolean;
+    /**
+     * Disables the switch and excludes it from the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The `id` of the `<form>` this switch submits with, for a switch that is not a DOM descendant of it. Mirrors the native `form` attribute onto the hidden input.
+     * @default undefined — the nearest ancestor `<form>`, as for a native input.
+     */
+    form?: string;
+    /**
+     * Visible caption, rendered into a derived `SwitchLabel` inside the button — the accessible name, since `role="switch"` takes its name from content. Ignored when `children` is given.
+     * @default undefined — no label rendered.
+     */
+    label?: string;
+    /**
+     * Which side of the derived `SwitchThumb` the derived `SwitchLabel` sits on. Only meaningful with `label`. Ignored when `children` is given.
+     * @default 'end'
+     */
+    labelPosition?: 'start' | 'end';
 }
 /** Props for the {@link SwitchThumb}, the sliding handle inside a {@link Switch}. */
 export interface SwitchThumbProps extends PrimitivePropsWithRef<'span'> {
 }
+/** Props for the {@link SwitchLabel}, the switch's visible text. */
+export interface SwitchLabelProps extends PrimitivePropsWithRef<'span'> {
+}