@ssa-ui-kit/core 3.21.3 → 3.22.0

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

@@ -1,7 +1,7 @@
 import { CSSProperties } from 'react';
 import { PathPattern } from 'react-router-dom';
 import { CSSObject } from '@emotion/react';
-import { NavBarExtendedGroup, NavBarExtendedItem, NavBarExtendedSubItem } from '../..';
+import { NavBarExtendedGroup, NavBarExtendedItem, NavBarExtendedSubItem } from '../NavBar/types';
 export interface CollapsibleNavBarItem extends NavBarExtendedItem {
     iconSize: number;
     css?: CSSObject;
@@ -11,20 +11,57 @@ export interface CollapsibleNavBarGroup<T extends NavBarExtendedSubItem = NavBar
     css?: CSSObject;
     prefix: string;
 }
+/**
+ * The panel header, above the menu.
+ *
+ * Every field is optional, which is what covers the design's three variants:
+ * headline alone, headline with a large picture above the name, and headline
+ * with a small avatar inline beside it. Pass elements rather than urls so the
+ * kit's `Avatar` — or anything else — can be dropped straight in.
+ */
+export interface CollapsibleNavBarHeader {
+    /** Headline, shown above everything else. */
+    title?: React.ReactNode;
+    /** Person's name, shown under the picture or beside the avatar. */
+    name?: React.ReactNode;
+    /** Small element rendered inline, before the name. Typically an `Avatar`. */
+    avatar?: React.ReactNode;
+    /** Large square picture above the name, e.g. an `img`. */
+    image?: React.ReactNode;
+}
 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;
+    renderLogo?: React.ReactElement;
+    /**
+     * Header shown above the menu in the expanded panel — headline, picture,
+     * avatar, name. Hidden in the collapsed rail, which has no room for it.
+     */
+    header?: CollapsibleNavBarHeader;
     /** Visual theme: dark (default) or light sidebar. */
     theme?: 'default' | 'light';
+    /**
+     * Colour of the active row and of the group that owns it. Defaults to the
+     * theme's own accent — `blueCool` on the dark sidebar, `primary.dark` on the
+     * light one — so an app with its own brand colour can override it without
+     * restyling the rows.
+     */
+    activeColor?: string;
     /** 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). */
+    /**
+     * Custom route matching for active state (e.g. for React Router): given a
+     * group's `prefix`, return the pattern that marks the group active.
+     *
+     * Must be a plain function — it is called once per group from a loop, so a
+     * hook inside it would change its call order whenever the menu gains or
+     * loses a group.
+     */
     useMatchPattern?: (prefix: string) => string | PathPattern<string>;
     /** Called when the sidebar expand/collapse state changes. */
     onChange?: (isChecked: boolean) => void;

package/dist/components/DatePicker/DatePicker.d.ts

@@ -1,2 +1,59 @@
 import { DatePickerProps } from './types';
+/**
+ * DatePicker — masked date input with a popover calendar. Use inside **`FormProvider`**
+ * (react-hook-form): the field value is the formatted string; **`onChange`** receives a
+ * JavaScript **`Date`** (or undefined when cleared). Supports **day**, **month**, or **year**
+ * granularity via **`pickerType`**, **`mm/dd/yyyy`** / **`dd/mm/yyyy`** / **`mm/yyyy`** / **`yyyy`**
+ * formats, optional **min/max** bounds, and **openCalendarMode** (icon, input, or both).
+ *
+ * ### Behavior notes
+ * - Parsing and display use **Luxon**; the form stores the string matching **`format`**.
+ * - Validation runs when the mask is complete or on **blur**; errors surface through
+ *   react-hook-form and **`onError`**.
+ * - **`highlightDates`** helps range UIs by styling days between two dates.
+ *
+ * @category Components
+ * @subcategory Form Controls
+ *
+ * @example
+ * ```tsx
+ * import { FormProvider, useForm } from 'react-hook-form';
+ * import { DatePicker } from '@ssa-ui-kit/core';
+ *
+ * function Example() {
+ *   const methods = useForm({ defaultValues: { startDate: '' } });
+ *   return (
+ *     <FormProvider {...methods}>
+ *       <DatePicker
+ *         name="startDate"
+ *         label="Start date"
+ *         format="mm/dd/yyyy"
+ *         onChange={(date) => console.log(date)}
+ *       />
+ *     </FormProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Month picker (mm/yyyy) with bounds
+ * <DatePicker
+ *   name="period"
+ *   label="Period"
+ *   pickerType="months"
+ *   dateMin="01/2020"
+ *   dateMax="12/2030"
+ *   onChange={(d) => {}}
+ * />
+ * ```
+ *
+ * @see {@link Input} — Underlying text field
+ * @see {@link Popover} — Calendar overlay
+ *
+ * @accessibility
+ * - Label is associated with the input via **`htmlFor`** / **`id`**
+ * - Calendar days use **`aria-disabled`** and **`aria-label`** where applicable
+ * - Icon trigger exposes **`aria-label="Calendar"`**
+ */
 export declare const DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/Drawer/DrawerRoot.d.ts

