@skdx/react 0.28.0 → 0.30.0

package/dist/toggle-group/ToggleGroup.d.cts

@@ -1,19 +1,11 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.cjs';
 import type { ToggleGroupContextValue, ToggleGroupProps } from './types.cjs';
-export declare const ToggleGroupProvider: {
-    (props: ToggleGroupContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useToggleGroupContext: (consumerName: string) => ToggleGroupContextValue;
+export declare const ToggleGroupProvider: React.FC<ToggleGroupContextValue & {
+    children: React.ReactNode;
+}>, useToggleGroupContext: (consumerName: string) => ToggleGroupContextValue;
 /**
- * Single or multiple selection toggle group: `role="group"` with roving tabindex
- * and arrow-key/Home/End navigation. Single: only pressed item is tab-stop.
- * Multiple: first pressed item is.
- *
- * Renders derived anatomy from `options` (one item per entry) or manual `children`.
- * With `name`, participates in form submission (one hidden input per pressed value);
- * forwarded ref carries `checkValidity()` / `reportValidity()`.
+ * Single- or multiple-selection toggle group with roving tabindex and arrow-key/Home/End navigation, rendering derived anatomy from `options` or manual `children`; `variant="segmented"` with `selectOnFocus` paints it as one joined strip whose choice follows focus.
  *
  * @example
  * ```tsx
@@ -27,20 +19,25 @@ export declare const ToggleGroupProvider: {
  *     { value: 'right', label: 'Right' },
  *   ]}
  * />
- * ```
  *
- * @example
- * ```tsx
  * <ToggleGroup
- *   type="multiple"
- *   name="format"
- *   required
- *   aria-label="Formatting"
+ *   type="single"
+ *   variant="segmented"
+ *   selectOnFocus
+ *   loop={false}
+ *   deselectable={false}
+ *   defaultValue="week"
+ *   aria-label="Date range"
  *   options={[
- *     { value: 'bold', label: 'B' },
- *     { value: 'italic', label: 'I' },
+ *     { value: 'day', label: 'Day' },
+ *     { value: 'week', label: 'Week' },
  *   ]}
  * />
  * ```
  */
-export declare const ToggleGroup: React.ForwardRefExoticComponent<Omit<ToggleGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const ToggleGroup: {
+    ({ ref: forwardedRef, ...props }: Omit<ToggleGroupProps, "ref"> & {
+        ref?: React.Ref<HTMLDivElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/toggle-group/ToggleGroup.d.ts

@@ -1,19 +1,11 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.js';
 import type { ToggleGroupContextValue, ToggleGroupProps } from './types.js';
-export declare const ToggleGroupProvider: {
-    (props: ToggleGroupContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useToggleGroupContext: (consumerName: string) => ToggleGroupContextValue;
+export declare const ToggleGroupProvider: React.FC<ToggleGroupContextValue & {
+    children: React.ReactNode;
+}>, useToggleGroupContext: (consumerName: string) => ToggleGroupContextValue;
 /**
- * Single or multiple selection toggle group: `role="group"` with roving tabindex
- * and arrow-key/Home/End navigation. Single: only pressed item is tab-stop.
- * Multiple: first pressed item is.
- *
- * Renders derived anatomy from `options` (one item per entry) or manual `children`.
- * With `name`, participates in form submission (one hidden input per pressed value);
- * forwarded ref carries `checkValidity()` / `reportValidity()`.
+ * Single- or multiple-selection toggle group with roving tabindex and arrow-key/Home/End navigation, rendering derived anatomy from `options` or manual `children`; `variant="segmented"` with `selectOnFocus` paints it as one joined strip whose choice follows focus.
  *
  * @example
  * ```tsx
@@ -27,20 +19,25 @@ export declare const ToggleGroupProvider: {
  *     { value: 'right', label: 'Right' },
  *   ]}
  * />
- * ```
  *
- * @example
- * ```tsx
  * <ToggleGroup
- *   type="multiple"
- *   name="format"
- *   required
- *   aria-label="Formatting"
+ *   type="single"
+ *   variant="segmented"
+ *   selectOnFocus
+ *   loop={false}
+ *   deselectable={false}
+ *   defaultValue="week"
+ *   aria-label="Date range"
  *   options={[
- *     { value: 'bold', label: 'B' },
- *     { value: 'italic', label: 'I' },
+ *     { value: 'day', label: 'Day' },
+ *     { value: 'week', label: 'Week' },
  *   ]}
  * />
  * ```
  */
-export declare const ToggleGroup: React.ForwardRefExoticComponent<Omit<ToggleGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const ToggleGroup: {
+    ({ ref: forwardedRef, ...props }: Omit<ToggleGroupProps, "ref"> & {
+        ref?: React.Ref<HTMLDivElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/toggle-group/ToggleGroup.js

@@ -1 +1,2 @@
-import*as l from"react";import{createSafeContext as A}from"../utils/createContext.js";import{useFormValidityHandle as K}from"../utils/formControl.js";import{MirroredValues as _}from"../utils/hiddenInput.js";import{skdxPart as q}from"../utils/part.js";import{composeEventHandlers as z,Primitive as B}from"../utils/primitive.js";import{useRovingFocus as W,useRovingTabStop as E}from"../utils/useRovingFocus.js";import{useSelection as $}from"../utils/useSelection.js";import*as y from"react";import{skdxPart as M}from"../utils/part.js";import{composeEventHandlers as D,Primitive as F}from"../utils/primitive.js";import{rovingTabIndex as L}from"../utils/useRovingFocus.js";import{jsx as O}from"react/jsx-runtime";var m=y.forwardRef(({value:o,disabled:t,...a},p)=>{let e=h("ToggleGroupItem"),n=e.value.includes(o),r=e.disabled||t||!1,g=e.firstEnabledValue===null?n&&!r&&e.value[0]===o:e.firstEnabledValue===o,s=M("toggle-group","item",a.className);return O(F.button,{type:"button","aria-pressed":n,"data-skdx-toggle-group-item":"","data-state":n?"on":"off","data-disabled":r?"":void 0,"data-value":o,disabled:r,tabIndex:L(e.rovingFocus&&(e.firstEnabledValue!==null||e.value.length>0),g,r),...a,...s,className:`skdx-toggle ${s.className}`,ref:p,onClick:D(a.onClick,()=>e.onItemToggle(o))})});m.displayName="ToggleGroupItem";import{Fragment as N,jsx as G}from"react/jsx-runtime";var x=({options:o=[]})=>G(N,{children:o.map(t=>G(m,{value:t.value,disabled:t.disabled,children:t.label},t.value))});import{jsx as c,jsxs as X}from"react/jsx-runtime";var J="[data-skdx-toggle-group-item]:not([disabled])",Q='[data-skdx-toggle-group-item][data-state="on"]:not([disabled])',[U,h]=A("ToggleGroup"),R=l.forwardRef((o,t)=>{let{type:a,value:p,defaultValue:e,onValueChange:n,disabled:r=!1,orientation:g="horizontal",loop:s=!0,deselectable:I=!0,rovingFocus:f=!0,name:P,required:V=!1,form:C,options:S,children:k,...u}=o,{selectedValues:T,selectItem:w}=$({value:p,defaultValue:e,onValueChange:n,multiple:a==="multiple",deselectable:I,label:"ToggleGroup"}),H=W({orientation:"both",loop:s,itemSelector:"[data-skdx-toggle-group-item]"}),i=l.useRef(null),b=l.useRef(null);K(t,i,b);let[d,v]=l.useState(null);return E(i,Q,"data-value",d,v),E(i,J,"data-value",d,v),X(U,{type:a,value:T,disabled:r,rovingFocus:f,onItemToggle:w,firstEnabledValue:d,children:[c(B.div,{role:"group","data-orientation":g,"data-disabled":r?"":void 0,...u,...q("toggle-group","root",u.className),ref:i,onKeyDown:z(u.onKeyDown,f?H:void 0),children:k??c(x,{options:S})}),c(_,{name:P,values:T,required:V,disabled:r,form:C,controlRef:b})]})});R.displayName="ToggleGroup";export{R as ToggleGroup,m as ToggleGroupItem,U as ToggleGroupProvider,h as useToggleGroupContext};
+'use client';
+import*as R from"react";import{appearanceAttrs as ee}from"../utils/appearance.js";import{createSafeContext as te}from"../utils/createContext.js";import{useFormValidityHandle as oe}from"../utils/formControl.js";import{MirroredValues as re}from"../utils/hiddenInput.js";import{skdxPart as ne}from"../utils/part.js";import{composeEventHandlers as le,Primitive as ae}from"../utils/primitive.js";import{useRovingFocus as se,useRovingTabStop as L}from"../utils/useRovingFocus.js";import{useSelection as ie}from"../utils/useSelection.js";import*as c from"react";import{useComposedRefs as q}from"../utils/composeRefs.js";import{skdxPart as z}from"../utils/part.js";import{Primitive as K}from"../utils/primitive.js";import{jsx as _}from"react/jsx-runtime";function W(o,l){let e=o.getBoundingClientRect(),r=l.getBoundingClientRect();return{x:e.left-r.left,y:e.top-r.top,width:e.width,height:e.height}}var E=({ref:o,...l})=>{let{value:e,orientation:r,rootRef:t}=G("ToggleGroupIndicator"),i=e.join("\0"),a=c.useRef(null),g=q(o,a),[s,u]=c.useState(null),p=c.useRef(null);c.useLayoutEffect(()=>{let n=t.current??a.current?.closest('[role="group"]');if(!n)return;let d=n.querySelector('[data-skdx-toggle-group-item][data-state="on"]');if(!d){p.current=null,u(null);return}let b=()=>{let m=W(d,n),v=`${m.x},${m.y},${m.width},${m.height}`;p.current!==v&&(p.current=v,u(m))};if(b(),typeof ResizeObserver>"u")return;let T=new ResizeObserver(b);return T.observe(n),T.observe(d),()=>T.disconnect()},[i,r,t]);let f=s?{"--skdx-toggle-group-x":`${s.x}px`,"--skdx-toggle-group-width":`${s.width}px`,...r==="vertical"&&{"--skdx-toggle-group-y":`${s.y}px`,"--skdx-toggle-group-height":`${s.height}px`}}:{};return _(K.div,{"aria-hidden":"true","data-orientation":r,"data-state":s?"visible":"hidden",...l,...z("toggle-group","indicator",l.className),ref:g,style:{...f,...l.style}})};E.displayName="ToggleGroupIndicator";import*as O from"react";import{skdxPart as J}from"../utils/part.js";import{composeEventHandlers as X,Primitive as Q,useComposedEventHandlers as P}from"../utils/primitive.js";import{rovingTabIndex as U}from"../utils/useRovingFocus.js";import{jsx as Y}from"react/jsx-runtime";var k=({value:o,disabled:l,ref:e,...r})=>{let t=G("ToggleGroupItem"),i=t.value.includes(o),a=t.disabled||l||!1,g=a&&!t.readOnly,s=O.useRef(!1),u=n=>{t.readOnly||a||t.onItemToggle(o,n)},p=t.firstEnabledValue===null?i&&!a&&t.value[0]===o:t.firstEnabledValue===o,f=J("toggle-group","item",r.className);return Y(Q.button,{type:"button","aria-pressed":i,"aria-disabled":a&&t.readOnly?!0:void 0,"data-skdx-toggle-group-item":"","data-state":i?"on":"off","data-disabled":a?"":void 0,"data-value":o,disabled:g,tabIndex:U(t.rovingFocus&&(t.firstEnabledValue!==null||t.value.length>0),p,g),...r,...f,className:`skdx-toggle ${f.className}`,ref:e,onClick:X(r.onClick,n=>u(n.detail===0?"keyboard":"pointer")),onPointerDown:P(r.onPointerDown,()=>{s.current=!0}),onBlur:P(r.onBlur,()=>{s.current=!1}),onFocus:P(r.onFocus,n=>{if(!t.selectOnFocus||a||i||s.current)return;let d=n.relatedTarget;d?.hasAttribute("data-skdx-toggle-group-item")&&d!==n.currentTarget&&u("keyboard")})})};k.displayName="ToggleGroupItem";import{Fragment as Z,jsx as F,jsxs as j}from"react/jsx-runtime";var w=({options:o=[],segmented:l=!1})=>j(Z,{children:[l?F(E,{}):null,o.map(e=>F(k,{value:e.value,disabled:e.disabled,children:e.label},e.value))]});import{jsx as S,jsxs as me}from"react/jsx-runtime";var ue="[data-skdx-toggle-group-item]:not([disabled])",de='[data-skdx-toggle-group-item][data-state="on"]:not([disabled])',[ge,G]=te("ToggleGroup");function pe(o,l,e){return{"data-readonly":o?"":void 0,"data-invalid":l?"":void 0,"data-required":e?"":void 0}}var M=({ref:o,...l})=>{let{type:e,value:r,defaultValue:t,onValueChange:i,disabled:a=!1,readOnly:g=!1,invalid:s=!1,orientation:u="horizontal",loop:p=!0,deselectable:f=!0,rovingFocus:n=!0,selectOnFocus:d=!1,name:b,required:T=!1,form:m,options:v,children:D,variant:I,fullWidth:N,size:$,...x}=l,{selectedValues:C,selectItem:A}=ie({value:r,defaultValue:t,onValueChange:i,multiple:e==="multiple",deselectable:f,label:"ToggleGroup"}),B=se({orientation:"both",loop:p,itemSelector:"[data-skdx-toggle-group-item]"}),y=R.useRef(null),V=R.useRef(null);oe(o,y,V);let[h,H]=R.useState(null);return L(y,de,"data-value",h,H),L(y,ue,"data-value",h,H),me(ge,{type:e,value:C,disabled:a,readOnly:g,selectOnFocus:d,orientation:u,rootRef:y,rovingFocus:n,onItemToggle:A,firstEnabledValue:h,children:[S(ae.div,{role:"group","data-orientation":u,"data-disabled":a?"":void 0,...pe(g,s,T),...x,...ee({variant:I,fullWidth:N,size:$},x),...ne("toggle-group","root",x.className),ref:y,onKeyDown:le(x.onKeyDown,n?B:void 0),children:D??S(w,{options:v,segmented:I==="segmented"})}),S(re,{name:b,values:C,required:T,disabled:a,form:m,controlRef:V})]})};M.displayName="ToggleGroup";export{M as ToggleGroup,E as ToggleGroupIndicator,k as ToggleGroupItem,ge as ToggleGroupProvider,G as useToggleGroupContext};

package/dist/toggle-group/ToggleGroupAnatomy.d.cts

@@ -1,9 +1,11 @@
+import type { JSX } from 'react';
 import type { ToggleGroupOption } from './types.cjs';
 /**
- * The anatomy a {@link ToggleGroup} draws from `options`: one `ToggleGroupItem` per entry.
+ * The anatomy a {@link ToggleGroup} draws from `options`: one `ToggleGroupItem` per entry, preceded by an Indicator when the group is painted as a segmented strip.
  *
  * @internal
  */
-export declare const ToggleGroupAnatomy: ({ options }: {
-    options?: ToggleGroupOption[];
-}) => import("react").JSX.Element;
+export declare const ToggleGroupAnatomy: ({ options, segmented, }: {
+    options?: ToggleGroupOption[] | undefined;
+    segmented?: boolean | undefined;
+}) => JSX.Element;

package/dist/toggle-group/ToggleGroupAnatomy.d.ts

@@ -1,9 +1,11 @@
+import type { JSX } from 'react';
 import type { ToggleGroupOption } from './types.js';
 /**
- * The anatomy a {@link ToggleGroup} draws from `options`: one `ToggleGroupItem` per entry.
+ * The anatomy a {@link ToggleGroup} draws from `options`: one `ToggleGroupItem` per entry, preceded by an Indicator when the group is painted as a segmented strip.
  *
  * @internal
  */
-export declare const ToggleGroupAnatomy: ({ options }: {
-    options?: ToggleGroupOption[];
-}) => import("react").JSX.Element;
+export declare const ToggleGroupAnatomy: ({ options, segmented, }: {
+    options?: ToggleGroupOption[] | undefined;
+    segmented?: boolean | undefined;
+}) => JSX.Element;

package/dist/toggle-group/ToggleGroupIndicator.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { ToggleGroupIndicatorProps } from './types.cjs';
+/**
+ * Decorative highlight that slides behind the pressed item, publishing its geometry as `--skdx-toggle-group-x`/`-y`/`-width`/`-height` for the skin's own transition.
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup type="single" variant="segmented" defaultValue="week" aria-label="Date range">
+ *   <ToggleGroupIndicator />
+ *   <ToggleGroupItem value="day">Day</ToggleGroupItem>
+ *   <ToggleGroupItem value="week">Week</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ */
+export declare const ToggleGroupIndicator: {
+    ({ ref: forwardedRef, ...props }: ToggleGroupIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/toggle-group/ToggleGroupIndicator.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { ToggleGroupIndicatorProps } from './types.js';
+/**
+ * Decorative highlight that slides behind the pressed item, publishing its geometry as `--skdx-toggle-group-x`/`-y`/`-width`/`-height` for the skin's own transition.
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup type="single" variant="segmented" defaultValue="week" aria-label="Date range">
+ *   <ToggleGroupIndicator />
+ *   <ToggleGroupItem value="day">Day</ToggleGroupItem>
+ *   <ToggleGroupItem value="week">Week</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ */
+export declare const ToggleGroupIndicator: {
+    ({ ref: forwardedRef, ...props }: ToggleGroupIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/toggle-group/ToggleGroupItem.d.cts

@@ -1,11 +1,7 @@
 import * as React from 'react';
 import type { ToggleGroupItemProps } from './types.cjs';
 /**
- * A single button within a {@link ToggleGroup}. Renders `<button aria-pressed
- * data-state data-disabled data-value>`. Clicking activates it. Clicking an
- * already-pressed item deactivates it in `'multiple'` mode, and in `'single'`
- * mode too unless the group sets `deselectable={false}` — pressing a
- * *different* item always switches the selection.
+ * A single button within a {@link ToggleGroup}, rendering `<button aria-pressed data-state data-disabled data-value>` and toggling on click per the group's `type` and `deselectable`.
  *
  * @example
  * ```tsx
@@ -15,4 +11,7 @@ import type { ToggleGroupItemProps } from './types.cjs';
  * </ToggleGroup>
  * ```
  */
-export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const ToggleGroupItem: {
+    ({ value, disabled: disabledProp, ref: forwardedRef, ...props }: ToggleGroupItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/toggle-group/ToggleGroupItem.d.ts

@@ -1,11 +1,7 @@
 import * as React from 'react';
 import type { ToggleGroupItemProps } from './types.js';
 /**
- * A single button within a {@link ToggleGroup}. Renders `<button aria-pressed
- * data-state data-disabled data-value>`. Clicking activates it. Clicking an
- * already-pressed item deactivates it in `'multiple'` mode, and in `'single'`
- * mode too unless the group sets `deselectable={false}` — pressing a
- * *different* item always switches the selection.
+ * A single button within a {@link ToggleGroup}, rendering `<button aria-pressed data-state data-disabled data-value>` and toggling on click per the group's `type` and `deselectable`.
  *
  * @example
  * ```tsx
@@ -15,4 +11,7 @@ import type { ToggleGroupItemProps } from './types.js';
  * </ToggleGroup>
  * ```
  */
-export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupItemProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const ToggleGroupItem: {
+    ({ value, disabled: disabledProp, ref: forwardedRef, ...props }: ToggleGroupItemProps): React.ReactNode;
+    displayName: string;
+};

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

@@ -1,10 +1,9 @@
 /**
- * Advanced primitives for `ToggleGroup` — the parts the recipe composes. Use
- * for full manual composition.
+ * Advanced primitives for `ToggleGroup` — the parts the recipe composes, for full manual composition.
  *
  * @example
  * ```tsx
- * import { ToggleGroup, ToggleGroupItem } from '@skdx/react/primitives/toggle-group';
+ * import { ToggleGroup, ToggleGroupIndicator, ToggleGroupItem } from '@skdx/react/primitives/toggle-group';
  *
  * <ToggleGroup type="single" aria-label="Text alignment">
  *   <ToggleGroupItem value="left">
@@ -16,5 +15,6 @@
  * ```
  */
 export { ToggleGroup } from './ToggleGroup.cjs';
+export { ToggleGroupIndicator } from './ToggleGroupIndicator.cjs';
 export { ToggleGroupItem } from './ToggleGroupItem.cjs';
-export type { ToggleGroupProps, ToggleGroupItemProps, ToggleGroupType } from './types.cjs';
+export type { ToggleGroupProps, ToggleGroupIndicatorProps, ToggleGroupItemProps, ToggleGroupType, } from './types.cjs';

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

@@ -1,10 +1,9 @@
 /**
- * Advanced primitives for `ToggleGroup` — the parts the recipe composes. Use
- * for full manual composition.
+ * Advanced primitives for `ToggleGroup` — the parts the recipe composes, for full manual composition.
  *
  * @example
  * ```tsx
- * import { ToggleGroup, ToggleGroupItem } from '@skdx/react/primitives/toggle-group';
+ * import { ToggleGroup, ToggleGroupIndicator, ToggleGroupItem } from '@skdx/react/primitives/toggle-group';
  *
  * <ToggleGroup type="single" aria-label="Text alignment">
  *   <ToggleGroupItem value="left">
@@ -16,5 +15,6 @@
  * ```
  */
 export { ToggleGroup } from './ToggleGroup.js';
+export { ToggleGroupIndicator } from './ToggleGroupIndicator.js';
 export { ToggleGroupItem } from './ToggleGroupItem.js';
-export type { ToggleGroupProps, ToggleGroupItemProps, ToggleGroupType } from './types.js';
+export type { ToggleGroupProps, ToggleGroupIndicatorProps, ToggleGroupItemProps, ToggleGroupType, } from './types.js';

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

@@ -2,28 +2,27 @@ import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { Orientation } from '../utils/useRovingFocus.cjs';
-import type { SelectionChangeDetail } from '../utils/useSelection.cjs';
+import type { SelectionChangeDetail, SelectionChangeReason } from '../utils/useSelection.cjs';
 /** Whether a {@link ToggleGroup} allows one pressed item at a time, or several. */
 export type ToggleGroupType = 'single' | 'multiple';
-/** @internal Shared state distributed from {@link ToggleGroup} to its {@link ToggleGroupItem}s via context. Not part of the public API. */
+/** @internal Shared state distributed from {@link ToggleGroup} to its {@link ToggleGroupItem}s via context. */
 export interface ToggleGroupContextValue {
     type: ToggleGroupType;
     value: string[];
     disabled: boolean;
     /** Whether the group manages one tab stop; `false` makes every enabled item its own. */
     rovingFocus: boolean;
-    /**
-     * Commits one item: presses it, or unpresses it when the group's own
-     * cardinality and `deselectable` allow. The item never branches on either —
-     * both live on the root, which is the only place that can see the whole
-     * selection.
-     */
-    onItemToggle: (value: string) => void;
-    /**
-     * The group's single tab stop, resolved against the DOM by `ToggleGroup`: a
-     * pressed item while one is mounted and enabled, else the first enabled item.
-     * `null` only before that has been resolved, or when every item is disabled.
-     */
+    /** Displays a committed choice: items stay focusable and navigable, but pressing them changes nothing. */
+    readOnly: boolean;
+    /** Whether arrow-key focus moving between siblings also presses the item it lands on. */
+    selectOnFocus: boolean;
+    /** Layout axis the Indicator measures along, deciding which cross-axis custom properties it publishes. */
+    orientation: Orientation;
+    /** The root element, which the Indicator measures the pressed item against. */
+    rootRef: React.RefObject<HTMLDivElement | null>;
+    /** Commits one item: presses it, or unpresses it when the group's cardinality and `deselectable` allow. */
+    onItemToggle: (value: string, reason?: SelectionChangeReason) => void;
+    /** The group's single tab stop, resolved against the DOM: a pressed item if one is enabled, else the first enabled item. */
     firstEnabledValue: string | null;
 }
 /** One entry of {@link ToggleGroupProps.options} — a single toggle button. */
@@ -37,7 +36,7 @@ export interface ToggleGroupOption {
      * order.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
 }
 /** Props for the {@link ToggleGroup} root; `type` picks single- or multiple-item selection. */
 export interface ToggleGroupProps extends PrimitivePropsWithRef<'div'> {
@@ -46,88 +45,100 @@ export interface ToggleGroupProps extends PrimitivePropsWithRef<'div'> {
      * `children` is given, which switches to full manual composition.
      * @default undefined — nothing is derived; compose the items as `children`.
      */
-    options?: ToggleGroupOption[];
+    options?: ToggleGroupOption[] | undefined;
     /**
-     * Whether at most one item may be pressed at a time (`'single'`) or any
-     * number (`'multiple'`). Determines whether `value` takes a bare `string`
-     * or `string[]`, and the shape of `onValueChange` payloads.
+     * Whether at most one item may be pressed at a time (`'single'`) or any number (`'multiple'`), deciding whether `value` takes a `string` or `string[]`.
      */
     type: ToggleGroupType;
     /**
-     * Pressed item's value(s), for controlled usage — a bare `string` or a
-     * `string[]`, whichever reads better at the call site; both are accepted
-     * regardless of cardinality. A `'single'` group given more than one value is
-     * a programming error and throws in a development build. Pair with
-     * `onValueChange`.
+     * Pressed item's value(s), for controlled usage — a `string` or `string[]`, accepted regardless of cardinality; pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own pressed items internally.
      */
-    value?: string | string[];
+    value?: string | string[] | undefined;
     /**
      * Initially pressed item's value(s), for uncontrolled usage — the same bare
      * `string` or `string[]` shapes `value` accepts, under either cardinality.
      * @default undefined — starts with no item pressed.
      */
-    defaultValue?: string | string[];
+    defaultValue?: string | string[] | undefined;
     /**
-     * Fires whenever the pressed items change, controlled or not, carrying the
-     * whole selection as a `string[]` alongside `selectedValue` — the same detail
-     * shape in `'single'` and `'multiple'` alike.
+     * Fires whenever the pressed items change, carrying the whole selection as a `string[]` alongside `selectedValue`.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (detail: SelectionChangeDetail) => void;
+    onValueChange?: ((detail: SelectionChangeDetail) => void) | undefined;
     /**
      * Disables every item in the group.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Layout axis for arrow-key roving focus between items, exposed as
      * `data-orientation`.
      * @default 'horizontal'
      */
-    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;
     /**
-     * Whether a `'single'` group may clear all selections by re-pressing the current item.
-     * Ignored when `type` is `'multiple'`, where items toggle individually.
+     * Whether a `'single'` group may clear all selections by re-pressing the current item; ignored when `type` is `'multiple'`.
      * @default true
      */
-    deselectable?: boolean;
+    deselectable?: boolean | undefined;
     /**
      * Whether the group manages one tab stop with arrow-key navigation (`true`)
      * or every item is its own tab stop with no arrow handling (`false`).
      * @default true
      */
-    rovingFocus?: boolean;
+    rovingFocus?: boolean | undefined;
     /**
-     * Form field name. The pressed value(s) are submitted under it through
-     * visually-hidden native inputs the group renders alongside itself — one per
-     * pressed value, so a `'multiple'` group produces the repeated `name=value`
-     * pairs a set of same-named checkboxes produces and `formData.getAll(name)`
-     * returns them all.
+     * Form field name; pressed values submit as repeated `name=value` pairs through hidden mirrored inputs.
      * @default undefined — the group renders no inputs and submits nothing.
      */
-    name?: string;
+    name?: string | undefined;
     /**
-     * Marks the group required: `valueMissing` until an item is pressed,
-     * reported through `checkValidity()`/`reportValidity()` on the forwarded ref.
-     * Only meaningful with `name`, which is what renders the control the
-     * constraint lives on.
+     * Marks the group required: `valueMissing` until an item is pressed, reported through `checkValidity()`/`reportValidity()`.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | undefined;
     /**
-     * Id of the `<form>` this group submits into, forwarded to every mirrored
-     * hidden input — one per pressed value — so the group can live outside the
-     * form it belongs to. Needs `name` to mean anything.
+     * Id of the `<form>` this group submits into, forwarded to every mirrored hidden input.
      * @default undefined — the group submits into its nearest ancestor form.
      */
-    form?: string;
+    form?: string | undefined;
+    /**
+     * Displays a committed choice the user may not change: items keep their tab stop and arrow navigation, the root carries `data-readonly`, and the value still submits.
+     * @default false
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Marks the group invalid via `data-invalid`; presentational only — use `required` or `setCustomValidity()` to block a submit.
+     * @default false
+     */
+    invalid?: boolean | undefined;
+    /**
+     * Whether roving focus landing on an item also presses it, so arrow keys browse the choices; only meaningful with `type="single"`, and never fired by focus arriving from outside the group.
+     * @default false
+     */
+    selectOnFocus?: boolean | undefined;
+    /**
+     * Shape rung the skin reads, mirrored to `data-variant` on the root; `'segmented'` paints the group as one joined strip with a sliding `ToggleGroupIndicator`.
+     * @default undefined — the skin's own default shape.
+     */
+    variant?: 'segmented' | (string & {}) | undefined;
+    /**
+     * Stretches the group to its container width, mirrored to `data-full-width` on the root.
+     * @default undefined — the group is only as wide as its items.
+     */
+    fullWidth?: boolean | undefined;
+    /**
+     * Visual size rung the skin scales the items by, mirrored to `data-size` on the root.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'lg' | (string & {}) | undefined;
 }
 /**
  * The forwarded ref's handle: the root `<div>` with constraint-validation
@@ -139,8 +150,22 @@ export interface ToggleGroupItemProps extends PrimitivePropsWithRef<'button'> {
     /** Unique identifier compared against the group's pressed value(s). */
     value: string;
     /**
-     * Disables this item and excludes it from the roving focus order.
+     * Disables this item and excludes it from the roving focus order; under a read-only group it keeps its tab stop and carries `aria-disabled` instead.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
+}
+/** The pressed item's box relative to the group root, which {@link ToggleGroupIndicator} publishes as custom properties. */
+export interface ToggleGroupRect {
+    /** Offset in CSS pixels from the root's left edge. */
+    x: number;
+    /** Offset in CSS pixels from the root's top edge. */
+    y: number;
+    /** Measured width of the pressed item, in CSS pixels. */
+    width: number;
+    /** Measured height of the pressed item, in CSS pixels. */
+    height: number;
+}
+/** Props for the {@link ToggleGroupIndicator}, the highlight that slides behind the pressed item. */
+export interface ToggleGroupIndicatorProps extends PrimitivePropsWithRef<'div'> {
 }