@ssa-ui-kit/core 3.1.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/components/Button/Button.d.ts +8 -8
  2. package/dist/components/Button/types.d.ts +12 -8
  3. package/dist/components/Chip/constants.d.ts +7 -0
  4. package/dist/components/Chip/helpers.d.ts +1 -1
  5. package/dist/components/Chip/styles.d.ts +4 -0
  6. package/dist/components/CollapsibleNavBar/CollapsibleNavBar.d.ts +1 -1
  7. package/dist/components/CollapsibleNavBar/types.d.ts +13 -0
  8. package/dist/components/DatePicker/types.d.ts +218 -5
  9. package/dist/components/DateRangePicker/DateRangePicker.d.ts +51 -0
  10. package/dist/components/DateRangePicker/DateRangePickerFormBridge.d.ts +29 -5
  11. package/dist/components/DateRangePicker/constants.d.ts +8 -0
  12. package/dist/components/DateRangePicker/types.d.ts +235 -11
  13. package/dist/components/Dropdown/Dropdown.d.ts +1 -1
  14. package/dist/components/Dropdown/types.d.ts +9 -0
  15. package/dist/components/History/History.d.ts +31 -0
  16. package/dist/components/History/index.d.ts +2 -0
  17. package/dist/components/History/styles.d.ts +9 -0
  18. package/dist/components/History/types.d.ts +56 -0
  19. package/dist/components/Icon/icons/EmployeeBlackboard.d.ts +3 -0
  20. package/dist/components/Icon/icons/FileMark.d.ts +3 -0
  21. package/dist/components/Icon/icons/FilePdf.d.ts +3 -0
  22. package/dist/components/Icon/icons/FileWord.d.ts +3 -0
  23. package/dist/components/Icon/icons/SettingClock.d.ts +3 -0
  24. package/dist/components/Icon/icons/all.d.ts +5 -0
  25. package/dist/components/Icon/icons/iconsList.d.ts +1 -1
  26. package/dist/components/MultipleDropdown/types.d.ts +9 -0
  27. package/dist/components/PersonInfo/PersonInfo.d.ts +78 -0
  28. package/dist/components/PersonInfo/PersonInfoAvatar.d.ts +6 -0
  29. package/dist/components/PersonInfo/PersonInfoBadges.d.ts +6 -0
  30. package/dist/components/PersonInfo/PersonInfoCounter.d.ts +6 -0
  31. package/dist/components/PersonInfo/PersonInfoIcon.d.ts +5 -0
  32. package/dist/components/PersonInfo/PersonInfoValue.d.ts +5 -0
  33. package/dist/components/PersonInfo/constants.d.ts +5 -0
  34. package/dist/components/PersonInfo/helpers.d.ts +5 -0
  35. package/dist/components/PersonInfo/index.d.ts +4 -0
  36. package/dist/components/PersonInfo/types.d.ts +54 -0
  37. package/dist/components/index.d.ts +2 -1
  38. package/dist/index.js +682 -65
  39. package/dist/index.js.map +1 -1
  40. package/package.json +3 -3