@@ -3,4 +3,74 @@ export interface DrawerProps extends UseDrawerOptions {
     children?: React.ReactElement;
     store?: UseDrawerStore;
 }
+/**
+ * Drawer.Root - Slide-out panel anchored to an edge of the screen.
+ *
+ * Exported as a namespace, so the parts are reached through it:
+ * `import { Drawer } from '@ssa-ui-kit/core'` then `<Drawer.Root>`. There is no
+ * bare `<Drawer>` component.
+ *
+ * ### Nesting is required
+ * ```
+ * Drawer.Root                 — owns the state
+ * └── Drawer.Portal           — renders outside the DOM subtree
+ *     └── Drawer.Overlay      — backdrop; click-outside to dismiss
+ *         └── Drawer.Content  — the panel itself
+ *             ├── Drawer.Header
+ *             │   ├── Drawer.Title
+ *             │   └── Drawer.CloseButton
+ *             └── …your content
+ * ```
+ * Each layer reads context from the one above, so skipping a level (Content
+ * without Overlay, say) leaves the drawer without its backdrop and dismiss
+ * behaviour.
+ *
+ * ### Controlled via the `useDrawer` store
+ * For a drawer opened from elsewhere — a toolbar button, a route — call
+ * `useDrawer()` in the parent and hand the result to `store`. That same object
+ * carries `interactions.getReferenceProps()` for wiring the trigger. Omit
+ * `store` and `Drawer.Root` keeps its own state from `defaultOpen`.
+ *
+ * ### It unmounts while closed
+ * `Drawer.Root` renders `null` until the open transition starts, so children do
+ * not exist in the DOM when the drawer is shut. Anything that must keep state
+ * across open/close belongs above the drawer, not inside it.
+ *
+ * Note `opened`/`defaultOpened` are the legacy spelling of `open`/`defaultOpen`;
+ * prefer the latter.
+ *
+ * @category Components
+ * @subcategory Overlay
+ *
+ * @example
+ * ```tsx
+ * // Controlled: the trigger lives outside the drawer
+ * const drawer = useDrawer({ title: 'Settings', withCloseButton: true });
+ *
+ * <>
+ *   <Button {...drawer.interactions.getReferenceProps()} text="Settings" />
+ *   <Drawer.Root store={drawer}>
+ *     <Drawer.Portal>
+ *       <Drawer.Overlay>
+ *         <Drawer.Content css={{ maxWidth: 400, padding: 24 }}>
+ *           {form}
+ *         </Drawer.Content>
+ *       </Drawer.Overlay>
+ *     </Drawer.Portal>
+ *   </Drawer.Root>
+ * </>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled, anchored left, not dismissable by click-outside
+ * <Drawer.Root defaultOpen position="left" dismissable={false}>
+ *   <Drawer.Portal>
+ *     <Drawer.Overlay>
+ *       <Drawer.Content>{content}</Drawer.Content>
+ *     </Drawer.Overlay>
+ *   </Drawer.Portal>
+ * </Drawer.Root>
+ * ```
+ */
 export declare const Drawer: ({ children, store: controlledStore, ...drawerProps }: DrawerProps) => import("@emotion/react/jsx-runtime").JSX.Element | null;

package/dist/components/DropdownOption/DropdownOption.d.ts

@@ -26,6 +26,49 @@ export interface DropdownItemProps extends CommonProps, Omit<React.LiHTMLAttribu
  * Thin wrapper over a styled `<li>`. It exists so that `disabled` can be
  * accepted as the supported prop name without emotion forwarding it to the
  * DOM, where `disabled` is not valid on an `<li>`.
