@ssa-ui-kit/core 3.1.0 → 3.2.0

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

@@ -2,16 +2,16 @@ 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.
+ * Variant colors are driven entirely by `theme.palette` for solid variants — each
+ * reads `palette.<variant>.main` (default), `palette.<variant>.dark` (hover/active),
+ * `palette.<variant>.light` (focus). Override any palette entry in a custom theme
+ * to restyle a variant without affecting other components.
  *
- * ### Variants (default: `tertiary`)
+ * ### Variants (default: `custom`)
+ * - `custom`    — transparent, dark text; recommended for low-emphasis actions (default)
  * - `primary`   — blue, high emphasis, white text
  * - `secondary` — grey, medium emphasis, dark text
- * - `tertiary`  — transparent background, dark text, focus outline only (default)
+ * - `tertiary`  — legacy; same as custom; prefer `custom` instead
  * - `error`     — red, destructive actions, white text
  * - `warning`   — orange, caution actions, white text
  * - `success`   — green, confirmation actions, white text
@@ -21,7 +21,7 @@ import { ButtonProps } from './types';
  *
  * @example
  * ```tsx
- * // No variant passed → tertiary (transparent ghost button)
+ * // No variant passed → custom (transparent, recommended)
  * <Button text="Cancel" onClick={handleCancel} />
  * ```
  *

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

