@skdx/react 0.26.0 → 0.28.0

package/dist/radio-card/types.d.ts

@@ -1,3 +1,5 @@
+import type * as React from 'react';
+import type { RadioGroupChangeReason } from '../radio-group/types.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 /** @internal Shared state distributed from {@link RadioCard} to its parts via context. Not part of the public API. */
 export interface RadioCardContextValue {
@@ -6,8 +8,17 @@ export interface RadioCardContextValue {
     disabled: boolean;
     /** Roving tabindex: only the checked card — or the first enabled one when nothing is checked — is a tab stop. */
     tabStop: boolean;
+    /**
+     * Whether the group has settled which card holds the tab stop, resolved
+     * after initial render for server-rendered unselected groups.
+     */
+    tabStopResolved: boolean;
     required: boolean;
+    /** The group's `readOnly`: the card keeps its tab stop and refuses the selection. */
+    readOnly: boolean;
     name: string | undefined;
+    /** The group's `form` id, forwarded to this card's hidden radio input. */
+    form: string | undefined;
     labelId: string;
     descriptionId: string;
     /** Whether a `RadioCardLabel` is mounted, so the control only points `aria-labelledby` at an id that exists. */
@@ -16,10 +27,10 @@ export interface RadioCardContextValue {
     hasDescription: boolean;
     setHasLabel: (present: boolean) => void;
     setHasDescription: (present: boolean) => void;
-    onSelect: () => void;
+    onSelect: (reason: RadioGroupChangeReason) => void;
 }
-/** Props for the {@link RadioCard} root, the `<label>` whose whole surface is the hit target. */
-export interface RadioCardProps extends PrimitivePropsWithRef<'label'> {
+/** Props for the {@link RadioCardRoot}, the `<label>` whose whole surface is the hit target. */
+export interface RadioCardRootProps extends PrimitivePropsWithRef<'label'> {
     /** Unique identifier compared against the enclosing `RadioGroup`'s selected `value`. */
     value: string;
     /**
@@ -29,6 +40,26 @@ export interface RadioCardProps extends PrimitivePropsWithRef<'label'> {
      */
     disabled?: boolean;
 }
+/**
+ * Props for the {@link RadioCard} recipe. Renders a label with optional title
+ * and description, with a radio control wired to its value.
+ */
+export interface RadioCardProps extends Omit<RadioCardRootProps, 'asChild'> {
+    /**
+     * The card's title line, rendered into a derived `RadioCardLabel` the control names
+     * itself from with `aria-labelledby`. Ignored when `children` is given,
+     * which switches to full manual composition.
+     * @default undefined — no label is rendered, and the control falls back to the card's whole text content.
+     */
+    label?: React.ReactNode;
+    /**
+     * Supporting copy under the title, rendered into a derived `RadioCardDescription`
+     * joined to the control's `aria-describedby`. Ignored when `children` is
+     * given, which switches to full manual composition.
+     * @default undefined — no description is rendered.
+     */
+    description?: React.ReactNode;
+}
 /** Props for the {@link RadioCardControl}, the real (visually hidden, still focusable) radio input. */
 export interface RadioCardControlProps extends Omit<PrimitivePropsWithRef<'input'>, 'checked' | 'defaultChecked' | 'type' | 'value'> {
 }

package/dist/radio-group/RadioGroup.cjs

@@ -1 +1 @@
-"use strict";var X=Object.create;var c=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var Z=Object.getOwnPropertyNames;var _=Object.getPrototypeOf,$=Object.prototype.hasOwnProperty;var j=(e,r)=>{for(var t in r)c(e,t,{get:r[t],enumerable:!0})},P=(e,r,t,a)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of Z(r))!$.call(e,o)&&o!==t&&c(e,o,{get:()=>r[o],enumerable:!(a=Y(r,o))||a.enumerable});return e};var v=(e,r,t)=>(t=e!=null?X(_(e)):{},P(r||!e||!e.__esModule?c(t,"default",{value:e,enumerable:!0}):t,e)),ee=e=>P(c({},"__esModule",{value:!0}),e);var re={};j(re,{RadioGroup:()=>S,RadioGroupIndicator:()=>y,RadioGroupItem:()=>x,RadioGroupProvider:()=>H,useRadioGroupContext:()=>h});module.exports=ee(re);var n=v(require("react"),1),k=require("../utils/composeRefs.cjs"),C=require("../utils/createContext.cjs"),E=require("../utils/formControl.cjs"),V=require("../utils/part.cjs"),f=require("../utils/primitive.cjs"),T=require("../utils/useControllableState.cjs"),w=require("../utils/useRovingFocus.cjs"),I=require("react/jsx-runtime"),[H,h]=(0,C.createSafeContext)("RadioGroup"),S=n.forwardRef(({value:e,defaultValue:r,onValueChange:t,name:a,required:o=!1,disabled:d=!1,invalid:i=!1,orientation:p="both",loop:u=!0,...s},R)=>{let[b,g]=(0,T.useControllableState)({prop:e,defaultProp:r,onChange:t}),J=(0,w.useRovingFocus)({orientation:p,loop:u,itemSelector:'[role="radio"]'}),G=n.useRef(null),O=(0,k.useComposedRefs)(R,G),[Q,U]=n.useState(null);return(0,E.useFormReset)(G,()=>g(r)),n.useLayoutEffect(()=>{if(b!==void 0)return;let W=G.current?.querySelector('[role="radio"]:not([disabled])');U(W?.getAttribute("data-value")??null)},[b]),(0,I.jsx)(H,{name:a,value:b,required:o,disabled:d,onValueChange:g,firstEnabledValue:Q,children:(0,I.jsx)(f.Primitive.div,{role:"radiogroup","aria-required":o||void 0,"aria-invalid":i?!0:void 0,"data-disabled":d?"":void 0,"data-invalid":i?"":void 0,"data-orientation":p,...s,...(0,V.skdxPart)("radio-group","root",s.className),ref:O,onKeyDown:(0,f.composeEventHandlers)(s.onKeyDown,J)})})});S.displayName="RadioGroup";var D=v(require("react"),1),L=require("../utils/createContext.cjs"),M=require("../utils/hiddenInput.cjs"),N=require("../utils/part.cjs"),l=require("../utils/primitive.cjs"),F=require("../utils/useRovingFocus.cjs");var m=require("react/jsx-runtime"),[oe,K]=(0,L.createSafeContext)("RadioGroupItem"),x=D.forwardRef(({value:e,disabled:r,...t},a)=>{let o=h("RadioGroupItem"),d=o.value===e,i=o.disabled||r||!1,p=d||o.value===void 0&&o.firstEnabledValue===e;return(0,m.jsxs)(oe,{checked:d,disabled:i,children:[(0,m.jsx)(l.Primitive.button,{type:"button",role:"radio","aria-checked":d,"data-state":d?"checked":"unchecked","data-disabled":i?"":void 0,"data-value":e,disabled:i,tabIndex:(0,F.rovingTabIndex)(o.value!==void 0||o.firstEnabledValue!==null,p,i),...t,...(0,N.skdxPart)("radio-group","item",t.className),ref:a,onClick:(0,l.composeEventHandlers)(t.onClick,()=>{d||o.onValueChange(e)}),onFocus:(0,l.composeEventHandlers)(t.onFocus,u=>{let s=u.relatedTarget,R=s?.getAttribute("role")==="radio"&&s.closest('[role="radiogroup"]')===u.currentTarget.closest('[role="radiogroup"]');!d&&R&&o.onValueChange(e)}),onKeyDown:(0,l.composeEventHandlers)(t.onKeyDown,u=>{u.key==="Enter"&&u.preventDefault()})}),o.name&&(0,m.jsx)(M.HiddenInput,{type:"radio",name:o.name,value:e,checked:d,required:o.required,disabled:i})]})});x.displayName="RadioGroupItem";var q=v(require("react"),1),A=require("../utils/part.cjs"),B=require("../utils/primitive.cjs");var z=require("react/jsx-runtime"),y=q.forwardRef(({forceMount:e,...r},t)=>{let a=K("RadioGroupIndicator");return e||a.checked?(0,z.jsx)(B.Primitive.span,{"data-state":a.checked?"checked":"unchecked","data-disabled":a.disabled?"":void 0,...r,...(0,A.skdxPart)("radio-group","indicator",r.className),ref:t}):null});y.displayName="RadioGroupIndicator";0&&(module.exports={RadioGroup,RadioGroupIndicator,RadioGroupItem,RadioGroupProvider,useRadioGroupContext});
+"use strict";var ie=Object.create;var G=Object.defineProperty;var de=Object.getOwnPropertyDescriptor;var ue=Object.getOwnPropertyNames;var le=Object.getPrototypeOf,se=Object.prototype.hasOwnProperty;var pe=(e,o)=>{for(var t in o)G(e,t,{get:o[t],enumerable:!0})},w=(e,o,t,a)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of ue(o))!se.call(e,r)&&r!==t&&G(e,r,{get:()=>o[r],enumerable:!(a=de(o,r))||a.enumerable});return e};var k=(e,o,t)=>(t=e!=null?ie(le(e)):{},w(o||!e||!e.__esModule?G(t,"default",{value:e,enumerable:!0}):t,e)),me=e=>w(G({},"__esModule",{value:!0}),e);var ge={};pe(ge,{RadioGroup:()=>S,RadioGroupIndicator:()=>h,RadioGroupItem:()=>b,RadioGroupProvider:()=>X,RadioItemProvider:()=>q,useRadioGroupContext:()=>v,useRadioItemContext:()=>V});module.exports=me(ge);var n=k(require("react"),1),U=require("../utils/createContext.cjs"),Y=require("../utils/declaredChildren.cjs"),C=require("../utils/formControl.cjs"),J=require("../utils/part.cjs"),E=require("../utils/primitive.cjs"),Q=require("../utils/useControllableState.cjs"),W=require("../utils/useRovingFocus.cjs");var K=k(require("react"),1),O=require("../utils/part.cjs"),_=require("../utils/primitive.cjs");var y=k(require("react"),1),L=require("../utils/createContext.cjs"),M=require("../utils/hiddenInput.cjs"),F=require("../utils/part.cjs"),l=require("../utils/primitive.cjs"),A=require("../utils/useRovingFocus.cjs");var f=require("react/jsx-runtime"),[q,V]=(0,L.createSafeContext)("RadioGroupItem"),b=y.forwardRef(({value:e,disabled:o,...t},a)=>{let r=v("RadioGroupItem"),i=r.value===e,d=r.disabled||o||!1,s=y.useRef(!1),R=i||r.value==null&&r.firstEnabledValue===e;return(0,f.jsxs)(q,{checked:i,disabled:d,children:[(0,f.jsx)(l.Primitive.button,{type:"button",role:"radio","aria-checked":i,"data-state":i?"checked":"unchecked","data-disabled":d?"":void 0,"data-value":e,disabled:d,tabIndex:(0,A.rovingTabIndex)(r.value!=null||r.firstEnabledValue!==null,R,d),...t,...(0,F.skdxPart)("radio-group","item",t.className),ref:a,onClick:(0,l.composeEventHandlers)(t.onClick,()=>{!i&&!r.readOnly&&r.onValueChange(e,"pointer")}),onPointerDown:(0,l.composeEventHandlers)(t.onPointerDown,()=>{s.current=!0}),onBlur:(0,l.composeEventHandlers)(t.onBlur,()=>{s.current=!1}),onFocus:(0,l.composeEventHandlers)(t.onFocus,u=>{if(i||r.readOnly)return;if(s.current){r.onValueChange(e,"pointer");return}let g=u.relatedTarget;g?.getAttribute("role")==="radio"&&g.closest('[role="radiogroup"]')===u.currentTarget.closest('[role="radiogroup"]')&&r.onValueChange(e,"keyboard")}),onKeyDown:(0,l.composeEventHandlers)(t.onKeyDown,u=>{u.key==="Enter"&&u.preventDefault()})}),r.name&&(0,f.jsx)(M.HiddenInput,{type:"radio",name:r.name,value:e,form:r.form,checked:i,required:r.required,disabled:d})]})});b.displayName="RadioGroupItem";var B=require("react/jsx-runtime"),h=K.forwardRef(({forceMount:e,...o},t)=>{let a=V("RadioGroupIndicator");return e||a.checked?(0,B.jsx)(_.Primitive.span,{"data-state":a.checked?"checked":"unchecked","data-disabled":a.disabled?"":void 0,...o,...(0,O.skdxPart)("radio-group","indicator",o.className),ref:t}):null});h.displayName="RadioGroupIndicator";var I=require("react/jsx-runtime");function z({options:e=[]}){return e.map(o=>(0,I.jsxs)(b,{value:o.value,disabled:o.disabled,children:[(0,I.jsx)(h,{}),o.label]},o.value))}var D=require("react/jsx-runtime"),ce='input[type="radio"]',fe=new Set(["RadioGroupItem","RadioCard","RadioCardRoot"]);function Re(e){let o=null;return(0,Y.forEachDeclaredElement)(e,(t,a)=>{o!==null||!fe.has(t??"")||a.disabled===!0||typeof a.value!="string"||(o=a.value)}),o}var[X,v]=(0,U.createSafeContext)("RadioGroup"),S=n.forwardRef(({value:e,defaultValue:o,onValueChange:t,name:a,form:r,required:i=!1,disabled:d=!1,readOnly:s=!1,invalid:R=!1,orientation:u="both",loop:g=!0,options:T,children:Z,...x},$)=>{let H=Z??z({options:T}),P=n.useRef({previousValue:null,reason:"programmatic"}),[m,N]=(0,Q.useControllableState)({prop:e,defaultProp:o,onChange:p=>{p!=null&&t?.({value:p,...P.current})}}),j=(0,W.useRovingFocus)({orientation:u,loop:g,itemSelector:'[role="radio"]'}),c=n.useRef(null),[ee,oe]=n.useState(null),re=ee??Re(H),te=n.useMemo(()=>({get current(){return c.current?.querySelector(ce)??null}}),[]);(0,C.useFormValidityHandle)($,c,te);let ae=(p,ne)=>{P.current={previousValue:m??null,reason:ne},N(p)};return(0,C.useFormReset)(c,()=>{P.current={previousValue:m??null,reason:"programmatic"},N(o)},r),n.useLayoutEffect(()=>{if(m!=null)return;let p=c.current?.querySelector('[role="radio"]:not([disabled])');oe(p?.getAttribute("data-value")??null)},[m]),(0,D.jsx)(X,{name:a,form:r,value:m,required:i,disabled:d,readOnly:s,onValueChange:ae,firstEnabledValue:re,children:(0,D.jsx)(E.Primitive.div,{role:"radiogroup","aria-required":i||void 0,"aria-readonly":s||void 0,"aria-invalid":R?!0:void 0,"data-disabled":d?"":void 0,"data-readonly":s?"":void 0,"data-invalid":R?"":void 0,"data-orientation":u,...x,...(0,J.skdxPart)("radio-group","root",x.className),ref:c,onKeyDown:(0,E.composeEventHandlers)(x.onKeyDown,j),children:H})})});S.displayName="RadioGroup";0&&(module.exports={RadioGroup,RadioGroupIndicator,RadioGroupItem,RadioGroupProvider,RadioItemProvider,useRadioGroupContext,useRadioItemContext});

