@skdx/react 0.26.0

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

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import type { RadioGroupContextValue, RadioGroupProps } from './types.js';
+export declare const RadioGroupProvider: {
+    (props: RadioGroupContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useRadioGroupContext: (consumerName: string) => RadioGroupContextValue;
+/**
+ * A single-selection group of radio buttons. Renders `role="radiogroup"`
+ * with `aria-required`, `data-disabled`, `data-orientation`, and
+ * `aria-invalid`/`data-invalid` when `invalid` is set. Manages roving
+ * tabindex and arrow-key/Home/End navigation between child
+ * `RadioGroupItem`s (per `orientation`/`loop`) — the currently checked item
+ * (or the first enabled one, when none is checked) is the sole tab stop.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="comfortable" name="density">
+ *   <RadioGroupItem value="compact">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="comfortable">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="spacious">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ * </RadioGroup>
+ * ```
+ */
+export declare const RadioGroup: React.ForwardRefExoticComponent<Omit<RadioGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/radio-group/RadioGroup.js

@@ -0,0 +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};

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

@@ -0,0 +1,15 @@
+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.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroupItem value="compact">
+ *   <RadioGroupIndicator />
+ * </RadioGroupItem>
+ * ```
+ */
+export declare const RadioGroupIndicator: React.ForwardRefExoticComponent<Omit<RadioGroupIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,15 @@
+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.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroupItem value="compact">
+ *   <RadioGroupIndicator />
+ * </RadioGroupItem>
+ * ```
+ */
+export declare const RadioGroupIndicator: React.ForwardRefExoticComponent<Omit<RadioGroupIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { RadioGroupItemProps, RadioItemContextValue } from './types.cjs';
+export declare const RadioItemProvider: {
+    (props: RadioItemContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    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.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="comfortable" name="density">
+ *   <RadioGroupItem value="compact">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="comfortable">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ * </RadioGroup>
+ * ```
+ */
+export declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioGroupItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

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

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { RadioGroupItemProps, RadioItemContextValue } from './types.js';
+export declare const RadioItemProvider: {
+    (props: RadioItemContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    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.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="comfortable" name="density">
+ *   <RadioGroupItem value="compact">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ *   <RadioGroupItem value="comfortable">
+ *     <RadioGroupIndicator />
+ *   </RadioGroupItem>
+ * </RadioGroup>
+ * ```
+ */
+export declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioGroupItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

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

@@ -0,0 +1,4 @@
+export * 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/index.d.ts

@@ -0,0 +1,4 @@
+export * 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

@@ -0,0 +1,81 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { Orientation } from '../utils/useRovingFocus.cjs';
+/** @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;
+    required: boolean;
+    disabled: boolean;
+    onValueChange: (value: string) => 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'> {
+    /**
+     * Selected item's value, for controlled usage. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own selected value internally.
+     */
+    value?: string;
+    /**
+     * Initially selected item's value, for uncontrolled usage.
+     * @default undefined — no item selected until the user picks one.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new value whenever the selected item changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Name for native form participation via a hidden input rendered by each item.
+     * @default undefined — no hidden input rendered.
+     */
+    name?: string;
+    /**
+     * Marks the group as required for native form validation.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Disables every item in the group.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Marks the group as invalid, exposed as `aria-invalid`/`data-invalid` on
+     * the `role="radiogroup"` root.
+     * @default false
+     */
+    invalid?: boolean;
+    /**
+     * Layout axis for arrow-key roving focus between items, exposed as
+     * `data-orientation`. `'both'` responds to all four arrow keys.
+     * @default 'both'
+     */
+    orientation?: Orientation;
+    /**
+     * Whether arrow-key navigation wraps from the last item back to the first
+     * (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+}
+/** @internal Shared state distributed from a {@link RadioGroupItem} to its {@link RadioGroupIndicator} via context. Not part of the public API. */
+export interface RadioItemContextValue {
+    checked: boolean;
+    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;
+}
+/** Props for a {@link RadioGroupIndicator}, the visual mark shown when its item is checked. */
+export interface RadioGroupIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Keep mounted regardless of state (for exit animations).
+     * @default false
+     */
+    forceMount?: boolean;
+}

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

@@ -0,0 +1,81 @@
+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. */
+export interface RadioGroupContextValue {
+    name?: string;
+    value?: string;
+    required: boolean;
+    disabled: boolean;
+    onValueChange: (value: string) => 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'> {
+    /**
+     * Selected item's value, for controlled usage. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own selected value internally.
+     */
+    value?: string;
+    /**
+     * Initially selected item's value, for uncontrolled usage.
+     * @default undefined — no item selected until the user picks one.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new value whenever the selected item changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Name for native form participation via a hidden input rendered by each item.
+     * @default undefined — no hidden input rendered.
+     */
+    name?: string;
+    /**
+     * Marks the group as required for native form validation.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Disables every item in the group.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Marks the group as invalid, exposed as `aria-invalid`/`data-invalid` on
+     * the `role="radiogroup"` root.
+     * @default false
+     */
+    invalid?: boolean;
+    /**
+     * Layout axis for arrow-key roving focus between items, exposed as
+     * `data-orientation`. `'both'` responds to all four arrow keys.
+     * @default 'both'
+     */
+    orientation?: Orientation;
+    /**
+     * Whether arrow-key navigation wraps from the last item back to the first
+     * (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+}
+/** @internal Shared state distributed from a {@link RadioGroupItem} to its {@link RadioGroupIndicator} via context. Not part of the public API. */
+export interface RadioItemContextValue {
+    checked: boolean;
+    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;
+}
+/** Props for a {@link RadioGroupIndicator}, the visual mark shown when its item is checked. */
+export interface RadioGroupIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Keep mounted regardless of state (for exit animations).
+     * @default false
+     */
+    forceMount?: boolean;
+}

package/dist/rating/Rating.cjs

@@ -0,0 +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});

