@ssa-ui-kit/core 2.33.0 → 3.0.0

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

@@ -1,53 +1,243 @@
 import { CommonProps } from '../../types/emotion';
 import { FieldError } from 'react-hook-form';
+/**
+ * Allowed value types for Typeahead options
+ */
 export type TypeaheadValue = string | number;
+/**
+ * Props for TypeaheadOption component
+ * Record type that allows any string or number properties.
+ * Common properties include: value, label, children, avatar, etc.
+ */
 export type TypeaheadOptionProps = Record<string, TypeaheadValue>;
+/**
+ * Props for the Typeahead component
+ *
+ * An advanced autocomplete component with search-as-you-type functionality.
+ * Supports single and multiple selection, filtering, custom rendering, and
+ * React Hook Form integration for validation.
+ *
+ * @example
+ * ```tsx
+ * <Typeahead
+ *   name="language"
+ *   label="Language"
+ *   placeholder="Select language"
+ *   validationSchema={{ required: 'Required' }}>
+ *   {options.map(opt => (
+ *     <TypeaheadOption key={opt.id} value={opt.id} label={opt.name}>
+ *       {opt.name}
+ *     </TypeaheadOption>
+ *   ))}
+ * </Typeahead>
+ * ```
+ */
 export interface TypeaheadProps {
+    /**
+     * Controlled selected items (array of values)
+     * When provided, controls the selected items externally
+     */
     selectedItems?: Array<TypeaheadValue>;
+    /**
+     * Default selected items for uncontrolled mode
+     */
     defaultSelectedItems?: Array<TypeaheadValue>;
+    /**
+     * Enable multiple selection mode
+     * When true, allows selecting multiple options
+     * @default false
+     */
     isMultiple?: boolean;
+    /**
+     * Whether the component is disabled
+     * Disabled typeahead cannot be interacted with
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * TypeaheadOption components as children
+     * Each child should be a TypeaheadOption component
+     */
     children?: React.ReactNode;
+    /**
+     * Custom CSS class name for the trigger input
+     */
     className?: string;
+    /**
+     * Custom CSS class name for the popover container
+     */
     popoverClassName?: string;
+    /**
+     * Custom CSS class name for the options list
+     */
     optionsClassName?: string;
+    /**
+     * Custom CSS class name for the wrapper container
+     */
     wrapperClassName?: string;
+    /**
+     * Width of the component
+     * Can be a number (pixels) or string (CSS value)
+     * @default 300
+     */
     width?: string | number;
+    /**
+     * Controlled open state
+     * When provided, controls dropdown open/closed state externally
+     */
     isOpen?: boolean;
+    /**
+     * Icon or element to display at the start of the input
+     */
     startIcon?: React.ReactNode;
+    /**
+     * Icon or element to display at the end of the input
+     */
     endIcon?: React.ReactNode;
+    /**
+     * Custom CSS class name for the start icon
+     */
     startIconClassName?: string;
+    /**
+     * Custom CSS class name for the end icon
+     */
     endIconClassName?: string;
+    /**
+     * Form field name (required for React Hook Form integration)
+     * @default 'typeahead-search'
+     */
     name?: string;
+    /**
+     * Label text displayed above the input
+     */
     label?: string;
+    /**
+     * Helper text displayed below the input
+     */
     helperText?: string;
+    /**
+     * Field error from React Hook Form
+     */
     error?: FieldError;
+    /**
+     * Whether to show success state
+     * @default false
+     */
     success?: boolean;
+    /**
+     * Validation schema for React Hook Form
+     * Used for form validation rules
+     */
     validationSchema?: Record<string, unknown>;
+    /**
+     * Placeholder text for the input
+     * @default 'Select something'
+     */
     placeholder?: string | null;
+    /**
+     * Whether to filter options based on input
+     * When false, all options are always shown
+     * @default true
+     */
     filterOptions?: boolean;
+    /**
+     * Whether to automatically select the first option on filter
+     * @default true
+     */
     autoSelect?: boolean;
+    /**
+     * Allow adding custom values not in the options list.
+     * When true, the current input is shown as the first dropdown option (highlighted)
+     * and can be selected or added with Enter.
+     * @default true
+     */
+    allowCustomValues?: boolean;
+    /**
+     * Callback fired when an option is selected/deselected
+     * Receives the selected item value and whether it's selected
+     */
     onChange?: (selectedItem: TypeaheadValue, isSelected: boolean) => void;
+    /**
+     * Callback fired when "Clear All" is clicked (multiple mode)
+     */
     onClearAll?: () => void;
+    /**
+     * Callback fired when a selected item's remove button is clicked
+     * Receives the item value to be removed
+     */
     onRemoveSelectedClick?: (selectedItem: TypeaheadValue) => void;
+    /**
+     * Callback fired when the selection becomes empty or non-empty
+     * Receives a boolean indicating if selection is empty
+     */
     onEmptyChange?: (isEmpty?: boolean) => void;
+    /**
+     * Custom render function for options
+     * Allows customizing the appearance of each option
+     * Receives value, input text, and label
+     */
     renderOption?: (data: {
         value: string | number;
         input: string;
         label: string;
     }) => React.ReactNode;
 }
