@skdx/react 0.27.0 → 0.29.0

package/dist/carousel/types.d.ts

@@ -1,3 +1,4 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 /** Shape returned by the exported `useCarouselContext` hook; distributed from {@link Carousel} to its parts via context. */
 export interface CarouselContextValue {
@@ -5,8 +6,11 @@ export interface CarouselContextValue {
     setValue: (index: number) => void;
     orientation: 'horizontal' | 'vertical';
     loop: boolean;
+    /** Every registered slide's id, in DOM order — the order a derived Indicators list must draw its dots in. */
     itemIds: string[];
-    registerItem: (id: string) => void;
+    /** Registers one slide, placing its id by the element's DOM position rather than by when it mounted. */
+    registerItem: (id: string, element: HTMLElement | null) => void;
+    /** Removes a slide's id from the registry when it unmounts. */
     unregisterItem: (id: string) => void;
     /** How many slides are visible at once. */
     slidesPerPage: number;
@@ -14,84 +18,114 @@ export interface CarouselContextValue {
     slidesPerMove: number;
     /** Highest index the carousel can rest at — `max(0, count - slidesPerPage)`, so the last page stays full. */
     maxIndex: number;
-    /** Moves to `index`, clamped into `[0, maxIndex]`. Ignores out-of-range values rather than throwing. */
+    /** Moves to `index`, clamped into `[0, maxIndex]`, ignoring out-of-range values rather than throwing. */
     scrollToIndex: (index: number) => void;
-    /** Steps forward by `slidesPerMove`, wrapping to the start when `loop` is set. The one stepping rule Next and the arrow keys share. */
+    /** Stepper forward by `slidesPerMove`, wrapping to the start when `loop` is set. */
     next: () => void;
-    /** Steps back by `slidesPerMove`, wrapping to the last page when `loop` is set. */
+    /** Stepper back by `slidesPerMove`, wrapping to the last page when `loop` is set. */
     previous: () => void;
+    /** Whether `next()` has somewhere to go — false at the last page of a non-looping carousel, and with no slides. */
+    canScrollNext: boolean;
+    /** Whether `previous()` has somewhere to go — false at the first slide of a non-looping carousel, and with no slides. */
+    canScrollPrev: boolean;
     /**
-     * Whether autoplay is switched on. This is the user's setting, not the live
-     * timer state — hover/focus/page-hidden suspend the timer without flipping it.
+     * User's autoplay intent, not live timer state — hover and a hidden page suspend the timer without flipping it, but focus entering the carousel does.
      */
     playing: boolean;
     /** Starts or stops autoplay — what `CarouselPlayPause` calls. */
     setPlaying: (playing: boolean) => void;
 }
-/** Props for the {@link Carousel} root. */
-export interface CarouselProps extends PrimitivePropsWithRef<'div'> {
+/**
+ * Props for {@link Carousel}, which tracks a controllable current-slide index
+ * over slides supplied as `items` or as children, with optional derived
+ * controls, indicators and an autoplay pause button — there is no
+ * track/transform sliding and no swipe gesture.
+ */
+export interface CarouselProps<T = unknown> extends PrimitivePropsWithRef<'div'> {
     /**
-     * Index of the active slide, for controlled usage. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own active slide internally.
+     * Manually-composed parts — `CarouselContent`, `CarouselItem`, etc. — for full control over the anatomy; omitted, the carousel derives it from `items` and related props.
+     * @default undefined — the carousel derives its anatomy.
      */
-    value?: number;
+    children?: React.ReactNode | undefined;
     /**
-     * Initial active slide index, for uncontrolled usage.
+     * Index of the first visible slide for controlled usage, paired with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own active window internally.
+     */
+    value?: number | undefined;
+    /**
+     * Initial index of the first slide in the active window, for uncontrolled usage.
      * @default 0
      */
-    defaultValue?: number;
+    defaultValue?: number | undefined;
     /**
      * Fires with the new active index whenever the slide changes, controlled or not.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (index: number) => void;
+    onValueChange?: ((index: number) => void) | undefined;
     /**
      * Layout axis, exposed as `data-orientation` and used to pick Arrow
      * Left/Right vs Arrow Up/Down for keyboard navigation.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
     /**
-     * Whether stepping past the last slide (via keyboard or `CarouselNext`)
-     * wraps to the first, and vice versa for `CarouselPrevious`. When `false`,
-     * `CarouselPrevious`/`CarouselNext` disable themselves at the ends.
+     * Whether stepping past the last slide wraps to the first (and vice versa for `CarouselPrevious`); when `false`, both disable themselves at the ends.
      * @default false
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
     /**
-     * How many slides are visible at once. Slides from `value` up to
-     * `value + slidesPerPage - 1` are active; the rest stay `hidden`. Values
-     * below 1 are treated as 1.
+     * How many slides are visible at once, from `value` up to `value + slidesPerPage - 1`; values below 1 are treated as 1.
      * @default 1
      */
-    slidesPerPage?: number;
+    slidesPerPage?: number | undefined;
     /**
-     * How many slides one Previous/Next step (or Arrow keypress) advances by.
-     * Set it equal to `slidesPerPage` for page-at-a-time paging.
+     * How many slides one Previous/Next step (or Arrow keypress) advances by; set equal to `slidesPerPage` for page-at-a-time paging.
      * @default 1
      */
-    slidesPerMove?: number;
+    slidesPerMove?: number | undefined;
     /**
-     * Gap between slides, published as the `--skdx-carousel-spacing` custom
-     * property on the root so your CSS can consume it (`gap: var(--skdx-carousel-spacing)`).
-     * A number is treated as pixels; a string is used verbatim.
+     * Gap between slides, published as the `--skdx-carousel-spacing` custom property; a number is treated as pixels, a string used verbatim.
      * @default undefined — the property is not set, and your CSS decides.
      */
-    spacing?: number | string;
+    spacing?: number | string | undefined;
     /**
-     * Advances the carousel on a timer. Off by default, per WCAG 2.2.2: moving
-     * content that starts automatically needs a way to pause it, which
-     * `CarouselPlayPause` provides. Autoplay never starts under
-     * `prefers-reduced-motion: reduce`, and pauses while the pointer is over the
-     * root, while focus is inside it, and while the page is hidden.
+     * Auto-advances on a timer; off by default (WCAG 2.2.2), never starts under `prefers-reduced-motion`, and pairs with `CarouselPlayPause` to pause.
      * @default false
      */
-    autoplay?: boolean;
+    autoplay?: boolean | undefined;
     /**
      * Milliseconds to wait between automatic slide advances.
      * @default 5000
      */
-    autoplayInterval?: number;
+    autoplayInterval?: number | undefined;
+    /**
+     * Data the derived anatomy renders one `CarouselItem` slide per, instead of
+     * hand-written children. Ignored when `children` is given.
+     * @default undefined — no slides render.
+     */
+    items?: T[] | undefined;
+    /**
+     * Renders one derived slide's content, in place of its `String(item)`
+     * fallback. Ignored when `children` is given.
+     * @default undefined — each slide renders `String(item)`.
+     */
+    renderItem?: ((item: T, index: number) => React.ReactNode) | undefined;
+    /**
+     * Whether the derived anatomy renders a `CarouselIndicators` strip, one dot
+     * per item. Ignored when `children` is given.
+     * @default false
+     */
+    showIndicators?: boolean | undefined;
+    /**
+     * Accessible names for derived indicator dots, one per `items` entry in order; a shorter list falls back to the positional default for the rest.
+     * @default undefined
+     */
+    indicatorLabels?: readonly string[] | undefined;
+    /**
+     * Renders derived `CarouselPrevious` / `CarouselNext` controls; `CarouselPlayPause` renders whenever `autoplay` is set, independent of this.
+     * @default true
+     */
+    showControls?: boolean | undefined;
 }
 /** Props for {@link CarouselContent}, the wrapper around the slide `CarouselItem`s. */
 export interface CarouselContentProps extends PrimitivePropsWithRef<'div'> {
@@ -108,3 +142,29 @@ export interface CarouselNextProps extends PrimitivePropsWithRef<'button'> {
 /** Props for {@link CarouselPlayPause}, the autoplay pause/resume control. */
 export interface CarouselPlayPauseProps extends PrimitivePropsWithRef<'button'> {
 }
+/** Props for {@link CarouselIndicators}, the `role="group"` strip of slide dots. */
+export interface CarouselIndicatorsProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for a single {@link CarouselIndicator} dot. */
+export interface CarouselIndicatorProps extends PrimitivePropsWithRef<'button'> {
+    /** Zero-based slide index this dot jumps to when pressed. */
+    index: number;
+    /**
+     * Accessible name for this dot, replacing the positional default "Go to slide N"; a consumer's own `aria-label` takes precedence.
+     * @default undefined
+     */
+    label?: string | undefined;
+}
+/** Props for {@link CarouselProgress}, the "slide 2 of 5" position readout. */
+export interface CarouselProgressProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /**
+     * Formats the position text from the 1-based current slide and total count, consumer-supplied for translation.
+     * @default (current, total) => `Slide ${current} of ${total}`
+     */
+    format?: ((current: number, total: number) => string) | undefined;
+    /**
+     * With `asChild`, the element the formatted text is cloned onto, replacing its own children with the readout.
+     * @default undefined
+     */
+    children?: React.ReactElement | undefined;
+}

package/dist/checkbox/Checkbox.cjs

@@ -1 +1,2 @@
-"use strict";var V=Object.create;var f=Object.defineProperty;var q=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var z=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var G=(e,t)=>{for(var o in t)f(e,o,{get:t[o],enumerable:!0})},b=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of F(t))!A.call(e,n)&&n!==o&&f(e,n,{get:()=>t[n],enumerable:!(r=q(t,n))||r.enumerable});return e};var R=(e,t,o)=>(o=e!=null?V(z(e)):{},b(t||!e||!e.__esModule?f(o,"default",{value:e,enumerable:!0}):o,e)),J=e=>b(f({},"__esModule",{value:!0}),e);var Q={};G(Q,{Checkbox:()=>w,CheckboxIndicator:()=>k,CheckboxProvider:()=>H,getState:()=>p,useCheckboxContext:()=>u});module.exports=J(Q);var c=R(require("react"),1),y=require("../utils/composeRefs.cjs"),P=require("../utils/createContext.cjs"),I=require("../utils/formControl.cjs"),S=require("../utils/hiddenInput.cjs"),v=require("../utils/part.cjs"),i=require("../utils/primitive.cjs"),E=require("../utils/useControllableState.cjs"),d=require("react/jsx-runtime");function O(e){let t=c.useRef(null);return c.useEffect(()=>{t.current&&(t.current.indeterminate=e==="indeterminate")},[e]),t}var[H,u]=(0,P.createSafeContext)("Checkbox");function p(e){return e==="indeterminate"?"indeterminate":e?"checked":"unchecked"}var w=c.forwardRef(({checked:e,defaultChecked:t=!1,onCheckedChange:o,required:r,name:n,value:g="on",disabled:s=!1,invalid:l=!1,...m},D)=>{let[a=!1,x]=(0,E.useControllableState)({prop:e,defaultProp:t,onChange:o}),B=O(a),h=c.useRef(null),K=(0,y.useComposedRefs)(D,h);return(0,I.useFormReset)(h,()=>x(t)),(0,d.jsxs)(H,{checked:a,disabled:s,children:[(0,d.jsx)(i.Primitive.button,{type:"button",role:"checkbox","aria-checked":a==="indeterminate"?"mixed":a,"aria-required":r||void 0,"aria-invalid":l?!0:void 0,"data-state":p(a),"data-disabled":s?"":void 0,"data-invalid":l?"":void 0,disabled:s,...m,...(0,v.skdxPart)("checkbox","root",m.className),ref:K,onClick:(0,i.composeEventHandlers)(m.onClick,()=>{x(a==="indeterminate"?!0:!a)}),onKeyDown:(0,i.composeEventHandlers)(m.onKeyDown,C=>{C.key==="Enter"&&C.preventDefault()})}),n&&(0,d.jsx)(S.HiddenInput,{ref:B,type:"checkbox",name:n,value:g,checked:a==="indeterminate"?!1:a,required:r,disabled:s})]})});w.displayName="Checkbox";var L=R(require("react"),1),M=require("../utils/part.cjs"),N=require("../utils/primitive.cjs");var T=require("react/jsx-runtime"),k=L.forwardRef(({forceMount:e,...t},o)=>{let r=u("CheckboxIndicator");return e||r.checked!==!1?(0,T.jsx)(N.Primitive.span,{"data-state":p(r.checked),"data-disabled":r.disabled?"":void 0,...t,...(0,M.skdxPart)("checkbox","indicator",t.className),ref:o}):null});k.displayName="CheckboxIndicator";0&&(module.exports={Checkbox,CheckboxIndicator,CheckboxProvider,getState,useCheckboxContext});
+'use client';
+"use strict";var X=Object.create;var p=Object.defineProperty;var z=Object.getOwnPropertyDescriptor;var Q=Object.getOwnPropertyNames;var U=Object.getPrototypeOf,W=Object.prototype.hasOwnProperty;var Y=(e,t)=>{for(var n in t)p(e,n,{get:t[n],enumerable:!0})},H=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of Q(t))!W.call(e,r)&&r!==n&&p(e,r,{get:()=>t[r],enumerable:!(o=z(t,r))||o.enumerable});return e};var Z=(e,t,n)=>(n=e!=null?X(U(e)):{},H(t||!e||!e.__esModule?p(n,"default",{value:e,enumerable:!0}):n,e)),_=e=>H(p({},"__esModule",{value:!0}),e);var ee={};Y(ee,{Checkbox:()=>I,CheckboxAnatomy:()=>y,CheckboxIndicator:()=>x,CheckboxProvider:()=>g,checkableStateAttrs:()=>F,getState:()=>b,useCheckableControl:()=>w,useCheckboxContext:()=>m});module.exports=_(ee);var k=Z(require("react"),1),E=require("../utils/appearance.cjs"),N=require("../utils/createContext.cjs"),C=require("../utils/formControl.cjs"),L=require("../utils/hiddenInput.cjs"),M=require("../utils/part.cjs"),h=require("../utils/primitive.cjs"),V=require("../utils/useControllableState.cjs");var R=require("../utils/Glyph.cjs");var P=require("../utils/part.cjs"),T=require("../utils/primitive.cjs");var S=require("react/jsx-runtime"),x=({forceMount:e,ref:t,...n})=>{let o=m("CheckboxIndicator");return e||o.checked!==!1?(0,S.jsx)(T.Primitive.span,{"aria-hidden":"true","data-state":b(o.checked),"data-disabled":o.disabled?"":void 0,...n,...(0,P.skdxPart)("checkbox","indicator",n.className),ref:t}):null};x.displayName="CheckboxIndicator";var l=require("react/jsx-runtime");function $(){let{checked:e}=m("CheckboxIndicator");return e==="indeterminate"?(0,l.jsx)(R.Glyph,{name:"dash"}):(0,l.jsx)(R.Glyph,{name:"check"})}function y({indicator:e}){return(0,l.jsx)(x,{children:e??(0,l.jsx)($,{})})}var c=require("react/jsx-runtime");function j(e){let t=k.useRef(null);return k.useEffect(()=>{t.current&&(t.current.indeterminate=e==="indeterminate")},[e]),t}var[g,m]=(0,N.createSafeContext)("Checkbox");function b(e){return e==="indeterminate"?"indeterminate":e?"checked":"unchecked"}function F(e,t,n,o,r){return{"aria-checked":e==="indeterminate"?"mixed":e,"aria-required":r||void 0,"aria-readonly":n||void 0,"aria-invalid":o?!0:void 0,"data-state":b(e),"data-disabled":t?"":void 0,"data-readonly":n?"":void 0,"data-invalid":o?"":void 0}}function w({checked:e,defaultChecked:t,onCheckedChange:n,form:o,ref:r}){let[s=t,f]=(0,V.useControllableState)({prop:e,defaultProp:t,onChange:n}),a=j(s),d=k.useRef(null);return(0,C.useFormValidityHandle)(r,d,a),(0,C.useFormReset)(d,()=>f(t),o),{checked:s,setChecked:f,rootRef:d,hiddenInputRef:a}}var I=({checked:e,defaultChecked:t=!1,onCheckedChange:n,required:o,name:r,value:s="on",form:f,disabled:a=!1,readOnly:d=!1,invalid:A=!1,indicator:B,size:D,children:q,ref:G,...u})=>{let{checked:i,setChecked:K,rootRef:O,hiddenInputRef:J}=w({checked:e,defaultChecked:t,onCheckedChange:n,form:f,ref:G});return(0,c.jsxs)(g,{checked:i,disabled:a,children:[(0,c.jsx)(h.Primitive.button,{type:"button",role:"checkbox",...F(i,a,d,A,o),disabled:a,...u,...(0,E.appearanceAttrs)({size:D},u),...(0,M.skdxPart)("checkbox","root",u.className),ref:O,onClick:(0,h.composeEventHandlers)(u.onClick,()=>{d||K(i==="indeterminate"?!0:!i)}),onKeyDown:(0,h.composeEventHandlers)(u.onKeyDown,v=>{v.key==="Enter"&&v.preventDefault()}),children:q??(0,c.jsx)(y,{indicator:B})}),r?(0,c.jsx)(L.HiddenInput,{ref:J,type:"checkbox",name:r,value:s,form:f,checked:i==="indeterminate"?!1:i,required:o,disabled:a}):null]})};I.displayName="Checkbox";0&&(module.exports={Checkbox,CheckboxAnatomy,CheckboxIndicator,CheckboxProvider,checkableStateAttrs,getState,useCheckableControl,useCheckboxContext});