@@ -2,16 +2,16 @@ import { ButtonProps } from './types';
2
2
  /**
3
3
  * Button - Interactive button component for user actions.
4
4
  *
5
- * Variant colors are driven entirely by `theme.palette` — each variant reads
6
- * `palette.<variant>.main` for the default background, `palette.<variant>.dark`
7
- * for hover and active states, and `palette.<variant>.light` for focus state.
8
- * Override any palette entry in a custom theme to restyle a variant without
9
- * affecting other components.
5
+ * Variant colors are driven entirely by `theme.palette` for solid variants — each
6
+ * reads `palette.<variant>.main` (default), `palette.<variant>.dark` (hover/active),
7
+ * `palette.<variant>.light` (focus). Override any palette entry in a custom theme
8
+ * to restyle a variant without affecting other components.
10
9
  *
11
- * ### Variants (default: `tertiary`)
10
+ * ### Variants (default: `custom`)
11
+ * - `custom` — transparent, dark text; recommended for low-emphasis actions (default)
12
12
  * - `primary` — blue, high emphasis, white text
13
13
  * - `secondary` — grey, medium emphasis, dark text
14
- * - `tertiary` — transparent background, dark text, focus outline only (default)
14
+ * - `tertiary` — legacy; same as custom; prefer `custom` instead
15
15
  * - `error` — red, destructive actions, white text
16
16
  * - `warning` — orange, caution actions, white text
17
17
  * - `success` — green, confirmation actions, white text
@@ -21,7 +21,7 @@ import { ButtonProps } from './types';
21
21
  *
22
22
  * @example
23
23
  * ```tsx
24
- * // No variant passed → tertiary (transparent ghost button)
24
+ * // No variant passed → custom (transparent, recommended)
25
25
  * <Button text="Cancel" onClick={handleCancel} />
26
26
  * ```
27
27
  *
@@ -1,4 +1,4 @@
1
- import { AriaAttributes } from 'react';
1
+ import React, { AriaAttributes } from 'react';
2
2
  import { SerializedStyles, Theme } from '@emotion/react';
3
3
  import { MouseEventHandler } from 'react';
4
4
  /**
@@ -72,9 +72,11 @@ export interface ButtonProps extends ButtonAriaProps {
72
72
  */
73
73
  endIconClassName?: string;
74
74
  /**
75
- * Visual style variant of the button (uses theme.palette)
76
- * - `primary` | `secondary` | `tertiary` | `error` | `warning` | `success`
77
- * @default 'tertiary'
75
+ * Visual style variant of the button (uses theme.palette for solid variants).
76
+ * - `custom` transparent, dark text; recommended for low-emphasis actions (default)
77
+ * - `primary` | `secondary` | `error` | `warning` | `success` — use theme.palette
78
+ * - `tertiary` — legacy; same as custom; prefer `custom` instead
79
+ * @default 'custom'
78
80
  */
79
81
  variant?: keyof ButtonVariants;
80
82
  /**
@@ -108,14 +110,16 @@ export interface ButtonProps extends ButtonAriaProps {
108
110
  }
109
111
  /**
110
112
  * Button variant style functions.
111
- * Each function reads from `theme.palette.<variant>` using the following convention:
112
- * - `main` → default background
113
- * - `dark` → hover and active background
114
- * - `light` → focus background
113
+ * Solid variants (primary, secondary, error, warning, success) read from
114
+ * `theme.palette.<variant>`: main (default), dark (hover/active), light (focus).
115
+ * Custom and tertiary are transparent (no palette); prefer custom to tertiary.
115
116
  */