-export type UseTypeaheadProps = Pick<TypeaheadProps, 'selectedItems' | 'defaultSelectedItems' | 'isDisabled' | 'children' | 'isMultiple' | 'onChange' | 'onClearAll' | 'onRemoveSelectedClick' | 'onEmptyChange' | 'renderOption' | 'isOpen' | 'className' | 'startIcon' | 'endIcon' | 'startIconClassName' | 'endIconClassName' | 'name' | 'validationSchema' | 'error' | 'success' | 'placeholder' | 'filterOptions' | 'autoSelect'>;
+/**
+ * Props used by the useTypeahead hook
+ * Internal type that picks specific props from TypeaheadProps
+ */
+export type UseTypeaheadProps = Pick<TypeaheadProps, 'selectedItems' | 'defaultSelectedItems' | 'isDisabled' | 'children' | 'isMultiple' | 'onChange' | 'onClearAll' | 'onRemoveSelectedClick' | 'onEmptyChange' | 'renderOption' | 'isOpen' | 'className' | 'startIcon' | 'endIcon' | 'startIconClassName' | 'endIconClassName' | 'name' | 'validationSchema' | 'error' | 'success' | 'placeholder' | 'filterOptions' | 'autoSelect' | 'allowCustomValues'>;
+/**
+ * Props for TypeaheadOptions container component
+ */
 export interface TypeaheadItemsListProps extends CommonProps {
     children?: React.ReactNode;
     noItemsMessage?: string;
 }
+/**
+ * Props for TypeaheadOption component
+ */
 export interface TypeaheadItemProps extends CommonProps {
+    /**
+     * Whether this option is currently selected
+     */
     isActive?: boolean;
+    /**
+     * Whether this option is disabled
+     */
     isDisabled?: boolean;
+    /**
+     * Value of the option (must be unique)
+     */
     value?: string | number;
+    /**
+     * Label text for the option
+     * Used for filtering and display
+     */
     label?: string | number;
+    /**
+     * Content to display in the option
+     * Can be custom React nodes
+     */
     children?: React.ReactNode;
+    /**
+     * Avatar or icon to display before the option content
+     */
     avatar?: React.ReactNode;
+    /**
+     * Click handler for the option
+     */
     onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+    /**
+     * When true, option is a user-typed custom value (shown first, highlighted in blue)
+     */
+    isCustomValue?: boolean;
+    /**
+     * ARIA role for the option (e.g. 'option')
+     */
+    role?: string;
+    /**
+     * ARIA selected state
+     */
+    'aria-selected'?: boolean;
 }

package/dist/components/Typeahead/useTypeahead.d.ts

@@ -1,16 +1,21 @@
 import React from 'react';
 import { OpenChangeReason } from '@floating-ui/react';
 import { TypeaheadOptionProps, TypeaheadValue, UseTypeaheadProps } from './types';