package/dist/rating/Rating.d.cts

@@ -0,0 +1,43 @@
+import * as React from 'react';
+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;
+/**
+ * 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`.
+ *
+ * @example
+ * ```tsx
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1} />
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export declare const Rating: React.ForwardRefExoticComponent<Omit<RatingProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/rating/Rating.d.ts

@@ -0,0 +1,43 @@
+import * as React from 'react';
+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;
+/**
+ * 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`.
+ *
+ * @example
+ * ```tsx
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1} />
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export declare const Rating: React.ForwardRefExoticComponent<Omit<RatingProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/rating/Rating.js

@@ -0,0 +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};

package/dist/rating/RatingItem.d.cts

@@ -0,0 +1,28 @@
+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.
+ *
+ * @example
+ * ```tsx
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1}>
+ *       <StarIcon />
+ *     </RatingItem>
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export declare const RatingItem: React.ForwardRefExoticComponent<Omit<RatingItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/rating/RatingItem.d.ts

@@ -0,0 +1,28 @@
+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.
+ *
+ * @example
+ * ```tsx
+ * <Rating defaultValue={3} max={5}>
+ *   {Array.from({ length: 5 }, (_, i) => (
+ *     <RatingItem key={i} value={i + 1}>
+ *       <StarIcon />
+ *     </RatingItem>
+ *   ))}
+ * </Rating>
+ * ```
+ */
+export declare const RatingItem: React.ForwardRefExoticComponent<Omit<RatingItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/rating/index.d.cts

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

package/dist/rating/index.d.ts

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

package/dist/rating/types.d.cts

@@ -0,0 +1,93 @@
+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. */
+export interface RatingContextValue {
+    value: number;
+    max: number;
+    allowHalf: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    hoverValue: number | null;
+    onValueChange: (value: number) => 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`.
+     * @default undefined — uncontrolled, tracks its own value internally.
+     */
+    value?: number;
+    /**
+     * Initial value, for uncontrolled usage, seeding the first render.
+     * @default 0 — no items filled until the user picks a rating.
+     */
+    defaultValue?: number;
+    /**
+     * Fires with the new value whenever the selected item changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: number) => 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.
+     * @default undefined — no-op if omitted.
+     */
+    onHoverValueChange?: (value: number | null) => void;
+    /**
+     * Number of items to render, e.g. stars.
+     * @default 5
+     */
+    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.
+     * @default false
+     */
+    allowHalf?: boolean;
+    /**
+     * Disables every `RatingItem`, blocking all interaction.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Displays the current value but blocks interaction (still focusable, unlike `disabled`).
+     * @default false
+     */
+    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`.
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Marks the rating required: with `name`, native `valueMissing` until an
+     * item is chosen, reported through `checkValidity()`/`reportValidity()`.
+     * @default false
+     */
+    required?: boolean;
+}
+/**
+ * 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)`.
+ */
+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;
+}