@ssa-ui-kit/core 2.33.0 → 3.1.0

package/dist/components/TextField/TextField.d.ts

@@ -1,3 +1,79 @@
 import { TextFieldProps } from './types';
+/**
+ * TextField - Ready-to-use text input (single- or multi-line) with label and validation UI.
+ *
+ * Purpose: one component for text inputs with built-in label, helper text, validation
+ * error/success display, and optional character counting. Renders as Input or Textarea
+ * based on the `multirow` prop. Automatically manages status (basic, error, success)
+ * from props. Use when you want a complete text field without composing Field primitives;
+ * use Field when you need custom layout or non-text controls.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Single-line text field
+ * const { register } = useForm();
+ * <TextField
+ *   name="username"
+ *   label="Username"
+ *   placeholder="Enter your username"
+ *   register={register}
+ *   helperText="Choose a unique username"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-line text field with character count
+ * <TextField
+ *   name="description"
+ *   label="Description"
+ *   multirow
+ *   rows={5}
+ *   maxLength={500}
+ *   register={register}
+ *   helperText="Tell us about yourself"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text field with validation errors
+ * <TextField
+ *   name="email"
+ *   label="Email Address"
+ *   register={register}
+ *   errors={errors.email}
+ *   helperText="We'll never share your email"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Success state
+ * <TextField
+ *   name="username"
+ *   label="Username"
+ *   register={register}
+ *   success={isValid}
+ *   helperText="Username is available!"
+ * />
+ * ```
+ *
+ * @see {@link Input} - For single-line input component
+ * @see {@link Textarea} - For multi-line textarea component
+ * @see {@link Field} - For more advanced field layout with Field.Root
+ *
+ * @note React Hook Form integration is optional. If `register` is not provided,
+ * the component will still work but validation features will be unavailable.
+ *
+ * @accessibility
+ * - Full keyboard navigation support
+ * - Screen reader friendly with proper labels
+ * - ARIA attributes via React Hook Form (when register is provided)
+ * - Error messages announced to screen readers
+ */
 declare const TextField: ({ multirow, name, label, errors, helperText, success, disabled, maxLength, ...props }: TextFieldProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default TextField;

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

@@ -1,11 +1,91 @@
 import type { UseFormReturn, FieldError } from 'react-hook-form';
 import { InputProps } from '../Input/types';
+/**
+ * Props for the TextField component
+ *
+ * A unified text input component that can render as either a single-line Input
+ * or multi-line Textarea based on the `multirow` prop. Includes built-in label,
+ * helper text, error handling, and character counting. Automatically switches
+ * between Input and Textarea components while maintaining consistent API.
+ *
+ * @example
+ * ```tsx
+ * // Single-line text field
+ * const { register } = useForm();
+ * <TextField
+ *   name="username"
+ *   label="Username"
+ *   placeholder="Enter your username"
+ *   register={register}
+ *   helperText="Choose a unique username"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-line text field
+ * <TextField
+ *   name="description"
+ *   label="Description"
+ *   multirow
+ *   rows={5}
+ *   maxLength={500}
+ *   register={register}
+ *   helperText="Maximum 500 characters"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text field with validation
+ * <TextField
+ *   name="email"
+ *   label="Email"
+ *   register={register}
+ *   errors={errors.email}
+ *   helperText="We'll never share your email"
+ * />
+ * ```
+ *
+ * @note React Hook Form integration is optional. If `register` is not provided,
+ * the component will still work but validation features will be unavailable.
+ */
 export interface TextFieldProps extends InputProps, Partial<Pick<UseFormReturn, 'register'>> {
+    /**
+     * Label text displayed above the input field
+     */
     label?: string;
+    /**
+     * React Hook Form field error object
+     * Used to display validation error messages
+     */
     errors?: FieldError;
+    /**
+     * Whether to display success state styling
+     * When true, status is set to 'success'
+     * @default false
+     */
     success?: boolean;
+    /**
+     * Helper text displayed below the input
+     * Shown when no errors are present
+     */
     helperText?: string;
+    /**
+     * Number of rows for multi-row text fields
+     * Only applies when `multirow` is true
+     * @default undefined (uses Textarea default)
+     */
     rows?: number;
+    /**
+     * Whether to render as multi-line textarea
+     * When true, uses Textarea component; when false, uses Input component
+     * @default false
+     */
     multirow?: boolean;
+    /**
+     * Maximum character length
+     * When provided, displays character count (e.g., "45 / 500")
+     */
     maxLength?: number;
 }

package/dist/components/Textarea/Textarea.d.ts

@@ -1,4 +1,85 @@
 import React from 'react';
 import { TextareaProps } from './types';
+/**
+ * Textarea - Multi-line text input component
+ *
+ * A textarea component with React Hook Form integration, validation support,
+ * character limits, and paste handling. Designed for longer text input such as
+ * comments, descriptions, messages, or any multi-line content.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Basic textarea with React Hook Form
+ * const { register } = useForm();
+ * <Textarea
+ *   name="message"
+ *   placeholder="Enter your message"
+ *   register={register}
+ *   rows={5}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Textarea with validation and character limit
+ * const { register } = useForm();
+ * const [charCount, setCharCount] = useState(0);
+ *
+ * <Textarea
+ *   name="description"
+ *   placeholder="Describe your project..."
+ *   register={register}
+ *   validationSchema={{
+ *     required: 'Description is required',
+ *     maxLength: { value: 500, message: 'Maximum 500 characters' }
+ *   }}
+ *   maxLength={500}
+ *   rows={8}
+ *   setCountChar={(e) => setCharCount(e.target.value.length)}
+ * />
+ * <span>{charCount} / 500 characters</span>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with Field component
+ * <Field.Root>
+ *   <Field.Label htmlFor="comments">Comments</Field.Label>
+ *   <Field.Control>
+ *     <Textarea
+ *       id="comments"
+ *       name="comments"
+ *       register={register}
+ *       rows={6}
+ *       css={{ width: '100%', border: '0 !important' }}
+ *     />
+ *   </Field.Control>
+ *   <Field.Description>Optional feedback or notes</Field.Description>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Standalone textarea without React Hook Form
+ * <Textarea
+ *   name="notes"
+ *   placeholder="Enter notes..."
+ *   rows={5}
+ *   onChange={(e) => handleChange(e.target.value)}
+ * />
+ * ```
+ *
+ * @see {@link Field} - Use Field.Root to wrap Textarea for labels and validation
+ * @see {@link Input} - For single-line text input
+ *
+ * @accessibility
+ * - Full keyboard navigation support
+ * - Screen reader friendly
+ * - ARIA attributes via React Hook Form (when register is provided)
+ * - Respects disabled and readOnly states
+ */
 declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
 export default Textarea;

package/dist/components/Textarea/TextareaBase.d.ts

@@ -1,4 +1,9 @@
+import type { Theme } from '@emotion/react';
+type TextareaStatus = 'basic' | 'error' | 'success' | 'custom';
 export declare const TextareaBase: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme;
+    theme?: Theme;
     as?: React.ElementType;
+} & {
+    status?: TextareaStatus;
 }, import("react").DetailedHTMLProps<import("react").TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, {}>;