-export declare const useTypeahead: ({ name, isOpen: isInitOpen, selectedItems: providedSelectedItems, defaultSelectedItems, isDisabled, isMultiple, children, className, startIcon, endIcon, startIconClassName, endIconClassName, validationSchema, error, success, placeholder, filterOptions, autoSelect, onChange, onClearAll, onRemoveSelectedClick, onEmptyChange, renderOption, }: UseTypeaheadProps) => {
+type HandleChangeParams = {
+    value?: string | number;
+    shouldClose?: boolean;
+    resetInput?: boolean;
+};
+export declare const useTypeahead: ({ name, isOpen: isInitOpen, selectedItems: providedSelectedItems, defaultSelectedItems, isDisabled, isMultiple, children, className, startIcon, endIcon, startIconClassName, endIconClassName, validationSchema, error, success, placeholder, filterOptions, autoSelect, allowCustomValues, onChange, onClearAll, onRemoveSelectedClick, onEmptyChange, renderOption, }: UseTypeaheadProps) => {
     isOpen: boolean;
     isDisabled: boolean | undefined;
     optionsWithKey: Record<string | number, TypeaheadOptionProps>;
     selectedItems: TypeaheadValue[];
-    inputRef: React.RefObject<HTMLInputElement>;
+    inputRef: React.RefObject<HTMLInputElement | null>;
     firstSuggestion: string;
     isMultiple: boolean | undefined;
     typeaheadId: string;
-    triggerRef: React.RefObject<HTMLDivElement>;
+    triggerRef: React.RefObject<HTMLDivElement | null>;
     className: string | undefined;
     startIcon: React.ReactNode;
     endIcon: React.ReactNode;
@@ -23,8 +28,10 @@ export declare const useTypeahead: ({ name, isOpen: isInitOpen, selectedItems: p
     status: "error" | "success" | "basic";
     error: import("react-hook-form").FieldError | import("react-hook-form").Merge<import("react-hook-form").FieldError, import("react-hook-form").FieldErrorsImpl<any>> | undefined;
     placeholder: string | null | undefined;
-    options: (React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null)[];
-    useFormResult: import("react-hook-form").UseFormReturn<import("react-hook-form").FieldValues, any, undefined>;
+    options: (React.ReactElement<any, string | React.JSXElementConstructor<any>> | null)[];
+    customOptionValue: string | null;
+    handleChange: ({ value, shouldClose, resetInput, }: HandleChangeParams) => void;
+    useFormResult: import("react-hook-form").UseFormReturn<import("react-hook-form").FieldValues, any, import("react-hook-form").FieldValues>;
     register: import("react-hook-form").UseFormRegister<import("react-hook-form").FieldValues>;
     setValue: import("react-hook-form").UseFormSetValue<import("react-hook-form").FieldValues>;
     onChange: ((selectedItem: TypeaheadValue, isSelected: boolean) => void) | undefined;
@@ -36,3 +43,4 @@ export declare const useTypeahead: ({ name, isOpen: isInitOpen, selectedItems: p
     handleRemoveSelectedClick: (value: string | number) => (e: React.MouseEvent) => void;
 };
 export type UseTypeaheadResult = ReturnType<typeof useTypeahead>;
+export {};

package/dist/components/Typography/Typography.d.ts

@@ -1,3 +1,53 @@
 import { TypographyProps } from './types';
+/**
+ * Typography - Text typography component with semantic variants
+ *
+ * A flexible typography component that provides consistent text styling across
+ * the application. Supports semantic HTML variants (headings, body text, captions)
+ * with customizable font weights, colors, and spacing. Automatically renders
+ * appropriate HTML elements based on variant while allowing semantic override.
+ *
+ * @category Components
+ * @subcategory Display
+ *
+ * @example
+ * ```tsx
+ * // Heading
+ * <Typography variant="h1">Main Title</Typography>
+ * <Typography variant="h2">Section Title</Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Body text
+ * <Typography variant="body1">
+ *   This is regular body text
+ * </Typography>
+ * <Typography variant="body2" weight="bold" color="#333">
+ *   This is bold, darker body text
+ * </Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Semantic override
+ * <Typography variant="h2" as="h1">
+ *   Looks like h2 but semantically is h1
+ * </Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With gutter for spacing
+ * <Typography variant="body1" gutter>
+ *   This text has bottom margin
+ * </Typography>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic HTML elements by default
+ * - Supports proper heading hierarchy
+ * - Respects user font size preferences
+ */
 declare const Typography: import("react").ForwardRefExoticComponent<Omit<TypographyProps, "ref"> & import("react").RefAttributes<HTMLElement>>;
 export default Typography;

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

@@ -1,11 +1,78 @@
+/**
+ * Props for the Typography component
+ *
+ * Text typography component with semantic variants, font weights, and customizable
+ * styling. Renders appropriate HTML elements based on variant while allowing
+ * custom element override via `as` prop. Supports all standard typography variants
+ * from headings to body text and captions.
+ *
+ * @example
+ * ```tsx
+ * // Heading variant
+ * <Typography variant="h1">Main Title</Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Body text with custom styling
+ * <Typography variant="body1" weight="bold" color="#333">
+ *   Important text
+ * </Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Semantic override
+ * <Typography variant="h2" as="h1">
+ *   Looks like h2, but renders as h1
+ * </Typography>
+ * ```
+ */
 export interface TypographyProps {
+    /**
+     * Typography variant determining size, line-height, and semantic HTML element
+     * - `h1`-`h6`: Heading variants (renders as h1-h6)
+     * - `subtitle`: Subtitle text (renders as h6)
+     * - `body1`-`body3`: Body text variants (renders as p)
+     * - `caption`: Caption/small text (renders as span)
+     * @default 'body1'
+     */
     variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle' | 'body1' | 'body2' | 'body3' | 'caption';
+    /**
+     * Font weight variant
+     * @default 'regular'
+     */
     weight?: 'lighter' | 'regular' | 'medium' | 'bold';
+    /**
+     * Whether to add bottom margin (gutter)
+     * Useful for spacing between typography elements
+     * @default false
+     */
     gutter?: boolean;
+    /**
+     * Text color (CSS color value)
+     * @default 'rgba(43, 45, 49, 1)'
+     */
     color?: string;
+    /**
+     * Text content to display
+     */
     children: React.ReactNode;
+    /**
+     * Override the HTML element type
+     * Allows semantic HTML override (e.g., h2 variant as h1 element)
+     */
     as?: React.ElementType;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
+    /**
+     * Ref to the rendered element
+     */
     ref?: React.Ref<HTMLElement>;
+    /**
+     * HTML id attribute
+     */
     id?: string;
 }

package/dist/components/UserProfile/UserProfile.d.ts

@@ -1,2 +1,78 @@
 import { UserProfileProps } from './types';
+/**
+ * UserProfile - User profile dropdown with logout functionality
+ *
+ * A user profile component that displays user information (name, email) and a
+ * logout button in a popover dropdown. Supports custom trigger elements, additional
+ * information display, and custom content sections. Uses Popover component for
+ * positioning and interactions.
+ *
+ * Component structure:
+ * - UserProfile (main component)
+ *   - Popover (wrapper with positioning)
+ *     - PopoverTrigger (custom trigger element)
+ *     - PopoverContent (profile content)
+ *       - UserInfo (name, email, additional info)
+ *       - CustomContent (optional custom section)
+ *       - LogoutButton (logout action)
+ *
+ * @category Components
+ * @subcategory Navigation
+ *
+ * @example
+ * ```tsx
+ * // Basic user profile with icon trigger
+ * <UserProfile
+ *   name="John Doe"
+ *   email="john.doe@example.com"
+ *   trigger={<Icon name="user" size={32} />}
+ *   onClick={() => handleLogout()}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With avatar trigger and additional info
+ * <UserProfile
+ *   name="Jane Smith"
+ *   email="jane@example.com"
+ *   trigger={<Avatar src="/avatar.jpg" size={40} />}
+ *   onClick={handleLogout}
+ *   additionalInfo={[
+ *     <Typography key="role">Administrator</Typography>,
+ *     <Typography key="department">Engineering</Typography>,
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom content section
+ * <UserProfile
+ *   name="Bob Johnson"
+ *   email="bob@example.com"
+ *   trigger={<Button variant="secondary">Profile</Button>}
+ *   onClick={handleLogout}
+ *   customContent={
+ *     <div css={{ padding: '12px', borderTop: '1px solid #eee' }}>
+ *       <Button onClick={handleSettings} variant="secondary">
+ *         Settings
+ *       </Button>
+ *     </div>
+ *   }
+ *   logOutText="Sign Out"
+ * />
+ * ```
+ *
+ * @see {@link Popover} - Used for dropdown positioning and interactions
+ * @see {@link Icon} - Common trigger element
+ * @see {@link Avatar} - Common trigger element
+ *
+ * @accessibility
+ * - ARIA attributes via Popover component
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ * - Proper focus management
+ * - Semantic heading structure
+ */
 export declare const UserProfile: ({ name, email, trigger, onClick, logOutText, className, additionalInfo, customContent, }: UserProfileProps) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -8,8 +8,9 @@ export declare const AdditionalInfoWrapper: import("@emotion/styled").StyledComp
     theme?: Theme;
     as?: React.ElementType;
 } & {
-    direction?: string;
-    alignItems?: string;
+    direction?: import("../Wrapper").WrapperDirection;
+    alignItems?: import("../Wrapper").WrapperAlignItems;
+    justifyContent?: import("../Wrapper").WrapperJustifyContent;
     fade?: boolean;
     fadeDelay?: number;
     isVisible?: boolean;
@@ -20,8 +21,9 @@ export declare const CustomContentWrapper: import("@emotion/styled").StyledCompo
     theme?: Theme;
     as?: React.ElementType;
 } & {
-    direction?: string;
-    alignItems?: string;
+    direction?: import("../Wrapper").WrapperDirection;
+    alignItems?: import("../Wrapper").WrapperAlignItems;
+    justifyContent?: import("../Wrapper").WrapperJustifyContent;
     fade?: boolean;
     fadeDelay?: number;
     isVisible?: boolean;

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

@@ -1,11 +1,95 @@
 import { ReactNode } from 'react';
+/**
+ * Props for the UserProfile component
+ *
+ * A user profile dropdown component that displays user information and a logout
+ * button in a popover. Supports custom trigger elements, additional info, and
+ * custom content sections.
+ *
+ * @example
+ * ```tsx
+ * // Basic user profile
+ * <UserProfile
+ *   name="John Doe"
+ *   email="john.doe@example.com"
+ *   trigger={<Icon name="user" size={32} />}
+ *   onClick={() => handleLogout()}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With additional info
+ * <UserProfile
+ *   name="Jane Smith"
+ *   email="jane@example.com"
+ *   trigger={<Avatar src="/avatar.jpg" />}
+ *   onClick={handleLogout}
+ *   additionalInfo={[
+ *     <Typography key="role">Administrator</Typography>,
+ *     <Typography key="org">Acme Corp</Typography>,
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom content
+ * <UserProfile
+ *   name="Bob Johnson"
+ *   email="bob@example.com"
+ *   trigger={<Button>Profile</Button>}
+ *   onClick={handleLogout}
+ *   customContent={
+ *     <div>
+ *       <Button onClick={handleSettings}>Settings</Button>
+ *       <Button onClick={handlePreferences}>Preferences</Button>
+ *     </div>
+ *   }
+ *   logOutText="Sign Out"
+ * />
+ * ```
+ */
 export interface UserProfileProps {
+    /**
+     * User's full name
+     * Displayed as heading in the profile popover
+     */
     name: string;
+    /**
+     * User's email address
+     * Displayed as description text in the profile popover
+     */
     email: string;
-    trigger: string | JSX.Element;
+    /**
+     * Trigger element that opens the profile popover
+     * Can be a string, icon, avatar, button, or any React element
+     */
+    trigger: string | React.JSX.Element;
+    /**
+     * Callback function when logout button is clicked
+     * Typically handles user logout logic
+     */
     onClick: () => void;
+    /**
+     * Text for the logout button
+     * @default 'Log Out'
+     */
     logOutText?: string;
+    /**
+     * Custom CSS class name for the popover content
+     */
     className?: string;
+    /**
+     * Array of additional information elements
+     * Displayed between email and custom content sections
+     * Each element is rendered in a wrapper div
+     */
     additionalInfo?: ReactNode[];
+    /**
+     * Custom content section
+     * Displayed between user info and logout button
+     * Useful for additional actions or information
+     */
     customContent?: ReactNode;
 }

package/dist/components/WidgetCard/Title.d.ts

@@ -1,3 +1,3 @@
-export declare const WidgetCardTitle: import("@emotion/styled").StyledComponent<Omit<import("../Typography/types").TypographyProps, "ref"> & import("react").RefAttributes<HTMLElement> & {
+export declare const WidgetCardTitle: import("@emotion/styled").StyledComponent<Omit<import("..").TypographyProps, "ref"> & import("react").RefAttributes<HTMLElement> & {
     theme?: import("@emotion/react").Theme;
 }, {}, {}>;

package/dist/components/WidgetCard/WidgetCardBase.d.ts

@@ -1,4 +1,4 @@
-export declare const WidgetCardBase: import("@emotion/styled").StyledComponent<import("../Card/types").CardProps & {
+export declare const WidgetCardBase: import("@emotion/styled").StyledComponent<import("..").CardProps & {
     theme?: import("@emotion/react").Theme;
 } & {
     isFullscreenMode?: boolean;

package/dist/components/WithLink.d.ts

@@ -4,4 +4,4 @@ export declare const WithLink: ({ link, onClick, children, className, }: {
     className?: string;
     onClick?: () => void;
     link?: To;
-}) => string | number | boolean | Iterable<import("react").ReactNode> | import("@emotion/react/jsx-runtime").JSX.Element | null | undefined;
+}) => string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("@emotion/react/jsx-runtime").JSX.Element | null | undefined;