@ssa-ui-kit/core 3.0.0 → 3.2.0

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

@@ -1 +1,2 @@
 export { default } from './MultipleDropdown';
+export type { DropdownProps, DropdownContextType } from './types';

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

@@ -1,18 +1,101 @@
 import { DropdownOptionProps } from '../DropdownOptions/types';
+/**
+ * Props for the MultipleDropdown component
+ *
+ * A dropdown that supports selecting one or more options from a list.
+ * In multi-select mode (`isMultiple=true`) options toggle independently and
+ * a `+N` badge is shown for overflow. In single-select mode the menu closes
+ * after a pick. Forwards its ref to the root container div.
+ *
+ * @example
+ * ```tsx
+ * <MultipleDropdown
+ *   label="Fruits"
+ *   selectedItems={[{ value: 'apple' }]}
+ *   onChange={(value, isSelected) => handleChange(value, isSelected)}
+ * >
+ *   <DropdownOption value="apple">Apple</DropdownOption>
+ *   <DropdownOption value="banana">Banana</DropdownOption>
+ * </MultipleDropdown>
+ * ```
+ */
 export type DropdownProps<P extends DropdownOptionProps> = {
+    /**
+     * List of currently selected items
+     * Each entry must match one of the DropdownOption values
+     * @default []
+     */
     selectedItems?: P[];
+    /**
+     * Enables multi-select mode — each option toggles independently.
+     * When `false` the dropdown behaves like a single-select and closes on pick.
+     * @default true
+     */
     isMultiple?: boolean;
+    /**
+     * Disables the dropdown, preventing any user interaction
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Placeholder shown in the toggle button when no item is selected
+     * @default 'Select something'
+     */
     placeholder?: string;
+    /**
+     * When `true` the placeholder value is included in the displayed list.
+     * Set to `false` to hide it and show only the badge count.
+     * @default true
+     */
     showPlaceholder?: boolean;
+    /**
+     * DropdownOption components to render as selectable items
+     */
     children?: React.ReactNode;
+    /**
+     * Custom CSS class name forwarded to the toggle button.
+     * Useful for styling via `styled(MultipleDropdown)`.
+     */
     className?: string;
+    /**
+     * Controlled open state — when provided, overrides internal open/close logic
+     */
     isOpen?: boolean;
+    /**
+     * Label prefix shown in the toggle button before the selected value(s)
+     * e.g. `label="Strategy"` renders "Strategy: Value"
+     */
     label?: string;
+    /**
+     * Callback fired when an option is toggled
+     * @param selectedItem - The value of the toggled option
+     * @param isSelected   - `true` if the option was just selected, `false` if deselected
+     */
     onChange?: (selectedItem: string | number, isSelected: boolean) => void;
+    /**
+     * Max height (px) of the options list; overflow scrolls.
+     * @default 200
+     */
+    maxHeight?: number;
 };
+/**
+ * Context value shared with child DropdownOption components via MultipleDropdownContext
+ */
 export interface DropdownContextType<T extends DropdownOptionProps> {
+    /**
+     * Function called when an option is clicked
+     */
     onChange: (item: T) => void;
+    /**
+     * Whether multi-select mode is active
+     */
     isMultiple?: boolean;
+    /**
+     * Map of all option values to their current state (including `isSelected`)
+     */
     allItems: Record<string | number, T>;
+    /**
+     * Max height (px) of the options list
+     */
+    maxHeight?: number;
 }

package/dist/components/PersonInfo/PersonInfo.d.ts

@@ -1,3 +1,81 @@
 import React from 'react';
 import { PersonInfoProps } from './types';
