@ssa-ui-kit/core 2.33.0 → 3.1.0

package/dist/components/RadioGroup/types.d.ts

@@ -1,4 +1,37 @@
 import { RadioProps } from '../Radio/types';
+/**
+ * Props for the RadioGroup component
+ *
+ * Orchestrates a set of Radio buttons so only one can be selected at a time.
+ * The group manages the active value in internal state, syncs with `externalState`,
+ * and injects `name`, `isChecked`, and `onChange` into every Radio child via
+ * `cloneElement`. Individual Radio components can still override the group's
+ * `color` prop with their own `color` prop.
+ *
+ * @example
+ * ```tsx
+ * // Basic radio group
+ * <RadioGroup name="fruit" onChange={(value) => console.log(value)}>
+ *   <Radio id="r1" value="apple" text="Apple" />
+ *   <Radio id="r2" value="orange" text="Orange" />
+ *   <Radio id="r3" value="banana" text="Banana" isDisabled />
+ * </RadioGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled with external state and success color
+ * const [selected, setSelected] = useState('apple');
+ * <RadioGroup
+ *   name="fruit"
+ *   color="success"
+ *   externalState={selected}
+ *   onChange={setSelected}>
+ *   <Radio id="r1" value="apple" text="Apple" />
+ *   <Radio id="r2" value="orange" text="Orange" />
+ * </RadioGroup>
+ * ```
+ */
 export interface RadioGroupProps {
     name: string;
     isRequired?: boolean;
@@ -6,4 +39,13 @@ export interface RadioGroupProps {
     className?: string;
     onChange: (value: string | number) => void;
     children?: React.ReactElement<RadioProps>[] | React.ReactElement<RadioProps>;
+    /**
+     * Palette-based color variant applied to every Radio child.
+     * Individual Radio components can still override this with their own `color` prop.
+     * - `primary` — blue (uses `palette.primary`)
+     * - `success` — green (uses `palette.success`)
+     * - `custom` — pass `colors` to each Radio individually
+     * @default 'primary'
+     */
+    color?: RadioProps['color'];
 }

package/dist/components/SearchBox/SearchBox.d.ts

@@ -1,2 +1,62 @@
 import { SearchBoxProps } from './types';
+/**
+ * SearchBox - Search input component with debounced callbacks
+ *
+ * A specialized search input component that combines Input functionality with
+ * search-specific features like debounced callbacks, clear button, and search
+ * icon. Automatically triggers search callbacks as the user types (with debounce)
+ * or immediately when Enter key is pressed.
+ *
+ * Features:
+ * - Debounced search callbacks to reduce API calls
+ * - Visual feedback: search icon when empty, clear icon when has value
+ * - Enter key for immediate search execution
+ * - Configurable auto-search trigger
+ * - React Hook Form integration for form state management
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * const { control, register, resetField } = useForm();
+ *
+ * <SearchBox
+ *   name="search"
+ *   placeholder="Search products..."
+ *   control={control}
+ *   register={register}
+ *   resetField={resetField}
+ *   callback={(term) => {
+ *     console.log('Searching for:', term);
+ *     // Perform search API call
+ *   }}
+ *   callbackDelay={500}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Manual search only (no auto-trigger)
+ * <SearchBox
+ *   name="query"
+ *   control={control}
+ *   register={register}
+ *   resetField={resetField}
+ *   callback={handleSearch}
+ *   autoSearchTrigger={false}
+ *   placeholder="Press Enter to search"
+ * />
+ * ```
+ *
+ * @see {@link Input} - Base input component used internally
+ *
+ * @requires React Hook Form - Must be used within FormProvider context
+ *
+ * @accessibility
+ * - Full keyboard navigation support
+ * - Enter key triggers search
+ * - Clear button accessible via keyboard
+ * - Screen reader friendly
+ */
 export declare const SearchBox: ({ name, placeholder, control, callbackDelay, autoSearchTrigger, register, resetField, callback, ...rest }: SearchBoxProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/SearchBox/SearchBoxInput.d.ts

@@ -1,3 +1,3 @@
-export declare const SearchBoxInput: import("@emotion/styled").StyledComponent<import("../Input/types").InputProps & import("react").RefAttributes<HTMLInputElement> & {
+export declare const SearchBoxInput: import("@emotion/styled").StyledComponent<import("..").InputProps & import("react").RefAttributes<HTMLInputElement> & {
     theme?: import("@emotion/react").Theme;
 }, {}, {}>;

package/dist/components/SearchBox/types.d.ts

@@ -1,7 +1,53 @@
 import { InputProps } from '../Input/types';
 import { UseFormReturn } from 'react-hook-form';
+/**
+ * Props for the SearchBox component
+ *
+ * A specialized search input component with debounced search callback, clear
+ * functionality, and React Hook Form integration. Automatically triggers search
+ * callbacks with configurable debounce delay and supports manual search via
+ * Enter key.
+ *
+ * Features:
+ * - Debounced search callbacks (reduces API calls)
+ * - Clear button that appears when input has value
+ * - Search icon when input is empty
+ * - Enter key to trigger immediate search
+ * - Auto-search trigger on input change (configurable)
+ *
+ * @example
+ * ```tsx
+ * const { control, register, resetField } = useForm();
+ * <SearchBox
+ *   name="search"
+ *   placeholder="Search products..."
+ *   control={control}
+ *   register={register}
+ *   resetField={resetField}
+ *   callback={(term) => handleSearch(term)}
+ *   callbackDelay={500}
+ * />
+ * ```
+ *
+ * @requires React Hook Form - Must be used within FormProvider context
+ */
 export type SearchBoxProps = InputProps & Pick<UseFormReturn, 'control' | 'resetField'> & {
+    /**
+     * Callback function called when search is triggered
+     * Receives the current search term as parameter
+     * Triggered either by debounced input changes or Enter key press
+     */
     callback: (searchTerm: string) => void;
+    /**
+     * Debounce delay in milliseconds for search callback
+     * Prevents excessive API calls while user is typing
+     * @default 500
+     */
     callbackDelay?: number;
+    /**
+     * Whether to automatically trigger search on input change
+     * When false, search only triggers on Enter key press
+     * @default true
+     */
     autoSearchTrigger?: boolean;
 };

package/dist/components/Slider/Slider.d.ts

@@ -0,0 +1,53 @@
+import { SliderProps } from './types';
+/**
+ * Slider — a dual-thumb range slider component.
+ *
+ * ## Variants
+ * - **Default** — floating value labels appear above each thumb
+ *   (`valueLabelDisplay`).
+ * - **With inputs** (`withInputs`) — two editable number fields above the
+ *   track; floating labels are hidden.
+ *
+ * ## Thumb-crossing behavior
+ * - **Default** (`disableSwap` omitted) — thumbs cross freely; values are
+ *   re-sorted automatically so the fill always sits between them.
+ * - **`disableSwap`** — the active thumb stops at the other thumb (or
+ *   `minDistance` away). Use with `minDistance` to enforce a minimum gap.
+ *
+ * ## Customization
+ * All inner styled sub-elements are exported from `@ssa-ui-kit/core` as
+ * `Slider*` components. Pass them as selectors inside the `css` prop or
+ * target them by their generated class names via `className`.
+ *
+ * ```tsx
+ * import { css } from '@emotion/react';
+ * import { Slider, SliderTrackFill, SliderRangeInput } from '@ssa-ui-kit/core';
+ *
+ * // Override fill color via the css prop
+ * <Slider
+ *   css={css`
+ *     ${SliderTrackFill} { background: #52c587; }
+ *     ${SliderRangeInput}::-webkit-slider-thumb { background: #52c587; }
+ *   `}
+ *   defaultValue={[20, 80]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Basic range slider (thumbs swap when they cross)
+ * <Slider label="Price" min={0} max={1000} defaultValue={[200, 800]} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Prevent crossing + enforce a gap of at least 50
+ * <Slider
+ *   label="Budget"
+ *   min={0} max={1000}
+ *   disableSwap minDistance={50}
+ *   defaultValue={[100, 900]}
+ * />
+ * ```
+ */
+export declare const Slider: ({ label, min, max, step, value: valueProp, defaultValue, onChange, size, withInputs, valueLabelDisplay, disableSwap, minDistance, marks, disabled, className, css: customCss, }: SliderProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Slider/consts.d.ts

@@ -0,0 +1,4 @@
+import { MainSizes } from '../../types/global';
+import { SliderSize } from './types';
+export declare const SLIDER_THUMB_SIZES: Record<SliderSize, number>;
+export declare const trackSizeStyles: MainSizes;

package/dist/components/Slider/index.d.ts

@@ -0,0 +1,4 @@
+export { Slider } from './Slider';
+export { SliderRoot, SliderLabel, SliderInputsRow, SliderNumberInput, SliderTrackWrapper, SliderValueLabelsContainer, SliderValueLabel, SliderTrackRow, SliderTrackBg, SliderTrackFill, SliderRangeInput, SliderMarksRow, SliderMarkItem, SliderMarkTick, SliderMarkLabel, } from './styles';
+export { SLIDER_THUMB_SIZES } from './consts';
+export type { SliderProps, SliderMark, SliderSize, ValueLabelDisplay, } from './types';

package/dist/components/Slider/styles.d.ts

@@ -0,0 +1,90 @@
+import { SliderSize } from './types';
+export declare const SliderRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderLabel: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>, {}>;
+export declare const SliderInputsRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderNumberInput: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, {}>;
+export declare const SliderTrackWrapper: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderValueLabelsContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * `leftCalc` is a CSS `calc()` string that aligns the label center precisely
+ * over the thumb, accounting for the thumb half-size offset at track edges.
+ */
+export declare const SliderValueLabel: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    leftCalc: string;
+    isVisible: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderTrackRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderTrackBg: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: SliderSize;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderTrackFill: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    left: number;
+    width: number;
+    isDisabled: boolean;
+    size: SliderSize;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * `sliderSize` is used instead of `size` because `<input size>` is a built-in
+ * HTML attribute typed as `number`, which would conflict with our `SliderSize`
+ * string union and collapse the whole props intersection to `never`.
+ * `shouldForwardProp` prevents both custom props from reaching the DOM.
+ */
+export declare const SliderRangeInput: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    sliderSize: SliderSize;
+    zIndex?: number;
+}, import("react").DetailedHTMLProps<import("react").InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, {}>;
+export declare const SliderMarksRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * `leftCalc` uses the same calc() formula as `SliderValueLabel` so ticks are
+ * pixel-perfect under each thumb position.
+ */
+export declare const SliderMarkItem: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    leftCalc: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderMarkTick: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const SliderMarkLabel: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;

package/dist/components/Slider/types.d.ts

@@ -0,0 +1,69 @@
+import { Interpolation, Theme } from '@emotion/react';
+import { MainSizes } from '../../types/global';
+export type SliderSize = keyof MainSizes;
+export type ValueLabelDisplay = 'auto' | 'on' | 'off';
+export interface SliderMark {
+    value: number;
+    label?: string;
+}
+export interface SliderProps {
+    /** Optional label shown above the slider */
+    label?: string;
+    /** Minimum value of the range */
+    min?: number;
+    /** Maximum value of the range */
+    max?: number;
+    /** Granularity of each step */
+    step?: number;
+    /** Controlled [min, max] value pair */
+    value?: [number, number];
+    /** Uncontrolled initial [min, max] value pair */
+    defaultValue?: [number, number];
+    /** Called whenever either thumb changes */
+    onChange?: (value: [number, number]) => void;
+    /** Track / thumb size */
+    size?: SliderSize;
+    /**
+     * Render two number inputs above the slider instead of floating value labels.
+     */
+    withInputs?: boolean;
+    /**
+     * Control visibility of the floating value labels above the thumbs.
+     * - `'auto'` (default) — show on hover/focus
+     * - `'on'`  — always visible
+     * - `'off'` — never shown
+     * Ignored when `withInputs` is `true`.
+     */
+    valueLabelDisplay?: ValueLabelDisplay;
+    /**
+     * Prevent the two thumbs from crossing each other — the moving thumb
+     * stops when it would reach the other thumb (or `minDistance` away from it).
+     * Default is `false` (thumbs can cross; values swap automatically).
+     */
+    disableSwap?: boolean;
+    /**
+     * Minimum gap enforced between the two thumb values.
+     * Only takes effect when `disableSwap` is `true`.
+     * @example `minDistance={10}` — thumbs can get no closer than 10 units apart.
+     */
+    minDistance?: number;
+    /**
+     * Tick marks rendered below the track — like a speedometer scale.
+     * Each mark has a required `value` (must be within `min`–`max`) and an
+     * optional `label` string shown beneath the tick.
+     *
+     * @example
+     * ```tsx
+     * marks={[
+     *   { value: 0,   label: '0' },
+     *   { value: 50,  label: '50' },
+     *   { value: 100, label: '100' },
+     * ]}
+     * ```
+     */
+    marks?: SliderMark[];
+    disabled?: boolean;
+    className?: string;
+    /** Emotion `css` override — applied to the outermost wrapper element. */
+    css?: Interpolation<Theme>;
+}

package/dist/components/Switch/Switch.d.ts

@@ -1,3 +1,68 @@
 import { SwitchProps } from './types';
-declare const Switch: ({ label, isDisabled }: SwitchProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * Switch - Toggle switch component for binary states
+ *
+ * A toggle switch component for enabling/disabling features or settings.
+ * Displays an on/off toggle that users can click to change state. Must be
+ * used within SwitchContextProvider which manages the switch state and
+ * provides toggle functionality.
+ *
+ * Colors are sourced from `theme.palette` for consistency with Button,
+ * Checkbox, and Radio. Pass `color="custom"` together with the `colors`
+ * object to supply arbitrary CSS color values.
+ *
+ * The off state always shows a neutral grey background. The disabled state
+ * always uses `greyFocused40`, regardless of color variant.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Default (primary / blue)
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch label="Enable notifications" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch label="Enable feature" color="success" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled (muted grey, cannot toggle)
+ * <SwitchContextProvider initialState={true}>
+ *   <Switch label="Locked feature" isDisabled />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color escape hatch
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch
+ *     label="Custom toggle"
+ *     color="custom"
+ *     colors={{ on: '#ff0000', offOutline: '#ff9999' }}
+ *   />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @see {@link SwitchContextProvider} - Required parent component for state management
+ *
+ * @accessibility
+ * - Uses role="switch" for proper ARIA semantics
+ * - aria-checked reflects current state
+ * - aria-readonly reflects disabled state
+ * - aria-label provided via label prop
+ * - Keyboard accessible (Space/Enter to toggle)
+ *
+ * @requires SwitchContextProvider - Must be wrapped in SwitchContextProvider
+ */
+declare const Switch: ({ label, isDisabled, color, colors, }: SwitchProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Switch;

package/dist/components/Switch/SwitchBase.d.ts

@@ -1,5 +1,9 @@
+interface SwitchBaseProps {
+    onColor: string;
+    offOutlineColor: string;
+}
 declare const SwitchBase: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
-}, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+} & SwitchBaseProps, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
 export default SwitchBase;

package/dist/components/Switch/SwitchContext.d.ts

@@ -1,10 +1,60 @@
+/**
+ * Switch context value
+ * Provides switch state and toggle function to Switch component
+ */
 export interface SwitchContext {
+    /**
+     * Current state of the switch
+     * - `true`: Switch is on/enabled
+     * - `false`: Switch is off/disabled (default)
+     */
     isOn: boolean;
+    /** Function to toggle switch state */
     toggle: () => void;
 }
+/**
+ * Default context value for SwitchContext
+ * Used as fallback when context is accessed outside SwitchContextProvider
+ * @default isOn: false - Switch defaults to off state
+ */
 export declare const SwitchContext: import("react").Context<SwitchContext>;
+/**
+ * Hook to access Switch context
+ *
+ * @returns Switch context with isOn state and toggle function
+ * @throws Error if used outside SwitchContextProvider
+ */
 export declare const useSwitchContext: () => SwitchContext;
+/**
+ * SwitchContextProvider - Context provider for Switch component
+ *
+ * Provides switch state management and toggle functionality to child Switch
+ * components. Manages the on/off state internally and exposes it via context.
+ *
+ * @category Form Controls
+ * @subcategory Context
+ *
+ * @example
+ * ```tsx
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch label="Enable feature" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple switches sharing state (if needed)
+ * <SwitchContextProvider initialState={true}>
+ *   <Switch label="Switch 1" />
+ *   <Switch label="Switch 2" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @see {@link Switch} - Component that consumes this context
+ */
 export declare const SwitchContextProvider: ({ initialState, children, }: {
+    /** Initial on/off state of the switch */
     initialState?: boolean;
+    /** Child components (typically Switch component) */
     children: React.ReactNode;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Switch/types.d.ts

@@ -1,4 +1,78 @@
+/**
+ * Props for the Switch component
+ *
+ * Toggle switch component for binary on/off states. Must be used within
+ * SwitchContextProvider to access toggle state and functionality.
+ *
+ * Colors are driven by `theme.palette` for consistency with Button, Checkbox,
+ * and Radio:
+ * - `primary` (default) — blue; uses `palette.primary.main` for the on-state
+ *   background, `palette.primary.light` for the off-state focus outline.
+ * - `success` — green; uses `palette.success.main` for the on-state background,
+ *   `palette.success.light` for the off-state focus outline.
+ * - `custom` — no built-in color; supply exact values via the `colors` prop.
+ *
+ * The off state always uses a neutral grey background regardless of variant.
+ * Disabled state always uses `greyFocused40` (semi-transparent grey, same for all variants).
+ *
+ * @example
+ * ```tsx
+ * // Default (primary / blue)
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch label="Enable notifications" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch label="Enable feature" color="success" />
+ * </SwitchContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color escape hatch
+ * <SwitchContextProvider initialState={false}>
+ *   <Switch
+ *     label="Custom toggle"
+ *     color="custom"
+ *     colors={{
+ *       on: '#ff0000',
+ *       offOutline: '#ff9999',
+ *     }}
+ *   />
+ * </SwitchContextProvider>
+ * ```
+ */
 export interface SwitchProps {
+    /**
+     * Accessible label for the switch
+     * Used as aria-label for screen readers
+     */
     label: string;
+    /**
+     * Whether the switch is disabled
+     * Disabled switches cannot be toggled and appear visually muted
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Palette-based color variant.
+     * - `primary` — blue (uses `palette.primary`)
+     * - `success` — green (uses `palette.success`)
+     * - `custom` — no built-in color; supply exact values via the `colors` prop
+     * @default 'primary'
+     */
+    color?: 'primary' | 'success' | 'custom';
+    /**
+     * Fine-grained color overrides — only applied when `color="custom"`.
+     */
+    colors?: {
+        /** Background color when the switch is on (checked) */
+        on?: string;
+        /** Border color of the outline shown when off and focused/hovered */
+        offOutline?: string;
+    };
 }