@skdx/react 0.27.0 → 0.29.0

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

@@ -1,75 +1,140 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { Orientation } from '../utils/useRovingFocus.js';
-/** @internal Shared state distributed from {@link RadioGroup} to its {@link RadioGroupItem}s via context. Not part of the public API. */
+/**
+ * Why the selected item changed: keyboard arrow/Home/End, pointer click/tap,
+ * or programmatic value write.
+ */
+export type RadioGroupChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/**
+ * The payload passed to `onValueChange`, carrying the new value, prior value, and reason.
+ */
+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. */
 export interface RadioGroupContextValue {
-    name?: string;
-    value?: string;
+    name?: string | undefined;
+    /** The group's `form` id, forwarded to every item's hidden radio input. */
+    form?: string | undefined;
+    /** `null` is the explicit empty selection; `undefined` only ever means "uncontrolled". */
+    value?: string | null | undefined;
     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, with `defaultValue` redeclared to accept `null`.
+ */
+export interface RadioGroupProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue'> {
+    /**
+     * The radios rendered from data, one derived `RadioGroupItem` each; ignored when `children` is given.
+     * @default undefined — nothing is derived; compose the items as `children`.
+     */
+    options?: RadioGroupOption[] | undefined;
     /**
-     * Selected item's value, for controlled usage. Pair with `onValueChange`.
+     * Selected item's value for controlled usage; `null` is explicit empty selection, `undefined` is uncontrolled.
      * @default undefined — uncontrolled, tracks its own selected value internally.
      */
-    value?: string;
+    value?: string | null | undefined;
     /**
-     * Initially selected item's value, for uncontrolled usage.
+     * Initially selected item's value for uncontrolled usage; `null` and `undefined` both start unselected.
      * @default undefined — no item selected until the user picks one.
      */
-    defaultValue?: string;
+    defaultValue?: string | null | undefined;
     /**
-     * Fires with the new value whenever the selected item changes, controlled or not.
+     * Fires when the selected item changes, with the new value, prior value, and reason; re-selecting emits nothing.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: ((detail: RadioGroupValueChangeDetail) => void) | undefined;
     /**
      * Name for native form participation via a hidden input rendered by each item.
      * @default undefined — no hidden input rendered.
      */
-    name?: string;
+    name?: string | undefined;
     /**
      * Marks the group as required for native form validation.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | undefined;
+    /**
+     * Id of the `<form>` that owns this group, for one rendered outside it (e.g. in a portal).
+     * @default undefined — the group belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string | undefined;
     /**
      * Disables every item in the group.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
+    /**
+     * Freezes the selection without freezing the group: focus and arrow keys still move, but `value` cannot change.
+     * @default false
+     */
+    readOnly?: boolean | undefined;
     /**
      * Marks the group as invalid, exposed as `aria-invalid`/`data-invalid` on
      * the `role="radiogroup"` root.
      * @default false
      */
-    invalid?: boolean;
+    invalid?: boolean | undefined;
     /**
-     * Layout axis for arrow-key roving focus between items, exposed as
-     * `data-orientation`. `'both'` responds to all four arrow keys.
+     * Layout axis for arrow-key roving focus between items; `'both'` responds to all four arrow keys.
      * @default 'both'
      */
-    orientation?: Orientation;
+    orientation?: Orientation | undefined;
     /**
      * Whether arrow-key navigation wraps from the last item back to the first
      * (and vice versa).
      * @default true
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
 }
-/** @internal Shared state distributed from a {@link RadioGroupItem} to its {@link RadioGroupIndicator} via context. Not part of the public API. */
+/** @internal Shared state distributed from a {@link RadioGroupItem} to its {@link RadioGroupIndicator} via context. */
 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 removes it from the roving order.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+}
 /** 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 | undefined;
 }
 /** Props for a {@link RadioGroupIndicator}, the visual mark shown when its item is checked. */
 export interface RadioGroupIndicatorProps extends PrimitivePropsWithRef<'span'> {
@@ -77,5 +142,5 @@ export interface RadioGroupIndicatorProps extends PrimitivePropsWithRef<'span'>
      * Keep mounted regardless of state (for exit animations).
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }

package/dist/rating/Rating.cjs