+/**
+ * PersonInfo - Compact row for displaying a person or entity with title, value, and optional metadata.
+ *
+ * Uses `theme.colors` only (e.g. greyDropdownFocused, greyDarker, blue for link hover). Does not use
+ * `theme.palette`. Link and value hover use theme.colors.blue. Badge colors come from BADGE_COLORS(theme).
+ *
+ * ### Structure
+ * - Optional leading icon (name or custom ReactNode)
+ * - Title (required) and a row with: optional avatar + value (optionally a link), optional counter with tooltip
+ * - Optional badges (Badge components or strings)
+ * - Optional attributes list (strings or ReactNodes)
+ * - Optional description text
+ *
+ * ### Key props
+ * - `title` (required) — main label
+ * - `value` — primary value; use with `link` / `openLinkInNewTab` for a clickable value
+ * - `icon` — Icon name or custom node before the title
+ * - `avatar` — image URL; shown next to value
+ * - `badges` — ReactNode or array of ReactNode/string; rendered as badges below the row
+ * - `counterTooltip` — { users: [{ id, name, avatar, link?, openLinkInNewTab? }] } for a count + tooltip
+ * - `attributes` — array of strings or ReactNodes below the row
+ * - `description` — extra text block
+ * - `styles` — optional overrides for title, avatarName, counter, attributes, badge, badgeItem, value, description
+ *
+ * @category Components
+ * @subcategory Display
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo title="Assignee" value="John Doe" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo
+ *   title="Owner"
+ *   value="Jane Smith"
+ *   icon="user"
+ *   avatar="/avatar.jpg"
+ *   link="/users/jane"
+ *   openLinkInNewTab={false}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo
+ *   title="Status"
+ *   value="In progress"
+ *   badges={[<Badge key="1">Active</Badge>]}
+ *   attributes={['Due: Jan 15', 'Priority: High']}
+ *   description="Additional context text."
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo
+ *   title="Participants"
+ *   value="3"
+ *   counterTooltip={{
+ *     users: [
+ *       { id: 1, name: 'Alice', avatar: '/a.jpg', link: '/users/1' },
+ *       { id: 2, name: 'Bob', avatar: '/b.jpg' },
+ *     ],
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link Avatar} - Often used for avatar prop or inside counter tooltip
+ * @see {@link Icon} - Common choice for icon prop
+ * @see {@link Badge} - Used when badges prop contains Badge components
+ *
+ * @accessibility
+ * - Semantic structure (heading-like title, list of attributes)
+ * - Links support openLinkInNewTab and get appropriate attributes
+ * - Counter tooltip is focusable and keyboard-accessible via Tooltip
+ */
 export declare const PersonInfo: React.ForwardRefExoticComponent<PersonInfoProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/PersonInfo/PersonInfoAvatar.d.ts

@@ -1,3 +1,9 @@
+/**
+ * PersonInfoAvatar - Avatar + value row for PersonInfo.
+ * Renders optional Avatar (image URL) and PersonInfoValue. When link is set, wraps in anchor
+ * using helpers.getLinkAttributes; link hover uses theme.colors.blue (avatarWrapperLinkStyles).
+ * Uses styles.avatarName when avatar present, styles.value when only value. Used only by PersonInfo.
+ */
 import React from 'react';
 import { PersonInfoAvatarProps } from './types';
 export declare const PersonInfoAvatar: React.FC<PersonInfoAvatarProps>;

package/dist/components/PersonInfo/PersonInfoBadges.d.ts