package/dist/checkbox/Checkbox.d.cts

@@ -1,22 +1,43 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.cjs';
 import type { CheckboxContextValue, CheckboxProps, CheckedState } from './types.cjs';
-export declare const CheckboxProvider: {
-    (props: CheckboxContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useCheckboxContext: (consumerName: string) => CheckboxContextValue;
+export declare const CheckboxProvider: React.FC<CheckboxContextValue & {
+    children: React.ReactNode;
+}>, useCheckboxContext: (consumerName: string) => CheckboxContextValue;
 /** @internal Maps a {@link CheckedState} to the `data-state` string (`'checked'` / `'unchecked'` / `'indeterminate'`). */
-export declare function getState(checked: CheckedState): "indeterminate" | "checked" | "unchecked";
+export declare function getState(checked: CheckedState): 'indeterminate' | 'checked' | 'unchecked';
+/**
+ * @internal The ARIA and `data-*` state a checkbox-style control publishes on its root.
+ * Shared with `Switch`, whose boolean state is a {@link CheckedState} that never goes indeterminate.
+ */
+export declare function checkableStateAttrs(checked: CheckedState, disabled: boolean, readOnly: boolean, invalid: boolean, required: boolean | undefined): {
+    'aria-checked': boolean | 'mixed';
+    'aria-required': true | undefined;
+    'aria-readonly': true | undefined;
+    'aria-invalid': true | undefined;
+    'data-state': 'indeterminate' | 'checked' | 'unchecked';
+    'data-disabled': '' | undefined;
+    'data-readonly': '' | undefined;
+    'data-invalid': '' | undefined;
+};
 /**
- * A tri-state checkbox button. Renders `role="checkbox"` with `aria-checked`
- * (`'mixed'` when indeterminate), `data-state` (`'checked'` / `'unchecked'` /
- * `'indeterminate'`), `data-disabled`, and `aria-invalid`/`data-invalid` when
- * `invalid` is set. Toggles between checked and unchecked on click or Space
- * (Enter is suppressed, matching native checkbox behavior); clicking while
- * indeterminate moves to checked. When `name` is set, also renders a
- * visually-hidden native `<input type="checkbox">` so the value participates
- * in real form submission.
+ * @internal The controlled/uncontrolled state, form-validity handle and reset listener a
+ * checkbox-style control needs, shared by `Checkbox` and `Switch`.
+ */
+export declare function useCheckableControl<T extends CheckedState>({ checked: checkedProp, defaultChecked, onCheckedChange, form, ref, }: {
+    checked?: T | undefined;
+    defaultChecked: T;
+    onCheckedChange?: ((checked: T) => void) | undefined;
+    form?: string | undefined;
+    ref?: React.Ref<HTMLButtonElement & FormValidityHandle> | undefined;
+}): {
+    checked: T;
+    setChecked: (next: T) => void;
+    rootRef: React.RefObject<HTMLButtonElement | null>;
+    hiddenInputRef: React.RefObject<HTMLInputElement | null>;
+};
+/**
+ * Tri-state checkbox that renders `role="checkbox"` with `aria-checked` (`'mixed'` when indeterminate), toggling on click or Space.
  *
  * @example
  * ```tsx
@@ -25,4 +46,9 @@ export declare function getState(checked: CheckedState): "indeterminate" | "chec
  * </Checkbox>
  * ```
  */
-export declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const Checkbox: {
+    ({ checked: checkedProp, defaultChecked, onCheckedChange, required, name, value, form, disabled, readOnly, invalid, indicator, size, children, ref: forwardedRef, ...props }: Omit<CheckboxProps, "ref"> & {
+        ref?: React.Ref<HTMLButtonElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/checkbox/Checkbox.d.ts

@@ -1,22 +1,43 @@
 import * as React from 'react';
+import { type FormValidityHandle } from '../utils/formControl.js';
 import type { CheckboxContextValue, CheckboxProps, CheckedState } from './types.js';
-export declare const CheckboxProvider: {
-    (props: CheckboxContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useCheckboxContext: (consumerName: string) => CheckboxContextValue;
+export declare const CheckboxProvider: React.FC<CheckboxContextValue & {
+    children: React.ReactNode;
+}>, useCheckboxContext: (consumerName: string) => CheckboxContextValue;
 /** @internal Maps a {@link CheckedState} to the `data-state` string (`'checked'` / `'unchecked'` / `'indeterminate'`). */
-export declare function getState(checked: CheckedState): "indeterminate" | "checked" | "unchecked";
+export declare function getState(checked: CheckedState): 'indeterminate' | 'checked' | 'unchecked';
+/**
+ * @internal The ARIA and `data-*` state a checkbox-style control publishes on its root.
+ * Shared with `Switch`, whose boolean state is a {@link CheckedState} that never goes indeterminate.
+ */
+export declare function checkableStateAttrs(checked: CheckedState, disabled: boolean, readOnly: boolean, invalid: boolean, required: boolean | undefined): {
+    'aria-checked': boolean | 'mixed';
+    'aria-required': true | undefined;
+    'aria-readonly': true | undefined;
+    'aria-invalid': true | undefined;
+    'data-state': 'indeterminate' | 'checked' | 'unchecked';
+    'data-disabled': '' | undefined;
+    'data-readonly': '' | undefined;
+    'data-invalid': '' | undefined;
+};
 /**
- * A tri-state checkbox button. Renders `role="checkbox"` with `aria-checked`
- * (`'mixed'` when indeterminate), `data-state` (`'checked'` / `'unchecked'` /
- * `'indeterminate'`), `data-disabled`, and `aria-invalid`/`data-invalid` when
- * `invalid` is set. Toggles between checked and unchecked on click or Space
- * (Enter is suppressed, matching native checkbox behavior); clicking while
- * indeterminate moves to checked. When `name` is set, also renders a
- * visually-hidden native `<input type="checkbox">` so the value participates
- * in real form submission.
+ * @internal The controlled/uncontrolled state, form-validity handle and reset listener a
+ * checkbox-style control needs, shared by `Checkbox` and `Switch`.
+ */
+export declare function useCheckableControl<T extends CheckedState>({ checked: checkedProp, defaultChecked, onCheckedChange, form, ref, }: {
+    checked?: T | undefined;
+    defaultChecked: T;
+    onCheckedChange?: ((checked: T) => void) | undefined;
+    form?: string | undefined;
+    ref?: React.Ref<HTMLButtonElement & FormValidityHandle> | undefined;
+}): {
+    checked: T;
+    setChecked: (next: T) => void;
+    rootRef: React.RefObject<HTMLButtonElement | null>;
+    hiddenInputRef: React.RefObject<HTMLInputElement | null>;
+};
+/**
+ * Tri-state checkbox that renders `role="checkbox"` with `aria-checked` (`'mixed'` when indeterminate), toggling on click or Space.
  *
  * @example
  * ```tsx
@@ -25,4 +46,9 @@ export declare function getState(checked: CheckedState): "indeterminate" | "chec
  * </Checkbox>
  * ```
  */
-export declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const Checkbox: {
+    ({ checked: checkedProp, defaultChecked, onCheckedChange, required, name, value, form, disabled, readOnly, invalid, indicator, size, children, ref: forwardedRef, ...props }: Omit<CheckboxProps, "ref"> & {
+        ref?: React.Ref<HTMLButtonElement & FormValidityHandle> | undefined;
+    }): React.ReactNode;
+    displayName: string;
+};

package/dist/checkbox/Checkbox.js

@@ -1 +1,2 @@
-import*as r from"react";import{useComposedRefs as I}from"../utils/composeRefs.js";import{createSafeContext as S}from"../utils/createContext.js";import{useFormReset as v}from"../utils/formControl.js";import{HiddenInput as E}from"../utils/hiddenInput.js";import{skdxPart as H}from"../utils/part.js";import{composeEventHandlers as k,Primitive as w}from"../utils/primitive.js";import{useControllableState as L}from"../utils/useControllableState.js";import{jsx as l,jsxs as g}from"react/jsx-runtime";function M(e){let t=r.useRef(null);return r.useEffect(()=>{t.current&&(t.current.indeterminate=e==="indeterminate")},[e]),t}var[N,x]=S("Checkbox");function s(e){return e==="indeterminate"?"indeterminate":e?"checked":"unchecked"}var T=r.forwardRef(({checked:e,defaultChecked:t=!1,onCheckedChange:i,required:n,name:d,value:b="on",disabled:a=!1,invalid:m=!1,...c},R)=>{let[o=!1,f]=L({prop:e,defaultProp:t,onChange:i}),y=M(o),p=r.useRef(null),P=I(R,p);return v(p,()=>f(t)),g(N,{checked:o,disabled:a,children:[l(w.button,{type:"button",role:"checkbox","aria-checked":o==="indeterminate"?"mixed":o,"aria-required":n||void 0,"aria-invalid":m?!0:void 0,"data-state":s(o),"data-disabled":a?"":void 0,"data-invalid":m?"":void 0,disabled:a,...c,...H("checkbox","root",c.className),ref:P,onClick:k(c.onClick,()=>{f(o==="indeterminate"?!0:!o)}),onKeyDown:k(c.onKeyDown,u=>{u.key==="Enter"&&u.preventDefault()})}),d&&l(E,{ref:y,type:"checkbox",name:d,value:b,checked:o==="indeterminate"?!1:o,required:n,disabled:a})]})});T.displayName="Checkbox";import*as h from"react";import{skdxPart as D}from"../utils/part.js";import{Primitive as B}from"../utils/primitive.js";import{jsx as K}from"react/jsx-runtime";var C=h.forwardRef(({forceMount:e,...t},i)=>{let n=x("CheckboxIndicator");return e||n.checked!==!1?K(B.span,{"data-state":s(n.checked),"data-disabled":n.disabled?"":void 0,...t,...D("checkbox","indicator",t.className),ref:i}):null});C.displayName="CheckboxIndicator";export{T as Checkbox,C as CheckboxIndicator,N as CheckboxProvider,s as getState,x as useCheckboxContext};
+'use client';
+import*as u from"react";import{appearanceAttrs as F}from"../utils/appearance.js";import{createSafeContext as w}from"../utils/createContext.js";import{useFormReset as A,useFormValidityHandle as B}from"../utils/formControl.js";import{HiddenInput as D}from"../utils/hiddenInput.js";import{skdxPart as q}from"../utils/part.js";import{composeEventHandlers as R,Primitive as G}from"../utils/primitive.js";import{useControllableState as K}from"../utils/useControllableState.js";import{Glyph as b}from"../utils/Glyph.js";import{skdxPart as L}from"../utils/part.js";import{Primitive as M}from"../utils/primitive.js";import{jsx as V}from"react/jsx-runtime";var k=({forceMount:e,ref:t,...o})=>{let n=l("CheckboxIndicator");return e||n.checked!==!1?V(M.span,{"aria-hidden":"true","data-state":s(n.checked),"data-disabled":n.disabled?"":void 0,...o,...L("checkbox","indicator",o.className),ref:t}):null};k.displayName="CheckboxIndicator";import{jsx as h}from"react/jsx-runtime";function g(){let{checked:e}=l("CheckboxIndicator");return e==="indeterminate"?h(b,{name:"dash"}):h(b,{name:"check"})}function C({indicator:e}){return h(k,{children:e??h(g,{})})}import{jsx as p,jsxs as Q}from"react/jsx-runtime";function O(e){let t=u.useRef(null);return u.useEffect(()=>{t.current&&(t.current.indeterminate=e==="indeterminate")},[e]),t}var[J,l]=w("Checkbox");function s(e){return e==="indeterminate"?"indeterminate":e?"checked":"unchecked"}function X(e,t,o,n,r){return{"aria-checked":e==="indeterminate"?"mixed":e,"aria-required":r||void 0,"aria-readonly":o||void 0,"aria-invalid":n?!0:void 0,"data-state":s(e),"data-disabled":t?"":void 0,"data-readonly":o?"":void 0,"data-invalid":n?"":void 0}}function z({checked:e,defaultChecked:t,onCheckedChange:o,form:n,ref:r}){let[m=t,c]=K({prop:e,defaultProp:t,onChange:o}),a=O(m),d=u.useRef(null);return B(r,d,a),A(d,()=>c(t),n),{checked:m,setChecked:c,rootRef:d,hiddenInputRef:a}}var y=({checked:e,defaultChecked:t=!1,onCheckedChange:o,required:n,name:r,value:m="on",form:c,disabled:a=!1,readOnly:d=!1,invalid:I=!1,indicator:v,size:H,children:P,ref:T,...f})=>{let{checked:i,setChecked:S,rootRef:E,hiddenInputRef:N}=z({checked:e,defaultChecked:t,onCheckedChange:o,form:c,ref:T});return Q(J,{checked:i,disabled:a,children:[p(G.button,{type:"button",role:"checkbox",...X(i,a,d,I,n),disabled:a,...f,...F({size:H},f),...q("checkbox","root",f.className),ref:E,onClick:R(f.onClick,()=>{d||S(i==="indeterminate"?!0:!i)}),onKeyDown:R(f.onKeyDown,x=>{x.key==="Enter"&&x.preventDefault()}),children:P??p(C,{indicator:v})}),r?p(D,{ref:N,type:"checkbox",name:r,value:m,form:c,checked:i==="indeterminate"?!1:i,required:n,disabled:a}):null]})};y.displayName="Checkbox";export{y as Checkbox,C as CheckboxAnatomy,k as CheckboxIndicator,J as CheckboxProvider,X as checkableStateAttrs,s as getState,z as useCheckableControl,l as useCheckboxContext};

package/dist/checkbox/CheckboxAnatomy.d.cts

@@ -0,0 +1,8 @@
+import type * as React from 'react';
+/**
+ * The anatomy a {@link Checkbox} draws when given no children: an Indicator holding `indicator`, or the default check/dash glyph.
+ * @internal
+ */
+export declare function CheckboxAnatomy({ indicator, }: {
+    indicator?: React.ReactNode | undefined;
+}): React.JSX.Element;

package/dist/checkbox/CheckboxAnatomy.d.ts

@@ -0,0 +1,8 @@
+import type * as React from 'react';
+/**
+ * The anatomy a {@link Checkbox} draws when given no children: an Indicator holding `indicator`, or the default check/dash glyph.
+ * @internal
+ */
+export declare function CheckboxAnatomy({ indicator, }: {
+    indicator?: React.ReactNode | undefined;
+}): React.JSX.Element;

package/dist/checkbox/CheckboxIndicator.d.cts

@@ -1,9 +1,7 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CheckboxIndicatorProps } from './types.cjs';
 /**
- * The visual mark (e.g. a check or dash icon) shown inside a {@link Checkbox}.
- * Renders `<span data-state data-disabled>` mirroring the parent checkbox's
- * state. Unmounts when unchecked unless `forceMount` is set.
+ * Visual mark (e.g. check or dash icon) inside a {@link Checkbox}, mirroring its state. Unmounts when unchecked unless `forceMount` is set.
  *
  * @example
  * ```tsx
@@ -12,4 +10,7 @@ import type { CheckboxIndicatorProps } from './types.cjs';
  * </Checkbox>
  * ```
  */
-export declare const CheckboxIndicator: React.ForwardRefExoticComponent<Omit<CheckboxIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const CheckboxIndicator: {
+    ({ forceMount, ref: forwardedRef, ...props }: CheckboxIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/checkbox/CheckboxIndicator.d.ts

@@ -1,9 +1,7 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CheckboxIndicatorProps } from './types.js';
 /**
- * The visual mark (e.g. a check or dash icon) shown inside a {@link Checkbox}.
- * Renders `<span data-state data-disabled>` mirroring the parent checkbox's
- * state. Unmounts when unchecked unless `forceMount` is set.
+ * Visual mark (e.g. check or dash icon) inside a {@link Checkbox}, mirroring its state. Unmounts when unchecked unless `forceMount` is set.
  *
  * @example
  * ```tsx
@@ -12,4 +10,7 @@ import type { CheckboxIndicatorProps } from './types.js';
  * </Checkbox>
  * ```
  */
-export declare const CheckboxIndicator: React.ForwardRefExoticComponent<Omit<CheckboxIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const CheckboxIndicator: {
+    ({ forceMount, ref: forwardedRef, ...props }: CheckboxIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/checkbox/index.d.cts

@@ -1,3 +1,2 @@
-export * from './Checkbox.cjs';
-export { CheckboxIndicator } from './CheckboxIndicator.cjs';
-export type { CheckboxProps, CheckboxIndicatorProps, CheckedState } from './types.cjs';
+export { Checkbox } from './Checkbox.cjs';
+export type { CheckboxHandle, CheckboxProps, CheckedState } from './types.cjs';

package/dist/checkbox/index.d.ts

@@ -1,3 +1,2 @@
-export * from './Checkbox.js';
-export { CheckboxIndicator } from './CheckboxIndicator.js';
-export type { CheckboxProps, CheckboxIndicatorProps, CheckedState } from './types.js';
+export { Checkbox } from './Checkbox.js';
+export type { CheckboxHandle, CheckboxProps, CheckedState } from './types.js';

package/dist/checkbox/primitives.d.cts

@@ -0,0 +1,15 @@
+/**
+ * Advanced primitives for `Checkbox` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { Checkbox, CheckboxIndicator } from '@skdx/react/primitives/checkbox';
+ *
+ * <Checkbox defaultChecked name="terms">
+ *   <CheckboxIndicator>✓</CheckboxIndicator>
+ * </Checkbox>
+ * ```
+ */
+export { Checkbox } from './Checkbox.cjs';
+export { CheckboxIndicator } from './CheckboxIndicator.cjs';
+export type { CheckboxProps, CheckboxHandle, CheckedState, CheckboxIndicatorProps } from './types.cjs';

package/dist/checkbox/primitives.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Advanced primitives for `Checkbox` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { Checkbox, CheckboxIndicator } from '@skdx/react/primitives/checkbox';
+ *
+ * <Checkbox defaultChecked name="terms">
+ *   <CheckboxIndicator>✓</CheckboxIndicator>
+ * </Checkbox>
+ * ```
+ */
+export { Checkbox } from './Checkbox.js';
+export { CheckboxIndicator } from './CheckboxIndicator.js';
+export type { CheckboxProps, CheckboxHandle, CheckedState, CheckboxIndicatorProps } from './types.js';

package/dist/checkbox/types.d.cts

@@ -1,7 +1,13 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 /** A checkbox's tri-state value: checked, unchecked, or indeterminate (partially checked). */
 export type CheckedState = boolean | 'indeterminate';
-/** @internal Shared state distributed from {@link Checkbox} to its {@link CheckboxIndicator} via context. Not part of the public API. */
+/**
+ * The `Checkbox` root `<button>` plus its constraint-validation methods, assigned onto the same node so existing `HTMLButtonElement` ref usage keeps working.
+ */
+export type CheckboxHandle = HTMLButtonElement & FormValidityHandle;
+/** @internal Shared state distributed from {@link Checkbox} to its {@link CheckboxIndicator} via context. */
 export interface CheckboxContextValue {
     checked: CheckedState;
     disabled: boolean;
@@ -12,37 +18,62 @@ export interface CheckboxProps extends Omit<PrimitivePropsWithRef<'button'>, 'de
      * Checked state, for controlled usage. Pair with `onCheckedChange`.
      * @default undefined — uncontrolled, tracks its own checked state internally.
      */
-    checked?: CheckedState;
+    checked?: CheckedState | undefined;
     /**
      * Initial checked state, for uncontrolled usage.
      * @default false
      */
-    defaultChecked?: CheckedState;
+    defaultChecked?: CheckedState | undefined;
     /**
      * Fires with the new checked state whenever it changes, controlled or not.
      * @default undefined — no-op if omitted.
      */
-    onCheckedChange?: (checked: CheckedState) => void;
+    onCheckedChange?: ((checked: CheckedState) => void) | undefined;
     /**
      * Marks the underlying hidden input as required for native form validation.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | undefined;
     /**
-     * Name for native form participation via a hidden input. Omitted: no hidden input is rendered.
+     * Name for native form participation via a hidden input.
      * @default undefined — no hidden input rendered.
      */
-    name?: string;
+    name?: string | undefined;
     /**
      * Value submitted with the hidden input when checked.
      * @default 'on'
      */
-    value?: string;
+    value?: string | undefined;
+    /**
+     * Id of the `<form>` that owns this checkbox when it renders outside it, forwarded to the hidden input's `form` attribute.
+     * @default undefined — the checkbox belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string | undefined;
+    /**
+     * Freezes the checked state without freezing the control: keeps focus and `aria-readonly`/`data-readonly`, and ignores click and Space.
+     * @default false
+     */
+    readOnly?: boolean | undefined;
     /**
      * Marks the checkbox as invalid, exposed as `aria-invalid`/`data-invalid`.
      * @default false
      */
-    invalid?: boolean;
+    invalid?: boolean | undefined;
+    /**
+     * Disables the checkbox and excludes it from the tab order.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Renders a derived `CheckboxIndicator` holding this content in place of the default check glyph, ignored when `children` is given.
+     * @default undefined — the default check/dash glyph.
+     */
+    indicator?: React.ReactNode | undefined;
+    /**
+     * Size rung the skin scales the box by, mirrored to `data-size` on the root.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'sm' | 'md' | 'lg' | (string & {}) | undefined;
 }
 /** Props for the {@link CheckboxIndicator}, the visual mark shown when checked or indeterminate. */
 export interface CheckboxIndicatorProps extends PrimitivePropsWithRef<'span'> {
@@ -50,5 +81,5 @@ export interface CheckboxIndicatorProps extends PrimitivePropsWithRef<'span'> {
      * Keep mounted regardless of state (for exit animations).
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }