@ssa-ui-kit/core 3.2.0 → 3.3.0

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

@@ -4,41 +4,142 @@ import { useMask } from '@react-input/mask';
 import { FieldContextValue } from '../Field/FieldProvider';
 import { InputProps } from '../Input/types';
 import type { PickerCalendarType, DateFormat } from '../JsonSchemaForm/utils/dateFormats';
+/**
+ * Which side of the range has focus for calendar selection and keyboard flow: **from** or **to**.
+ */
 export type LastFocusedElement = 'from' | 'to';
+/**
+ * Calendar granularity: **days**, **months**, or **years** (same as **DatePicker** / shared **PickerCalendarType**).
+ */
 export type RangePickerType = PickerCalendarType;
+/**
+ * Mask and parse format for both inputs (e.g. **`mm/dd/yyyy`**, **`dd/mm/yyyy`**, **`mm/yyyy`**, **`yyyy`**).
+ */
 export type Format = DateFormat;
 /**
- * Type for the dates tuple passed to DateRangePicker's onChange callback.
+ * Tuple passed to **`onChange`**: **[start, end]** in JavaScript **`Date`**, **`null`**, or **`undefined`**.
  *
- * - Date: A valid date was selected
- * - null: "Present" option was selected (end date only)
- * - undefined: Date field is empty/unset
+ * - **`Date`** — valid anchor for that side
+ * - **`null`** — **end date only**: user chose **“Present”** (open-ended range). **Start** is never **`null`**.
+ * - **`undefined`** — that side is empty / cleared
  */
 export type DateRangePickerOnChangeDates = [
     Date | null | undefined,
     Date | null | undefined
 ];