@@ -1,3 +1,9 @@
+/**
+ * PersonInfoBadges - Badge row for PersonInfo.
+ * badges can be a single ReactNode or array of string | ReactNode. Strings are rendered with
+ * CustomBadge using DEFAULT_BADGE_COLORS (cycled by index) and BADGE_COLORS(theme) for text/bg.
+ * Other items rendered as-is (e.g. <Badge>). Uses styles.badge and styles.badgeItem.
+ */
 import React from 'react';
 import { PersonInfoStyles } from './types';
 interface PersonInfoBadgesProps {

package/dist/components/PersonInfo/PersonInfoCounter.d.ts

@@ -1,3 +1,9 @@
+/**
+ * PersonInfoCounter - “+N” counter with tooltip for PersonInfo.
+ * Renders counter value from counterTooltip.users.length; tooltip lists users via ImageItem
+ * (image, name, optional link). Uses Tooltip (hover, no click). Counter text uses
+ * theme.colors.greyDropdownFocused (S.Counter). Used only by PersonInfo when counterTooltip is set.
+ */
 import React from 'react';
 import { PersonInfoCounterProps } from './types';
 export declare const PersonInfoCounter: React.FC<PersonInfoCounterProps>;

package/dist/components/PersonInfo/PersonInfoIcon.d.ts

@@ -1,3 +1,8 @@
+/**
+ * PersonInfoIcon - Leading icon for PersonInfo row.
+ * Renders Icon with theme.colors.greyDarker when icon is a string; otherwise renders custom ReactNode.
+ * Used only by PersonInfo when icon prop is set.
+ */
 import React from 'react';
 import type { IconProps } from '../Icon/types';
 interface PersonInfoIconProps {

package/dist/components/PersonInfo/PersonInfoValue.d.ts

@@ -1,3 +1,8 @@
+/**
+ * PersonInfoValue - Primary value cell for PersonInfo, optionally a link.
+ * When linkAttributes (from getLinkAttributes) are provided, renders as <a> with
+ * personInfoValueLinkStyles: theme.colors.greyDarker, hover theme.colors.blue. Used by PersonInfoAvatar.
+ */
 import React from 'react';
 import { PersonInfoValueProps } from './types';
 export declare const PersonInfoValue: React.FC<PersonInfoValueProps>;

package/dist/components/PersonInfo/constants.d.ts

@@ -1,3 +1,8 @@
+/**
+ * PersonInfo badge color config. Uses theme.colors only (no palette).
+ * DEFAULT_BADGE_COLORS: order of MainColors keys used when badges are strings (cycled by index).
+ * BADGE_COLORS(theme): map of MainColors key → { text, bg } using theme.colors.* and theme.colors.*20.
+ */
 import type { Theme } from '@emotion/react';
 type BadgeColorName = keyof MainColors;
 export declare const DEFAULT_BADGE_COLORS: Array<keyof MainColors>;

package/dist/components/PersonInfo/helpers.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Returns link props for PersonInfo value/avatar when link is set.
+ * For AI: used by PersonInfoAvatar and PersonInfoValue. Returns { as: 'a', href, target?, rel? }
+ * when link is truthy; otherwise {}. openLinkInNewTab sets target="_blank" and rel="noreferrer".
+ */
 export declare const getLinkAttributes: (link?: string, openLinkInNewTab?: boolean) => {
     as: "a";
     href: string | undefined;

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

@@ -1,2 +1,6 @@
+/**
+ * PersonInfo public API. Re-exports PersonInfo component and all types (PersonInfoProps,
+ * PersonInfoStyles, PersonInfoCounterTooltip, etc.) for consumers.
+ */
 export * from './PersonInfo';
 export * from './types';

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

@@ -3,8 +3,16 @@ import { Interpolation, Theme } from '@emotion/react';
 import { CommonProps } from '../../types/emotion';
 import { IconProps } from '../Icon/types';
 import { getLinkAttributes } from './helpers';
+/**
+ * Style keys that can be overridden via PersonInfoProps.styles.
+ * All PersonInfo sub-components accept optional css from this map.
+ */
 type PersonInfoStyleKeys = 'title' | 'avatarName' | 'counter' | 'attributes' | 'badge' | 'badgeItem' | 'value' | 'description';
 export type PersonInfoStyles = Partial<Record<PersonInfoStyleKeys, Interpolation<Theme>>>;
+/**
+ * Single user entry for the counter tooltip list.
+ * Used by PersonInfoCounter; avatar is image URL, link opens in same/new tab per openLinkInNewTab.
+ */
 export interface PersonInfoCounterTooltipUser {
     id: string | number;
     name: string;
@@ -12,28 +20,70 @@ export interface PersonInfoCounterTooltipUser {
     link?: string;
     openLinkInNewTab?: boolean;
 }
+/**
+ * Tooltip payload for the “+N” counter next to the value.
+ * users array is rendered as a list inside the tooltip (e.g. via ImageItem).
+ */
 export interface PersonInfoCounterTooltip {
     users: PersonInfoCounterTooltipUser[];
 }
 export type PersonInfoLinkAttributes = ReturnType<typeof getLinkAttributes>;
+/**
+ * Props for the value sub-component (avatar row value, optionally a link).
+ * linkAttributes come from helpers.getLinkAttributes(link, openLinkInNewTab).
+ */
 export interface PersonInfoValueProps {
     value: string;
     css?: Interpolation<Theme>;
     linkAttributes?: PersonInfoLinkAttributes;
 }
+/**
+ * Props for the PersonInfo component.
+ * Uses theme.colors only (no theme.palette). See PersonInfo.tsx JSDoc for structure and examples.
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo title="Assignee" value="John Doe" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo title="Owner" value="Jane" avatar="/j.jpg" link="/users/jane" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PersonInfo title="Status" value="3" counterTooltip={{ users: [...] }} />
+ * ```
+ */
 export interface PersonInfoProps extends CommonProps {
+    /** Main label (required). */
     title: string;
+    /** Icon name or custom ReactNode before the title. */
     icon?: IconProps['name'] | ReactNode;
+    /** Primary value; with link becomes a link. */
     value?: string;
+    /** Badge(s): single node or array of string | ReactNode. Strings use DEFAULT_BADGE_COLORS. */
     badges?: ReactNode | (string | ReactNode)[];
+    /** Avatar image URL, shown next to value. */
     avatar?: string;
+    /** “+N” counter with tooltip listing users. */
     counterTooltip?: PersonInfoCounterTooltip;
+    /** List of strings or ReactNodes below the row. */
     attributes?: (string | ReactNode)[];
+    /** Extra description text. */
     description?: string;
+    /** Optional style overrides per PersonInfoStyleKeys. */
     styles?: PersonInfoStyles;
+    /** If set, value (or avatar+value) renders as a link. */
     link?: string;
+    /** When link is set, open in new tab and use rel="noreferrer". */
     openLinkInNewTab?: boolean;
 }
+/**
+ * Props for PersonInfoAvatar (value + optional avatar, optional link).
+ * Used internally by PersonInfo.
+ */
 export interface PersonInfoAvatarProps {
     avatar?: string;
     value?: string;
@@ -41,6 +91,10 @@ export interface PersonInfoAvatarProps {
     link?: string;
     openLinkInNewTab?: boolean;
 }
+/**
+ * Props for PersonInfoCounter (“+N” with tooltip).
+ * css overrides styles.counter.
+ */
 export interface PersonInfoCounterProps {
     counterTooltip?: PersonInfoCounterTooltip;
     css?: PersonInfoStyles['counter'];

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

@@ -84,6 +84,15 @@ export interface TextareaProps extends Partial<Pick<UseFormReturn, 'register'>>
      * 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)
      */
@@ -97,6 +106,11 @@ export interface TextareaProps extends Partial<Pick<UseFormReturn, 'register'>>
      * 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

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

@@ -10,7 +10,7 @@ export declare const TypeaheadOption: import("@emotion/styled").StyledComponent<
     as?: React.ElementType;
 } & TypeaheadItemProps, import("react").DetailedHTMLProps<import("react").LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, {}>;
 export declare const TypeaheadInput: (theme: Theme) => string;
-export declare const TypeaheadInputPlaceholder: string;
+export declare const TypeaheadInputPlaceholder: (theme: Theme) => string;
 export declare const TypeaheadInputWrapper: string;
 export declare const TypeaheadItem: import("@emotion/styled").StyledComponent<{
     theme?: Theme;