+export {};

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

@@ -1,16 +1,125 @@
 import { ReactEventHandler } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
+/**
+ * Props for the Textarea component
+ *
+ * A multi-line text input component with React Hook Form integration and validation.
+ * Supports character limits, paste handling, and all standard textarea features.
+ *
+ * @example
+ * ```tsx
+ * // Basic textarea with React Hook Form
+ * const { register } = useForm();
+ * <Textarea
+ *   name="message"
+ *   placeholder="Enter your message"
+ *   register={register}
+ *   rows={5}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Textarea with validation and character limit
+ * <Textarea
+ *   name="description"
+ *   register={register}
+ *   validationSchema={{
+ *     required: 'Description is required',
+ *     maxLength: { value: 500, message: 'Maximum 500 characters' }
+ *   }}
+ *   maxLength={500}
+ *   rows={10}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Read-only textarea
+ * <Textarea
+ *   name="readonly-content"
+ *   register={register}
+ *   readOnly
+ *   rows={8}
+ * />
+ * ```
+ *
+ * @note React Hook Form integration is optional. If `register` is not provided,
+ * the component will still work but validation features will be unavailable.
+ */
 export interface TextareaProps extends Partial<Pick<UseFormReturn, 'register'>> {
+    /**
+     * Name attribute for the textarea, required for React Hook Form integration
+     */
     name: string;
+    /**
+     * Placeholder text displayed when textarea is empty
+     */
     placeholder?: string;
+    /**
+     * React Hook Form validation schema
+     * Object containing validation rules (required, maxLength, pattern, etc.)
+     */
     validationSchema?: Record<string, unknown>;
+    /**
+     * Whether the textarea is disabled
+     * Disabled textarea elements cannot be edited
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Whether the textarea is read-only
+     * Read-only textarea elements can be focused and scrolled but not edited
+     * @default false
+     */
     readOnly?: boolean;
+    /**
+     * Number of visible text rows
+     * Determines the initial height of the textarea
+     * @default 10
+     */
     rows?: number;
+    /**
+     * Maximum character length for the textarea
+     * Use with setCountChar callback to track character count
+     */
     maxLength?: number;
+    /**
+     * Visual validation status (aligns with Input/TextField palette behavior).
+     * - `basic`: default border/outline (theme.colors grey)
+     * - `error`: error state (theme.palette.error)
+     * - `success`: success state (theme.palette.success)
+     * - `custom`: same as basic (no palette styling)
+     * @default 'basic'
+     */
+    status?: 'basic' | 'error' | 'success' | 'custom';
+    /**
+     * Custom element type to render as (for composition)
+     */
     as?: React.ElementType;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Title attribute for the textarea element
+     * Provides tooltip text on hover
+     */
     title?: string;
+    /**
+     * HTML id attribute for the textarea (e.g. for label htmlFor).
+     * Defaults to `formElement-${name}` when not provided.
+     */
+    id?: string;
+    /**
+     * Paste event handler
+     * Fired when content is pasted into the textarea
+     */
     onPaste?: React.ClipboardEventHandler<HTMLTextAreaElement>;
+    /**
+     * Callback function to track character count
+     * Called with the event when content changes
+     * Useful for displaying character count UI
+     */
     setCountChar?: ReactEventHandler;
 }

package/dist/components/Tooltip/SimpleChartTooltip.d.ts

@@ -1,2 +1,3 @@
+import { LineSeries } from '@nivo/line';
 import { SimpleChartTooltipProps } from './types';
-export declare const SimpleChartTooltip: ({ point, size, renderValue, }: SimpleChartTooltipProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const SimpleChartTooltip: <Series extends LineSeries>({ point, size, renderValue, }: SimpleChartTooltipProps<Series>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Tooltip/Tooltip.d.ts

@@ -1,3 +1,76 @@
 import { TooltipProps } from './types';
+/**
+ * Tooltip - Contextual information component
+ *
+ * A flexible tooltip system built on Floating UI that provides contextual
+ * information when users interact with trigger elements. Uses a compound
+ * component pattern with Tooltip (root), TooltipTrigger (activator), and
+ * TooltipContent (display).
+ *
+ * Supports multiple interaction modes (hover, click, follow cursor), flexible
+ * positioning with auto-adjustment, and customizable appearance with size
+ * variants and optional arrows.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * // Basic tooltip on hover
+ * <Tooltip>
+ *   <TooltipTrigger>
+ *     <Button>Hover me</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>This is helpful information</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with custom placement
+ * <Tooltip placement="bottom" size="large">
+ *   <TooltipTrigger>
+ *     <Icon name="info" />
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <div>
+ *       <strong>Detailed Information</strong>
+ *       <p>This is a larger tooltip with more content</p>
+ *     </div>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Click-to-open tooltip
+ * <Tooltip enableClick enableHover={false}>
+ *   <TooltipTrigger>
+ *     <Button>Click for info</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>Information that appears on click</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip without arrow
+ * <Tooltip hasArrow={false}>
+ *   <TooltipTrigger>
+ *     <span>?</span>
+ *   </TooltipTrigger>
+ *   <TooltipContent>No arrow tooltip</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @see {@link TooltipTrigger} - Trigger element component
+ * @see {@link TooltipContent} - Content display component
+ *
+ * @accessibility
+ * - Keyboard accessible (ESC to close)
+ * - Focus management for click-triggered tooltips
+ * - ARIA attributes automatically applied
+ * - Screen reader friendly
+ */
 declare const Tooltip: ({ children, ...props }: TooltipProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Tooltip;

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

@@ -1,30 +1,110 @@
 import { useInteractions, FloatingArrow, Placement, UseFloatingReturn, OffsetOptions } from '@floating-ui/react';
-import { PointTooltipProps, Point } from '@nivo/line';
+import { PointTooltipProps, Point, LineSeries } from '@nivo/line';
 import { MapIconsType } from '../Icon/types';
 import { ProgressBarProps } from '../ProgressBar/types';
 import { SerializedStyles } from '@emotion/react';
 import { CommonProps } from '../../types/emotion';
+/**
+ * Size variant for tooltip content
+ * - `small`: Compact tooltip with minimal padding
+ * - `medium`: Standard tooltip size (default)
+ * - `large`: Larger tooltip for more content
+ */
 export type TooltipSize = 'small' | 'medium' | 'large';
+/**
+ * Props for the Tooltip component
+ *
+ * Root container component for tooltip system using compound component pattern.
+ * Provides context and positioning configuration for TooltipTrigger and TooltipContent.
+ * Built on Floating UI for flexible positioning and interaction modes.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip placement="top">
+ *   <TooltipTrigger>
+ *     <Button>Hover me</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>This is a tooltip</TooltipContent>
+ * </Tooltip>
+ * ```
+ */
 export interface TooltipProps extends CommonProps {
+    /**
+     * TooltipTrigger and TooltipContent components
+     * Must include both TooltipTrigger and TooltipContent as children
+     */
     children: React.ReactNode;
+    /**
+     * Preferred placement of the tooltip relative to trigger
+     * Floating UI will auto-adjust if space is insufficient
+     */
     placement?: Placement;
+    /**
+     * Enable tooltip on hover interaction
+     * @default true
+     */
     enableHover?: boolean;
+    /**
+     * Enable tooltip on click interaction
+     * @default false
+     */
     enableClick?: boolean;
+    /**
+     * Enable tooltip to follow client point (mouse position)
+     * Useful for interactive tooltips like charts
+     * @default false
+     */
     enableClientPoint?: boolean;
+    /**
+     * Offset configuration for tooltip positioning
+     * Allows fine-tuning of spacing from trigger element
+     */
     offsetOptions?: OffsetOptions;
+    /**
+     * Allow hovering over tooltip content itself
+     * When true, tooltip stays open when hovering over content
+     * @default false
+     */
     allowHoverContent?: boolean;
+    /**
+     * Delay in milliseconds before tooltip appears on hover
+     * Helps prevent "traffic light" effect when quickly moving through multiple tooltips
+     * @default 0
+     */
+    hoverOpenDelay?: number;
+    /**
+     * Delay in milliseconds before tooltip disappears after mouse leaves
+     * Helps prevent tooltip from flickering when moving between trigger and content
+     * @default 0
+     */
+    hoverCloseDelay?: number;
+    /**
+     * Size variant of the tooltip content
+     * @default 'medium'
+     */
     size?: TooltipSize;
+    /**
+     * Whether to display arrow pointing to trigger
+     * @default true
+     */
     hasArrow?: boolean;
+    /**
+     * Additional props for the arrow element
+     */
     arrowProps?: TooltipArrowProps;
+    /**
+     * Controlled open state
+     * When provided, controls tooltip visibility externally
+     */
     isOpen?: boolean;
 }
 export type UseTooltipArgs = Omit<TooltipProps, 'children'>;
 type UseInteractions = ReturnType<typeof useInteractions>;
-interface MutableRefObject<T> {
+interface RefObject<T> {
     current: T;
 }
 export type UseTooltip = (props?: UseTooltipArgs) => Pick<TooltipProps, 'size' | 'hasArrow' | 'arrowProps'> & {
-    arrowRef: MutableRefObject<null>;
+    arrowRef: RefObject<null>;
     isOpen: boolean;
     setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
 } & UseFloatingReturn & UseInteractions;
@@ -34,9 +114,26 @@ export type TooltipContextType = (UseFloatingReturn & ReturnType<typeof useInter
     setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
 } & Pick<TooltipProps, 'size' | 'hasArrow' | 'arrowProps'>) | null;
 export type TooltipArrowProps = Omit<React.ComponentProps<typeof FloatingArrow>, 'context'>;
+/**
+ * Props for TooltipContent component
+ *
+ * Content container for tooltip. Renders the actual tooltip content that appears
+ * when the trigger is activated. Supports custom styling and is automatically
+ * positioned using Floating UI.
+ */
 export interface TooltipContentProps {
+    /**
+     * Tooltip content to display
+     * Can be text, React nodes, or formatted content
+     */
     children: React.ReactNode;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Inline styles for the tooltip content
+     */
     style?: React.CSSProperties;
 }
 export interface TooltipContentSizes {
@@ -44,12 +141,26 @@ export interface TooltipContentSizes {
     medium: SerializedStyles;
     large: SerializedStyles;
 }
+/**
+ * Props for TooltipTrigger component
+ *
+ * Trigger element that activates the tooltip. Must be a single React element
+ * (component or DOM element) that will receive the tooltip trigger props.
+ */
 export interface TooltipTriggerProps {
+    /**
+     * Single React element to use as trigger
+     * Can be any element (Button, Icon, div, etc.)
+     * Must be a valid React element (not fragment or array)
+     */
     children: React.ReactNode;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 }
-export type SimpleChartTooltipProps = PointTooltipProps & Pick<TooltipProps, 'size'> & {
-    renderValue?: (data: Point['data']) => React.ReactNode;
+export type SimpleChartTooltipProps<Series extends LineSeries> = PointTooltipProps<Series> & Pick<TooltipProps, 'size'> & {
+    renderValue?: (data: Point<Series>['data']) => React.ReactNode;
 };
 export interface ProgressChartTooltipProps {
     caption: string;

package/dist/components/TooltipContent/TooltipContent.d.ts

@@ -1,3 +1,48 @@
 import { TooltipContentProps } from '../Tooltip/types';
+/**
+ * TooltipContent - Content container for tooltip display
+ *
+ * Renders the actual tooltip content that appears when the trigger is activated.
+ * Uses Floating Portal for proper z-index stacking and FloatingFocusManager for
+ * keyboard accessibility. Automatically positions based on Floating UI context
+ * and respects size variants and arrow configuration.
+ *
+ * Only renders when tooltip is open (isOpen is true). Supports custom styling
+ * and can contain any React content.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger>
+ *     <Button>Info</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     This is the tooltip content
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with custom styling
+ * <TooltipContent style={{ padding: 16, maxWidth: 300 }}>
+ *   <div>
+ *     <strong>Title</strong>
+ *     <p>Detailed description here</p>
+ *   </div>
+ * </TooltipContent>
+ * ```
+ *
+ * @see {@link Tooltip} - Parent component that provides context
+ * @see {@link TooltipTrigger} - Trigger component that activates tooltip
+ *
+ * @accessibility
+ * - Renders in FloatingPortal for proper stacking
+ * - Uses FloatingFocusManager for keyboard navigation
+ * - Only visible when isOpen is true
+ */
 declare const TooltipContent: import("react").ForwardRefExoticComponent<TooltipContentProps & import("react").RefAttributes<HTMLDivElement>>;
 export default TooltipContent;