@skdx/react 0.26.0 → 0.28.0

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

@@ -1,32 +1,81 @@
+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';
+/**
+ * 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'> {

package/dist/rating/Rating.cjs

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

package/dist/rating/Rating.d.cts

@@ -7,37 +7,26 @@ export declare const RatingProvider: {
     displayName: string;
 }, 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.
+ * Root of a rating widget (e.g. stars): owns selected value and hover-preview state,
+ * hands them down to `RatingItem`s via context. Renders `role="radiogroup"` `<div>` with
+ * `aria-disabled`/`aria-readonly` and `data-disabled`. Arrow-key navigation roves focus
+ * (horizontal, no wrap); 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.
+ * Hover preview is display-only: drives `data-highlighted`/`data-half` and `onHoverValueChange`,
+ * never touches committed `value` (same preview/commit split as `Slider`).
  *
- * 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}.
+ * With `allowHalf`, root becomes `role="slider"`: half-star values can't be told by radios,
+ * so root takes tab stop and reports `aria-valuenow`; items become purely visual.
  *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * Root takes no name from content (give it `aria-label`); each item named from {@link RatingProps.itemLabel}.
  *
- * 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`.
+ * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * With `name`, visually-hidden native input submits rating as `String(value)`, form reset restores `defaultValue`.
+ * Given no `children`, draws `max` derived `RatingItem`s holding `icon`.
  *
  * @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>>;

package/dist/rating/Rating.d.ts

@@ -7,37 +7,26 @@ export declare const RatingProvider: {
     displayName: string;
 }, 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.
+ * Root of a rating widget (e.g. stars): owns selected value and hover-preview state,
+ * hands them down to `RatingItem`s via context. Renders `role="radiogroup"` `<div>` with
+ * `aria-disabled`/`aria-readonly` and `data-disabled`. Arrow-key navigation roves focus
+ * (horizontal, no wrap); 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.
+ * Hover preview is display-only: drives `data-highlighted`/`data-half` and `onHoverValueChange`,
+ * never touches committed `value` (same preview/commit split as `Slider`).
  *
- * 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}.
+ * With `allowHalf`, root becomes `role="slider"`: half-star values can't be told by radios,
+ * so root takes tab stop and reports `aria-valuenow`; items become purely visual.
  *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * Root takes no name from content (give it `aria-label`); each item named from {@link RatingProps.itemLabel}.
  *
- * 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`.
+ * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * With `name`, visually-hidden native input submits rating as `String(value)`, form reset restores `defaultValue`.
+ * Given no `children`, draws `max` derived `RatingItem`s holding `icon`.
  *
  * @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>>;

package/dist/rating/Rating.js

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

package/dist/rating/RatingItem.d.cts

@@ -1,18 +1,13 @@
 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.
+ * Single selectable item in a {@link Rating}. Renders `role="radio"` with
+ * `aria-checked`, `data-state`, `data-highlighted` (to hovered item or committed value),
+ * and `data-disabled`. Only checked item (or 1 when unselected) is tab-stop; click/focus/hover selects.
  *
- * 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.
+ * Accessible name from root's `itemLabel` (default `"3 of 5 stars"`). With `allowHalf`,
+ * item is `aria-hidden` with `role="presentation"` (root is `role="slider"`);
+ * still emits `data-highlighted` and `data-half` for half-star styling.
  *
  * @example
  * ```tsx

package/dist/rating/RatingItem.d.ts

@@ -1,18 +1,13 @@
 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.
+ * Single selectable item in a {@link Rating}. Renders `role="radio"` with
+ * `aria-checked`, `data-state`, `data-highlighted` (to hovered item or committed value),
+ * and `data-disabled`. Only checked item (or 1 when unselected) is tab-stop; click/focus/hover selects.
  *
- * 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.
+ * Accessible name from root's `itemLabel` (default `"3 of 5 stars"`). With `allowHalf`,
+ * item is `aria-hidden` with `role="presentation"` (root is `role="slider"`);
+ * still emits `data-highlighted` and `data-half` for half-star styling.
  *
  * @example
  * ```tsx

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,14 +1,41 @@
+import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/**
+ * Payload `onValueChange` receives: new value, previous value, and `reason`
+ * (keyboard/pointer/programmatic). Spelled out since headless packages don't
+ * depend on `@skdx/shared`.
+ */
+export interface RatingValueChangeDetail {
+    /** The rating value the change settled on. */
+    value: number;
+    /**
+     * The value held before the change, or `null` when it was `0` — 0 and
+     * "unrated" are the same state, so there is no real previous rating to
+     * report.
+     */
+    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. Not part of the public API. */
 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. */
@@ -24,15 +51,14 @@ export interface RatingProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChang
      */
     defaultValue?: number;
     /**
-     * Fires with the new value whenever the selected item changes, controlled or not.
+     * Fires when selected value changes (controlled or not), carrying new value,
+     * previous, and reason. Re-picking swallows unless `allowClear` is set.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: number) => void;
+    onValueChange?: (detail: RatingValueChangeDetail) => void;
     /**
-     * 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 previewed value while hovering; never changes committed value.
+     * Purely a display signal for hover visuals.
      * @default undefined — no-op if omitted.
      */
     onHoverValueChange?: (value: number | null) => void;
@@ -42,16 +68,22 @@ export interface RatingProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChang
      */
     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.
+     * Names each item as `aria-label`; items are `role="radio"` and need names
+     * to announce properly. Default: "X of Y stars". Item-level `aria-label`
+     * overrides for named scales.
+     * @default (value, max) => `${value} of ${max} stars`
+     */
+    itemLabel?: (value: number, max: number) => string;
+    /**
+     * Clear committed value to `0` by picking it again; off by default.
+     * With `allowHalf`, exact half-value must match to clear.
+     * @default false
+     */
+    allowClear?: boolean;
+    /**
+     * Allow half-item values; pointer picks leading half, keyboard steps by 0.5.
+     * Switches root to `role="slider"` with single tab stop; items become
+     * non-focusable `role="presentation"`. Give root `aria-label`.
      * @default false
      */
     allowHalf?: boolean;
@@ -66,10 +98,8 @@ export interface RatingProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChang
      */
     readOnly?: boolean;
     /**
-     * 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, hidden input submits rating as `String(value)`.
+     * Rating of `0` submits empty entry. Form reset restores `defaultValue`.
      * @default undefined — submits nothing.
      */
     name?: string;
@@ -79,15 +109,31 @@ export interface RatingProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChang
      * @default false
      */
     required?: boolean;
+    /**
+     * Form ID for this rating when rendered outside it (e.g., in a Dialog portal).
+     * Set on hidden input; used to resolve form resets.
+     * @default undefined — the rating belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string;
+    /**
+     * Content inside each derived `RatingItem`, replacing the default star glyph.
+     * Ignored when `children` is given.
+     * @default undefined — the default star glyph.
+     */
+    icon?: React.ReactNode;
 }
 /**
- * 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>` plus FormValidityHandle constraint-validation methods.
+ * Type your ref as this to call them.
  */
 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;
 }