@@ -1 +1,2 @@
-"use strict";var Q=Object.create;var w=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var Z=Object.getOwnPropertyNames;var j=Object.getPrototypeOf,ee=Object.prototype.hasOwnProperty;var te=(e,o)=>{for(var n in o)w(e,n,{get:o[n],enumerable:!0})},L=(e,o,n,f)=>{if(o&&typeof o=="object"||typeof o=="function")for(let t of Z(o))!ee.call(e,t)&&t!==n&&w(e,t,{get:()=>o[t],enumerable:!(f=Y(o,t))||f.enumerable});return e};var M=(e,o,n)=>(n=e!=null?Q(j(e)):{},L(o||!e||!e.__esModule?w(n,"default",{value:e,enumerable:!0}):n,e)),ne=e=>L(w({},"__esModule",{value:!0}),e);var ae={};te(ae,{Rating:()=>W,RatingItem:()=>I,RatingProvider:()=>B,useRatingContext:()=>D});module.exports=ne(ae);var u=M(require("react"),1),K=require("../utils/clamp.cjs"),F=require("../utils/createContext.cjs"),C=require("../utils/direction.cjs"),E=require("../utils/formControl.cjs"),A=require("../utils/hiddenInput.cjs"),N=require("../utils/part.cjs"),b=require("../utils/primitive.cjs"),O=require("../utils/useControllableState.cjs"),z=require("../utils/useRovingFocus.cjs"),P=require("react/jsx-runtime"),oe="[data-skdx-rating-item]",[B,D]=(0,F.createSafeContext)("Rating"),W=u.forwardRef(({value:e,defaultValue:o=0,onValueChange:n,onHoverValueChange:f,max:t=5,allowHalf:r=!1,disabled:i=!1,readOnly:l=!1,name:v,required:x=!1,...g},H)=>{let[s=0,R]=(0,O.useControllableState)({prop:e,defaultProp:o,onChange:n}),[k,a]=u.useState(null),c=u.useRef(null),y=u.useRef(null);(0,E.useFormValidityHandle)(H,c,y),(0,E.useFormReset)(c,()=>R(o));let V=(0,C.useDirection)(),_=(0,z.useRovingFocus)({orientation:"horizontal",loop:!1,itemSelector:oe}),S=u.useRef(null),T=u.useCallback(d=>{S.current!==d&&(S.current=d,a(d),f?.(d))},[f]),G=d=>{let h=(0,C.directionalKey)(d.key,c.current,V),p=null;h==="ArrowRight"||h==="ArrowUp"?p=s+.5:h==="ArrowLeft"||h==="ArrowDown"?p=s-.5:h==="Home"?p=0:h==="End"&&(p=t),p!==null&&(d.preventDefault(),R((0,K.clamp)(p,0,t)))},J=r?{role:"slider","aria-valuemin":0,"aria-valuemax":t,"aria-valuenow":s,"aria-valuetext":`${s} out of ${t}`,"aria-orientation":"horizontal",tabIndex:i?-1:0}:{role:"radiogroup"};return(0,P.jsxs)(B,{value:s,max:t,allowHalf:r,disabled:i,readOnly:l,hoverValue:k,onValueChange:R,onHoverValueChange:T,children:[(0,P.jsx)(b.Primitive.div,{...J,"aria-disabled":i||void 0,"aria-readonly":l||void 0,"data-disabled":i?"":void 0,"data-readonly":l?"":void 0,...g,...(0,N.skdxPart)("rating","root",g.className),ref:c,onKeyDown:(0,b.composeEventHandlers)(g.onKeyDown,d=>{i||l||(r?G(d):_(d))}),onPointerLeave:(0,b.composeEventHandlers)(g.onPointerLeave,()=>T(null))}),v&&(0,P.jsx)(A.HiddenInput,{ref:y,type:"text",name:v,value:s>0?String(s):"",required:x,disabled:i})]})});W.displayName="Rating";var $=M(require("react"),1),q=require("../utils/direction.cjs"),U=require("../utils/part.cjs"),m=require("../utils/primitive.cjs");var X=require("react/jsx-runtime"),I=$.forwardRef(({value:e,disabled:o,...n},f)=>{let t=D("RatingItem"),{allowHalf:r}=t,i=t.value===e||r&&t.value===e-.5,l=t.disabled||o||!1,v=t.hoverValue??t.value,x=v>=(r?e-.5:e),g=r&&v===e-.5,H=i||t.value===0&&e===1,s=a=>{l||t.readOnly||t.onValueChange(a)},R=a=>{if(!r)return e;let c=a.currentTarget.getBoundingClientRect();if(!c.width)return e;let y=(a.clientX-c.left)/c.width;return((0,q.resolveDirection)(a.currentTarget)==="rtl"?1-y:y)<=.5?e-.5:e},k=r?{"aria-hidden":!0,tabIndex:-1}:{role:"radio","aria-checked":i,tabIndex:H?0:-1};return(0,X.jsx)(m.Primitive.button,{type:"button",...k,"data-skdx-rating-item":"","data-state":i?"checked":"unchecked","data-highlighted":x?"":void 0,"data-half":g?"":void 0,"data-disabled":l?"":void 0,disabled:l,...n,...(0,U.skdxPart)("rating","item",n.className),ref:f,onClick:(0,m.composeEventHandlers)(n.onClick,a=>s(R(a))),onFocus:(0,m.composeEventHandlers)(n.onFocus,()=>{!r&&!i&&s(e)}),onPointerEnter:(0,m.composeEventHandlers)(n.onPointerEnter,a=>{!l&&!t.readOnly&&t.onHoverValueChange(R(a))}),onPointerMove:(0,m.composeEventHandlers)(n.onPointerMove,a=>{!r||l||t.readOnly||t.onHoverValueChange(R(a))}),onKeyDown:(0,m.composeEventHandlers)(n.onKeyDown,a=>{a.key==="Enter"&&a.preventDefault()})})});I.displayName="RatingItem";0&&(module.exports={Rating,RatingItem,RatingProvider,useRatingContext});
+'use client';
+"use strict";var se=Object.create;var x=Object.defineProperty;var ce=Object.getOwnPropertyDescriptor;var me=Object.getOwnPropertyNames;var fe=Object.getPrototypeOf,de=Object.prototype.hasOwnProperty;var Re=(e,n)=>{for(var r in n)x(e,r,{get:n[r],enumerable:!0})},G=(e,n,r,a)=>{if(n&&typeof n=="object"||typeof n=="function")for(let t of me(n))!de.call(e,t)&&t!==r&&x(e,t,{get:()=>n[t],enumerable:!(a=ce(n,t))||a.enumerable});return e};var W=(e,n,r)=>(r=e!=null?se(fe(e)):{},G(n||!e||!e.__esModule?x(r,"default",{value:e,enumerable:!0}):r,e)),ge=e=>G(x({},"__esModule",{value:!0}),e);var Ve={};Re(Ve,{Rating:()=>T,RatingItem:()=>S,RatingProvider:()=>ne,useRatingContext:()=>M});module.exports=ge(Ve);var u=W(require("react"),1),U=require("../utils/appearance.cjs"),Q=require("../utils/clamp.cjs"),Y=require("../utils/createContext.cjs"),I=require("../utils/direction.cjs"),L=require("../utils/formControl.cjs"),Z=require("../utils/hiddenInput.cjs"),j=require("../utils/part.cjs"),V=require("../utils/primitive.cjs"),ee=require("../utils/useControllableState.cjs"),te=require("../utils/useRovingFocus.cjs");var B=require("../utils/Glyph.cjs");var X=W(require("react"),1),_=require("../utils/direction.cjs"),q=require("../utils/part.cjs"),l=require("../utils/primitive.cjs");var K=require("react/jsx-runtime");function pe(e,n,r,a,t){return e?{role:"presentation"}:{role:"radio","aria-checked":n,"aria-label":t.itemLabel(a,t.max),tabIndex:r?0:-1}}var S=({value:e,disabled:n,ref:r,...a})=>{let t=M("RatingItem"),{allowHalf:s}=t,g=t.value===e||s&&t.value===e-.5,m=t.disabled||n||!1,d=t.hoverValue??t.value,b=d>=(s?e-.5:e),P=s&&d===e-.5,A=g||t.value===0&&e===1,p=X.useRef(!1),D=(o,f)=>{if(!(m||t.readOnly)){if(t.allowClear&&o===t.value){t.onValueChange(0,f);return}t.onValueChange(o,f)}},v=o=>{if(!s)return e;let f=o.currentTarget.getBoundingClientRect();if(!f.width)return e;let C=(o.clientX-f.left)/f.width;return((0,_.resolveDirection)(o.currentTarget)==="rtl"?1-C:C)<=.5?e-.5:e},k={...pe(s,g,A,e,t),"data-skdx-rating-item":"","data-state":g?"checked":"unchecked","data-half":P?"":void 0,"data-highlighted":b?"":void 0,"data-disabled":m?"":void 0,...a,...(0,q.skdxPart)("rating","item",a.className),onClick:(0,l.composeEventHandlers)(a.onClick,o=>D(v(o),"pointer")),onFocus:(0,l.useComposedEventHandlers)(a.onFocus,()=>{let o=p.current?"pointer":"keyboard";p.current=!1,!s&&!g&&D(e,o)}),onPointerDown:(0,l.useComposedEventHandlers)(a.onPointerDown,()=>{p.current=!0}),onPointerEnter:(0,l.composeEventHandlers)(a.onPointerEnter,o=>{!m&&!t.readOnly&&t.onHoverValueChange(v(o))}),onPointerMove:(0,l.composeEventHandlers)(a.onPointerMove,o=>{!s||m||t.readOnly||t.onHoverValueChange(v(o))}),onKeyDown:(0,l.composeEventHandlers)(a.onKeyDown,o=>{o.key==="Enter"&&o.preventDefault()})};return s?(0,K.jsx)(l.Primitive.span,{...k,ref:r}):(0,K.jsx)(l.Primitive.button,{type:"button",disabled:m,...k,ref:r})};S.displayName="RatingItem";var R=require("react/jsx-runtime");function he(){return(0,R.jsx)(B.Glyph,{name:"star"})}function J({max:e,icon:n}){return(0,R.jsx)(R.Fragment,{children:Array.from({length:e},(r,a)=>(0,R.jsx)(S,{value:a+1,children:n??(0,R.jsx)(he,{})},a))})}var y=require("react/jsx-runtime"),ye="[data-skdx-rating-item]",be=(e,n)=>`${e} of ${n} stars`,[ne,M]=(0,Y.createSafeContext)("Rating");function ve(e,n,r,a){return e?{role:"slider","aria-valuemin":0,"aria-valuemax":n,"aria-valuenow":r,"aria-valuetext":`${r} out of ${n}`,"aria-orientation":"horizontal",tabIndex:a?-1:0}:{role:"radiogroup"}}function Ce(e,n){return{"aria-disabled":e||void 0,"aria-readonly":n||void 0,"data-disabled":e?"":void 0,"data-readonly":n?"":void 0}}var T=({value:e,defaultValue:n=0,onValueChange:r,onHoverValueChange:a,max:t=5,itemLabel:s=be,allowClear:g=!1,allowHalf:m=!1,disabled:d=!1,readOnly:b=!1,name:P,required:A=!1,form:p,icon:D,children:v,ref:F,size:k,...o})=>{let f=u.useRef("programmatic"),C=u.useRef(null),[c=0,N]=(0,ee.useControllableState)({prop:e,defaultProp:n,onChange:i=>r?.({value:i,previousValue:C.current,reason:f.current})}),E=u.useCallback((i,h)=>{f.current=h,C.current=c===0?null:c,N(i)},[c,N]),[oe,ae]=u.useState(null),w=u.useRef(null),O=u.useRef(null);(0,L.useFormValidityHandle)(F,w,O),(0,L.useFormReset)(w,()=>E(n,"programmatic"),p);let re=(0,I.useDirection)(),ie=(0,te.useRovingFocus)({orientation:"horizontal",loop:!1,itemSelector:ye}),$=u.useRef(null),z=u.useCallback(i=>{$.current!==i&&($.current=i,ae(i),a?.(i))},[a]),le=i=>{let h=(0,I.directionalKey)(i.key,w.current,re),H=null;h==="ArrowRight"||h==="ArrowUp"?H=c+.5:(h==="ArrowLeft"||h==="ArrowDown")&&(H=c-.5),H!==null&&(i.preventDefault(),E((0,Q.clamp)(H,0,t),"keyboard"))},ue=ve(m,t,c,d);return(0,y.jsxs)(ne,{value:c,max:t,itemLabel:s,allowClear:g,allowHalf:m,disabled:d,readOnly:b,hoverValue:oe,onValueChange:E,onHoverValueChange:z,children:[(0,y.jsx)(V.Primitive.div,{...ue,...Ce(d,b),...o,...(0,U.appearanceAttrs)({size:k},o),...(0,j.skdxPart)("rating","root",o.className),ref:w,onKeyDown:(0,V.useComposedEventHandlers)(o.onKeyDown,i=>{if(!(d||b)){if(i.key==="Home"||i.key==="End"){i.preventDefault(),E(i.key==="Home"?0:t,"keyboard");return}m?le(i):ie(i)}}),onPointerLeave:(0,V.useComposedEventHandlers)(o.onPointerLeave,()=>z(null)),children:v??(0,y.jsx)(J,{max:t,icon:D})}),P?(0,y.jsx)(Z.HiddenInput,{ref:O,type:"text",name:P,form:p,value:c>0?String(c):"",required:A,disabled:d}):null]})};T.displayName="Rating";0&&(module.exports={Rating,RatingItem,RatingProvider,useRatingContext});