package/dist/radio-group/RadioGroup.d.cts

@@ -14,19 +14,42 @@ export declare const RadioGroupProvider: {
  * `RadioGroupItem`s (per `orientation`/`loop`) — the currently checked item
  * (or the first enabled one, when none is checked) is the sole tab stop.
  *
+ * The forwarded ref carries `checkValidity()`/`reportValidity()`/
+ * `setCustomValidity()` as well as everything an `HTMLDivElement` ref already
+ * did — type it with {@link RadioGroupHandle}. They live on the *group*, not
+ * the item, because `required` here means "pick one of these", which is a
+ * property of the group and of no single radio. All three delegate to one of
+ * the hidden inputs the items render; with no `name` there are none, nothing is
+ * submitted, the two readable ones report valid and the write is dropped.
+ *
+ * `value` accepts `null` as the explicit empty selection. `undefined` is
+ * reserved for "uncontrolled" — that is how the controlled/uncontrolled
+ * decision is made — so without `null` a controlled group could never be
+ * cleared without remounting it.
+ *
+ * `readOnly` freezes the selection without freezing the group: the roving tab
+ * stop is unchanged, arrow keys still move focus, and neither focus nor click
+ * changes `value`. `aria-readonly` goes on the `radiogroup` root, which
+ * supports it; nothing gains `aria-disabled`.
+ *
+ * Given no `children` it draws the derived anatomy from `options` — one `RadioGroupItem`
+ * per entry, each holding its `RadioGroupIndicator` and its label text. Given children,
+ * they are rendered verbatim for full manual composition, which is also how a
+ * group of `RadioCard`s is built. Only presence is inspected, never what the
+ * children are — reach for `@skdx/react/primitives/radio-group` for the parts.
+ *
  * @example
  * ```tsx
- * <RadioGroup defaultValue="comfortable" name="density">
- *   <RadioGroupItem value="compact">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- *   <RadioGroupItem value="comfortable">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- *   <RadioGroupItem value="spacious">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- * </RadioGroup>
+ * <RadioGroup
+ *   defaultValue="comfortable"
+ *   name="density"
+ *   aria-label="Density"
+ *   options={[
+ *     { value: 'compact', label: 'Compact' },
+ *     { value: 'comfortable', label: 'Comfortable' },
+ *     { value: 'spacious', label: 'Spacious' },
+ *   ]}
+ * />
  * ```
  */
 export declare const RadioGroup: React.ForwardRefExoticComponent<Omit<RadioGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/radio-group/RadioGroup.d.ts

@@ -14,19 +14,42 @@ export declare const RadioGroupProvider: {
  * `RadioGroupItem`s (per `orientation`/`loop`) — the currently checked item
  * (or the first enabled one, when none is checked) is the sole tab stop.
  *
+ * The forwarded ref carries `checkValidity()`/`reportValidity()`/
+ * `setCustomValidity()` as well as everything an `HTMLDivElement` ref already
+ * did — type it with {@link RadioGroupHandle}. They live on the *group*, not
+ * the item, because `required` here means "pick one of these", which is a
+ * property of the group and of no single radio. All three delegate to one of
+ * the hidden inputs the items render; with no `name` there are none, nothing is
+ * submitted, the two readable ones report valid and the write is dropped.
+ *
+ * `value` accepts `null` as the explicit empty selection. `undefined` is
+ * reserved for "uncontrolled" — that is how the controlled/uncontrolled
+ * decision is made — so without `null` a controlled group could never be
+ * cleared without remounting it.
+ *
+ * `readOnly` freezes the selection without freezing the group: the roving tab
+ * stop is unchanged, arrow keys still move focus, and neither focus nor click
+ * changes `value`. `aria-readonly` goes on the `radiogroup` root, which
+ * supports it; nothing gains `aria-disabled`.
+ *
+ * Given no `children` it draws the derived anatomy from `options` — one `RadioGroupItem`
+ * per entry, each holding its `RadioGroupIndicator` and its label text. Given children,
+ * they are rendered verbatim for full manual composition, which is also how a
+ * group of `RadioCard`s is built. Only presence is inspected, never what the
+ * children are — reach for `@skdx/react/primitives/radio-group` for the parts.
+ *
  * @example
  * ```tsx
- * <RadioGroup defaultValue="comfortable" name="density">
- *   <RadioGroupItem value="compact">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- *   <RadioGroupItem value="comfortable">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- *   <RadioGroupItem value="spacious">
- *     <RadioGroupIndicator />
- *   </RadioGroupItem>
- * </RadioGroup>
+ * <RadioGroup
+ *   defaultValue="comfortable"
+ *   name="density"
+ *   aria-label="Density"
+ *   options={[
+ *     { value: 'compact', label: 'Compact' },
+ *     { value: 'comfortable', label: 'Comfortable' },
+ *     { value: 'spacious', label: 'Spacious' },
+ *   ]}
+ * />
  * ```
  */
 export declare const RadioGroup: React.ForwardRefExoticComponent<Omit<RadioGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/radio-group/RadioGroup.js

@@ -1 +1 @@
-import*as d from"react";import{useComposedRefs as T}from"../utils/composeRefs.js";import{createSafeContext as w}from"../utils/createContext.js";import{useFormReset as H}from"../utils/formControl.js";import{skdxPart as S}from"../utils/part.js";import{composeEventHandlers as D,Primitive as L}from"../utils/primitive.js";import{useControllableState as M}from"../utils/useControllableState.js";import{useRovingFocus as N}from"../utils/useRovingFocus.js";import{jsx as b}from"react/jsx-runtime";var[F,G]=w("RadioGroup"),K=d.forwardRef(({value:o,defaultValue:i,onValueChange:t,name:n,required:e=!1,disabled:r=!1,invalid:a=!1,orientation:l="both",loop:u=!0,...s},m)=>{let[p,R]=M({prop:o,defaultProp:i,onChange:t}),P=N({orientation:l,loop:u,itemSelector:'[role="radio"]'}),c=d.useRef(null),k=T(m,c),[C,E]=d.useState(null);return H(c,()=>R(i)),d.useLayoutEffect(()=>{if(p!==void 0)return;let V=c.current?.querySelector('[role="radio"]:not([disabled])');E(V?.getAttribute("data-value")??null)},[p]),b(F,{name:n,value:p,required:e,disabled:r,onValueChange:R,firstEnabledValue:C,children:b(L.div,{role:"radiogroup","aria-required":e||void 0,"aria-invalid":a?!0:void 0,"data-disabled":r?"":void 0,"data-invalid":a?"":void 0,"data-orientation":l,...s,...S("radio-group","root",s.className),ref:k,onKeyDown:D(s.onKeyDown,P)})})});K.displayName="RadioGroup";import*as I from"react";import{createSafeContext as q}from"../utils/createContext.js";import{HiddenInput as A}from"../utils/hiddenInput.js";import{skdxPart as B}from"../utils/part.js";import{composeEventHandlers as f,Primitive as z}from"../utils/primitive.js";import{rovingTabIndex as J}from"../utils/useRovingFocus.js";import{jsx as v,jsxs as Q}from"react/jsx-runtime";var[O,h]=q("RadioGroupItem"),x=I.forwardRef(({value:o,disabled:i,...t},n)=>{let e=G("RadioGroupItem"),r=e.value===o,a=e.disabled||i||!1,l=r||e.value===void 0&&e.firstEnabledValue===o;return Q(O,{checked:r,disabled:a,children:[v(z.button,{type:"button",role:"radio","aria-checked":r,"data-state":r?"checked":"unchecked","data-disabled":a?"":void 0,"data-value":o,disabled:a,tabIndex:J(e.value!==void 0||e.firstEnabledValue!==null,l,a),...t,...B("radio-group","item",t.className),ref:n,onClick:f(t.onClick,()=>{r||e.onValueChange(o)}),onFocus:f(t.onFocus,u=>{let s=u.relatedTarget,m=s?.getAttribute("role")==="radio"&&s.closest('[role="radiogroup"]')===u.currentTarget.closest('[role="radiogroup"]');!r&&m&&e.onValueChange(o)}),onKeyDown:f(t.onKeyDown,u=>{u.key==="Enter"&&u.preventDefault()})}),e.name&&v(A,{type:"radio",name:e.name,value:o,checked:r,required:e.required,disabled:a})]})});x.displayName="RadioGroupItem";import*as y from"react";import{skdxPart as U}from"../utils/part.js";import{Primitive as W}from"../utils/primitive.js";import{jsx as X}from"react/jsx-runtime";var g=y.forwardRef(({forceMount:o,...i},t)=>{let n=h("RadioGroupIndicator");return o||n.checked?X(W.span,{"data-state":n.checked?"checked":"unchecked","data-disabled":n.disabled?"":void 0,...i,...U("radio-group","indicator",i.className),ref:t}):null});g.displayName="RadioGroupIndicator";export{K as RadioGroup,g as RadioGroupIndicator,x as RadioGroupItem,F as RadioGroupProvider,G as useRadioGroupContext};
+import*as n from"react";import{createSafeContext as $}from"../utils/createContext.js";import{forEachDeclaredElement as j}from"../utils/declaredChildren.js";import{useFormReset as ee,useFormValidityHandle as oe}from"../utils/formControl.js";import{skdxPart as re}from"../utils/part.js";import{composeEventHandlers as te,Primitive as ae}from"../utils/primitive.js";import{useControllableState as ne}from"../utils/useControllableState.js";import{useRovingFocus as ie}from"../utils/useRovingFocus.js";import*as k from"react";import{skdxPart as J}from"../utils/part.js";import{Primitive as Q}from"../utils/primitive.js";import*as g from"react";import{createSafeContext as K}from"../utils/createContext.js";import{HiddenInput as O}from"../utils/hiddenInput.js";import{skdxPart as _}from"../utils/part.js";import{composeEventHandlers as c,Primitive as B}from"../utils/primitive.js";import{rovingTabIndex as z}from"../utils/useRovingFocus.js";import{jsx as x,jsxs as Y}from"react/jsx-runtime";var[U,P]=K("RadioGroupItem"),b=g.forwardRef(({value:r,disabled:o,...t},a)=>{let e=v("RadioGroupItem"),i=e.value===r,d=e.disabled||o||!1,l=g.useRef(!1),f=i||e.value==null&&e.firstEnabledValue===r;return Y(U,{checked:i,disabled:d,children:[x(B.button,{type:"button",role:"radio","aria-checked":i,"data-state":i?"checked":"unchecked","data-disabled":d?"":void 0,"data-value":r,disabled:d,tabIndex:z(e.value!=null||e.firstEnabledValue!==null,f,d),...t,..._("radio-group","item",t.className),ref:a,onClick:c(t.onClick,()=>{!i&&!e.readOnly&&e.onValueChange(r,"pointer")}),onPointerDown:c(t.onPointerDown,()=>{l.current=!0}),onBlur:c(t.onBlur,()=>{l.current=!1}),onFocus:c(t.onFocus,u=>{if(i||e.readOnly)return;if(l.current){e.onValueChange(r,"pointer");return}let R=u.relatedTarget;R?.getAttribute("role")==="radio"&&R.closest('[role="radiogroup"]')===u.currentTarget.closest('[role="radiogroup"]')&&e.onValueChange(r,"keyboard")}),onKeyDown:c(t.onKeyDown,u=>{u.key==="Enter"&&u.preventDefault()})}),e.name&&x(O,{type:"radio",name:e.name,value:r,form:e.form,checked:i,required:e.required,disabled:d})]})});b.displayName="RadioGroupItem";import{jsx as W}from"react/jsx-runtime";var h=k.forwardRef(({forceMount:r,...o},t)=>{let a=P("RadioGroupIndicator");return r||a.checked?W(Q.span,{"data-state":a.checked?"checked":"unchecked","data-disabled":a.disabled?"":void 0,...o,...J("radio-group","indicator",o.className),ref:t}):null});h.displayName="RadioGroupIndicator";import{jsx as X,jsxs as Z}from"react/jsx-runtime";function V({options:r=[]}){return r.map(o=>Z(b,{value:o.value,disabled:o.disabled,children:[X(h,{}),o.label]},o.value))}import{jsx as D}from"react/jsx-runtime";var de='input[type="radio"]',ue=new Set(["RadioGroupItem","RadioCard","RadioCardRoot"]);function le(r){let o=null;return j(r,(t,a)=>{o!==null||!ue.has(t??"")||a.disabled===!0||typeof a.value!="string"||(o=a.value)}),o}var[se,v]=$("RadioGroup"),S=n.forwardRef(({value:r,defaultValue:o,onValueChange:t,name:a,form:e,required:i=!1,disabled:d=!1,readOnly:l=!1,invalid:f=!1,orientation:u="both",loop:R=!0,options:I,children:T,...G},H)=>{let C=T??V({options:I}),y=n.useRef({previousValue:null,reason:"programmatic"}),[p,E]=ne({prop:r,defaultProp:o,onChange:s=>{s!=null&&t?.({value:s,...y.current})}}),N=ie({orientation:u,loop:R,itemSelector:'[role="radio"]'}),m=n.useRef(null),[w,L]=n.useState(null),M=w??le(C),F=n.useMemo(()=>({get current(){return m.current?.querySelector(de)??null}}),[]);oe(H,m,F);let A=(s,q)=>{y.current={previousValue:p??null,reason:q},E(s)};return ee(m,()=>{y.current={previousValue:p??null,reason:"programmatic"},E(o)},e),n.useLayoutEffect(()=>{if(p!=null)return;let s=m.current?.querySelector('[role="radio"]:not([disabled])');L(s?.getAttribute("data-value")??null)},[p]),D(se,{name:a,form:e,value:p,required:i,disabled:d,readOnly:l,onValueChange:A,firstEnabledValue:M,children:D(ae.div,{role:"radiogroup","aria-required":i||void 0,"aria-readonly":l||void 0,"aria-invalid":f?!0:void 0,"data-disabled":d?"":void 0,"data-readonly":l?"":void 0,"data-invalid":f?"":void 0,"data-orientation":u,...G,...re("radio-group","root",G.className),ref:m,onKeyDown:te(G.onKeyDown,N),children:C})})});S.displayName="RadioGroup";export{S as RadioGroup,h as RadioGroupIndicator,b as RadioGroupItem,se as RadioGroupProvider,U as RadioItemProvider,v as useRadioGroupContext,P as useRadioItemContext};

package/dist/radio-group/RadioGroupAnatomy.d.cts

@@ -0,0 +1,11 @@
+import type * as React from 'react';
+import type { RadioGroupOption } from './types.cjs';
+/**
+ * The anatomy a {@link RadioGroup} draws from `options`: one `RadioGroupItem` per entry,
+ * holding its `RadioGroupIndicator` and its label text.
+ *
+ * @internal
+ */
+export declare function RadioGroupAnatomy({ options, }: {
+    options?: RadioGroupOption[];
+}): React.ReactNode;

package/dist/radio-group/RadioGroupAnatomy.d.ts

@@ -0,0 +1,11 @@
+import type * as React from 'react';
+import type { RadioGroupOption } from './types.js';
+/**
+ * The anatomy a {@link RadioGroup} draws from `options`: one `RadioGroupItem` per entry,
+ * holding its `RadioGroupIndicator` and its label text.
+ *
+ * @internal
+ */
+export declare function RadioGroupAnatomy({ options, }: {
+    options?: RadioGroupOption[];
+}): React.ReactNode;

package/dist/radio-group/RadioGroupIndicator.d.cts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import type { RadioGroupIndicatorProps } from './types.cjs';
 /**
- * The visual mark (e.g. a dot) shown inside a checked {@link RadioGroupItem}.
- * Renders `<span data-state data-disabled>` mirroring the parent item's
- * state. Unmounts when unchecked unless `forceMount` is set.
+ * Visual mark (e.g. dot) inside a checked {@link RadioGroupItem}, mirroring its state. Unmounts when unchecked unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/radio-group/RadioGroupIndicator.d.ts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import type { RadioGroupIndicatorProps } from './types.js';
 /**
- * The visual mark (e.g. a dot) shown inside a checked {@link RadioGroupItem}.
- * Renders `<span data-state data-disabled>` mirroring the parent item's
- * state. Unmounts when unchecked unless `forceMount` is set.
+ * Visual mark (e.g. dot) inside a checked {@link RadioGroupItem}, mirroring its state. Unmounts when unchecked unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/radio-group/RadioGroupItem.d.cts

@@ -7,14 +7,11 @@ export declare const RadioItemProvider: {
     displayName: string;
 }, useRadioItemContext: (consumerName: string) => RadioItemContextValue;
 /**
- * A single radio button within a {@link RadioGroup}. Renders `role="radio"`
- * with `aria-checked`, `data-state` (`'checked'` / `'unchecked'`),
- * `data-disabled`, and `data-value`. Selects on click, and also selects on
- * focus (matching the WAI-ARIA radio group pattern where arrow-key
- * navigation selects as it moves). Only tabbable when checked, or when
- * nothing in the group is checked and it's the first enabled item. When the
- * group has a `name`, also renders a visually-hidden native
- * `<input type="radio">` for real form submission.
+ * A single radio button within a {@link RadioGroup}. Renders `role="radio"` with
+ * `aria-checked`, `data-state` (`'checked'` / `'unchecked'`), `data-disabled`, and `data-value`.
+ * Selects on click or focus (WAI-ARIA pattern where arrow-key navigation selects as it moves).
+ * Only tabbable when checked or when nothing is checked and it's the first enabled item.
+ * Renders a visually-hidden native `<input type="radio">` for form submission when group has `name`.
  *
  * @example
  * ```tsx

package/dist/radio-group/RadioGroupItem.d.ts

@@ -7,14 +7,11 @@ export declare const RadioItemProvider: {
     displayName: string;
 }, useRadioItemContext: (consumerName: string) => RadioItemContextValue;
 /**
- * A single radio button within a {@link RadioGroup}. Renders `role="radio"`
- * with `aria-checked`, `data-state` (`'checked'` / `'unchecked'`),
- * `data-disabled`, and `data-value`. Selects on click, and also selects on
- * focus (matching the WAI-ARIA radio group pattern where arrow-key
- * navigation selects as it moves). Only tabbable when checked, or when
- * nothing in the group is checked and it's the first enabled item. When the
- * group has a `name`, also renders a visually-hidden native
- * `<input type="radio">` for real form submission.
+ * A single radio button within a {@link RadioGroup}. Renders `role="radio"` with
+ * `aria-checked`, `data-state` (`'checked'` / `'unchecked'`), `data-disabled`, and `data-value`.
+ * Selects on click or focus (WAI-ARIA pattern where arrow-key navigation selects as it moves).
+ * Only tabbable when checked or when nothing is checked and it's the first enabled item.
+ * Renders a visually-hidden native `<input type="radio">` for form submission when group has `name`.
  *
  * @example
  * ```tsx

package/dist/radio-group/index.d.cts

@@ -1,4 +1,2 @@
-export * from './RadioGroup.cjs';
-export { RadioGroupItem } from './RadioGroupItem.cjs';
-export { RadioGroupIndicator } from './RadioGroupIndicator.cjs';
-export type { RadioGroupProps, RadioGroupItemProps, RadioGroupIndicatorProps } from './types.cjs';
+export { RadioGroup, useRadioGroupContext, } from './RadioGroup.cjs';
+export type { RadioGroupProps, RadioGroupOption, RadioGroupHandle, RadioGroupChangeReason, RadioGroupValueChangeDetail, } from './types.cjs';

package/dist/radio-group/index.d.ts

@@ -1,4 +1,2 @@
-export * from './RadioGroup.js';
-export { RadioGroupItem } from './RadioGroupItem.js';
-export { RadioGroupIndicator } from './RadioGroupIndicator.js';
-export type { RadioGroupProps, RadioGroupItemProps, RadioGroupIndicatorProps } from './types.js';
+export { RadioGroup, useRadioGroupContext, } from './RadioGroup.js';
+export type { RadioGroupProps, RadioGroupOption, RadioGroupHandle, RadioGroupChangeReason, RadioGroupValueChangeDetail, } from './types.js';

package/dist/radio-group/primitives.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Advanced primitives for `RadioGroup` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { RadioGroup, RadioGroupIndicator, RadioGroupItem } from '@skdx/react/primitives/radio-group';
+ *
+ * <RadioGroup defaultValue="comfortable" name="density" aria-label="Density">
+ *   <RadioGroupItem value="compact">
+ *     <RadioGroupIndicator />
+ *     Compact
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="comfortable">
+ *     <RadioGroupIndicator />
+ *     Comfortable
+ *   </RadioGroupItem>
+ * </RadioGroup>
+ * ```
+ */
+export { RadioGroup } from './RadioGroup.cjs';
+export { RadioGroupItem } from './RadioGroupItem.cjs';
+export { RadioGroupIndicator } from './RadioGroupIndicator.cjs';
+export type { RadioGroupProps, RadioGroupItemProps, RadioGroupIndicatorProps } from './types.cjs';

package/dist/radio-group/primitives.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Advanced primitives for `RadioGroup` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { RadioGroup, RadioGroupIndicator, RadioGroupItem } from '@skdx/react/primitives/radio-group';
+ *
+ * <RadioGroup defaultValue="comfortable" name="density" aria-label="Density">
+ *   <RadioGroupItem value="compact">
+ *     <RadioGroupIndicator />
+ *     Compact
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="comfortable">
+ *     <RadioGroupIndicator />
+ *     Comfortable
+ *   </RadioGroupItem>
+ * </RadioGroup>
+ * ```
+ */
+export { RadioGroup } from './RadioGroup.js';
+export { RadioGroupItem } from './RadioGroupItem.js';
+export { RadioGroupIndicator } from './RadioGroupIndicator.js';
+export type { RadioGroupProps, RadioGroupItemProps, RadioGroupIndicatorProps } from './types.js';

package/dist/radio-group/types.d.cts

@@ -1,32 +1,81 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { Orientation } from '../utils/useRovingFocus.cjs';
+/**
+ * Why the selected item changed: keyboard arrow/Home/End, pointer click/tap,
+ * or programmatic value write.
+ */
+export type RadioGroupChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/**
+ * The payload `onValueChange` receives, carrying both ends of the change plus
+ * what drove it. `reason` distinguishes keyboard browse from click; `previousValue`
+ * needed because in a controlled group the old value is gone by handler runtime.
+ */
+export interface RadioGroupValueChangeDetail {
+    /** The item that is now selected. */
+    value: string;
+    /** The value selected before this change, or `null` when nothing was. */
+    previousValue: string | null;
+    /**
+     * What drove the change: `'pointer'` for a click, `'keyboard'` for the focus
+     * an arrow key/Home/End moved, `'programmatic'` for a form reset.
+     */
+    reason: RadioGroupChangeReason;
+}
+/**
+ * The forwarded ref's handle: the root `<div>` with constraint-validation
+ * methods assigned on, preserving all HTMLDivElement methods.
+ */
+export type RadioGroupHandle = HTMLDivElement & FormValidityHandle;
 /** @internal Shared state distributed from {@link RadioGroup} to its {@link RadioGroupItem}s via context. Not part of the public API. */
 export interface RadioGroupContextValue {
     name?: string;
-    value?: string;
+    /** The group's `form` id, forwarded to every item's hidden radio input. */
+    form?: string;
+    /** `null` is the explicit empty selection; `undefined` only ever means "uncontrolled". */
+    value?: string | null;
     required: boolean;
     disabled: boolean;
-    onValueChange: (value: string) => void;
+    /** Frozen but not disabled: items keep their tab stop and refuse to change the value. */
+    readOnly: boolean;
+    /** Selects `value` and reports it, tagged with what drove the selection. */
+    onValueChange: (value: string, reason: RadioGroupChangeReason) => void;
     /** Fallback single tab stop when no item is checked yet. */
     firstEnabledValue: string | null;
 }
-/** Props for the {@link RadioGroup} root. */
-export interface RadioGroupProps extends PrimitivePropsWithRef<'div'> {
+/**
+ * Props for the {@link RadioGroup} root. `defaultValue` is redeclared to
+ * accept `null` for explicit empty selection.
+ */
+export interface RadioGroupProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue'> {
+    /**
+     * The radios the group renders, one derived `RadioGroupItem` (with its `RadioGroupIndicator`)
+     * each. Ignored when `children` is given, which switches to full manual
+     * composition.
+     * @default undefined — nothing is derived; compose the items as `children`.
+     */
+    options?: RadioGroupOption[];
     /**
      * Selected item's value, for controlled usage. Pair with `onValueChange`.
+     * `null` means explicit empty selection; `undefined` means uncontrolled.
      * @default undefined — uncontrolled, tracks its own selected value internally.
      */
-    value?: string;
+    value?: string | null;
     /**
-     * Initially selected item's value, for uncontrolled usage.
+     * Initially selected item's value, for uncontrolled usage. `null` and
+     * `undefined` both start with nothing selected; `null` is accepted so the
+     * same expression can feed either this or `value`.
      * @default undefined — no item selected until the user picks one.
      */
-    defaultValue?: string;
+    defaultValue?: string | null;
     /**
-     * Fires with the new value whenever the selected item changes, controlled or not.
+     * Fires whenever the selected item changes, controlled or not, with the new
+     * value, the one it replaced and the reason it changed. Selecting the item
+     * already selected emits nothing.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: (detail: RadioGroupValueChangeDetail) => void;
     /**
      * Name for native form participation via a hidden input rendered by each item.
      * @default undefined — no hidden input rendered.
@@ -37,11 +86,27 @@ export interface RadioGroupProps extends PrimitivePropsWithRef<'div'> {
      * @default false
      */
     required?: boolean;
+    /**
+     * Id of the `<form>` that owns this group, for a group rendered outside it —
+     * inside a `Dialog`'s portal, for instance. Forwarded to every item's hidden
+     * `<input type="radio">`.
+     * @default undefined — the group belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string;
     /**
      * Disables every item in the group.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Freezes the selection without freezing the group: the roving tab stop is
+     * unchanged, arrow keys still move focus between items, but neither focus nor
+     * click changes `value` and `onValueChange` never fires. `aria-readonly` goes
+     * on the `radiogroup` root, which supports it; nothing gains `aria-disabled`,
+     * and the items keep submitting their `name`/`value`.
+     * @default false
+     */
+    readOnly?: boolean;
     /**
      * Marks the group as invalid, exposed as `aria-invalid`/`data-invalid` on
      * the `role="radiogroup"` root.
@@ -66,10 +131,28 @@ export interface RadioItemContextValue {
     checked: boolean;
     disabled: boolean;
 }
+/** One entry of {@link RadioGroupProps.options} — a single radio. */
+export interface RadioGroupOption {
+    /** Unique identifier compared against the group's selected `value`. */
+    value: string;
+    /** Text rendered inside the derived `RadioGroupItem`, which is what names it. */
+    label: React.ReactNode;
+    /**
+     * Prevents this radio from being selected, and takes it out of the roving
+     * order.
+     * @default false
+     */
+    disabled?: boolean;
+}
 /** Props for a single {@link RadioGroupItem}. */
 export interface RadioGroupItemProps extends PrimitivePropsWithRef<'button'> {
     /** Unique identifier compared against the group's selected `value`. */
     value: string;
+    /**
+     * Prevents this radio from being selected; when set, ORs with group's `disabled`.
+     * @default false
+     */
+    disabled?: boolean;
 }
 /** Props for a {@link RadioGroupIndicator}, the visual mark shown when its item is checked. */
 export interface RadioGroupIndicatorProps extends PrimitivePropsWithRef<'span'> {