-export type DateRangePickerProps = {
+/**
+ * Parsed range as **Luxon** values before emitting JS dates (**`[from, to]`**).
+ */
+export type DateTimeTuple = [DateTime | undefined, DateTime | undefined];
+/**
+ * Active calendar view: day grid, month grid, or year list (aligned with **rangePickerType** / header navigation).
+ */
+export type CalendarType = PickerCalendarType;
+/**
+ * Props for **DateRangePicker**
+ *
+ * Two masked inputs registered as **`${name}From`** and **`${name}To`** under **react-hook-form**
+ * **`FormProvider`**. Stored values are **formatted strings**; **`onChange`** receives **`DateRangePickerOnChangeDates`**.
+ * Optional **“Present”** applies only to the **end** date (**`showPresentOption`**).
+ *
+ * @example
+ * ```tsx
+ * <DateRangePicker
+ *   name="employment"
+ *   label="Employment period"
+ *   messages={{ description: 'Start and end dates' }}
+ *   onChange={(dates) => console.log(dates)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <DateRangePicker
+ *   name="period"
+ *   rangePickerType="months"
+ *   format="mm/yyyy"
+ *   dateMin="01/2020"
+ *   dateMax="12/2030"
+ *   showPresentOption
+ * />
+ * ```
+ */
+export interface DateRangePickerProps {
+    /**
+     * Base field name; registers **`${name}From`** and **`${name}To`** with react-hook-form.
+     */
     name: string;
+    /**
+     * Optional label (**`Field.Label`**); **`htmlFor`** follows the focused input.
+     */
     label?: string;
+    /**
+     * Date string format for both fields. Defaults from **`rangePickerType`** if omitted.
+     */
     format?: Format;
+    /**
+     * Initial open state for the calendar popover (controlled open seed).
+     */
     isOpenState?: boolean;
+    /**
+     * Controlled tuple of string values matching **format**; **`null`** at index **1** means **“Present”** end.
+     */
     value?: [string | undefined | null, string | undefined | null];
+    /**
+     * Initial tuple; **`[string, null]`** end means **Present** (open-ended).
+     */
     defaultValue?: [string, string | null] | [string, string];
+    /**
+     * Options for **`@react-input/mask`** (shared pattern for both inputs).
+     */
     maskOptions?: Parameters<typeof useMask>[0];
+    /**
+     * Extra props for the underlying **Input** fields.
+     */
     inputProps?: Partial<InputProps>;
+    /**
+     * Visual status for **`Field.Root`** (**error** / **success** / **basic**).
+     */
     status?: FieldContextValue['status'];
+    /**
+     * Whether **`messages`** render in **`TriggerStatusArea`** below the inputs.
+     * @default true
+     */
     showStatusArea?: boolean;
+    /**
+     * Inclusive minimum date string (shape matches **format** and **rangePickerType**).
+     */
     dateMin?: string;
+    /**
+     * Inclusive maximum date string (shape matches **format** and **rangePickerType**).
+     */
     dateMax?: string;
+    /**
+     * Disables both inputs and the calendar trigger.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Shows the calendar icon button to open the popover.
+     * @default true
+     */
     showCalendarIcon?: boolean;
+    /**
+     * **days** | **months** | **years** — drives default **format**, mask, and calendar chrome.
+     * @default 'days'
+     */
     rangePickerType?: RangePickerType;
+    /**
+     * Optional copy for the status area (description / success / error messaging).
+     */
     messages?: {
         description?: string;
         success?: string;
         error?: string;
     };
+    /**
+     * Optional class names for trigger layout, inputs, icon, calendar shell, and label.
+     */
     classNames?: {
         trigger?: {
             root?: string;
@@ -51,54 +152,177 @@ export type DateRangePickerProps = {
         calendar?: string;
         label?: string;
     };
+    /**
+     * Emits **`[start, end]`** as **`Date`**, **`null`** (Present end only), or **`undefined`** per side.
+     */
     onChange?: (dates?: DateRangePickerOnChangeDates) => void;
+    /**
+     * Calendar popover opened.
+     */
     onOpen?: () => void;
+    /**
+     * Calendar popover closed.
+     */
     onClose?: () => void;
+    /**
+     * Validation or parse error: raw input value and message (e.g. invalid / out of range).
+     */
     onError?: (date: unknown, error?: string | null) => void;
+    /**
+     * Visible month changed (prev/next) while in day view.
+     */
     onMonthChange?: (date: Date) => void;
+    /**
+     * Year changed from year list or header drill-down.
+     */
     onYearChange?: (date: Date) => void;
+    /**
+     * Blur handler composed with internal validation.
+     */
     onBlur?: FocusEventHandler<HTMLInputElement>;
+    /**
+     * If the user picks an end before a start, swap the two dates instead of rejecting.
+     * @default false
+     */
     allowReverseSelection?: boolean;
+    /**
+     * Shows a **Present** control in the calendar (end date only — ongoing range).
+     * @default false
+     */
     showPresentOption?: boolean;
-};
-export type DateTimeTuple = [DateTime | undefined, DateTime | undefined];
-export type DateRangePickerContextProps = Omit<DateRangePickerProps, 'dateMin' | 'dateMax'> & {
+}
+/**
+ * Context value for **DateRangePicker** (provider + subcomponents). Extends picker props but
+ * replaces **`dateMin`** / **`dateMax`** strings with **Luxon** bounds and segment arrays; adds
+ * dual field names, refs, range selection step, and **Present** end state.
+ *
+ * Most apps use **DateRangePicker** only; this documents **useDateRangePickerContext** consumers.
+ */
+export interface DateRangePickerContextProps extends Omit<DateRangePickerProps, 'dateMin' | 'dateMax'> {
+    /**
+     * Registered field name for the **start** input (**`${name}From`**).
+     */
     nameFrom: string;
+    /**
+     * Registered field name for the **end** input (**`${name}To`**).
+     */
     nameTo: string;
+    /**
+     * Whether the calendar popover is open.
+     */
     isOpen: boolean;
+    /**
+     * **Luxon** date for the calendar header / navigation (current visible month or year).
+     */
     currentCalendarViewDT: DateTime;
+    /**
+     * **`0`** when **from** is focused, **`1`** when **to** is focused.
+     */
     currentIndex: number;
+    /**
+     * Per-side calendar view anchors (**`[fromView, toView]`**).
+     */
     calendarViewDateTime: DateTimeTuple;
+    /**
+     * Active popover view: **days**, **months**, or **years**.
+     */
     calendarType: CalendarType;
+    /**
+     * Watched form value for the **from** field.
+     */
     inputValueFrom?: string;
+    /**
+     * Watched form value for the **to** field.
+     */
     inputValueTo?: string;
+    /**
+     * Ref for the **from** masked input (merged).
+     */
     inputFromRef: React.ForwardedRef<HTMLInputElement | null>;
+    /**
+     * Ref for the **to** masked input (merged).
+     */
     inputToRef: React.ForwardedRef<HTMLInputElement | null>;
+    /**
+     * Parsed **Luxon** range (**`[from, to]`**).
+     */
     dateTime: DateTimeTuple;
+    /**
+     * **`dateMin`** split by **`/`** into numeric segments (index **i** matches **format** segment **i**).
+     */
     dateMinParts: number[];
+    /**
+     * **`dateMax`** split by **`/`** into numeric segments (index **i** matches **format** segment **i**).
+     */
     dateMaxParts: number[];
+    /**
+     * Inclusive minimum as **DateTime**.
+     */
     dateMinDT: DateTime;
+    /**
+     * Inclusive maximum as **DateTime**.
+     */
     dateMaxDT: DateTime;
+    /**
+     * Indices of **dd**, **mm**, **yyyy** in the **format** string.
+     */
     formatIndexes: {
         day: number;
         month: number;
         year: number;
     };
+    /**
+     * Which input is focused for calendar and validation.
+     */
     lastFocusedElement: LastFocusedElement;
+    /**
+     * Last **`onChange`** tuple in **JS** dates (supports **Present** as **`null`** on end).
+     */
     lastChangedDate?: [Date | undefined | null, Date | undefined | null];
+    /**
+     * Internal change handler (Luxon) used when selecting from the calendar.
+     */
     safeOnChange?: (date?: DateTime) => void;
+    /**
+     * Sets **from** vs **to** focus.
+     */
     setLastFocusedElement: Dispatch<SetStateAction<LastFocusedElement>>;
+    /**
+     * Updates last emitted **Date** tuple for parents and highlights.
+     */
     setLastChangedDate: Dispatch<SetStateAction<[Date | undefined | null, Date | undefined | null]>>;
+    /**
+     * Toggles popover from icon or input (**implementation**-specific rules).
+     */
     handleToggleOpen: MouseEventHandler<HTMLButtonElement | HTMLInputElement>;
+    /**
+     * Updates one or both calendar view anchors.
+     */
     setCalendarViewDateTime: Dispatch<SetStateAction<DateTimeTuple>>;
+    /**
+     * Sets the selected **Luxon** range.
+     */
     setDateTime: Dispatch<SetStateAction<DateTimeTuple>>;
+    /**
+     * Opens or closes the popover.
+     */
     setIsOpen: Dispatch<SetStateAction<boolean>>;
+    /**
+     * Switches day / month / year surface in the popover.
+     */
     setCalendarType: Dispatch<SetStateAction<CalendarType>>;
+    /**
+     * **start** → **end** two-step calendar selection, or **null** when not in that flow.
+     */
     rangeSelectionStep: 'start' | 'end' | null;
     setRangeSelectionStep: Dispatch<SetStateAction<'start' | 'end' | null>>;
+    /**
+     * Clears **from** or **to** and syncs form state.
+     */
     clearInputValue: (field: 'from' | 'to') => void;
-    showPresentOption?: boolean;
+    /**
+     * End field shows **Present** (open-ended); form **to** value may be empty while flag is true.
+     */
     isEndDatePresent: boolean;
     setIsEndDatePresent: Dispatch<SetStateAction<boolean>>;
-};
-export type CalendarType = PickerCalendarType;
+}

package/dist/components/History/History.d.ts

@@ -0,0 +1,31 @@
+import { HistoryProps } from './types';
+/**
+ * History - Vertical timeline component for chronological events.
+ *
+ * Renders a date column and content column for each item, connected by
+ * timeline markers. Marker colors can be set per item or via defaults.
+ *
+ * ### Color behavior
+ * - `item.color` overrides the marker color for a specific row
+ * - `defaultColor` is used when `item.color` is not provided
+ * - fallback default marker color: `theme.palette.primary.main`
+ * - fallback connector color: `theme.colors.greyLighter`
+ *
+ * ### Alignment behavior
+ * The marker is vertically aligned to the first text line and adapts when
+ * `circleSize` changes.
+ *
+ * @category Components
+ * @subcategory Display
+ *
+ * @example
+ * ```tsx
+ * <History
+ *   items={[
+ *     { date: '01.01.2026', content: 'Account created' },
+ *     { date: '03.01.2026', content: 'Plan upgraded', color: '#10b981' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare const History: ({ items, defaultColor, lineColor, dateWidth, circleSize, sx, }: HistoryProps) => import("@emotion/react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export * from './History';
+export type * from './types';

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

@@ -0,0 +1,9 @@
+export declare const FIRST_LINE_TOP_PADDING = 2;
+export declare const FIRST_LINE_HEIGHT = 20;
+export declare const container: import("@emotion/react").SerializedStyles;
+export declare const row: import("@emotion/react").SerializedStyles;
+export declare const leftColumn: (width: number) => import("@emotion/react").SerializedStyles;
+export declare const circle: (color: string, size: number, topOffset: number) => import("@emotion/react").SerializedStyles;
+export declare const connector: (color: string, circleTopOffset: number, circleSize: number) => import("@emotion/react").SerializedStyles;
+export declare const dateColumn: (width: number) => import("@emotion/react").SerializedStyles;
+export declare const contentColumn: import("@emotion/react").SerializedStyles;

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

@@ -0,0 +1,56 @@
+import React from 'react';
+/**
+ * Single timeline row model for `History`.
+ */
+export interface HistoryItemType {
+    /**
+     * Left column value (date/time/period label).
+     */
+    date: React.ReactNode;
+    /**
+     * Main row content shown in the right column.
+     */
+    content: React.ReactNode;
+    /**
+     * Optional marker color for this row.
+     * If omitted, `defaultColor` from `HistoryProps` is used.
+     */
+    color?: string;
+    /**
+     * Optional stable React key.
+     */
+    key?: string | number;
+}
+/**
+ * Props for the `History` timeline component.
+ */
+export interface HistoryProps {
+    /**
+     * Timeline rows to render from top to bottom.
+     */
+    items: HistoryItemType[];
+    /**
+     * Default marker color for rows without `item.color`.
+     * Falls back to `theme.palette.primary.main`.
+     */
+    defaultColor?: string;
+    /**
+     * Connector line color between markers.
+     * Falls back to `theme.colors.greyLighter`.
+     */
+    lineColor?: string;
+    /**
+     * Width of the date column in pixels.
+     * @default 120
+     */
+    dateWidth?: number;
+    /**
+     * Marker circle diameter in pixels.
+     * @default 12
+     */
+    circleSize?: number;
+    /**
+     * Inline style for the root container.
+     */
+    sx?: React.CSSProperties;
+}

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

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

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

@@ -98,6 +98,7 @@ export * as Roles from './Roles';
 export * as Search from './Search';
 export * as Seniority from './Seniority';
 export * as Settings from './Settings';
+export * as SettingClock from './SettingClock';
 export * as Signature from './Signature';
 export * as Sleep from './Sleep';
 export * as StaffGrowthCoefficient from './StaffGrowthCoefficient';

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" | "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")[];
+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" | "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")[];

package/dist/components/index.d.ts

@@ -37,7 +37,6 @@ export { default as MultipleDropdownOptions } from './MultipleDropdownOptions';
 export * from './Typeahead';
 export * from './DatePicker';
 export * from './DateRangePicker';
-export type { CalendarType } from './DatePicker/types';
 export * from './ColorPicker';
 export * from './SearchBox';
 export type * from './SearchBox/types';
@@ -111,6 +110,8 @@ export type * from './Stepper/types';
 export { default as Step } from './Step';
 export { default as StepConnector } from './StepConnector';
 export { default as StepLabel } from './StepLabel';
+export * from './History';
+export type * from './History/types';
 export * from './Pagination';
 export { default as Link } from './Link';
 export * from './WithLink';