@ssa-ui-kit/core 2.33.0 → 3.0.0

package/dist/components/Radio/Radio.d.ts

@@ -1,3 +1,71 @@
 import { RadioProps } from './types';
-declare const Radio: ({ id, name, value, isChecked, isDisabled, isRequired, text, colors, className, onChange, }: RadioProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * Radio - Radio button component for single selection
+ *
+ * A radio button component for selecting a single option from a group.
+ * Supports controlled and uncontrolled states, palette-based color variants,
+ * and full accessibility. Displays a radio icon that changes appearance based
+ * on checked state and hover interactions.
+ *
+ * Colors are sourced from `theme.palette` for consistency with Button and
+ * Checkbox. Pass `color="custom"` together with the `colors` object to supply
+ * arbitrary CSS color values.
+ *
+ * Typically used within RadioGroup for managing selection state across
+ * multiple radio buttons, but can also be used standalone.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Default (primary / blue)
+ * <Radio
+ *   id="option1"
+ *   name="choice"
+ *   value="option1"
+ *   text="Option 1"
+ *   onChange={(value) => console.log(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <Radio
+ *   name="status"
+ *   value="active"
+ *   text="Active"
+ *   color="success"
+ *   onChange={handleChange}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color escape hatch
+ * <Radio
+ *   name="priority"
+ *   value="high"
+ *   text="High Priority"
+ *   color="custom"
+ *   colors={{
+ *     default: '#ff0000',
+ *     hovered: '#cc0000',
+ *     disabled: '#cccccc',
+ *     focusShadow: 'rgba(255,0,0,0.25)',
+ *   }}
+ *   onChange={handleChange}
+ * />
+ * ```
+ *
+ * @see {@link RadioGroup} - For managing groups of radio buttons
+ *
+ * @accessibility
+ * - Full keyboard navigation (Arrow keys to navigate group, Space to select)
+ * - Proper ARIA attributes (role="radio", aria-checked)
+ * - Screen reader friendly
+ * - Focus management with visible focus indicators
+ */
+declare const Radio: ({ id, name, value, isChecked, isDisabled, isRequired, text, color, colors, className, onChange, }: RadioProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Radio;

package/dist/components/Radio/RadioBase.d.ts

@@ -1,4 +1,4 @@
-export declare const RadioBase: import("@emotion/styled").StyledComponent<import("../Label/types").LabelProps & {
+export declare const RadioBase: import("@emotion/styled").StyledComponent<import("..").LabelProps & {
     theme?: import("@emotion/react").Theme;
 } & {
     focusShadowColor?: string;

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

@@ -1,17 +1,126 @@
+/**
+ * Props for the Radio component
+ *
+ * Radio button component for single selection from a group of options.
+ * Supports controlled and uncontrolled states, palette-based color variants,
+ * and full accessibility. Typically used within RadioGroup for managing
+ * selection state.
+ *
+ * Colors are driven by `theme.palette`:
+ * - `primary` (default) — blue; uses `palette.primary.main` for resting/checked,
+ *   `palette.primary.dark` for hover.
+ * - `success` — green; uses `palette.success.main` for resting/checked,
+ *   `palette.success.dark` for hover.
+ * - `custom` — no built-in color; provide exact values via the `colors` object.
+ *
+ * @example
+ * ```tsx
+ * // Basic radio button (primary / blue by default)
+ * <Radio
+ *   id="option1"
+ *   name="choice"
+ *   value="option1"
+ *   text="Option 1"
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success (green) variant
+ * <Radio
+ *   name="status"
+ *   value="active"
+ *   text="Active"
+ *   color="success"
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom color via escape hatch
+ * <Radio
+ *   name="priority"
+ *   value="high"
+ *   text="High Priority"
+ *   color="custom"
+ *   colors={{
+ *     default: '#ff0000',
+ *     hovered: '#cc0000',
+ *     disabled: '#cccccc',
+ *     focusShadow: 'rgba(255, 0, 0, 0.25)',
+ *   }}
+ *   onChange={(value) => handleChange(value)}
+ * />
+ * ```
+ */
 export interface RadioProps {
+    /**
+     * Unique identifier for the radio input
+     * If not provided, a unique ID will be auto-generated
+     */
     id?: string;
+    /**
+     * Value of the radio button
+     * Passed to onChange callback when selected
+     */
     value: string;
+    /**
+     * Name attribute for grouping radio buttons
+     * Radio buttons with the same name form a group
+     * @default ''
+     */
     name?: string;
+    /**
+     * Whether the radio button is checked
+     * Use for controlled component pattern
+     */
     isChecked?: boolean;
+    /**
+     * Whether the radio button is disabled
+     * Disabled radios cannot be selected
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Whether the radio button is required for form validation
+     * @default false
+     */
     isRequired?: boolean;
+    /**
+     * Callback function called when radio is selected
+     * Receives the radio's value as parameter
+     */
     onChange?: (value: string) => void;
+    /**
+     * Label text displayed next to the radio button
+     */
     text?: string;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Palette-based color variant.
+     * - `primary` — blue (uses `palette.primary`)
+     * - `success` — green (uses `palette.success`)
+     * - `custom` — unstyled; supply exact colors via the `colors` prop
+     * @default 'primary'
+     */
+    color?: 'primary' | 'success' | 'custom';
+    /**
+     * Fine-grained color overrides — only applied when `color="custom"`.
+     * Allows overriding every interactive state independently.
+     */
     colors?: {
+        /** Resting (and checked) icon color */
         default?: string;
+        /** Hover icon color */
         hovered?: string;
+        /** Disabled state icon color */
         disabled?: string;
+        /** Focus ring drop-shadow color */
         focusShadow?: string;
     };
 }

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

@@ -1,3 +1,3 @@
 import { RadioGroupProps } from './types';
-declare const RadioGroup: ({ name, isRequired, externalState, onChange, children, className, }: RadioGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const RadioGroup: ({ name, isRequired, externalState, onChange, children, className, color, }: RadioGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default RadioGroup;

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

@@ -1 +1,2 @@
 export { default } from './RadioGroup';
+export type * from './types';

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>;
+}