+ *
+ * ### The parent supplies the visible label
+ * Options are not rendered as written: the enclosing dropdown clones each one
+ * and injects the label, resolved as **`children` → `label` → `value`**. So
+ * `<DropdownOption value="Sales" />` displays "Sales" with no children needed,
+ * `label` overrides that for a different display string, and `children` wins
+ * over both when a row needs custom markup.
+ *
+ * The clone also wraps the label for truncation and attaches a tooltip, so put
+ * custom content in `children` rather than styling the `<li>` directly.
+ *
+ * ### Selection state comes from the parent
+ * `isActive`, `isMultiple` and the click wiring are set by `Dropdown` /
+ * `MultipleDropdown`; you supply `value` and let the parent report selection
+ * through its own `onChange`. Note `disabled` is only styled in `isMultiple`
+ * mode.
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * // Label falls back to `value`
+ * <Dropdown onChange={handleChange}>
+ *   {teams.map((team) => (
+ *     <DropdownOption key={team.id} value={team.name} />
+ *   ))}
+ * </Dropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Report an id, display something else
+ * <DropdownOption value={user.id} label={user.fullName} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom row content; `avatar` fills the leading slot
+ * <DropdownOption value={user.id} avatar={<Avatar size={20} image={user.photo} />}>
+ *   {user.fullName} — {user.role}
+ * </DropdownOption>
+ * ```
  */
 declare const DropdownOption: React.ForwardRefExoticComponent<DropdownItemProps & React.RefAttributes<HTMLLIElement>>;
 export default DropdownOption;

package/dist/components/Form/Form.d.ts

@@ -1,4 +1,44 @@
 import { CommonProps } from '../../types/emotion';
+/**
+ * Form - Styled `<form>` element that lays its children out as a wrapping flex row.
+ *
+ * ### It does not manage form state
+ * Unlike the `Form` component in many other kits, this one adds **no** state,
+ * validation, context or submit handling — it is a layout primitive over a real
+ * `<form>`. There is no `onSubmit` wiring, no `values`/`errors`, and nothing is
+ * provided to descendants via context.
+ *
+ * State comes from `react-hook-form`: keep `useForm` in your component and hand
+ * `handleSubmit` to the native `onSubmit`. Because it renders a plain `<form>`,
+ * every native attribute (`onSubmit`, `noValidate`, `id`, `method`) works as-is.
+ *
+ * ### Layout
+ * Children flow in a wrapping row. For a stacked form, override the direction
+ * with `css` rather than reaching for a different component.
+ *
+ * @category Form Structure
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * // State lives in react-hook-form; Form only lays the fields out
+ * const { register, handleSubmit, formState } = useForm<Values>();
+ *
+ * <Form onSubmit={handleSubmit(onSubmit)}>
+ *   <TextField name="title" register={register} errors={formState.errors.title} />
+ *   <Button type="submit" variant="primary" text="Save" />
+ * </Form>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Stack the fields instead of wrapping them in a row
+ * <Form onSubmit={handleSubmit(onSubmit)} css={{ flexFlow: 'column', gap: 16 }}>
+ *   <TextField name="email" register={register} />
+ *   <TextField name="password" type="password" register={register} />
+ * </Form>
+ * ```
+ */
 declare const Form: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;

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

@@ -1,3 +1,50 @@
 import { IconProps } from './types';
