@ssa-ui-kit/core 2.33.0 → 3.0.0

package/dist/components/AccordionGroup/Accordion.d.ts

@@ -1,2 +1,39 @@
 import { AccordionViewProps } from './types';
+/**
+ * Accordion - Individual accordion item component
+ *
+ * A single accordion item that can be expanded or collapsed. Uses render props pattern
+ * for flexible content and title rendering. Must be used as a child of AccordionGroup.
+ *
+ * The component renders a CardBase with a title header and collapsible content panel.
+ * The open/close state is managed by the parent AccordionGroup through context.
+ *
+ * @category Components
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   id="accordion-1"
+ *   title="Click to expand"
+ *   ariaControls="panel-1"
+ *   isOpened={false}
+ *   renderTitle={AccordionTitle}
+ *   renderContent={(props) => (
+ *     <AccordionContent {...props}>
+ *       <p>Accordion content goes here</p>
+ *     </AccordionContent>
+ *   )}
+ * />
+ * ```
+ *
+ * @see {@link AccordionGroup} - Parent container component
+ * @see {@link AccordionTitle} - Default title render function
+ * @see {@link AccordionContent} - Default content component
+ *
+ * @accessibility
+ * - Uses role="region" for semantic structure
+ * - ARIA controls and labelledby attributes for accessibility
+ * - Keyboard accessible
+ */
 export declare const Accordion: ({ title, isOpened, ariaControls, id, size, contentProps, renderTitle, renderContent, onClick, ...rest }: AccordionViewProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/AccordionGroup/AccordionContent.d.ts

@@ -1,4 +1,52 @@
 import { RenderContentProps } from './types';
+/**
+ * AccordionContent - Default component for accordion content panels
+ *
+ * A pre-built component for rendering accordion content that handles styling
+ * and accessibility attributes. Can be used as the content in `renderContent`
+ * prop for Accordion components, or as a reference for custom content implementations.
+ *
+ * Features:
+ * - Proper ARIA attributes for accessibility
+ * - Size-aware styling
+ * - Smooth expand/collapse transitions
+ * - Accepts any React children
+ *
+ * @category Components
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   id="example"
+ *   title="My Accordion"
+ *   renderTitle={AccordionTitle}
+ *   renderContent={(props) => (
+ *     <AccordionContent {...props}>
+ *       <p>This is the accordion content</p>
+ *       <ul>
+ *         <li>Item 1</li>
+ *         <li>Item 2</li>
+ *       </ul>
+ *     </AccordionContent>
+ *   )}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom content using AccordionContent props
+ * <Accordion
+ *   renderContent={({ isOpened, ...props }) => (
+ *     <div {...props} style={{ display: isOpened ? 'block' : 'none' }}>
+ *       Custom content with conditional rendering
+ *     </div>
+ *   )}
+ * />
+ * ```
+ *
+ * @see {@link Accordion} - Parent component that uses this component
+ */
 export declare const AccordionContent: ({ isOpened, children, size, ...rest }: RenderContentProps & {
     children: React.ReactNode;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/AccordionGroup/AccordionContext.d.ts

@@ -1,6 +1,80 @@
 import { AccordionGroupContextProps } from './types';
+/**
+ * React context for AccordionGroup state management
+ *
+ * Provides state and control functions to accordion components within an AccordionGroup.
+ * Used internally by AccordionGroupContextProvider and accessed via useAccordionGroupContext hook.
+ */
 export declare const AccordionGroupContext: import("react").Context<AccordionGroupContextProps>;
+/**
+ * Hook to access AccordionGroup context
+ *
+ * Returns the AccordionGroup context value including opened accordions state,
+ * toggle functions, and stay-open behavior. Must be used within an AccordionGroupContextProvider.
+ *
+ * @returns AccordionGroupContextProps - Context value with state and control functions
+ * @throws Error if used outside AccordionGroupContextProvider
+ *
+ * @example
+ * ```tsx
+ * function CustomAccordionControl() {
+ *   const { openedAccordions, toggleOpenedAccordion } = useAccordionGroupContext();
+ *
+ *   return (
+ *     <button onClick={() => toggleOpenedAccordion({ id: 'accordion-1' })}>
+ *       Toggle Accordion 1
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link AccordionGroupContextProvider} - Required provider component
+ */
 export declare const useAccordionGroupContext: () => AccordionGroupContextProps;
-export declare const AccordionGroupContextProvider: ({ children, }: {
+/**
+ * Props for AccordionGroupContextProvider
+ */
+export interface AccordionGroupContextProviderProps {
+    /**
+     * Child components that will have access to accordion context
+     * Should include AccordionGroup and Accordion components
+     */
     children: React.ReactNode;
-}) => import("@emotion/react/jsx-runtime").JSX.Element;
+}
+/**
+ * AccordionGroupContextProvider - Context provider for accordion group state
+ *
+ * Provides accordion state management context to all child components.
+ * This provider must wrap any AccordionGroup components to enable state management
+ * and coordination between multiple accordions.
+ *
+ * @category Components
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <AccordionGroupContextProvider>
+ *   <AccordionGroup>
+ *     <Accordion id="1" title="Section 1" renderContent={...} renderTitle={AccordionTitle} />
+ *     <Accordion id="2" title="Section 2" renderContent={...} renderTitle={AccordionTitle} />
+ *   </AccordionGroup>
+ * </AccordionGroupContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple accordion groups in the same provider
+ * <AccordionGroupContextProvider>
+ *   <AccordionGroup size="large">
+ *     <Accordion id="group1-1" ... />
+ *   </AccordionGroup>
+ *   <AccordionGroup size="medium">
+ *     <Accordion id="group2-1" ... />
+ *   </AccordionGroup>
+ * </AccordionGroupContextProvider>
+ * ```
+ *
+ * @see {@link AccordionGroup} - Component that requires this provider
+ * @see {@link useAccordionGroupContext} - Hook to access context
+ */
+export declare const AccordionGroupContextProvider: ({ children, }: AccordionGroupContextProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/AccordionGroup/AccordionGroup.d.ts

@@ -1,2 +1,58 @@
 import { AccordionGroupProps } from './types';
+/**
+ * AccordionGroup - Container component for managing multiple accordion items
+ *
+ * Manages the state and behavior of multiple accordion components within a group.
+ * Supports both single and multiple accordion open modes, and provides size variants
+ * for different visual appearances. Must be used within an AccordionGroupContextProvider.
+ *
+ * Component structure:
+ * - AccordionGroupContextProvider (required wrapper)
+ *   - AccordionGroup (manages accordion state)
+ *     - Accordion (individual accordion items)
+ *       - AccordionTitle (header with toggle)
+ *       - AccordionContent (collapsible content)
+ *
+ * @category Components
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <AccordionGroupContextProvider>
+ *   <AccordionGroup size="large" accordionsStayOpen={true}>
+ *     <Accordion
+ *       id="first"
+ *       title="First Section"
+ *       ariaControls="first-panel"
+ *       renderContent={(props) => (
+ *         <AccordionContent {...props}>
+ *           <p>Content for first section</p>
+ *         </AccordionContent>
+ *       )}
+ *       renderTitle={AccordionTitle}
+ *     />
+ *   </AccordionGroup>
+ * </AccordionGroupContextProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Single accordion open mode
+ * <AccordionGroup size="medium" accordionsStayOpen={false}>
+ *   <Accordion id="1" title="Section 1" renderContent={...} renderTitle={AccordionTitle} />
+ *   <Accordion id="2" title="Section 2" renderContent={...} renderTitle={AccordionTitle} />
+ * </AccordionGroup>
+ * ```
+ *
+ * @see {@link Accordion} - Individual accordion item component
+ * @see {@link AccordionGroupContextProvider} - Required context provider
+ * @see {@link AccordionTitle} - Default title render function
+ * @see {@link AccordionContent} - Default content component
+ *
+ * @accessibility
+ * - ARIA attributes set according to WAI-ARIA accordion pattern
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ * - Proper focus management
+ */
 export declare const AccordionGroup: ({ children, size, accordionsStayOpen, ...rest }: AccordionGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/AccordionGroup/AccordionTitle.d.ts

@@ -1,2 +1,43 @@
 import { AccordionProps } from './types';
+/**
+ * AccordionTitle - Default render function for accordion headers
+ *
+ * A pre-built render function for accordion titles that displays the title text
+ * with an expand/collapse icon indicator. Can be used as the `renderTitle` prop
+ * for Accordion components, or as a reference for custom title implementations.
+ *
+ * Features:
+ * - Displays title text with icon indicator
+ * - Shows carrot-up icon when closed, carrot-down when open
+ * - Proper ARIA attributes for accessibility
+ * - Click handler for toggling accordion state
+ *
+ * @category Components
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   id="example"
+ *   title="My Accordion"
+ *   renderTitle={AccordionTitle}
+ *   renderContent={...}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom title using AccordionTitle as reference
+ * <Accordion
+ *   renderTitle={({ title, isOpened, onClick }) => (
+ *     <button onClick={onClick} aria-expanded={isOpened}>
+ *       <span>{title}</span>
+ *       <Icon name={isOpened ? "chevron-down" : "chevron-right"} />
+ *     </button>
+ *   )}
+ * />
+ * ```
+ *
+ * @see {@link Accordion} - Parent component that uses this render function
+ */
 export declare const AccordionTitle: AccordionProps['renderTitle'];

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

@@ -1,51 +1,249 @@
 import { SerializedStyles } from '@emotion/react';
 import { AriaAttributes } from 'react';
+/**
+ * Size variants for accordion components
+ * Controls visual appearance and spacing
+ */
 export type AccordionSize = 'empty' | 'small' | 'medium' | 'large';
+/**
+ * Style mapping for accordion sizes
+ */
 export type SizeStyles = {
     [K in AccordionSize]: SerializedStyles;
 };
 type AccordionGroupChildren = React.ReactElement<React.PropsWithChildren<AccordionViewProps>>;
+/**
+ * Props for the AccordionGroup component
+ *
+ * A container component that manages multiple accordion items and their open/close state.
+ * Supports both single and multiple accordion open modes, and provides size variants
+ * for different visual appearances.
+ *
+ * @example
+ * ```tsx
+ * <AccordionGroupContextProvider>
+ *   <AccordionGroup size="large" accordionsStayOpen={true}>
+ *     <Accordion
+ *       id="first"
+ *       title="First Accordion"
+ *       ariaControls="first-panel"
+ *       renderContent={(props) => (
+ *         <AccordionContent {...props}>
+ *           <p>Content for first accordion</p>
+ *         </AccordionContent>
+ *       )}
+ *       renderTitle={AccordionTitle}
+ *     />
+ *     <Accordion
+ *       id="second"
+ *       title="Second Accordion"
+ *       ariaControls="second-panel"
+ *       isOpened
+ *       renderContent={(props) => (
+ *         <AccordionContent {...props}>
+ *           <p>Content for second accordion</p>
+ *         </AccordionContent>
+ *       )}
+ *       renderTitle={AccordionTitle}
+ *     />
+ *   </AccordionGroup>
+ * </AccordionGroupContextProvider>
+ * ```
+ */
 export interface AccordionGroupProps {
+    /**
+     * Unique identifier for the accordion group
+     * Used for accessibility and testing purposes
+     */
     id?: string;
+    /**
+     * Accordion components as children
+     * Each child should be an Accordion component
+     */
     children: AccordionGroupChildren | AccordionGroupChildren[];
+    /**
+     * Size variant for the accordion group
+     * Controls padding, spacing, and visual appearance
+     * @default 'empty'
+     */
     size?: AccordionSize;
+    /**
+     * Whether multiple accordions can be open simultaneously
+     * When false, opening one accordion closes others
+     * @default true
+     */
     accordionsStayOpen?: boolean;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 }
+/**
+ * Props for the Accordion component
+ *
+ * An individual accordion item that can be expanded or collapsed.
+ * Uses render props pattern for flexible content and title rendering.
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   id="accordion-1"
+ *   title="Click to expand"
+ *   ariaControls="panel-1"
+ *   isOpened={false}
+ *   renderTitle={AccordionTitle}
+ *   renderContent={(props) => (
+ *     <AccordionContent {...props}>
+ *       <p>Accordion content goes here</p>
+ *     </AccordionContent>
+ *   )}
+ * />
+ * ```
+ */
 export interface AccordionProps {
+    /**
+     * Unique identifier for the accordion
+     * Used for state management and accessibility
+     */
     id: number | string;
+    /**
+     * Size variant for the accordion
+     * Inherits from AccordionGroup if not specified
+     */
     size?: AccordionSize;
+    /**
+     * Render function for the accordion title
+     * Receives title data and control props
+     */
     renderTitle: (data: RenderContentProps & {
         title: string;
         ariaControls?: string;
         onClick?: () => void;
     }) => React.ReactNode;
+    /**
+     * Render function for the accordion content
+     * Receives content props including open state
+     */
     renderContent: (accordion: RenderContentProps) => React.ReactNode;
+    /**
+     * Custom element type to render as
+     * Allows composition with other components
+     */
     as?: React.ElementType;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 }
+/**
+ * Props passed to render functions for accordion content
+ *
+ * Contains accordion state and accessibility attributes
+ * that are passed to renderContent and renderTitle functions.
+ */
 export type RenderContentProps = Pick<AccordionProps, 'id' | 'size'> & Pick<AriaAttributes, 'aria-labelledby'> & {
+    /**
+     * Whether the accordion is currently open
+     * @default false
+     */
     isOpened?: boolean;
+    /**
+     * Custom element type to render as
+     */
     as?: React.ElementType;
+    /**
+     * Custom CSS class name
+     */
     className?: string;
 } & Record<string, unknown>;
+/**
+ * Extended props for Accordion component view
+ *
+ * Includes all AccordionProps plus additional view-specific properties
+ * like title, open state, and event handlers.
+ */
 export interface AccordionViewProps extends AccordionProps {
+    /**
+     * ARIA controls attribute
+     * Links the accordion header to its content panel
+     * Should match the id of the content panel
+     */
     ariaControls?: string;
+    /**
+     * Whether the accordion is currently open
+     * @default false
+     */
     isOpened?: boolean;
+    /**
+     * Whether the accordion is hidden
+     * Used for conditional rendering
+     * @default false
+     */
     isHidden?: boolean;
+    /**
+     * Title text displayed in the accordion header
+     */
     title: string;
+    /**
+     * Click handler for the accordion header
+     * Called when user clicks to toggle accordion
+     */
     onClick?: () => void;
+    /**
+     * Additional content to render
+     */
     children?: React.ReactNode;
+    /**
+     * Additional props to pass to content render function
+     * Allows passing custom props to AccordionContent
+     */
     contentProps?: Record<string, unknown>;
 }
+/**
+ * Represents an opened accordion in the group state
+ *
+ * Used to track which accordions are currently open
+ * in the AccordionGroup context.
+ */
 export type OpenedAccordion = {
+    /**
+     * Unique identifier of the opened accordion
+     */
     id: string | number;
 };
+/**
+ * Context props for AccordionGroup
+ *
+ * Provides state and control functions to accordion components
+ * within an AccordionGroup. Used internally by the context provider.
+ */
 export interface AccordionGroupContextProps {
+    /**
+     * Array of currently opened accordions
+     * Contains accordion IDs that are currently expanded
+     */
     openedAccordions: Array<OpenedAccordion> | [];
+    /**
+     * Whether multiple accordions can stay open
+     * When false, only one accordion can be open at a time
+     */
     stayOpen: boolean;
-    setOpenedAccordions: (accordions: Array<OpenedAccordion>) => void;
+    /**
+     * Function to set the opened accordions array
+     * Used internally for state management
+     */
+    setOpenedAccordions: React.Dispatch<React.SetStateAction<Array<OpenedAccordion>>>;
+    /**
+     * Function to toggle an accordion's open state
+     * @param accordion - The accordion to toggle
+     * @param opened - Optional explicit open state (true/false)
+     *                 If not provided, toggles based on current state
+     */
     toggleOpenedAccordion: (accordion: OpenedAccordion, opened?: boolean) => void;
+    /**
+     * Function to set whether accordions can stay open
+     * Updates the stayOpen behavior dynamically
+     */
     setStayOpen: (isStayOpen: boolean) => void;
 }
 export {};

package/dist/components/Avatar/Avatar.d.ts

@@ -1,4 +1,37 @@
 import { CommonProps } from '../../types/emotion';
+/**
+ * Avatar - Circular image component for user profiles
+ *
+ * A simple circular avatar component that displays an image with customizable size.
+ * The image is displayed with a circular border-radius and centered within the container.
+ *
+ * @category Components
+ * @subcategory Display
+ *
+ * @example
+ * ```tsx
+ * // Basic avatar
+ * <Avatar size={40} image="/path/to/avatar.jpg" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Large avatar
+ * <Avatar size={100} image={user.avatarUrl} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Avatar with custom styling
+ * <Avatar
+ *   size={60}
+ *   image="/avatar.png"
+ *   css={{ border: '2px solid blue' }}
+ * />
+ * ```
+ *
+ * @see {@link UserProfile} - For complete user profile display with avatar
+ */
 declare const Avatar: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;

package/dist/components/Button/Button.d.ts

@@ -1,3 +1,64 @@
 import { ButtonProps } from './types';
+/**
+ * Button - Interactive button component for user actions.
+ *
+ * Variant colors are driven entirely by `theme.palette` — each variant reads
+ * `palette.<variant>.main` for the default background, `palette.<variant>.dark`
+ * for hover and active states, and `palette.<variant>.light` for focus state.
+ * Override any palette entry in a custom theme to restyle a variant without
+ * affecting other components.
+ *
+ * ### Variants (default: `tertiary`)
+ * - `primary`   — blue, high emphasis, white text
+ * - `secondary` — grey, medium emphasis, dark text
+ * - `tertiary`  — transparent background, dark text, focus outline only (default)
+ * - `error`     — red, destructive actions, white text
+ * - `warning`   — orange, caution actions, white text
+ * - `success`   — green, confirmation actions, white text
+ *
+ * @category Form Controls
+ * @subcategory Action
+ *
+ * @example
+ * ```tsx
+ * // No variant passed → tertiary (transparent ghost button)
+ * <Button text="Cancel" onClick={handleCancel} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" size="medium" onClick={handleSave}>
+ *   Save
+ * </Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-width block button
+ * <Button variant="primary" size="large" block type="submit">
+ *   Submit Form
+ * </Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button with custom children
+ * <Button variant="secondary" onClick={handleAction}>
+ *   <span>Custom Content</span>
+ *   <Icon name="arrow-right" />
+ * </Button>
+ * ```
+ *
+ * @see {@link ButtonGroup} - For grouped button layouts
+ * @see {@link Icon} - For button icons
+ *
+ * @accessibility
+ * Supports full ARIA attributes including:
+ * - aria-label, aria-labelledby for accessible labels
+ * - aria-disabled for disabled state
+ * - aria-pressed for toggle buttons
+ * - Keyboard navigation (Enter/Space to activate)
+ * - Focus management
+ */
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
 export default Button;