@@ -1,4 +1,4 @@
-import { AriaAttributes } from 'react';
+import React, { AriaAttributes } from 'react';
 import { SerializedStyles, Theme } from '@emotion/react';
 import { MouseEventHandler } from 'react';
 /**
@@ -72,9 +72,11 @@ export interface ButtonProps extends ButtonAriaProps {
      */
     endIconClassName?: string;
     /**
-     * Visual style variant of the button (uses theme.palette)
-     * - `primary` | `secondary` | `tertiary` | `error` | `warning` | `success`
-     * @default 'tertiary'
+     * Visual style variant of the button (uses theme.palette for solid variants).
+     * - `custom` — transparent, dark text; recommended for low-emphasis actions (default)
+     * - `primary` | `secondary` | `error` | `warning` | `success` — use theme.palette
+     * - `tertiary` — legacy; same as custom; prefer `custom` instead
+     * @default 'custom'
      */
     variant?: keyof ButtonVariants;
     /**
@@ -108,14 +110,16 @@ export interface ButtonProps extends ButtonAriaProps {
 }
 /**
  * Button variant style functions.
- * Each function reads from `theme.palette.<variant>` using the following convention:
- * - `main`  → default background
- * - `dark`  → hover and active background
- * - `light` → focus background
+ * Solid variants (primary, secondary, error, warning, success) read from
+ * `theme.palette.<variant>`: main (default), dark (hover/active), light (focus).
+ * Custom and tertiary are transparent (no palette); prefer custom to tertiary.
  */
 export interface ButtonVariants {
+    /** Recommended transparent variant; no focus outline. */
+    custom: (theme: Theme) => SerializedStyles;
     primary: (theme: Theme) => SerializedStyles;
     secondary: (theme: Theme) => SerializedStyles;
+    /** Legacy transparent variant; prefer custom. */
     tertiary: (theme: Theme) => SerializedStyles;
     error: (theme: Theme) => SerializedStyles;
     warning: (theme: Theme) => SerializedStyles;

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

@@ -10,6 +10,13 @@ export declare const COLORS: {
     readonly ERROR: "error";
     readonly WARNING: "warning";
 };
+/** Outlined variant background opacity (light color with opacity) */
+export declare const OUTLINED_BG_OPACITY: {
+    readonly DEFAULT: 0.08;
+    readonly HOVER: 0.24;
+    readonly ACTIVE: 0.4;
+    readonly DISABLED: 0.24;
+};
 export declare const mapSizes: {
     small: import("@emotion/react").SerializedStyles;
     medium: import("@emotion/react").SerializedStyles;

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

@@ -12,7 +12,7 @@ type ColorConfig = {
     darkText?: boolean;
 };
 export declare const colorMap: (theme: Theme) => Record<SemanticColor, ColorConfig>;
-export declare const getVariantColors: (theme: Theme, variant: ChipProps["variant"], color: ChipProps["color"], disabled: boolean) => {
+export declare const getVariantColors: (theme: Theme, variant: ChipProps["variant"], color: ChipProps["color"], disabled: boolean, isClickable?: boolean) => {
     chipStyles: import("@emotion/react").SerializedStyles;
     iconColor: string | undefined;
 };

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

@@ -11,7 +11,11 @@ export declare const filled: (theme: Theme) => import("@emotion/react").Serializ
 export declare const filledDisabled: (theme: Theme) => import("@emotion/react").SerializedStyles;
 export declare const outlined: (theme: Theme) => import("@emotion/react").SerializedStyles;
 export declare const outlinedDisabled: (theme: Theme) => import("@emotion/react").SerializedStyles;
+/** Hover/active bg opacity for default (grey) outlined clickable chip */
+export declare const clickableOutlinedDefault: (theme: Theme) => import("@emotion/react").SerializedStyles;
 export declare const clickable: import("@emotion/react").SerializedStyles;
+/** cursor + transition only; hover/active handled by variant (e.g. outlined bg opacity) */
+export declare const clickableBase: import("@emotion/react").SerializedStyles;
 export declare const clickableDisabled: import("@emotion/react").SerializedStyles;
 export declare const IconWrapper: import("@emotion/styled").StyledComponent<{
     theme?: Theme;

package/dist/components/CollapsibleNavBar/CollapsibleNavBar.d.ts

@@ -2,4 +2,4 @@ import { CollapsibleNavBarExtendedProps } from './types';
 /**
  * UI Component that shows the collapsible navigation bar
  */
-export declare const CollapsibleNavBar: ({ items, renderLogo, theme, subMenuMaxWidth, showIconTooltip, className, useMatchPattern, onChange, exactMatch, }: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const CollapsibleNavBar: ({ items, renderLogo, theme, subMenuMaxWidth, showIconTooltip, className, useMatchPattern, onChange, exactMatch, defaultExpanded, }: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -12,13 +12,21 @@ export interface CollapsibleNavBarGroup<T extends NavBarExtendedSubItem = NavBar
     prefix: string;
 }
 export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem = NavBarExtendedSubItem> {
+    /** Nav items: link items (path, iconName, iconSize, title) or groups with prefix, iconName, iconSize, title, items (sub-items: path, title). */
     items: Array<CollapsibleNavBarItem | CollapsibleNavBarGroup<T>>;
+    /** Logo or branding element (e.g. image or div) shown above the nav. */
     renderLogo: React.ReactElement;
+    /** Visual theme: dark (default) or light sidebar. */
     theme?: 'default' | 'light';
+    /** Optional CSS class for the root. */
     className?: string;
+    /** Max width for submenu panels (e.g. 220). */
     subMenuMaxWidth?: CSSProperties['maxWidth'];
+    /** When true, show tooltips on nav icons when sidebar is collapsed. */
     showIconTooltip?: boolean;
+    /** Custom route matching for active state (e.g. for React Router). */
     useMatchPattern?: (prefix: string) => string | PathPattern<string>;
+    /** Called when the sidebar expand/collapse state changes. */
     onChange?: (isChecked: boolean) => void;
     /**
      * If true, only exact path matches will be considered active.
@@ -26,4 +34,9 @@ export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem
      * @default false
      */
     exactMatch?: boolean;
+    /**
+     * Initial expanded state (sidebar shows icon + text). When false, only icons are shown until the user toggles.
+     * @default false
+     */
+    defaultExpanded?: boolean;
 }

package/dist/components/Dropdown/Dropdown.d.ts

@@ -88,5 +88,5 @@ import { DropdownProps } from './types';
  *
  * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
  */
-declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Dropdown;

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

@@ -71,6 +71,11 @@ export interface DropdownProps<P extends DropdownOptionProps> extends CommonProp
      * When provided, controls dropdown open/closed state externally
      */
     isOpen?: boolean;
+    /**
+     * Max height (px) of the options list; overflow scrolls.
+     * @default 200
+     */
+    maxHeight?: number;
     /**
      * Props object for sub-components
      * Allows fine-grained control over component parts
@@ -121,4 +126,8 @@ export interface DropdownContextType {
      * Used to highlight the selected option
      */
     activeItem?: DropdownOptionProps | null;
+    /**
+     * Max height (px) of the options list
+     */
+    maxHeight?: number;
 }

package/dist/components/Icon/icons/EmployeeBlackboard.d.ts

@@ -0,0 +1,3 @@
+import { SVGProps } from '../types';
+export declare const EmployeeBlackboard: ({ fill, size, tooltip, ...props }: SVGProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const ICON_NAME = "employee-blackboard";

package/dist/components/Icon/icons/FileMark.d.ts

@@ -0,0 +1,3 @@
+import { SVGProps } from '../types';
+export declare const FileMark: ({ fill, size, tooltip, ...props }: SVGProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const ICON_NAME = "file-mark";

package/dist/components/Icon/icons/FilePdf.d.ts

@@ -0,0 +1,3 @@
+import { SVGProps } from '../types';
+export declare const FilePdf: ({ fill, size, tooltip, ...props }: SVGProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const ICON_NAME = "file-pdf";

package/dist/components/Icon/icons/FileWord.d.ts

@@ -0,0 +1,3 @@
+import { SVGProps } from '../types';
+export declare const FileWord: ({ fill, size, tooltip, ...props }: SVGProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const ICON_NAME = "file-word";

package/dist/components/Icon/icons/all.d.ts

@@ -48,8 +48,12 @@ export * as Email from './Email';
 export * as Employee from './Employee';
 export * as EmployeeProfile from './EmployeeProfile';
 export * as EmployeeTerminated from './EmployeeTerminated';
+export * as EmployeeBlackboard from './EmployeeBlackboard';
 export * as ExcelDownload from './ExcelDownload';
 export * as Export from './Export';
+export * as FileMark from './FileMark';
+export * as FilePdf from './FilePdf';
+export * as FileWord from './FileWord';
 export * as Filter from './Filter';
 export * as FilterFunnel from './FilterFunnel';
 export * as FollowLink from './FollowLink';

package/dist/components/Icon/icons/iconsList.d.ts

@@ -1 +1 @@
-export declare const iconsList: ("visible" | "warning" | "archive" | "document" | "link" | "search" | "arrow-down" | "arrow-up" | "clipboard-assessment" | "attention" | "award" | "ban-user" | "bench" | "bin" | "calendar" | "calendar-schedule" | "carrot-down" | "carrot-left" | "carrot-right" | "carrot-up" | "card-text" | "case" | "certification" | "certification-expiring" | "camera" | "change" | "chart" | "check" | "check-circle" | "check-circle-inverted" | "children" | "circle" | "circular" | "clock" | "cogwheel" | "comments" | "briefcase" | "building" | "compensation" | "confirm-email" | "contacts" | "copy" | "copy-link" | "cross" | "delete" | "diamond-ring" | "diet" | "documents" | "edit" | "education" | "email" | "employee" | "employee-profile" | "employee-terminated" | "excel-download" | "export" | "filter" | "filter-funnel" | "follow-link" | "fte" | "clipboard-form" | "geography" | "gender" | "gift" | "home" | "import" | "information" | "inventory" | "invisible" | "language" | "lock" | "log-in" | "log-out" | "maximize" | "measurements" | "message" | "minus" | "minus-circle" | "minus-circle-inverted" | "more" | "more-vertical" | "notification" | "office-chair" | "open-book" | "pages" | "party" | "plus" | "plus-circle" | "plus-circle-inverted" | "probation-period" | "profiles-changes" | "radio-on" | "clipboard-report" | "clipboard-result" | "robot" | "roles" | "seniority" | "settings" | "signature" | "sleep" | "staff-growth-coefficient" | "staff-turnover-coefficient" | "stats" | "clipboard-summary" | "team" | "clipboard-star" | "time-tracking" | "timeline" | "tennis-ball" | "trainings" | "unarchive" | "union" | "union-circle" | "unlock" | "url" | "user")[];
+export declare const iconsList: ("visible" | "warning" | "archive" | "document" | "link" | "search" | "arrow-down" | "arrow-up" | "clipboard-assessment" | "attention" | "award" | "ban-user" | "bench" | "bin" | "calendar" | "calendar-schedule" | "carrot-down" | "carrot-left" | "carrot-right" | "carrot-up" | "card-text" | "case" | "certification" | "certification-expiring" | "camera" | "change" | "chart" | "check" | "check-circle" | "check-circle-inverted" | "children" | "circle" | "circular" | "clock" | "cogwheel" | "comments" | "briefcase" | "building" | "compensation" | "confirm-email" | "contacts" | "copy" | "copy-link" | "cross" | "delete" | "diamond-ring" | "diet" | "documents" | "edit" | "education" | "email" | "employee" | "employee-profile" | "employee-terminated" | "employee-blackboard" | "excel-download" | "export" | "file-mark" | "file-pdf" | "file-word" | "filter" | "filter-funnel" | "follow-link" | "fte" | "clipboard-form" | "geography" | "gender" | "gift" | "home" | "import" | "information" | "inventory" | "invisible" | "language" | "lock" | "log-in" | "log-out" | "maximize" | "measurements" | "message" | "minus" | "minus-circle" | "minus-circle-inverted" | "more" | "more-vertical" | "notification" | "office-chair" | "open-book" | "pages" | "party" | "plus" | "plus-circle" | "plus-circle-inverted" | "probation-period" | "profiles-changes" | "radio-on" | "clipboard-report" | "clipboard-result" | "robot" | "roles" | "seniority" | "settings" | "signature" | "sleep" | "staff-growth-coefficient" | "staff-turnover-coefficient" | "stats" | "clipboard-summary" | "team" | "clipboard-star" | "time-tracking" | "timeline" | "tennis-ball" | "trainings" | "unarchive" | "union" | "union-circle" | "unlock" | "url" | "user")[];

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

@@ -72,6 +72,11 @@ export type DropdownProps<P extends DropdownOptionProps> = {
      * @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
@@ -89,4 +94,8 @@ export interface DropdownContextType<T extends DropdownOptionProps> {
      * 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'];