+/**
+ * Icon - Renders one of the kit's built-in SVG icons by name.
+ *
+ * `name` is type-checked against the generated icon list, so a typo fails to
+ * compile instead of rendering nothing. Browse the full set under
+ * "Design System / Icons" in Storybook.
+ *
+ * ### Accessibility
+ * Icons are **decorative by default** — no `tooltip` means no accessible name,
+ * which is what you want when the icon sits next to a text label. When the icon
+ * is the only content of a control, give it a name: either pass `tooltip`, or
+ * put an `aria-label` on the surrounding button.
+ *
+ * ### Passing `tooltip` changes the markup
+ * With `tooltip` the icon is wrapped in a `Tooltip` plus an `inline-flex` span,
+ * so it is no longer a bare `<svg>` at that position. If the parent relies on
+ * the svg being a direct child (grid placement, `& > svg` selectors), style the
+ * wrapper instead — or leave `tooltip` off and use `aria-label`.
+ *
+ * ### Sizing and colour
+ * `size` sets both width and height. `color` paints the glyph and defaults to
+ * black; some icons paint with `stroke` rather than `fill`, so to dim an icon
+ * prefer `opacity` over recolouring.
+ *
+ * @category Components
+ * @subcategory Display
+ *
+ * @example
+ * ```tsx
+ * // Decorative — the adjacent text already names the action
+ * <Button startIcon={<Icon name="plus" size={16} />} text="Add member" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon-only control: name it, or screen readers announce nothing
+ * <Icon name="information" size={16} tooltip="Salary is pre-tax" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Same accessible name, without the extra wrapper element
+ * <button aria-label="Delete row">
+ *   <Icon name="bin" size={20} />
+ * </button>
+ * ```
+ */
 declare const Icon: ({ name, color, size, tooltip, ...props }: IconProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Icon;

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

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

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

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

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

@@ -223,3 +223,5 @@ export * as Billable from './Billable';
 export * as NonBillable from './NonBillable';
 export * as RecruitmentTeam from './RecruitmentTeam';
 export * as Clear from './Clear';
+export * as List from './List';
+export * as Columns from './Columns';

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

@@ -1 +1 @@
-export declare const iconsList: ("visible" | "reset" | "warning" | "h1" | "h2" | "h3" | "bold" | "archive" | "document" | "link" | "menu" | "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" | "setting-clock" | "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" | "panelLeft" | "panelRight" | "emailOutlined" | "lockOutlined" | "addFolder" | "moveFolder" | "attention-circle" | "zoom" | "zoom-in" | "zoom-out" | "pan" | "box-select" | "lasso-select" | "autoscale" | "reset-axes" | "star" | "preview" | "dashboard" | "phone" | "tablet" | "desktop" | "more-info" | "filter-list" | "history" | "overtime" | "save-2" | "folder" | "salary-reports" | "assessment-stages" | "comments-on-achievements" | "code-review-comments" | "support" | "leave" | "vacation" | "sick-leave" | "day-off" | "arrow-sort" | "dragndrop" | "send" | "save" | "today" | "busket" | "copy-link-2" | "upload" | "picture" | "warning-2" | "info" | "sort-up" | "sort-down" | "italic" | "strikethrough" | "underline" | "markup" | "numbered-list" | "bulleted-list" | "uppercase" | "dash" | "brackets" | "undo" | "redo" | "new-line" | "quotation" | "close-circle-outline" | "close-square-outline" | "close-circle-filled" | "close-square-filled" | "plus-square-outline" | "plus-square-filled" | "minus-square-outline" | "minus-square-filled" | "tick-square-outline" | "tick-square-filled" | "warning-circle-outline" | "warning-square-outline" | "warning-circle-filled" | "warning-square-filled" | "info-square-outline" | "info-square-filled" | "info-circle-filled" | "more-circle-outline" | "more-square-outline" | "more-circle-filled" | "more-square-filled" | "client-feedback" | "expertise" | "responsibilities" | "mobile" | "delivery-address" | "delivery-address-2" | "pdp" | "versions" | "experience" | "projects" | "cooperation-model" | "billable" | "non-billable" | "recruitment-team" | "clear")[];
+export declare const iconsList: ("visible" | "reset" | "warning" | "h1" | "h2" | "h3" | "bold" | "archive" | "document" | "link" | "list" | "menu" | "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" | "setting-clock" | "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" | "panelLeft" | "panelRight" | "emailOutlined" | "lockOutlined" | "addFolder" | "moveFolder" | "attention-circle" | "zoom" | "zoom-in" | "zoom-out" | "pan" | "box-select" | "lasso-select" | "autoscale" | "reset-axes" | "star" | "preview" | "dashboard" | "phone" | "tablet" | "desktop" | "more-info" | "filter-list" | "history" | "overtime" | "save-2" | "folder" | "salary-reports" | "assessment-stages" | "comments-on-achievements" | "code-review-comments" | "support" | "leave" | "vacation" | "sick-leave" | "day-off" | "arrow-sort" | "dragndrop" | "send" | "save" | "today" | "busket" | "copy-link-2" | "upload" | "picture" | "warning-2" | "info" | "sort-up" | "sort-down" | "italic" | "strikethrough" | "underline" | "markup" | "numbered-list" | "bulleted-list" | "uppercase" | "dash" | "brackets" | "undo" | "redo" | "new-line" | "quotation" | "close-circle-outline" | "close-square-outline" | "close-circle-filled" | "close-square-filled" | "plus-square-outline" | "plus-square-filled" | "minus-square-outline" | "minus-square-filled" | "tick-square-outline" | "tick-square-filled" | "warning-circle-outline" | "warning-square-outline" | "warning-circle-filled" | "warning-square-filled" | "info-square-outline" | "info-square-filled" | "info-circle-filled" | "more-circle-outline" | "more-square-outline" | "more-circle-filled" | "more-square-filled" | "client-feedback" | "expertise" | "responsibilities" | "mobile" | "delivery-address" | "delivery-address-2" | "pdp" | "versions" | "experience" | "projects" | "cooperation-model" | "billable" | "non-billable" | "recruitment-team" | "clear" | "columns")[];

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

@@ -1,10 +1,23 @@
 import React from 'react';
 import { iconsList } from './icons/iconsList';
 export interface SVGProps extends React.SVGProps<SVGSVGElement> {
+    /** Width and height in px. Icons are square, so one value sets both. */
     size?: number;
 }
 export interface IconProps extends Omit<SVGProps, 'fill'> {
+    /**
+     * Which icon to render. Type-checked against the generated icon list, so a
+     * name that does not exist is a compile error rather than a blank render.
+     * Browse the set under "Design System / Icons" in Storybook.
+     */
     name: keyof MapIconsType;
+    /**
+     * Tooltip text shown on hover. Also becomes the icon's `aria-label`.
+     *
+     * Opt-in: without it the icon renders as decorative, with no accessible name.
+     * Supplying it wraps the icon in an extra inline-flex `span` — see the note on
+     * the component about layout impact.
+     */
     tooltip?: string;
 }
 export type MapIconsType = {

package/dist/components/Input/Input.d.ts

@@ -1,4 +1,98 @@
 import React from 'react';
 import { InputProps } from './types';
+/**
+ * Input - Text input component with validation and status indicators
+ *
+ * A comprehensive text input component with built-in React Hook Form integration,
+ * validation states, icon support, helper text, and character counting. Provides
+ * visual feedback through status colors and icons, and supports all standard HTML
+ * input types.
+ *
+ * @category Form Controls
+ * @subcategory Input
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with React Hook Form
+ * const { register } = useForm();
+ * <Input
+ *   name="email"
+ *   type="email"
+ *   placeholder="Enter your email"
+ *   register={register}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Input with validation
+ * <Input
+ *   name="password"
+ *   type="password"
+ *   register={register}
+ *   validationSchema={{
+ *     required: 'Password is required',
+ *     minLength: { value: 8, message: 'Must be at least 8 characters' }
+ *   }}
+ *   status={errors.password ? 'error' : 'basic'}
+ *   errors={errors.password}
+ *   showHelperText
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Input with icons and helper text (without React Hook Form)
+ * <Input
+ *   name="search"
+ *   placeholder="Search products..."
+ *   startElement={<Icon name="search" />}
+ *   endElement={<Icon name="clear" onClick={handleClear} />}
+ *   helperText="Type to search"
+ *   showHelperText
+ *   onChange={(e) => handleSearch(e.target.value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Input with character count
+ * <Input
+ *   name="bio"
+ *   placeholder="Tell us about yourself"
+ *   register={register}
+ *   maxLength={200}
+ *   showHelperText
+ *   helperText="Maximum 200 characters"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with Field component
+ * <Field.Root status={errors.email ? 'error' : 'basic'}>
+ *   <Field.Label htmlFor="email">Email</Field.Label>
+ *   <Field.Control>
+ *     <Input
+ *       id="email"
+ *       name="email"
+ *       register={register}
+ *       css={{ width: '100%', border: '0 !important' }}
+ *     />
+ *   </Field.Control>
+ *   <Field.Error>{errors.email?.message}</Field.Error>
+ * </Field.Root>
+ * ```
+ *
+ * @see {@link Field} - Use Field.Root to wrap Input for labels and validation
+ * @see {@link Textarea} - For multi-line text input
+ * @see {@link TextField} - Alternative text input component
+ *
+ * @accessibility
+ * - Full keyboard navigation support
+ * - Screen reader friendly with proper labels
+ * - ARIA attributes via React Hook Form
+ * - Error messages announced to screen readers
+ */
 declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
 export default Input;

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

@@ -1,5 +1,78 @@
 import React from 'react';
 import { DropdownOptionProps } from '../DropdownOptions/types';
 import { DropdownProps } from './types';
+/**
+ * MultipleDropdown - Dropdown component for multi-select and single-select
+ *
+ * A flexible dropdown that lets users select one or more options from a list.
+ * In multi-select mode (`isMultiple=true`, default) each option toggles independently;
+ * the toggle button shows the first selected value and a `+N` badge for overflow.
+ * In single-select mode (`isMultiple=false`) selecting an option closes the menu.
+ * Forwards its ref to the root container div.
+ *
+ * Component structure:
+ * - MultipleDropdown (root container with context)
+ *   - DropdownToggle (button that opens/closes the menu)
+ *   - MultipleDropdownOptions (menu container rendered when open)
+ *     - DropdownOption (individual selectable items)
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * // Basic multi-select
+ * <MultipleDropdown
+ *   label="Fruits"
+ *   selectedItems={[{ value: 'apple' }]}
+ *   onChange={(value, isSelected) => handleChange(value, isSelected)}
+ * >
+ *   <DropdownOption value="apple">Apple</DropdownOption>
+ *   <DropdownOption value="banana">Banana</DropdownOption>
+ *   <DropdownOption value="cherry">Cherry</DropdownOption>
+ * </MultipleDropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Single-select mode (closes on pick)
+ * <MultipleDropdown
+ *   label="Country"
+ *   isMultiple={false}
+ *   selectedItems={selected}
+ *   onChange={handleChange}
+ * >
+ *   <DropdownOption value="us">United States</DropdownOption>
+ *   <DropdownOption value="uk">United Kingdom</DropdownOption>
+ * </MultipleDropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Hide placeholder text, only show badge count
+ * <MultipleDropdown
+ *   label="Tags"
+ *   showPlaceholder={false}
+ *   selectedItems={tags}
+ *   onChange={handleChange}
+ * >
+ *   {tags.map(tag => (
+ *     <DropdownOption key={tag.value} value={tag.value}>{tag.label}</DropdownOption>
+ *   ))}
+ * </MultipleDropdown>
+ * ```
+ *
+ * @see {@link DropdownOption} - Child component for individual options
+ * @see {@link DropdownToggle} - Toggle button component
+ * @see {@link MultipleDropdownOptions} - Options menu container
+ *
+ * @accessibility
+ * - ARIA attributes set according to WAI-ARIA combobox pattern
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - Click outside to close
+ * - Screen reader friendly with aria-expanded and aria-controls
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
+ */
 declare const MultipleDropdown: React.ForwardRefExoticComponent<DropdownProps<DropdownOptionProps> & React.RefAttributes<HTMLDivElement>>;
 export default MultipleDropdown;

package/dist/components/NestedTable/WithNestedTableRow.d.ts

@@ -1,2 +1,41 @@
 import { WithNestedTableRowProps } from './types';
+/**
+ * WithNestedTableRow - Groups rows into one collapsible unit.
+ *
+ * Wrap a run of `NestedTableRow` children in it. **Position decides role**: the
+ * first child becomes the sub-header that carries the toggle, and the rest are
+ * the rows it shows and hides. Renders no markup of its own — it only supplies
+ * each child with the group's context — so it is safe between `TableBody` and
+ * the rows.
+ *
+ * A group containing a single row has nothing to toggle, so it renders no icon
+ * and ignores `defaultCollapsed` — otherwise it could start collapsed with no
+ * way to reopen it.
+ *
+ * @category Components
+ * @subcategory Data Display
+ *
+ * @example
+ * ```tsx
+ * // One group per team; each starts expanded
+ * {teams.map((team) => (
+ *   <WithNestedTableRow key={team.id}>
+ *     <NestedTableRow>
+ *       <NestedTableCell>{team.name}</NestedTableCell>
+ *     </NestedTableRow>
+ *     {team.members.map((member) => (
+ *       <NestedTableRow key={member.id}>
+ *         <NestedTableCell>{member.name}</NestedTableCell>
+ *       </NestedTableRow>
+ *     ))}
+ *   </WithNestedTableRow>
+ * ))}
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Collapse just this group, whatever the table default is
+ * <WithNestedTableRow defaultCollapsed>{rows}</WithNestedTableRow>
+ * ```
+ */
 export declare const WithNestedTableRow: ({ children, defaultCollapsed, }: WithNestedTableRowProps) => import("@emotion/react/jsx-runtime").JSX.Element[] | null | undefined;