package/dist/rating/Rating.d.cts

@@ -1,43 +1,20 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.cjs';
 import type { RatingContextValue, RatingProps } from './types.cjs';
-export declare const RatingProvider: {
-    (props: RatingContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useRatingContext: (consumerName: string) => RatingContextValue;
+export declare const RatingProvider: React.FC<RatingContextValue & {
+    children: React.ReactNode;
+}>, useRatingContext: (consumerName: string) => RatingContextValue;
 /**
- * Root of a rating widget (e.g. stars): owns the selected value and
- * hover-preview state, and hands them down to `RatingItem`s via context.
- * Renders a `role="radiogroup"` `<div>` with `aria-disabled`/`aria-readonly`
- * and `data-disabled`. Arrow-key navigation roves focus between items
- * (horizontal, no wrap), and hover state resets on pointer leave.
- *
- * The hover preview is display-only: it drives `data-highlighted`/`data-half`
- * and the `onHoverValueChange` callback, and never touches the committed
- * `value` — same preview/commit split as `Slider`, where dragging paints the
- * track but only pointer-up writes the value.
- *
- * With `allowHalf`, the root becomes a `role="slider"` instead: half-star
- * values cannot be told truthfully by a set of whole-star radios, so the root
- * takes the tab stop and reports `aria-valuenow`, and the items become purely
- * visual. See {@link RatingProps.allowHalf}.
- *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
- *
- * With a `name` a visually-hidden native input submits the rating as
- * `String(value)` (an empty entry while nothing is chosen), a form reset
- * restores `defaultValue`, and the ref carries
- * `checkValidity()`/`reportValidity()` — with `required`, an unrated control
- * reports `valueMissing`.
+ * Root of a rating widget (e.g. stars) that manages selected value, hover preview, and keyboard navigation.
  *
  * @example
  * ```tsx
- * <Rating defaultValue={3} max={5}>
- *   {Array.from({ length: 5 }, (_, i) => (
- *     <RatingItem key={i} value={i + 1} />
- *   ))}
- * </Rating>
+ * <Rating defaultValue={3} max={5} />
  * ```
  */
-export declare const Rating: React.ForwardRefExoticComponent<Omit<RatingProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const Rating: {
+    ({ value: valueProp, defaultValue, onValueChange, onHoverValueChange, max, itemLabel, allowClear, allowHalf, disabled, readOnly, name, required, form, icon, children, ref: forwardedRef, size, ...props }: Omit<RatingProps, "ref"> & {
+        ref?: React.Ref<HTMLDivElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/rating/Rating.d.ts

@@ -1,43 +1,20 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.js';
 import type { RatingContextValue, RatingProps } from './types.js';
-export declare const RatingProvider: {
-    (props: RatingContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useRatingContext: (consumerName: string) => RatingContextValue;
+export declare const RatingProvider: React.FC<RatingContextValue & {
+    children: React.ReactNode;
+}>, useRatingContext: (consumerName: string) => RatingContextValue;
 /**
- * Root of a rating widget (e.g. stars): owns the selected value and
- * hover-preview state, and hands them down to `RatingItem`s via context.
- * Renders a `role="radiogroup"` `<div>` with `aria-disabled`/`aria-readonly`
- * and `data-disabled`. Arrow-key navigation roves focus between items
- * (horizontal, no wrap), and hover state resets on pointer leave.
- *
- * The hover preview is display-only: it drives `data-highlighted`/`data-half`
- * and the `onHoverValueChange` callback, and never touches the committed
- * `value` — same preview/commit split as `Slider`, where dragging paints the
- * track but only pointer-up writes the value.
- *
- * With `allowHalf`, the root becomes a `role="slider"` instead: half-star
- * values cannot be told truthfully by a set of whole-star radios, so the root
- * takes the tab stop and reports `aria-valuenow`, and the items become purely
- * visual. See {@link RatingProps.allowHalf}.
- *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
- *
- * With a `name` a visually-hidden native input submits the rating as
- * `String(value)` (an empty entry while nothing is chosen), a form reset
- * restores `defaultValue`, and the ref carries
- * `checkValidity()`/`reportValidity()` — with `required`, an unrated control
- * reports `valueMissing`.
+ * Root of a rating widget (e.g. stars) that manages selected value, hover preview, and keyboard navigation.
  *
  * @example
  * ```tsx
- * <Rating defaultValue={3} max={5}>
- *   {Array.from({ length: 5 }, (_, i) => (
- *     <RatingItem key={i} value={i + 1} />
- *   ))}
- * </Rating>
+ * <Rating defaultValue={3} max={5} />
  * ```
  */
-export declare const Rating: React.ForwardRefExoticComponent<Omit<RatingProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const Rating: {
+    ({ value: valueProp, defaultValue, onValueChange, onHoverValueChange, max, itemLabel, allowClear, allowHalf, disabled, readOnly, name, required, form, icon, children, ref: forwardedRef, size, ...props }: Omit<RatingProps, "ref"> & {
+        ref?: React.Ref<HTMLDivElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/rating/Rating.js

@@ -1 +1,2 @@
-import*as s from"react";import{clamp as M}from"../utils/clamp.js";import{createSafeContext as K}from"../utils/createContext.js";import{directionalKey as F,useDirection as A}from"../utils/direction.js";import{useFormReset as N,useFormValidityHandle as O}from"../utils/formControl.js";import{HiddenInput as z}from"../utils/hiddenInput.js";import{skdxPart as B}from"../utils/part.js";import{composeEventHandlers as H,Primitive as W}from"../utils/primitive.js";import{useControllableState as $}from"../utils/useControllableState.js";import{useRovingFocus as q}from"../utils/useRovingFocus.js";import{jsx as k,jsxs as G}from"react/jsx-runtime";var U="[data-skdx-rating-item]",[X,D]=K("Rating"),_=s.forwardRef(({value:n,defaultValue:v=0,onValueChange:d,onHoverValueChange:y,max:e=5,allowHalf:o=!1,disabled:a=!1,readOnly:r=!1,name:g,required:b=!1,...m},P)=>{let[i=0,c]=$({prop:n,defaultProp:v,onChange:d}),[w,t]=s.useState(null),u=s.useRef(null),h=s.useRef(null);O(P,u,h),N(u,()=>c(v));let C=A(),S=q({orientation:"horizontal",loop:!1,itemSelector:U}),E=s.useRef(null),x=s.useCallback(l=>{E.current!==l&&(E.current=l,t(l),y?.(l))},[y]),T=l=>{let f=F(l.key,u.current,C),R=null;f==="ArrowRight"||f==="ArrowUp"?R=i+.5:f==="ArrowLeft"||f==="ArrowDown"?R=i-.5:f==="Home"?R=0:f==="End"&&(R=e),R!==null&&(l.preventDefault(),c(M(R,0,e)))},L=o?{role:"slider","aria-valuemin":0,"aria-valuemax":e,"aria-valuenow":i,"aria-valuetext":`${i} out of ${e}`,"aria-orientation":"horizontal",tabIndex:a?-1:0}:{role:"radiogroup"};return G(X,{value:i,max:e,allowHalf:o,disabled:a,readOnly:r,hoverValue:w,onValueChange:c,onHoverValueChange:x,children:[k(W.div,{...L,"aria-disabled":a||void 0,"aria-readonly":r||void 0,"data-disabled":a?"":void 0,"data-readonly":r?"":void 0,...m,...B("rating","root",m.className),ref:u,onKeyDown:H(m.onKeyDown,l=>{a||r||(o?T(l):S(l))}),onPointerLeave:H(m.onPointerLeave,()=>x(null))}),g&&k(z,{ref:h,type:"text",name:g,value:i>0?String(i):"",required:b,disabled:a})]})});_.displayName="Rating";import*as I from"react";import{resolveDirection as J}from"../utils/direction.js";import{skdxPart as Q}from"../utils/part.js";import{composeEventHandlers as p,Primitive as Y}from"../utils/primitive.js";import{jsx as Z}from"react/jsx-runtime";var V=I.forwardRef(({value:n,disabled:v,...d},y)=>{let e=D("RatingItem"),{allowHalf:o}=e,a=e.value===n||o&&e.value===n-.5,r=e.disabled||v||!1,g=e.hoverValue??e.value,b=g>=(o?n-.5:n),m=o&&g===n-.5,P=a||e.value===0&&n===1,i=t=>{r||e.readOnly||e.onValueChange(t)},c=t=>{if(!o)return n;let u=t.currentTarget.getBoundingClientRect();if(!u.width)return n;let h=(t.clientX-u.left)/u.width;return(J(t.currentTarget)==="rtl"?1-h:h)<=.5?n-.5:n},w=o?{"aria-hidden":!0,tabIndex:-1}:{role:"radio","aria-checked":a,tabIndex:P?0:-1};return Z(Y.button,{type:"button",...w,"data-skdx-rating-item":"","data-state":a?"checked":"unchecked","data-highlighted":b?"":void 0,"data-half":m?"":void 0,"data-disabled":r?"":void 0,disabled:r,...d,...Q("rating","item",d.className),ref:y,onClick:p(d.onClick,t=>i(c(t))),onFocus:p(d.onFocus,()=>{!o&&!a&&i(n)}),onPointerEnter:p(d.onPointerEnter,t=>{!r&&!e.readOnly&&e.onHoverValueChange(c(t))}),onPointerMove:p(d.onPointerMove,t=>{!o||r||e.readOnly||e.onHoverValueChange(c(t))}),onKeyDown:p(d.onKeyDown,t=>{t.key==="Enter"&&t.preventDefault()})})});V.displayName="RatingItem";export{_ as Rating,V as RatingItem,X as RatingProvider,D as useRatingContext};
+'use client';
+import*as i from"react";import{appearanceAttrs as te}from"../utils/appearance.js";import{clamp as ne}from"../utils/clamp.js";import{createSafeContext as oe}from"../utils/createContext.js";import{directionalKey as ae,useDirection as re}from"../utils/direction.js";import{useFormReset as ie,useFormValidityHandle as le}from"../utils/formControl.js";import{HiddenInput as ue}from"../utils/hiddenInput.js";import{skdxPart as se}from"../utils/part.js";import{Primitive as ce,useComposedEventHandlers as z}from"../utils/primitive.js";import{useControllableState as me}from"../utils/useControllableState.js";import{useRovingFocus as fe}from"../utils/useRovingFocus.js";import{Glyph as Z}from"../utils/Glyph.js";import*as N from"react";import{resolveDirection as U}from"../utils/direction.js";import{skdxPart as Q}from"../utils/part.js";import{composeEventHandlers as k,Primitive as M,useComposedEventHandlers as T}from"../utils/primitive.js";import{jsx as F}from"react/jsx-runtime";function Y(t,r,l,o,e){return t?{role:"presentation"}:{role:"radio","aria-checked":r,"aria-label":e.itemLabel(o,e.max),tabIndex:l?0:-1}}var H=({value:t,disabled:r,ref:l,...o})=>{let e=O("RatingItem"),{allowHalf:u}=e,d=e.value===t||u&&e.value===t-.5,c=e.disabled||r||!1,f=e.hoverValue??e.value,p=f>=(u?t-.5:t),b=u&&f===t-.5,w=d||e.value===0&&t===1,R=N.useRef(!1),v=(n,m)=>{if(!(c||e.readOnly)){if(e.allowClear&&n===e.value){e.onValueChange(0,m);return}e.onValueChange(n,m)}},h=n=>{if(!u)return t;let m=n.currentTarget.getBoundingClientRect();if(!m.width)return t;let y=(n.clientX-m.left)/m.width;return(U(n.currentTarget)==="rtl"?1-y:y)<=.5?t-.5:t},C={...Y(u,d,w,t,e),"data-skdx-rating-item":"","data-state":d?"checked":"unchecked","data-half":b?"":void 0,"data-highlighted":p?"":void 0,"data-disabled":c?"":void 0,...o,...Q("rating","item",o.className),onClick:k(o.onClick,n=>v(h(n),"pointer")),onFocus:T(o.onFocus,()=>{let n=R.current?"pointer":"keyboard";R.current=!1,!u&&!d&&v(t,n)}),onPointerDown:T(o.onPointerDown,()=>{R.current=!0}),onPointerEnter:k(o.onPointerEnter,n=>{!c&&!e.readOnly&&e.onHoverValueChange(h(n))}),onPointerMove:k(o.onPointerMove,n=>{!u||c||e.readOnly||e.onHoverValueChange(h(n))}),onKeyDown:k(o.onKeyDown,n=>{n.key==="Enter"&&n.preventDefault()})};return u?F(M.span,{...C,ref:l}):F(M.button,{type:"button",disabled:c,...C,ref:l})};H.displayName="RatingItem";import{Fragment as ee,jsx as E}from"react/jsx-runtime";function j(){return E(Z,{name:"star"})}function $({max:t,icon:r}){return E(ee,{children:Array.from({length:t},(l,o)=>E(H,{value:o+1,children:r??E(j,{})},o))})}import{jsx as x,jsxs as ye}from"react/jsx-runtime";var de="[data-skdx-rating-item]",Re=(t,r)=>`${t} of ${r} stars`,[ge,O]=oe("Rating");function pe(t,r,l,o){return t?{role:"slider","aria-valuemin":0,"aria-valuemax":r,"aria-valuenow":l,"aria-valuetext":`${l} out of ${r}`,"aria-orientation":"horizontal",tabIndex:o?-1:0}:{role:"radiogroup"}}function he(t,r){return{"aria-disabled":t||void 0,"aria-readonly":r||void 0,"data-disabled":t?"":void 0,"data-readonly":r?"":void 0}}var G=({value:t,defaultValue:r=0,onValueChange:l,onHoverValueChange:o,max:e=5,itemLabel:u=Re,allowClear:d=!1,allowHalf:c=!1,disabled:f=!1,readOnly:p=!1,name:b,required:w=!1,form:R,icon:v,children:h,ref:S,size:C,...n})=>{let m=i.useRef("programmatic"),y=i.useRef(null),[s=0,I]=me({prop:t,defaultProp:r,onChange:a=>l?.({value:a,previousValue:y.current,reason:m.current})}),V=i.useCallback((a,g)=>{m.current=g,y.current=s===0?null:s,I(a)},[s,I]),[W,X]=i.useState(null),P=i.useRef(null),L=i.useRef(null);le(S,P,L),ie(P,()=>V(r,"programmatic"),R);let _=re(),q=fe({orientation:"horizontal",loop:!1,itemSelector:de}),A=i.useRef(null),K=i.useCallback(a=>{A.current!==a&&(A.current=a,X(a),o?.(a))},[o]),B=a=>{let g=ae(a.key,P.current,_),D=null;g==="ArrowRight"||g==="ArrowUp"?D=s+.5:(g==="ArrowLeft"||g==="ArrowDown")&&(D=s-.5),D!==null&&(a.preventDefault(),V(ne(D,0,e),"keyboard"))},J=pe(c,e,s,f);return ye(ge,{value:s,max:e,itemLabel:u,allowClear:d,allowHalf:c,disabled:f,readOnly:p,hoverValue:W,onValueChange:V,onHoverValueChange:K,children:[x(ce.div,{...J,...he(f,p),...n,...te({size:C},n),...se("rating","root",n.className),ref:P,onKeyDown:z(n.onKeyDown,a=>{if(!(f||p)){if(a.key==="Home"||a.key==="End"){a.preventDefault(),V(a.key==="Home"?0:e,"keyboard");return}c?B(a):q(a)}}),onPointerLeave:z(n.onPointerLeave,()=>K(null)),children:h??x($,{max:e,icon:v})}),b?x(ue,{ref:L,type:"text",name:b,form:R,value:s>0?String(s):"",required:w,disabled:f}):null]})};G.displayName="Rating";export{G as Rating,H as RatingItem,ge as RatingProvider,O as useRatingContext};

package/dist/rating/RatingAnatomy.d.cts

@@ -0,0 +1,11 @@
+import type * as React from 'react';
+/**
+ * The anatomy a {@link Rating} draws when given no children: `max` derived
+ * `RatingItem`s, each holding `icon` in place of the default star glyph.
+ *
+ * @internal
+ */
+export declare function RatingAnatomy({ max, icon, }: {
+    max: number;
+    icon?: React.ReactNode | undefined;
+}): React.JSX.Element;

package/dist/rating/RatingAnatomy.d.ts

@@ -0,0 +1,11 @@
+import type * as React from 'react';
+/**
+ * The anatomy a {@link Rating} draws when given no children: `max` derived
+ * `RatingItem`s, each holding `icon` in place of the default star glyph.
+ *
+ * @internal
+ */
+export declare function RatingAnatomy({ max, icon, }: {
+    max: number;
+    icon?: React.ReactNode | undefined;
+}): React.JSX.Element;

package/dist/rating/RatingItem.d.cts

@@ -1,18 +1,7 @@
 import * as React from 'react';
 import type { RatingItemProps } from './types.cjs';
 /**
- * A single selectable item (e.g. one star) within a {@link Rating}. Renders
- * `role="radio"` with `aria-checked`, `data-state="checked"|"unchecked"`,
- * `data-highlighted` (set for this item and every one before it, either up
- * to the hovered item or the committed value), and `data-disabled`. Only the
- * checked item (or item 1 when nothing is selected) is a tab stop; clicking,
- * focusing, or hovering (when not disabled/read-only) selects it.
- *
- * When the {@link Rating} root sets `allowHalf` the item is purely visual —
- * `aria-hidden`, out of the tab order, no `role="radio"` — because the root
- * carries the whole widget's semantics as a `role="slider"`. It still emits
- * `data-highlighted` plus `data-half` (present when the effective value lands
- * on this item's leading half) so a brand layer can paint half a star.
+ * Single selectable item in a {@link Rating} that selects on click, focus, or hover.
  *
  * @example
  * ```tsx
@@ -25,4 +14,7 @@ import type { RatingItemProps } from './types.cjs';
  * </Rating>
  * ```
  */
-export declare const RatingItem: React.ForwardRefExoticComponent<Omit<RatingItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const RatingItem: {
+    ({ value, disabled: disabledProp, ref: forwardedRef, ...props }: RatingItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/rating/RatingItem.d.ts

@@ -1,18 +1,7 @@
 import * as React from 'react';
 import type { RatingItemProps } from './types.js';
 /**
- * A single selectable item (e.g. one star) within a {@link Rating}. Renders
- * `role="radio"` with `aria-checked`, `data-state="checked"|"unchecked"`,
- * `data-highlighted` (set for this item and every one before it, either up
- * to the hovered item or the committed value), and `data-disabled`. Only the
- * checked item (or item 1 when nothing is selected) is a tab stop; clicking,
- * focusing, or hovering (when not disabled/read-only) selects it.
- *
- * When the {@link Rating} root sets `allowHalf` the item is purely visual —
- * `aria-hidden`, out of the tab order, no `role="radio"` — because the root
- * carries the whole widget's semantics as a `role="slider"`. It still emits
- * `data-highlighted` plus `data-half` (present when the effective value lands
- * on this item's leading half) so a brand layer can paint half a star.
+ * Single selectable item in a {@link Rating} that selects on click, focus, or hover.
  *
  * @example
  * ```tsx
@@ -25,4 +14,7 @@ import type { RatingItemProps } from './types.js';
  * </Rating>
  * ```
  */
-export declare const RatingItem: React.ForwardRefExoticComponent<Omit<RatingItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const RatingItem: {
+    ({ value, disabled: disabledProp, ref: forwardedRef, ...props }: RatingItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/rating/index.d.cts

@@ -1,3 +1,2 @@
-export * from './Rating.cjs';
-export { RatingItem } from './RatingItem.cjs';
-export type { RatingProps, RatingHandle, RatingItemProps } from './types.cjs';
+export { Rating } from './Rating.cjs';
+export type { RatingProps, RatingHandle, RatingValueChangeDetail } from './types.cjs';

package/dist/rating/index.d.ts

@@ -1,3 +1,2 @@
-export * from './Rating.js';
-export { RatingItem } from './RatingItem.js';
-export type { RatingProps, RatingHandle, RatingItemProps } from './types.js';
+export { Rating } from './Rating.js';
+export type { RatingProps, RatingHandle, RatingValueChangeDetail } from './types.js';

package/dist/rating/primitives.d.cts

@@ -0,0 +1,17 @@
+/**
+ * `Rating` and `RatingItem` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { Rating, RatingItem } from '@skdx/react/primitives/rating';
+ *
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1} />
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export { Rating } from './Rating.cjs';
+export { RatingItem } from './RatingItem.cjs';
+export type { RatingProps, RatingHandle, RatingItemProps, RatingValueChangeDetail } from './types.cjs';

package/dist/rating/primitives.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `Rating` and `RatingItem` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { Rating, RatingItem } from '@skdx/react/primitives/rating';
+ *
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1} />
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export { Rating } from './Rating.js';
+export { RatingItem } from './RatingItem.js';
+export type { RatingProps, RatingHandle, RatingItemProps, RatingValueChangeDetail } from './types.js';

package/dist/rating/types.d.cts

@@ -1,93 +1,128 @@
+import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
-/** @internal Shared state distributed from {@link Rating} to its `RatingItem`s via context. Not part of the public API. */
+/**
+ * Payload passed to `onValueChange`: new value, previous value, and what drove the change.
+ */
+export interface RatingValueChangeDetail {
+    /** The rating value the change settled on. */
+    value: number;
+    /** The value held before the change, or `null` when it was `0` (unrated). */
+    previousValue: number | null;
+    /**
+     * What drove the change: `'keyboard'` for an arrow key, Home/End, or focus
+     * landing on an item; `'pointer'` for a click; `'programmatic'` when the
+     * application set it (a controlled-prop write, an imperative method, or a
+     * form reset).
+     */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+}
+/** @internal Shared state distributed from {@link Rating} to its `RatingItem`s via context. */
 export interface RatingContextValue {
     value: number;
     max: number;
+    /** Whether re-picking the committed value clears the rating to 0. */
+    allowClear: boolean;
     allowHalf: boolean;
     disabled: boolean;
     readOnly: boolean;
     hoverValue: number | null;
-    onValueChange: (value: number) => void;
+    /** Resolved {@link RatingProps.itemLabel} — each item calls it with its own value and the group's `max`. */
+    itemLabel: (value: number, max: number) => string;
+    onValueChange: (value: number, reason: RatingValueChangeDetail['reason']) => void;
     onHoverValueChange: (value: number | null) => void;
 }
 /** Props for the {@link Rating} root. */
 export interface RatingProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
     /**
-     * Current value, for controlled usage. Pair with `onValueChange`.
+     * Current value for controlled usage; pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own value internally.
      */
-    value?: number;
+    value?: number | undefined;
     /**
      * Initial value, for uncontrolled usage, seeding the first render.
      * @default 0 — no items filled until the user picks a rating.
      */
-    defaultValue?: number;
+    defaultValue?: number | undefined;
     /**
-     * Fires with the new value whenever the selected item changes, controlled or not.
+     * Fires when the selected value changes, carrying new value, previous value, and reason.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: number) => void;
+    onValueChange?: ((detail: RatingValueChangeDetail) => void) | undefined;
     /**
-     * Fires with the previewed value while the pointer moves across the items,
-     * and with `null` when the pointer leaves. Purely a display signal — it
-     * never changes the committed `value` — so a consumer can render "3.5" next
-     * to the stars while hovering without touching state.
+     * Fires with the previewed value while hovering; a display-only signal that never touches committed value.
      * @default undefined — no-op if omitted.
      */
-    onHoverValueChange?: (value: number | null) => void;
+    onHoverValueChange?: ((value: number | null) => void) | undefined;
     /**
      * Number of items to render, e.g. stars.
      * @default 5
+     * @min 1
      */
-    max?: number;
-    /**
-     * Allow half-item values (`0.5`, `1`, `1.5`, …). Pointer input picks a half
-     * from the leading half of an item's box (the trailing half under RTL);
-     * keyboard input steps by `0.5` per arrow key, so half values are reachable
-     * without a pointer.
-     *
-     * This changes the widget's ARIA, deliberately: a set of whole-star
-     * `role="radio"` items cannot say "2.5" truthfully, so the root becomes a
-     * `role="slider"` reporting `aria-valuenow`/`aria-valuetext`, takes the
-     * single tab stop, and the items become `aria-hidden` visuals. Give the root
-     * an accessible name (`aria-label`) either way.
+    max?: number | undefined;
+    /**
+     * Names each item as `aria-label`, since a bare icon announces nothing; an item's own `aria-label` overrides it.
+     * @default (value, max) => `${value} of ${max} stars`
+     */
+    itemLabel?: ((value: number, max: number) => string) | undefined;
+    /**
+     * Clears the committed value to `0` when picked again; with `allowHalf`, the exact half-value must match.
      * @default false
      */
-    allowHalf?: boolean;
+    allowClear?: boolean | undefined;
+    /**
+     * Allows half-item values, switching the root to `role="slider"` with items as non-focusable `role="presentation"`.
+     * @default false
+     */
+    allowHalf?: boolean | undefined;
     /**
      * Disables every `RatingItem`, blocking all interaction.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Displays the current value but blocks interaction (still focusable, unlike `disabled`).
      * @default false
      */
-    readOnly?: boolean;
+    readOnly?: boolean | undefined;
     /**
-     * Form field name. With it, a visually-hidden native input submits the
-     * rating as `String(value)`. A rating of `0` — nothing chosen — submits an
-     * empty entry, mirroring `<skdx-rating>`, which publishes `null` there. A
-     * form reset restores `defaultValue`.
+     * Form field name; with it, a hidden input submits the rating as `String(value)`, or empty when `0`.
      * @default undefined — submits nothing.
      */
-    name?: string;
+    name?: string | undefined;
     /**
      * Marks the rating required: with `name`, native `valueMissing` until an
      * item is chosen, reported through `checkValidity()`/`reportValidity()`.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | undefined;
+    /**
+     * Form ID for this rating when rendered outside it, e.g. in a Dialog portal.
+     * @default undefined — the rating belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string | undefined;
+    /**
+     * Content inside each derived `RatingItem`, replacing the default star glyph; ignored when `children` is given.
+     * @default undefined — the default star glyph.
+     */
+    icon?: React.ReactNode | undefined;
+    /**
+     * Size rung the skin scales the stars by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'md' | 'sm' | 'lg' | (string & {}) | undefined;
 }
 /**
- * What {@link Rating}'s forwarded ref carries: the root `<div>` plus the two
- * constraint-validation methods. Type your ref as this to call them —
- * `React.useRef<RatingHandle>(null)`.
+ * Root `<div>` ref augmented with `FormValidityHandle` constraint-validation methods.
  */
 export type RatingHandle = HTMLDivElement & FormValidityHandle;
 /** Props for a single {@link RatingItem}, e.g. one star. */
 export interface RatingItemProps extends PrimitivePropsWithRef<'button'> {
     /** This item's 1-indexed position within the rating scale. */
     value: number;
+    /**
+     * Disables this item, blocking selection and interaction.
+     * @default false
+     */
+    disabled?: boolean | undefined;
 }