116
117
  export interface ButtonVariants {
118
+ /** Recommended transparent variant; no focus outline. */
119
+ custom: (theme: Theme) => SerializedStyles;
117
120
  primary: (theme: Theme) => SerializedStyles;
118
121
  secondary: (theme: Theme) => SerializedStyles;
122
+ /** Legacy transparent variant; prefer custom. */
119
123
  tertiary: (theme: Theme) => SerializedStyles;
120
124
  error: (theme: Theme) => SerializedStyles;
121
125
  warning: (theme: Theme) => SerializedStyles;
@@ -10,6 +10,13 @@ export declare const COLORS: {
10
10
  readonly ERROR: "error";
11
11
  readonly WARNING: "warning";
12
12
  };
13
+ /** Outlined variant background opacity (light color with opacity) */
14
+ export declare const OUTLINED_BG_OPACITY: {
15
+ readonly DEFAULT: 0.08;
16
+ readonly HOVER: 0.24;
17
+ readonly ACTIVE: 0.4;
18
+ readonly DISABLED: 0.24;
19
+ };
13
20
  export declare const mapSizes: {
14
21
  small: import("@emotion/react").SerializedStyles;
15
22
  medium: import("@emotion/react").SerializedStyles;
@@ -12,7 +12,7 @@ type ColorConfig = {
12
12
  darkText?: boolean;
13
13
  };
14
14
  export declare const colorMap: (theme: Theme) => Record<SemanticColor, ColorConfig>;
15
- export declare const getVariantColors: (theme: Theme, variant: ChipProps["variant"], color: ChipProps["color"], disabled: boolean) => {
15
+ export declare const getVariantColors: (theme: Theme, variant: ChipProps["variant"], color: ChipProps["color"], disabled: boolean, isClickable?: boolean) => {
16
16
  chipStyles: import("@emotion/react").SerializedStyles;
17
17
  iconColor: string | undefined;
18
18
  };
@@ -11,7 +11,11 @@ export declare const filled: (theme: Theme) => import("@emotion/react").Serializ
11
11
  export declare const filledDisabled: (theme: Theme) => import("@emotion/react").SerializedStyles;
12
12
  export declare const outlined: (theme: Theme) => import("@emotion/react").SerializedStyles;
13
13
  export declare const outlinedDisabled: (theme: Theme) => import("@emotion/react").SerializedStyles;
14
+ /** Hover/active bg opacity for default (grey) outlined clickable chip */
15
+ export declare const clickableOutlinedDefault: (theme: Theme) => import("@emotion/react").SerializedStyles;
14
16
  export declare const clickable: import("@emotion/react").SerializedStyles;
17
+ /** cursor + transition only; hover/active handled by variant (e.g. outlined bg opacity) */
18
+ export declare const clickableBase: import("@emotion/react").SerializedStyles;
15
19
  export declare const clickableDisabled: import("@emotion/react").SerializedStyles;
16
20
  export declare const IconWrapper: import("@emotion/styled").StyledComponent<{
17
21
  theme?: Theme;
@@ -2,4 +2,4 @@ import { CollapsibleNavBarExtendedProps } from './types';
2
2
  /**
3
3
  * UI Component that shows the collapsible navigation bar
4
4
  */
5
- export declare const CollapsibleNavBar: ({ items, renderLogo, theme, subMenuMaxWidth, showIconTooltip, className, useMatchPattern, onChange, exactMatch, }: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;
5
+ export declare const CollapsibleNavBar: ({ items, renderLogo, theme, subMenuMaxWidth, showIconTooltip, className, useMatchPattern, onChange, exactMatch, defaultExpanded, }: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;
@@ -12,13 +12,21 @@ export interface CollapsibleNavBarGroup<T extends NavBarExtendedSubItem = NavBar
12
12
  prefix: string;
13
13
  }
14
14
  export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem = NavBarExtendedSubItem> {
15
+ /** Nav items: link items (path, iconName, iconSize, title) or groups with prefix, iconName, iconSize, title, items (sub-items: path, title). */
15
16
  items: Array<CollapsibleNavBarItem | CollapsibleNavBarGroup<T>>;
17
+ /** Logo or branding element (e.g. image or div) shown above the nav. */
16
18
  renderLogo: React.ReactElement;
19
+ /** Visual theme: dark (default) or light sidebar. */
17
20
  theme?: 'default' | 'light';
21
+ /** Optional CSS class for the root. */
18
22
  className?: string;
23
+ /** Max width for submenu panels (e.g. 220). */
19
24
  subMenuMaxWidth?: CSSProperties['maxWidth'];
25
+ /** When true, show tooltips on nav icons when sidebar is collapsed. */
20
26
  showIconTooltip?: boolean;
27
+ /** Custom route matching for active state (e.g. for React Router). */
21
28
  useMatchPattern?: (prefix: string) => string | PathPattern<string>;
29
+ /** Called when the sidebar expand/collapse state changes. */
22
30
  onChange?: (isChecked: boolean) => void;
23
31
  /**
24
32
  * If true, only exact path matches will be considered active.
@@ -26,4 +34,9 @@ export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem
26
34
  * @default false
27
35
  */
28
36
  exactMatch?: boolean;
37
+ /**
38
+ * Initial expanded state (sidebar shows icon + text). When false, only icons are shown until the user toggles.
39
+ * @default false
40
+ */
41
+ defaultExpanded?: boolean;
29
42
  }
@@ -5,29 +5,158 @@ import { InputProps } from '../Input/types';
5
5
  import { PICKER_TYPE } from './constants';
6
6
  import { RegisterOptions } from 'react-hook-form';
7
7
  import type { PickerCalendarType, DateFormat } from '../JsonSchemaForm/utils/dateFormats';
8
+ /**
9
+ * Which calendar granularity the picker uses: full **days**, **months** only, or **years** only.
10
+ * Drives default **format**, mask, initial calendar view, and the **Date** passed to **onChange**
11
+ * (`startOf('day' | 'month' | 'year')`).
12
+ *
13
+ * - **`days`** — `mm/dd/yyyy` (or `dd/mm/yyyy`), day-level selection
14
+ * - **`months`** — `mm/yyyy`, month-level selection
15
+ * - **`years`** — `yyyy`, year-level selection
16
+ */
8
17
  export type PickerType = (typeof PICKER_TYPE)[keyof typeof PICKER_TYPE];
18
+ /**
19
+ * Input/output string format for the form field. Must match **`pickerType`** (e.g. **`yyyy`** for
20
+ * year picker). Parsed with Luxon using **`mm`** → month tokens in the format string.
21
+ *
22
+ * - **`mm/dd/yyyy`** | **`dd/mm/yyyy`** — day pickers
23
+ * - **`mm/yyyy`** — month picker
24
+ * - **`yyyy`** — year picker
25
+ */
9
26
  export type DatePickerFormat = DateFormat;
10
- export type DatePickerProps = {
27
+ /**
28
+ * Which surface of the popover calendar is shown: day grid, month grid, or year list.
29
+ * Usually advanced; the header toggles this for day pickers.
30
+ */
31
+ export type CalendarType = PickerCalendarType;
32
+ /**
33
+ * Props for the DatePicker component
34
+ *
35
+ * Masked date field integrated with **react-hook-form**. Register **`name`** via
36
+ * **`FormProvider`**; the stored value is the **formatted string**. Use **`onChange`** for a
37
+ * **`Date`** (or undefined when cleared). Optional **`dateMin`** / **`dateMax`** use the same
38
+ * string shape as **`format`**.
39
+ *
40
+ * @example
41
+ * ```tsx
42
+ * // Basic (day picker, US format)
43
+ * <DatePicker name="due" label="Due date" helperText="Optional" />
44
+ * ```
45
+ *
46
+ * @example
47
+ * ```tsx
48
+ * // European format, open calendar from icon or input
49
+ * <DatePicker
50
+ * name="eu"
51
+ * format="dd/mm/yyyy"
52
+ * openCalendarMode="both"
53
+ * dateMin="01/01/2024"
54
+ * dateMax="31/12/2025"
55
+ * />
56
+ * ```
57
+ *
58
+ * @example
59
+ * ```tsx
60
+ * // Month-only picker with bounds
61
+ * <DatePicker
62
+ * name="period"
63
+ * label="Period"
64
+ * pickerType="months"
65
+ * dateMin="01/2020"
66
+ * dateMax="12/2030"
67
+ * />
68
+ * ```
69
+ */
70
+ export interface DatePickerProps {
71
+ /**
72
+ * Field name registered with react-hook-form (**required**).
73
+ */
11
74
  name: string;
75
+ /**
76
+ * Optional label rendered above the input (**`Label`**).
77
+ */
12
78
  label?: string;
79
+ /**
80
+ * Date string format for display, mask, and parsing.
81
+ * @default From **`pickerType`**: `mm/dd/yyyy`, `mm/yyyy`, or `yyyy`
82
+ */
13
83
  format?: DatePickerFormat;
84
+ /**
85
+ * Options passed to **`@react-input/mask`** (mask pattern, **`replacement`**, etc.).
86
+ * Defaults include the built-in date/month/year masks.
87
+ */
14
88
  maskOptions?: Parameters<typeof useMask>[0];
89
+ /**
90
+ * What opens the calendar: calendar **icon** only, **input** click only, or **both**.
91
+ * @default 'icon'
92
+ */
15
93
  openCalendarMode?: 'icon' | 'input' | 'both';
94
+ /**
95
+ * Day vs month vs year picker; sets default **format**, mask length, and calendar start view.
96
+ * @default 'days' (**`PICKER_TYPE.DAYS`**)
97
+ */
16
98
  pickerType?: PickerType;
99
+ /**
100
+ * Extra props forwarded to the underlying **Input** (e.g. **`id`**, **`inputProps`**).
101
+ */
17
102
  inputProps?: Partial<InputProps>;
103
+ /**
104
+ * Controlled string value (must match **format**). Synced into the form via **`setValue`**.
105
+ */
18
106
  value?: string;
107
+ /**
108
+ * Initial string value when uncontrolled (must match **format**).
109
+ */
19
110
  defaultValue?: string;
111
+ /**
112
+ * Inclusive minimum date as a string in the current **format** (and **pickerType**).
113
+ * @default Built-in minimum for the picker type (e.g. `01/01/1900` for days)
114
+ */
20
115
  dateMin?: string;
116
+ /**
117
+ * Inclusive maximum date as a string in the current **format** (and **pickerType**).
118
+ * @default Built-in maximum for the picker type (e.g. `01/01/2150` for days)
119
+ */
21
120
  dateMax?: string;
121
+ /**
122
+ * Disables the input and calendar trigger.
123
+ * @default false
124
+ */
22
125
  disabled?: boolean;
126
+ /**
127
+ * Helper text below the field (shown with validation message when present).
128
+ */
23
129
  helperText?: string;
130
+ /**
131
+ * Whether the trailing calendar icon button is shown.
132
+ * @default true
133
+ */
24
134
  showCalendarIcon?: boolean;
135
+ /**
136
+ * Last **Date** emitted from **onChange**; used with **`highlightDates`** for range styling
137
+ * in the calendar (e.g. paired with another picker’s value).
138
+ */
25
139
  lastChangedDate?: Date;
140
+ /**
141
+ * Optional range highlight between this picker’s value and **`otherDate`** (e.g. date-range UX).
142
+ */
26
143
  highlightDates?: {
144
+ /**
145
+ * When true, range styling is applied between anchors according to **mode**.
146
+ */
27
147
  enabled: boolean;
148
+ /**
149
+ * Whether this picker represents the **start** or **end** of the highlighted span.
150
+ */
28
151
  mode: 'dateFrom' | 'dateTo';
152
+ /**
153
+ * The other boundary date (from a sibling field or parent state).
154
+ */
29
155
  otherDate: Date | null;
30
156
  };
157
+ /**
158
+ * Optional class names for calendar shell, header, trigger, month arrows, and label.
159
+ */
31
160
  classNames?: {
32
161
  header?: string;
33
162
  trigger?: {
@@ -42,36 +171,120 @@ export type DatePickerProps = {
42
171
  calendar?: string;
43
172
  label?: string;
44
173
  };
174
+ /**
175
+ * Called with the selected **`Date`** (Luxon-normalized to start of day/month/year), or
176
+ * **undefined** when the field is cleared or invalid.
177
+ */
45
178
  onChange?: (date?: Date) => void;
179
+ /**
180
+ * Called when the popover opens.
181
+ */
46
182
  onOpen?: () => void;
183
+ /**
184
+ * Called when the popover closes (not on first mount).
185
+ */
47
186
  onClose?: () => void;
187
+ /**
188
+ * Called when validation fails or clears: first argument is the raw input string or **null**;
189
+ * second is an error message (e.g. invalid date / out of range) or **null** when cleared.
190
+ */
48
191
  onError?: (date: any, error?: string | null) => void;
192
+ /**
193
+ * Called when the visible month changes (day picker, prev/next month).
194
+ */
49
195
  onMonthChange?: (date: Date) => void;
196
+ /**
197
+ * Called when the selected or browsed **year** changes (year list or drilling into months).
198
+ */
50
199
  onYearChange?: (date: Date) => void;
200
+ /**
201
+ * Blur handler composed with internal validation (runs after **`processValue`** on blur).
202
+ */
51
203
  onBlur?: React.FocusEventHandler<HTMLInputElement>;
204
+ /**
205
+ * Extra **react-hook-form** rules merged with the field (e.g. **required**).
206
+ */
52
207
  validationSchema?: RegisterOptions;
53
- };
54
- export type DatePickerContextProps = Omit<DatePickerProps, 'dateMin' | 'dateMax'> & {
208
+ }
209
+ /**
210
+ * Context value for **DatePicker** internals (provider) and advanced composition.
211
+ * Extends **DatePicker** props but replaces **`dateMin`** / **`dateMax`** strings with parsed
212
+ * **Luxon** values and numeric parts for masks; adds open state and calendar navigation.
213
+ *
214
+ * Most consumers should use **DatePicker** only; this type documents hooks and subcomponents
215
+ * that read context.
216
+ */
217
+ export interface DatePickerContextProps extends Omit<DatePickerProps, 'dateMin' | 'dateMax'> {
218
+ /**
219
+ * Ref applied to the masked **input** (merged: mask ref + forwarded ref from **DatePicker**).
220
+ */
55
221
  inputRef?: React.ForwardedRef<HTMLInputElement | null>;
222
+ /**
223
+ * Whether the calendar popover is open.
224
+ */
56
225
  isOpen: boolean;
226
+ /**
227
+ * Active calendar surface: days grid, months, or years.
228
+ */
57
229
  calendarType: CalendarType;
230
+ /**
231
+ * Current string value watched from the form (may be partial while typing).
232
+ */
58
233
  inputValue?: string;
234
+ /**
235
+ * Parsed selected value in the picker’s **Luxon** representation.
236
+ */
59
237
  dateTime?: DateTime;
238
+ /**
239
+ * **Luxon** date driving the visible calendar month/year (clamped between min and max).
240
+ */
60
241
  calendarViewDateTime?: DateTime;
242
+ /**
243
+ * **`dateMin`** string split by **`/`** into numeric segments (index **i** matches **format** segment **i**).
244
+ */
61
245
  dateMinParts: number[];
246
+ /**
247
+ * **`dateMax`** string split by **`/`** into numeric segments (index **i** matches **format** segment **i**).
248
+ */
62
249
  dateMaxParts: number[];
250
+ /**
251
+ * Inclusive minimum as **DateTime** (from **dateMin** or defaults).
252
+ */
63
253
  dateMinDT: DateTime;
254
+ /**
255
+ * Inclusive maximum as **DateTime** (from **dateMax** or defaults).
256
+ */
64
257
  dateMaxDT: DateTime;
258
+ /**
259
+ * Indices of **day**, **month**, and **year** segments in the format string (for masks and bounds).
260
+ */
65
261
  formatIndexes: {
66
262
  day: number;
67
263
  month: number;
68
264
  year: number;
69
265
  };
266
+ /**
267
+ * Resolved picker type (**days** / **months** / **years**).
268
+ */
70
269
  pickerType: PickerType;
270
+ /**
271
+ * Internal **onChange** that dedupes emissions and normalizes to the picker **unit**.
272
+ */
71
273
  safeOnChange?: (date?: DateTime) => void;
274
+ /**
275
+ * Updates the calendar’s visible month/year without necessarily committing a selection.
276
+ */
72
277
  setCalendarViewDateTime: Dispatch<SetStateAction<DateTime | undefined>>;
278
+ /**
279
+ * Sets the selected **DateTime** (and syncs formatted string to the form when valid).
280
+ */
73
281
  setDateTime: Dispatch<SetStateAction<DateTime<boolean> | undefined>>;
282
+ /**
283
+ * Opens or closes the popover.
284
+ */
74
285
  setIsOpen: Dispatch<SetStateAction<boolean>>;
286
+ /**
287
+ * Switches between days / months / years views in the popover.
288
+ */
75
289
  setCalendarType: Dispatch<SetStateAction<CalendarType>>;
76
- };
77
- export type CalendarType = PickerCalendarType;
290
+ }
@@ -1,2 +1,53 @@
1
1
  import { DateRangePickerProps } from './types';
2
+ /**
3
+ * DateRangePicker — two masked inputs (**from** / **to**) with a shared popover calendar and
4
+ * **react-hook-form** fields **`${name}From`** and **`${name}To`** inside **`FormProvider`**.
5
+ * **`onChange`** emits **`[start, end]`** as **`Date`**, **`undefined`**, or **`null`** on the **end**
6
+ * only for **“Present”** (open-ended range) when **`showPresentOption`** is enabled.
7
+ *
8
+ * ### Behavior notes
9
+ * - **Luxon** parses strings; the form stores **formatted strings** per **format** / **rangePickerType**.
10
+ * - Calendar selection uses a **start → end** step; **`allowReverseSelection`** can swap inverted picks.
11
+ * - Use **`DateRangePickerFormBridge`** when the form stores **ISO** strings and **`PRESENT_VALUE`**
12
+ * for Present (string-safe schemas).
13
+ *
14
+ * @category Components
15
+ * @subcategory Form Controls
16
+ *
17
+ * @example
18
+ * ```tsx
19
+ * import { FormProvider, useForm } from 'react-hook-form';
20
+ * import { DateRangePicker } from '@ssa-ui-kit/core';
21
+ *
22
+ * function Example() {
23
+ * const methods = useForm({
24
+ * defaultValues: { tripFrom: '', tripTo: '' },
25
+ * });
26
+ * return (
27
+ * <FormProvider {...methods}>
28
+ * <DateRangePicker
29
+ * name="trip"
30
+ * label="Trip dates"
31
+ * onChange={(dates) => console.log(dates)}
32
+ * />
33
+ * </FormProvider>
34
+ * );
35
+ * }
36
+ * ```
37
+ *
38
+ * @example
39
+ * ```tsx
40
+ * // Open-ended end date: `to === null` means Present
41
+ * <DateRangePicker name="job" showPresentOption onChange={() => {}} />
42
+ * ```
43
+ *
44
+ * @see {@link Input} — Masked inputs
45
+ * @see {@link Popover} — Calendar overlay
46
+ * @see {@link DateRangePickerFormBridge} — ISO / string form adapter
47
+ *
48
+ * @accessibility
49
+ * - **Field** label associates with the focused input
50
+ * - Calendar controls reuse **aria-** patterns from day/month/year views
51
+ * - Calendar trigger uses an **aria-label** on the icon button
52
+ */
2
53
  export declare const DateRangePicker: ({ format, showCalendarIcon, showStatusArea, rangePickerType, showPresentOption, ...rest }: DateRangePickerProps) => import("@emotion/react/jsx-runtime").JSX.Element;
@@ -19,17 +19,22 @@ import { type DateFormat } from '../JsonSchemaForm/utils/dateFormats';
19
19
  * - UI display: Used as display text shown to users when "Present" is selected
20
20
  */
21
21
  export declare const PRESENT_VALUE = "Present";
22
+ /**
23
+ * Form-side shape: **start** / **end** strings in **`outputFormat`**; **end** may be **`PRESENT_VALUE`**
24
+ * when the user chose **Present** (maps to **`null`** inside **DateRangePicker**).
25
+ */
22
26
  export type DateRangePickerFormBridgeValue = {
27
+ /** Start date string (e.g. ISO in **outputFormat**) */
23
28
  start?: string;
29
+ /** End date string, or **`PRESENT_VALUE`** for open-ended range */
24
30
  end?: string | typeof PRESENT_VALUE;
25
31
  };
26
32
  /**
27
- * DateRangePickerFormBridge - adapter between form builders and DateRangePicker
33
+ * Props for **DateRangePickerFormBridge** adapter between string-based forms and **DateRangePicker**.
28
34
  *
29
- * PURPOSE:
30
- * - Keeps DateRangePicker "pure": it only ever sees inputFormat and null for "Present"
31
- * - Converts form value (outputFormat + PRESENT_VALUE string) picker value (inputFormat + null)
32
- * - Used by DateRangeField (RJSF); can be used by other form builders
35
+ * - Keeps **DateRangePicker** on **inputFormat** and **`null`** for Present
36
+ * - Converts **outputFormat** storage display **inputFormat**
37
+ * - Used by **DateRangeField** (RJSF) and similar builders
33
38
  */
34
39
  export type DateRangePickerFormBridgeProps = Omit<DateRangePickerProps, 'defaultValue' | 'value' | 'onChange'> & {
35
40
  /** Form value: dates in outputFormat, end can be PRESENT_VALUE for "Present" */
@@ -43,4 +48,23 @@ export type DateRangePickerFormBridgeProps = Omit<DateRangePickerProps, 'default
43
48
  /** Format used for display in the picker, e.g. 'dd/mm/yyyy' */
44
49
  inputFormat: DateFormat;
45
50
  };
51
+ /**
52
+ * Wraps **DateRangePicker** with an internal **FormProvider** and converts between
53
+ * **`outputFormat`** (form storage) and **`inputFormat`** (picker display). Maps **`null`** ↔
54
+ * **`PRESENT_VALUE`** for the end date only.
55
+ *
56
+ * @category Components
57
+ * @subcategory Form Controls
58
+ *
59
+ * @example
60
+ * ```tsx
61
+ * <DateRangePickerFormBridge
62
+ * name="contract"
63
+ * outputFormat="yyyy-MM-dd"
64
+ * inputFormat="mm/dd/yyyy"
65
+ * value={{ start: '2024-01-01', end: 'Present' }}
66
+ * onChange={(v) => save(v)}
67
+ * />
68
+ * ```
69
+ */
46
70
  export declare const DateRangePickerFormBridge: ({ value, defaultValue: defaultValueProp, onChange, outputFormat, inputFormat: inputFormatProp, ...pickerProps }: DateRangePickerFormBridgeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
@@ -1,6 +1,14 @@
1
+ /**
2
+ * Default formats, masks, bounds, and validation messages for **DateRangePicker**
3
+ * (aligned with **DatePicker** constants for shared behavior).
4
+ */
5
+ /** Default US day format (`mm/dd/yyyy`). Re-exported from the package barrel. */
1
6
  export declare const DEFAULT_MASK_FORMAT = "mm/dd/yyyy";
7
+ /** Default European day format (`dd/mm/yyyy`). Re-exported from the package barrel. */
2
8
  export declare const DEFAULT_EUROPEAN_MASK_FORMAT = "dd/mm/yyyy";
9
+ /** Default month format (`mm/yyyy`). Re-exported from the package barrel. */
3
10
  export declare const DEFAULT_MONTH_MASK_FORMAT = "mm/yyyy";
11
+ /** Default year-only format (`yyyy`). Re-exported from the package barrel. */
4
12
  export declare const DEFAULT_YEAR_MASK_FORMAT = "yyyy";
5
13
  export declare const DEFAULT_MASK = "__/__/____";
6
14
  export declare const DEFAULT_MONTH_MASK = "__/____";