@rippling/pebble-sdui-web 0.7.0 → 0.9.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 (37) hide show
  1. package/dist/catalogs/ai_gateway/action-params.d.ts +5 -0
  2. package/dist/catalogs/ai_gateway/actions.d.ts +5 -0
  3. package/dist/catalogs/ai_gateway/catalog.d.ts +33 -0
  4. package/dist/catalogs/ai_gateway/component-events.d.ts +6 -0
  5. package/dist/catalogs/ai_gateway/component-props.d.ts +51 -0
  6. package/dist/catalogs/ai_gateway/components.d.ts +7 -0
  7. package/dist/catalogs/ai_gateway/function-params.d.ts +5 -0
  8. package/dist/catalogs/ai_gateway/functions.d.ts +5 -0
  9. package/dist/catalogs/ai_gateway/index.cjs +2 -0
  10. package/dist/catalogs/ai_gateway/index.cjs.map +1 -0
  11. package/dist/catalogs/ai_gateway/index.d.ts +11 -0
  12. package/dist/catalogs/ai_gateway/index.js +366 -0
  13. package/dist/catalogs/ai_gateway/index.js.map +1 -0
  14. package/dist/catalogs/ai_gateway/render.d.ts +20 -0
  15. package/dist/catalogs/custom-apps/action-params.d.ts +4 -0
  16. package/dist/catalogs/custom-apps/actions.d.ts +2 -1
  17. package/dist/catalogs/custom-apps/catalog.d.ts +1 -1
  18. package/dist/catalogs/custom-apps/component-events.d.ts +16 -13
  19. package/dist/catalogs/custom-apps/component-props.d.ts +973 -161
  20. package/dist/catalogs/custom-apps/components.d.ts +5 -2
  21. package/dist/catalogs/custom-apps/index.cjs +3 -2
  22. package/dist/catalogs/custom-apps/index.cjs.map +1 -1
  23. package/dist/catalogs/custom-apps/index.d.ts +5 -5
  24. package/dist/catalogs/custom-apps/index.js +5951 -1306
  25. package/dist/catalogs/custom-apps/index.js.map +1 -1
  26. package/dist/docs/typescript/web/catalogs/ai_gateway/actions.md +6 -0
  27. package/dist/docs/typescript/web/catalogs/ai_gateway/components.md +31 -0
  28. package/dist/docs/typescript/web/catalogs/ai_gateway/computed-functions.md +6 -0
  29. package/dist/docs/typescript/web/catalogs/ai_gateway/definitions.md +6 -0
  30. package/dist/docs/typescript/web/catalogs/ai_gateway/readme.md +16 -0
  31. package/dist/docs/typescript/web/catalogs/ai_gateway/types.md +75 -0
  32. package/dist/docs/typescript/web/catalogs/custom-apps/actions.md +28 -0
  33. package/dist/docs/typescript/web/catalogs/custom-apps/components.md +450 -222
  34. package/dist/docs/typescript/web/catalogs/custom-apps/definitions.md +274 -242
  35. package/dist/docs/typescript/web/catalogs/custom-apps/readme.md +1 -1
  36. package/dist/docs/typescript/web/catalogs/custom-apps/types.md +1329 -116
  37. package/package.json +6 -1
@@ -7,7 +7,7 @@ Import component builders from `@rippling/pebble-sdui-web/catalogs/custom-apps`.
7
7
 
8
8
  Placeholder for states like empty, success, error, and loading, featuring animations, icons, text, and action buttons.
9
9
 
10
- primaryActionTitle and secondaryActionTitle create action buttons. Bind pressPrimary and pressSecondary events to handle clicks. Use animation instead of icon to show a Lottie animation as the card asset. Skipped on action buttons: tip (TipTypes), badge (BadgeProps), onMouseEnter/onMouseLeave (DOM events), onClickWhileDisabled (callback).
10
+ primaryAction and secondaryAction create action buttons. Bind pressPrimary and pressSecondary events to handle clicks. Use animation instead of icon to show a Lottie animation as the card asset. Padding accepts top/right/bottom/left Pebble spacing tokens.
11
11
 
12
12
  Catalog key: `ActionCard`
13
13
  Builder: `ActionCard`
@@ -21,17 +21,12 @@ Events: `pressPrimary`, `pressSecondary`
21
21
  |---|---:|---|---|
22
22
  | `alignment` | no | [ActionCardAlignment](./definitions.md#actioncardalignment) | Content alignment within the card. Default: CENTER |
23
23
  | `animation` | no | [ActionCardAnimation](./definitions.md#actioncardanimation) | Lottie animation name to display as the card asset instead of an icon |
24
- | `caption` | yes | string | Card caption/description text |
24
+ | `caption` | yes | string \| number | Card caption/description text |
25
25
  | `icon` | no | string | Icon type string from Icon.TYPES for the card asset |
26
26
  | `iconColor` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Pebble text/icon color token |
27
- | `primaryActionIcon` | no | string | Icon type string for the primary action button |
28
- | `primaryActionIsDisabled` | no | boolean | Disable the primary action button. Default: false |
29
- | `primaryActionTitle` | no | string | Label for the primary action button |
30
- | `primaryActionTo` | no | string \| [ActionCardPrimaryActionTo](./types.md#actioncardprimaryactionto) | Navigation destination for primary action. String URL or { path, openInNewTab? } |
31
- | `secondaryActionIcon` | no | string | Icon type string for the secondary action button |
32
- | `secondaryActionIsDisabled` | no | boolean | Disable the secondary action button. Default: false |
33
- | `secondaryActionTitle` | no | string | Label for the secondary action button |
34
- | `secondaryActionTo` | no | string \| [ActionCardSecondaryActionTo](./types.md#actioncardsecondaryactionto) | Navigation destination for secondary action. String URL or { path, openInNewTab? } |
27
+ | `padding` | no | [ActionCardPadding](./types.md#actioncardpadding) | Override container padding per side using Pebble spacing tokens |
28
+ | `primaryAction` | no | [ActionCardPrimaryAction](./types.md#actioncardprimaryaction) | Primary action button configuration |
29
+ | `secondaryAction` | no | [ActionCardSecondaryAction](./types.md#actioncardsecondaryaction) | Secondary action button configuration |
35
30
  | `shouldShowAsset` | no | boolean | Show the icon/animation asset. Default: true |
36
31
  | `title` | no | string | Card title text |
37
32
 
@@ -56,7 +51,6 @@ Events: _none_
56
51
  | `aria-label` | no | string | Accessible label for the icon |
57
52
  | `showText` | no | boolean | Whether to show the "Rippling AI" text alongside the icon. Default: true |
58
53
  | `size` | no | [AiIconSize](./definitions.md#aiiconsize) | Size of the AI icon. One of: SMALL, MEDIUM, LARGE. Default: MEDIUM |
59
- | `testId` | no | string | Value for data-testid attribute |
60
54
 
61
55
  No additional properties.
62
56
 
@@ -64,7 +58,7 @@ No additional properties.
64
58
 
65
59
  A persistent, high-priority notice that conveys critical information (errors, warnings, success confirmations, or informational messages) and guides users to proceed or resolve issues. Appears with page content and remains visible until dismissed or resolved. Use for system-level or page-level messaging, not for ephemeral feedback (use SnackBar instead) or for interruptions requiring immediate input (use Modal instead).
66
60
 
67
- primaryActionTitle and secondaryActionTitle create action buttons. Bind pressPrimary and pressSecondary events to handle clicks. Use isDismissible with the dismiss event to handle close actions.
61
+ primaryAction and secondaryAction create action buttons. Bind pressPrimary and pressSecondary events to handle clicks. Use isCloseable with the dismiss event to handle close actions.
68
62
 
69
63
  Catalog key: `Alert`
70
64
  Builder: `Alert`
@@ -76,21 +70,13 @@ Events: `pressPrimary`, `pressSecondary`, `dismiss`
76
70
 
77
71
  | Name | Required | Type | Description |
78
72
  |---|---:|---|---|
79
- | `isDismissible` | no | boolean | Shows close button when true. Default: false |
73
+ | `description` | no | string | Main description content to display in the alert |
74
+ | `isCloseable` | no | boolean | Shows close button when true. Default: false |
80
75
  | `isFluid` | no | boolean | If true, the alert takes full width of its container. Default: false |
81
- | `message` | no | string | Main message content to display in the alert |
82
- | `primaryActionIcon` | no | string | Icon type string from Icon.TYPES for the primary action button |
83
- | `primaryActionIsDisabled` | no | boolean | Disable the primary action button. Default: false |
84
- | `primaryActionShouldShowSpinner` | no | boolean | Show spinner on the primary action button. Default: false |
85
- | `primaryActionTitle` | no | string | Label text for the primary (filled) action button |
86
- | `primaryActionTo` | no | string \| [AlertPrimaryActionTo](./types.md#alertprimaryactionto) | Navigation destination for primary action. String URL or { path, openInNewTab? } |
87
- | `secondaryActionIcon` | no | string | Icon type string from Icon.TYPES for the secondary action button |
88
- | `secondaryActionIsDisabled` | no | boolean | Disable the secondary action button. Default: false |
89
- | `secondaryActionShouldShowSpinner` | no | boolean | Show spinner on the secondary action button. Default: false |
90
- | `secondaryActionTitle` | no | string | Label text for the secondary (outlined) action button |
91
- | `secondaryActionTo` | no | string \| [AlertSecondaryActionTo](./types.md#alertsecondaryactionto) | Navigation destination for secondary action. String URL or { path, openInNewTab? } |
76
+ | `primaryAction` | no | [AlertPrimaryAction](./types.md#alertprimaryaction) | Primary action button configuration |
77
+ | `secondaryAction` | no | [AlertSecondaryAction](./types.md#alertsecondaryaction) | Secondary action button configuration |
92
78
  | `title` | no | string | Alert title text displayed above the message |
93
- | `type` | no | [AlertType](./definitions.md#alerttype) | Alert type determining color and icon. Default: INFO |
79
+ | `type` | no | [AlertType](./definitions.md#alerttype) | Alert type determining color and icon. Default: Info |
94
80
 
95
81
  No additional properties.
96
82
 
@@ -160,8 +146,8 @@ A multi-select dropdown for choosing multiple options from grouped categories, w
160
146
 
161
147
  AppGroupSelect is a specialized multi-select variant designed for app group selection. It automatically sets isMulti=true, isAppGroup=true, and theme=TRANSPARENT_BORDER.
162
148
  onChange stores an array of selected values in state (multi-select only).
163
- Options support grouped structure with label and list properties for categorizing options.
164
- Options also support rich metadata: secondaryLabel/tertiaryLabel/quaternaryLabel for multi-line text, leftIconType/labelIcon for icons (use Icon.TYPES glyph names like 'CHECK_CIRCLE_OUTLINE'), avatarProps for user options, flag for country codes, isRecommended for badges, isSeparator for dividers.
149
+ List supports grouped structure with label and list properties for categorizing options.
150
+ List items also support rich metadata: secondaryLabel/tertiaryLabel/quaternaryLabel for multi-line text, leftIconType/labelIcon for icons (use Icon.TYPES glyph names like 'CHECK_CIRCLE_OUTLINE'), avatarProps for user options, flag for country codes, isRecommended for badges, isSeparator for dividers.
165
151
  onMenuToggle emits 'menuToggle' event when dropdown opens/closes.
166
152
  Footer onClick emits the custom event name specified in footer.onClick.
167
153
 
@@ -196,9 +182,9 @@ Events: `change`, `blur`, `focus`, `paste`, `menuToggle`
196
182
  | `isRequired` | no | boolean | Marks the field as required |
197
183
  | `isSearchable` | no | boolean | Enable type-to-search filtering |
198
184
  | `label` | no | string | Label text above the select |
185
+ | `list` | no | [AppGroupSelectList](./types.md#appgroupselectlist) \| [AppGroupSelectList](./types.md#appgroupselectlist)[] | Array of options or grouped options. Supports flat list or nested groups with label and list properties |
199
186
  | `maxHeight` | no | string \| number | Max height of multi-select container (CSS value) |
200
187
  | `maxTruncationLines` | no | number | Max rows of chips visible before "+X" overflow chip appears |
201
- | `options` | no | [AppGroupSelectOption](./types.md#appgroupselectoption) \| [AppGroupSelectOption](./types.md#appgroupselectoption)[] | Array of options or grouped options. Supports flat list or nested groups with label and list properties |
202
188
  | `placeholder` | no | string | Placeholder text when empty |
203
189
  | `placement` | no | [AppGroupSelectPlacement](./definitions.md#appgroupselectplacement) | Dropdown position relative to input. Default: bottom-start |
204
190
  | `rows` | no | number | Minimum number of rows to show |
@@ -269,7 +255,7 @@ No additional properties.
269
255
 
270
256
  A visual representation of an entity, such as a user, organization, or product. Use circular shape (isRounded=true) for people and rounded square (isRounded=false) for non-human entities like organizations or brands.
271
257
 
272
- Type semantics: USER is the default for people (shows image or initials fallback). TEXT shows first+last initials from title. ICON displays a specified icon to represent an entity. NUMBER indicates overflow count in avatar lists. RIPPLING is exclusive to the Rippling brand. Badge and flag are mutually exclusive — use either badgeChar or flagCountryCode, not both. When using flagCountryCode, flagSurfaceColor is required. tip.content accepts a plain string for tooltip text shown on hover.
258
+ Type semantics: USER is the default for people (shows image or initials fallback). TEXT shows first+last initials from title. ICON displays a specified icon to represent an entity. NUMBER indicates overflow count in avatar lists. RIPPLING is exclusive to the Rippling brand. Badge and flag are mutually exclusive — use either badge or flagCountryCode, not both. When using flagCountryCode, surfaceColor is required. tip.content accepts a plain string for tooltip text shown on hover.
273
259
 
274
260
  Catalog key: `Avatar`
275
261
  Builder: `Avatar`
@@ -285,17 +271,16 @@ Events: `press`
285
271
  | `aria-label` | no | string | Accessible label for the avatar |
286
272
  | `aria-labelledby` | no | string | ID of element that labels the avatar |
287
273
  | `aria-role` | no | string | ARIA role for the avatar element |
288
- | `badgeAriaLabel` | no | string | Accessible label for the badge. Required when badgeChar is set |
289
- | `badgeChar` | no | string | Single character to display in a small badge overlay on the avatar |
274
+ | `badge` | no | [AvatarBadge](./types.md#avatarbadge) | Badge overlay configuration for the avatar |
290
275
  | `caption` | no | string | Secondary text shown below the title |
291
276
  | `flagCountryCode` | no | string | ISO country code (e.g. US, IN) to show a flag overlay on the avatar |
292
- | `flagSurfaceColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Surface color for flag background. Pebble color token. Required with flagCountryCode |
293
277
  | `icon` | no | string \| [AvatarIcon](./types.md#avataricon) | Icon name from Icon.TYPES (e.g. EDIT_OUTLINE) or { type, color?, backgroundColor? } when type is ICON |
294
278
  | `image` | no | string | Image URL for the avatar |
295
- | `imageBackground` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Surface color token behind the avatar image |
279
+ | `imageBackground` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Surface color token behind the avatar image |
296
280
  | `isCompact` | no | boolean | Compact mode hides title and caption. Default: false |
297
281
  | `isRounded` | no | boolean | Fully rounded (circle) shape. Default: true |
298
- | `size` | no | [AvatarSize](./definitions.md#avatarsize) | Avatar size variant. Default: S |
282
+ | `size` | no | 24 \| 32 \| 40 \| 56 \| 64 | Avatar size in pixels. One of: 24, 32, 40, 56, 64. Default: 40 |
283
+ | `surfaceColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Surface color for flag background. Pebble color token. Required with flagCountryCode |
299
284
  | `tip` | no | [AvatarTip](./types.md#avatartip) | Tooltip shown on avatar hover. Object with content string and optional title |
300
285
  | `title` | no | string | Display name shown below or beside the avatar |
301
286
  | `to` | no | string \| [AvatarTo](./types.md#avatarto) | Navigation destination. String URL or { path, openInNewTab? }. Use instead of click event if click is just for navigation |
@@ -320,11 +305,14 @@ Events: _none_
320
305
 
321
306
  | Name | Required | Type | Description |
322
307
  |---|---:|---|---|
308
+ | `aria-describedby` | no | string | ID of element that describes the avatar list |
309
+ | `aria-label` | no | string | Accessible label for the avatar list |
310
+ | `aria-labelledby` | no | string | ID of element that labels the avatar list |
323
311
  | `isRounded` | no | boolean | If false, avatars render as rounded squares |
324
312
  | `limit` | no | number | Maximum number of avatars to display before +N overflow |
325
313
  | `modalTitle` | no | string | Title of the modal shown when clicking overflow |
326
314
  | `roles` | no | [Role](./types.md#role)[] | Array of role/person objects for avatars |
327
- | `size` | no | [AvatarSize](./definitions.md#avatarsize) | Size of the avatars. Default: S |
315
+ | `size` | no | 24 \| 32 \| 40 \| 56 \| 64 | Avatar size in pixels. One of: 24, 32, 40, 56, 64. Default: 40 |
328
316
  | `totalCount` | no | number | Total count for overflow indicator |
329
317
  | `type` | no | [AvatarType](./definitions.md#avatartype) | Avatar content type |
330
318
 
@@ -347,10 +335,9 @@ Events: _none_
347
335
  | Name | Required | Type | Description |
348
336
  |---|---:|---|---|
349
337
  | `appearance` | no | [BadgeAppearance](./definitions.md#badgeappearance) | Visual appearance variant (INFO_DARK, SUCCESS_DARK, etc.). Default: INFO_DARK |
350
- | `ariaHidden` | no | boolean | Hide badge from screen readers |
351
- | `ariaLabel` | no | string | Accessibility label for screen readers |
352
- | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the badge (XS, S, M, L). Default: S |
353
- | `testId` | no | string | Test identifier for automated testing |
338
+ | `aria-hidden` | no | boolean | Hide badge from screen readers |
339
+ | `aria-label` | no | string | Accessibility label for screen readers |
340
+ | `size` | no | [BadgeSize](./definitions.md#badgesize) | Size of the badge. One of: EXTRA_SMALL, SMALL, MEDIUM, LARGE. Default: SMALL |
354
341
  | `text` | yes | string | Text content to display in the badge. Required. |
355
342
  | `tip` | no | [BadgeTip](./types.md#badgetip) | Tooltip configuration to show on hover |
356
343
 
@@ -397,7 +384,7 @@ Events: _none_
397
384
  |---|---:|---|---|
398
385
  | `align` | no | string | Align items on cross axis. CSS align-items value (e.g., "center", "flex-start") |
399
386
  | `alignSelf` | no | string | Align this child on cross axis. CSS align-self value (e.g., "center", "flex-end") |
400
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
387
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
401
388
  | `basis` | no | number \| string | Flex basis value. Number (pixels) or CSS string |
402
389
  | `border` | no | string \| [BoxBorder](./types.md#boxborder) \| [BoxBorder](./types.md#boxborder) | Border value. CSS string, strict token parts, or directional border object |
403
390
  | `boxSizing` | no | string | CSS box-sizing value. "content-box" or "border-box". Default: content-box |
@@ -469,6 +456,9 @@ Events: `select`
469
456
  | Name | Required | Type | Description |
470
457
  |---|---:|---|---|
471
458
  | `active` | no | string | Value of the active breadcrumb item. Default: last item |
459
+ | `aria-describedby` | no | string | ID of element that describes the breadcrumb nav |
460
+ | `aria-label` | no | string | Accessible label for the breadcrumb nav |
461
+ | `aria-labelledby` | no | string | ID of element that labels the breadcrumb nav |
472
462
  | `items` | yes | [BreadcrumbItem](./types.md#breadcrumbitem)[] | Array of breadcrumb items: {title, value, isDisabled?, href?} |
473
463
  | `noMargin` | no | boolean | Remove default margin from the component. Default: false |
474
464
  | `shouldCollapseMiddle` | no | boolean | Collapse middle items into a dropdown on desktop. Default: false |
@@ -542,7 +532,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
542
532
  | `shouldShowSpinner` | no | boolean | Show loading spinner explicitly. Default: false |
543
533
  | `size` | no | [ButtonSize](./definitions.md#buttonsize) | Button size. Default: M |
544
534
  | `tabIndex` | no | number | Tab order index for keyboard navigation |
545
- | `testId` | no | string | Sets data-testid attribute. Default: "test_button" |
546
535
  | `tip` | no | string \| [ButtonTip](./types.md#buttontip) | Tooltip configuration. Can be simple string content or object with appearance/placement |
547
536
  | `to` | no | string \| [ButtonTo](./types.md#buttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
548
537
  | `type` | no | [ButtonType](./definitions.md#buttontype) | HTML button type attribute. Default: button |
@@ -578,27 +567,29 @@ No additional properties.
578
567
 
579
568
  An inline calendar for selecting single or multiple dates. Displays a monthly view with navigation controls. Use for date selection UI without input field — when the calendar should always be visible. Use Date input for calendar in a popover; use DateInlineMulti for multiple date selection with different layout options.
580
569
 
581
- onClick stores an ISO 8601 date string (or array of strings for multi-select) in state. The format prop controls display only and does not affect the stored value. Use minDate/maxDate to restrict selectable range. onClear emits when user clicks clear button (if shown via footer).
570
+ onClick stores an ISO 8601 date string (or array of strings for multi-select) in state. confirmMobile does the same when mobile date selection is confirmed. The format prop controls display only and does not affect the stored value. Use minDate/maxDate to restrict selectable range. onClear clears the bound value and emits when user clicks clear button (if shown via footer).
582
571
 
583
572
  Catalog key: `Calendar`
584
573
  Builder: `Calendar`
585
574
  Props type: `CalendarProps`
586
575
  Accepts children: no
587
- Events: `click`, `clear`
576
+ Events: `click`, `clear`, `confirmMobile`
588
577
 
589
578
  ### Props
590
579
 
591
580
  | Name | Required | Type | Description |
592
581
  |---|---:|---|---|
582
+ | `displayDate` | no | string | Month to show initially as an ISO date string |
593
583
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
594
584
  | `isDisabled` | no | boolean | Disables the calendar |
595
585
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
586
+ | `locale` | no | string | Locale string used to determine the start of week |
596
587
  | `maxDate` | no | string | Latest selectable date as ISO string |
597
588
  | `minDate` | no | string | Earliest selectable date as ISO string |
598
589
  | `shouldShowFooter` | no | boolean | Controls footer visibility. Default: true |
599
590
  | `shouldShowHeader` | no | boolean \| [ShouldShowHeader](./types.md#shouldshowheader) | Controls header visibility. Default: true |
600
591
  | `shouldShowWeekDayInitials` | no | boolean | If false, hides week day initials. Default: true |
601
- | `testId` | no | string | Data test id for testing purposes |
592
+ | `showMonthYearPicker` | no | boolean | Show month and year picker in the calendar header. Default: false |
602
593
  | `value` | no | string \| string[] | Selected date(s) as ISO string(s). Single date or array for multi-select |
603
594
 
604
595
  No additional properties.
@@ -607,7 +598,7 @@ No additional properties.
607
598
 
608
599
  Visually groups related information and components into a contained, interactive card. Use for summarizing content, facilitating comparisons, or guiding users toward specific actions. Renders as a simple layout container when used with children only (no title/content).
609
600
 
610
- Card emits "click" when clicked, "edit"/"delete" for those actions, "add" for add cards, and "action" when a dropdown action is clicked. The clicked action id is written to the selectedActionId bound state before the "action" event fires. Use "to" prop for navigation. Use "content" prop for simple text or children for complex layouts. IMPORTANT: There is no margin beneath the card title. Always use a VStack with a top padding token as the first child of the Card to create spacing between the title and the content below.
601
+ Card emits "click" when clicked, "edit"/"delete" for those actions, "add" for add cards, and "action" when a dropdown action is clicked. The clicked action id is written to the selectedActionId bound state before the "action" event fires. Use "to" prop for navigation. Use "content" prop for simple text or children for complex layouts. In layout mode (children only, no title/content), padding and theme are passed to Card.Layout. IMPORTANT: There is no margin beneath the card title. Always use a VStack with a top padding token as the first child of the Card to create spacing between the title and the content below.
611
602
 
612
603
  Catalog key: `Card`
613
604
  Builder: `Card`
@@ -625,9 +616,11 @@ Events: `edit`, `delete`, `add`, `click`, `action`
625
616
  | `isAddCard` | no | boolean | Render as add card with plus icon. Emits "add" event when clicked. Default: false |
626
617
  | `isDisabled` | no | boolean | Whether the card is disabled. Default: false |
627
618
  | `minCardHeight` | no | number | Minimum height of card in pixels. Default: 150 |
619
+ | `padding` | no | 0 \| 8 \| 16 \| 24 \| 32 \| string | Padding for layout mode. Supports Card.Layout PADDINGS values or CSS string |
628
620
  | `selectedActionId` | no | string | Bound state path for the selected action id. Written before "action" event fires |
629
621
  | `showDelete` | no | boolean | Show delete button. Emits "delete" event when clicked. Default: false |
630
622
  | `showEdit` | no | boolean | Show edit button. Emits "edit" event when clicked. Default: false |
623
+ | `theme` | no | [CardTheme](./definitions.md#cardtheme) | Visual theme for layout mode. DEFAULT or SELECTABLE |
631
624
  | `title` | no | string | Card header title text |
632
625
  | `to` | no | string \| [CardTo](./types.md#cardto) | Route destination. String URL or object with {path, openInNewTab}. Card renders as anchor when provided |
633
626
  | `value` | no | unknown | Identifier value for the card, passed to event handlers |
@@ -737,7 +730,7 @@ No additional properties.
737
730
 
738
731
  A group of checkboxes that lets users select multiple options from a predefined list. Use when users can choose all, some, or none of the options. Use Radio instead for mutually exclusive single selection, or Toggle for immediate on/off activation.
739
732
 
740
- onChange stores an array of selected values in state. Each value matches the value field of a selected option. Options support secondaryLabel for multi-line text, tag for badges (string or {label, appearance}), tip for hover tooltips, and isDisabled for individual checkbox disabling. When isReadOnly=true, displays selected values as chips instead of checkboxes. Use variant=LIST for vertical list, variant=BOX for outlined boxes, variant=GRID for grid layout. Standalone — does not register with Form; use FormCheckboxGroup inside a Form instead.
733
+ onChange stores an array of selected values in state. Each value matches the value field of a selected option. List items support secondaryLabel for multi-line text, tag for badges (string or {label, appearance}), tip for hover tooltips, and isDisabled for individual checkbox disabling. When isReadOnly=true, displays selected values as chips instead of checkboxes. Use variant=LIST for vertical list, variant=BOX for outlined boxes, variant=GRID for grid layout. Standalone — does not register with Form; use FormCheckboxGroup inside a Form instead.
741
734
 
742
735
  Catalog key: `CheckboxGroup`
743
736
  Builder: `CheckboxGroup`
@@ -761,7 +754,7 @@ Events: `change`, `blur`
761
754
  | `isReadOnly` | no | boolean | Makes the checkbox group read-only (displays as chips) |
762
755
  | `isRequired` | no | boolean | Marks the field as required |
763
756
  | `label` | no | string | Label text above the checkbox group |
764
- | `options` | no | [CheckboxGroupOption](./types.md#checkboxgroupoption)[] | Array of { label, value } checkbox option objects |
757
+ | `list` | no | [CheckboxGroupList](./types.md#checkboxgrouplist)[] | Array of { label, value } checkbox option objects |
765
758
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
766
759
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
767
760
  | `value` | no | unknown[] | Currently selected values bound to state |
@@ -836,11 +829,11 @@ Events: `dismiss`, `press`
836
829
  | `avatar` | no | string \| [ChipAvatar](./types.md#chipavatar) | Avatar to display at the beginning. Can be image URL string or object with image/title/imageProps |
837
830
  | `icon` | no | string \| [ChipIcon](./types.md#chipicon) | Icon to display. Can be string name or object with type/color/alignment |
838
831
  | `isActive` | no | boolean | If true, applies active/selected styling (used inside SelectableGroup) |
832
+ | `isCloseable` | no | boolean | Shows close button when true. Default: false |
839
833
  | `isDisabled` | no | boolean | If true, the chip is visually and functionally disabled |
840
- | `isDismissible` | no | boolean | Shows close button when true. Default: false |
841
834
  | `isFluid` | no | boolean | If true, the chip takes all available width. Default: false |
842
835
  | `maxWidth` | no | number | Maximum width in pixels. Default: 400px |
843
- | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the chip (S, M, L, XL). Default: L |
836
+ | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the chip (SMALL, MEDIUM, LARGE, EXTRA_LARGE). Default: LARGE |
844
837
  | `text` | no | string | Text content to display in the chip |
845
838
  | `tip` | no | [ChipTip](./types.md#chiptip) | Tooltip configuration. Chip has default overflow tooltip behavior |
846
839
  | `to` | no | string \| [ChipTo](./types.md#chipto) | Navigation destination. Renders chip as anchor with router integration. Use for guaranteed navigation |
@@ -856,10 +849,10 @@ A layout container for grouping multiple Chip components (tags, filters, attribu
856
849
  **Overflow behavior:** When maxLinesToWrap is set, chips exceeding the line limit are hidden. A "+N more" button appears that opens an overflow modal showing all chips.
857
850
 
858
851
  **Events:**
859
- - overflowChange: Emitted when the overflow modal opens or closes. The isOpen state (boolean) is written to the component's state before the event fires.
852
+ - overflowChange: Emitted when the overflow modal opens or closes. The overflowModalIsOpen state (boolean) is written before the event fires.
860
853
 
861
854
  **State shape:**
862
- - onOverflowModalStateChange writes a boolean to state (true when modal opens, false when closes)
855
+ - onOverflowModalStateChange writes a boolean to overflowModalIsOpen (true when modal opens, false when closes)
863
856
 
864
857
  **Children:** Should contain Chip components.
865
858
 
@@ -876,8 +869,8 @@ Events: `overflowChange`
876
869
  | `batchSize` | no | number | Number of elements rendered in each incremental step, optimizing performance for large datasets |
877
870
  | `gap` | no | [BoxGap](./definitions.md#boxgap) | Spacing token for the flex gap between chip items. Default: theme default spacing |
878
871
  | `maxLinesToWrap` | no | number | Maximum number of lines to display before showing overflow modal. When set, chips exceeding this limit are hidden with a "+N more" trigger that opens a modal |
872
+ | `overflowModalIsOpen` | no | boolean | Bindable state value written when the overflow modal opens or closes. True when open, false when closed |
879
873
  | `overflowModalTitle` | no | string | Title text shown in the overflow modal header when maxLinesToWrap limit is exceeded |
880
- | `testId` | no | string | Test ID for the chip group container element |
881
874
 
882
875
  No additional properties.
883
876
 
@@ -955,7 +948,7 @@ Events: _none_
955
948
  | Name | Required | Type | Description |
956
949
  |---|---:|---|---|
957
950
  | `animate` | no | boolean | Enable animation. Default: true |
958
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token. Default: #f5f6f7 |
951
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token. Default: #f5f6f7 |
959
952
  | `backgroundOpacity` | no | number | Opacity of background color. Default: 1 |
960
953
  | `foregroundColor` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Foreground shimmer color token. Default: #eee |
961
954
  | `foregroundOpacity` | no | number | Opacity of foreground shimmer. Default: 1 |
@@ -993,7 +986,7 @@ No additional properties.
993
986
 
994
987
  Displays a country by its ISO code, showing flag and/or name. Can show both (default), flag only, or name only. Ideal for profiles, address settings, or regional customization contexts where country identification is needed.
995
988
 
996
- Country displays a country flag and name given an ISO country code (e.g. "US", "IN"). Use size to control flag dimensions (S/M/L, default L). Set onlyFlag=true to show only the flag, or shouldShowFlag=false to show only the country name. The icon prop accepts either a string icon name (e.g. "INFO_CIRCLE_OUTLINE") or an object with type, alignment ("RIGHT"), tip, and color for more control.
989
+ Country displays a country flag and name given an ISO country code (e.g. "US", "IN"). Use size to control flag dimensions (SMALL/MEDIUM/LARGE, default LARGE). Set onlyFlag=true to show only the flag, or shouldShowFlag=false to show only the country name. The icon prop accepts either a string icon name (e.g. "INFO_CIRCLE_OUTLINE") or an object with type, alignment ("RIGHT"), tip, color, size, state props, and ARIA labels for more control.
997
990
 
998
991
  Catalog key: `Country`
999
992
  Builder: `Country`
@@ -1006,11 +999,11 @@ Events: _none_
1006
999
  | Name | Required | Type | Description |
1007
1000
  |---|---:|---|---|
1008
1001
  | `countryCode` | yes | string | ISO country code (e.g. "US", "IN", "GB"). Used to display the country flag and name. |
1009
- | `icon` | no | string \| [CountryIcon](./types.md#countryicon) | Icon displayed alongside the country. Accepts a string icon name or an object with type, alignment, tip, and color. |
1002
+ | `icon` | no | string \| [CountryIcon](./types.md#countryicon) | Icon displayed alongside the country. Accepts a string icon name or an object with type, alignment, tip, color, size, state, and ARIA props. |
1010
1003
  | `onlyFlag` | no | boolean | When true, shows only the flag without rendering the country name. Default: false |
1011
1004
  | `shouldShowFlag` | no | boolean | When false, hides the country flag and shows only the country name. Default: true |
1012
1005
  | `shouldShowTipOnOverflow` | no | boolean | When false, disables the tooltip that appears when the country name overflows. Default: true |
1013
- | `size` | no | [CountrySize](./definitions.md#countrysize) | Size of the country flag. "S" = small, "M" = medium, "L" = large. Default: "L" |
1006
+ | `size` | no | [AiIconSize](./definitions.md#aiiconsize) | Size of the country flag. SMALL, MEDIUM, or LARGE. Default: LARGE |
1014
1007
 
1015
1008
  No additional properties.
1016
1009
 
@@ -1018,7 +1011,7 @@ No additional properties.
1018
1011
 
1019
1012
  Specialized input for entering monetary amounts with currency symbol/code prefix and locale-aware number formatting. Supports arithmetic expression evaluation, currency type selection via dropdown, and decimal precision control.
1020
1013
 
1021
- onChange stores a numeric value (number | string) in state. The prefix prop sets the currency symbol/code displayed before the amount; it does not affect the stored value. Use decimalPlaces to control precision. When canSelectCurrencyType is true, a dropdown selector is shown for currency selection. The currencyType prop controls the selected currency code (bind to state for user selection). Currency formatting is determined by the locale prop or user locale setting when shouldLocalize is true. When shouldAllowCalculation is true, users can enter arithmetic expressions (e.g. "100+50") which are evaluated on blur. Standalone — does not register with Form; use FormCurrency inside a Form instead.
1014
+ onChange stores a numeric value (number | string) in state by default. When shouldSendCurrencyType=true, onChange stores { value, type } using currencyTypeProps.value or currencyTypeProps.defaultValue for the type. The prefix prop sets the currency symbol/code displayed before the amount; it does not affect the stored value. Use decimalPlaces to control precision. When canSelectCurrencyType is true, a dropdown selector is shown for currency selection and currencyTypeProps controls the nested Select props. Currency formatting is determined by the locale prop or user locale setting when shouldLocalize is true. When shouldAllowCalculation is true, users can enter arithmetic expressions (e.g. "100+50") which are evaluated on blur. Standalone — does not register with Form; use FormCurrency inside a Form instead.
1022
1015
 
1023
1016
  Catalog key: `Currency`
1024
1017
  Builder: `Currency`
@@ -1039,10 +1032,9 @@ Events: `change`, `blur`
1039
1032
  | `autoFocus` | no | boolean | If true, input will be focused on mount |
1040
1033
  | `canSelectCurrencyType` | no | boolean | If true, displays a dropdown to select currency type |
1041
1034
  | `checks` | no | [CurrencyCheck](./types.md#currencycheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1042
- | `currencyType` | no | string | Currency code for the selector when canSelectCurrencyType is true (e.g. USD, EUR) |
1043
- | `currencyTypeDefaultValue` | no | string | Default currency code for uncontrolled selector. Default: USD |
1035
+ | `currencyTypeProps` | no | [CurrencyCurrencyTypeProp](./types.md#currencycurrencytypeprop) | Nested Select props for the currency selector |
1044
1036
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
1045
- | `defaultValue` | no | string \| number | Initial value for uncontrolled component |
1037
+ | `defaultValue` | no | string \| number \| [CurrencyDefaultValue](./types.md#currencydefaultvalue) | Initial value for uncontrolled component. Use { value, type } with shouldSendCurrencyType |
1046
1038
  | `isDisabled` | no | boolean | Disables the input |
1047
1039
  | `isIntegerOnly` | no | boolean | If true, only integer values will be allowed. Default: false |
1048
1040
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -1059,10 +1051,11 @@ Events: `change`, `blur`
1059
1051
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates equation on blur |
1060
1052
  | `shouldDisableRedundantZeroFormatting` | no | boolean | If false, redundant zeros are removed using parseFloat. If true (default), zeros are preserved. Default: true |
1061
1053
  | `shouldLocalize` | no | boolean | If true, currency format is determined from user locale setting. Default: true |
1054
+ | `shouldSendCurrencyType` | no | boolean | If true, onChange writes { value, type } using currencyTypeProps value/defaultValue |
1062
1055
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1063
1056
  | `step` | no | number | Value to add/subtract on pressing arrow up/down respectively. Default: 1 |
1064
1057
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1065
- | `value` | no | string \| number | Current currency value bound to state |
1058
+ | `value` | no | string \| number \| [CurrencyValue](./types.md#currencyvalue) | Current currency value bound to state. Use { value, type } with shouldSendCurrencyType |
1066
1059
 
1067
1060
  No additional properties.
1068
1061
 
@@ -1070,7 +1063,7 @@ No additional properties.
1070
1063
 
1071
1064
  A date input that lets users select a single date via calendar or keyboard entry. Use for collecting exact, approximate, or memorable dates (e.g. birth date, start date) and for scheduling. Optionally includes time selection with timezone support. Use DateRange for start/end date pairs; use DateInlineMulti for selecting multiple individual dates without an input field.
1072
1065
 
1073
- onChange stores an ISO 8601 date string in state. When shouldShowTime is true, the stored ISO string includes time. The format prop is display-only and does not affect the stored value. Defaults to MM/dd/yyyy format and en-US locale. Standalone — does not register with Form; use FormDate inside a Form instead.
1066
+ onChange stores an ISO 8601 date string or null in state. When shouldShowTime is true, the stored ISO string includes time. The format prop is display-only and does not affect the stored value. Defaults to MM/dd/yyyy format and en-US locale. Use theme=NO_BOX to remove input box styling. Standalone — does not register with Form; use FormDate inside a Form instead.
1074
1067
 
1075
1068
  Catalog key: `Date`
1076
1069
  Builder: `Date`
@@ -1089,6 +1082,7 @@ Events: `change`, `blur`
1089
1082
  | `aria-labelledby` | no | string | ID of element that labels this input |
1090
1083
  | `canClear` | no | boolean | Show clear button |
1091
1084
  | `checks` | no | [DateCheck](./types.md#datecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1085
+ | `defaultValue` | no | string | Initial ISO date string or null for uncontrolled usage |
1092
1086
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1093
1087
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1094
1088
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
@@ -1109,10 +1103,11 @@ Events: `change`, `blur`
1109
1103
  | `shouldShowTime` | no | boolean | Include time selection |
1110
1104
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
1111
1105
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1106
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1112
1107
  | `timeProps` | no | [TimeProp](./types.md#timeprop) | Configuration for time picker. Sets initial time value independently of date input |
1113
1108
  | `timezone` | no | string | Timezone name (e.g. "America/New_York"). Used with shouldShowTime |
1114
1109
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1115
- | `value` | no | string | ISO date string bound to state |
1110
+ | `value` | no | string | ISO date string or null bound to state |
1116
1111
 
1117
1112
  No additional properties.
1118
1113
 
@@ -1120,7 +1115,7 @@ No additional properties.
1120
1115
 
1121
1116
  An always-visible inline calendar for selecting multiple individual dates without an input field. Use when users need to pick several non-contiguous dates (e.g. holidays, blocked days). Use Date for single-date entry with an input field, or DateRange for start/end date pairs.
1122
1117
 
1123
- onChange stores an array of ISO 8601 date strings in state. Each date toggle adds or removes an ISO string from the array. The format prop is display-only and does not affect stored values.
1118
+ onChange stores an array of ISO 8601 date strings or null in state. Each date toggle adds or removes an ISO string from the array. The format prop is display-only and does not affect stored values.
1124
1119
 
1125
1120
  Catalog key: `DateInlineMulti`
1126
1121
  Builder: `DateInlineMulti`
@@ -1134,6 +1129,7 @@ Events: `change`, `blur`
1134
1129
  |---|---:|---|---|
1135
1130
  | `name` | no | string | Unique identifier for the input |
1136
1131
  | `checks` | no | [DateInlineMultiCheck](./types.md#dateinlinemulticheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1132
+ | `defaultValue` | no | string[] | Initial array of selected ISO 8601 date strings |
1137
1133
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: yyyy-MM-dd |
1138
1134
  | `isDisabled` | no | boolean | Disables the calendar |
1139
1135
  | `isReadOnly` | no | boolean | Makes the calendar read-only |
@@ -1143,7 +1139,7 @@ Events: `change`, `blur`
1143
1139
  | `maxDate` | no | string | Latest selectable date as ISO string |
1144
1140
  | `minDate` | no | string | Earliest selectable date as ISO string |
1145
1141
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1146
- | `value` | no | string[] | Array of selected ISO 8601 date strings bound to state |
1142
+ | `value` | no | string[] | Array of selected ISO 8601 date strings or null bound to state |
1147
1143
 
1148
1144
  No additional properties.
1149
1145
 
@@ -1151,7 +1147,7 @@ No additional properties.
1151
1147
 
1152
1148
  A date range picker for selecting a start date and end date pair, such as travel dates, leave periods, or reporting intervals. Use Date instead when only a single date is needed.
1153
1149
 
1154
- onChange stores an array of two ISO strings [startDate, endDate] in state. When shouldShowTime is true, the stored ISO strings include time. The format prop is display-only for user interface. timezone must be set when shouldShowTime is true for correct time conversion. shouldLocalize controls whether display format is determined from locale (default: true). startDateLabel/endDateLabel customize the field labels. Use aria-label or aria-labelledby for accessibility when label is not provided.
1150
+ onChange stores null or an array of two ISO strings/null entries [startDate, endDate] in state. When shouldShowTime is true, the stored ISO strings include time. The format prop is display-only for user interface. timezone must be set when shouldShowTime is true for correct time conversion. shouldLocalize controls whether display format is determined from locale (default: true). startDateLabel/endDateLabel customize the field labels. Use theme=NO_BOX to remove input box styling. Use aria-label or aria-labelledby for accessibility when label is not provided.
1155
1151
 
1156
1152
  Catalog key: `DateRange`
1157
1153
  Builder: `DateRange`
@@ -1170,10 +1166,12 @@ Events: `change`, `blur`
1170
1166
  | `aria-labelledby` | no | string | ID of element that labels the date range picker |
1171
1167
  | `canClear` | no | boolean | Show clear button |
1172
1168
  | `checks` | no | [DateRangeCheck](./types.md#daterangecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1169
+ | `defaultValue` | no | string[] | Initial null or array of ISO date strings/null entries [start, end] |
1173
1170
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1174
1171
  | `endDateLabel` | no | string | Label for the end date field |
1175
1172
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1176
1173
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
1174
+ | `id` | no | string | HTML id attribute for the date range input |
1177
1175
  | `isCalendarDefaultOpen` | no | boolean | If true, calendar will be open by default on mount |
1178
1176
  | `isDisabled` | no | boolean | Disables the date range picker |
1179
1177
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
@@ -1190,9 +1188,10 @@ Events: `change`, `blur`
1190
1188
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
1191
1189
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1192
1190
  | `startDateLabel` | no | string | Label for the start date field |
1191
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1193
1192
  | `timezone` | no | string | Timezone for date/time display and storage. Used with shouldShowTime |
1194
1193
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1195
- | `value` | no | string[] | Array of two ISO date strings [start, end] |
1194
+ | `value` | no | string[] | Null or array of ISO date strings/null entries [start, end] bound to state |
1196
1195
 
1197
1196
  No additional properties.
1198
1197
 
@@ -1219,7 +1218,7 @@ Events: `change`
1219
1218
  | `isReadOnly` | no | boolean | Makes the input read-only |
1220
1219
  | `isRequired` | no | boolean | Marks the field as required |
1221
1220
  | `label` | no | string | Label text above the input |
1222
- | `renderProps` | no | [RenderProp](./types.md#renderprop) | Per-day configuration. Keys are day names (Sunday, Monday, etc.). Each can have isDisabled (boolean) and tip (object with content string) |
1221
+ | `renderProps` | no | [DaySelectorRenderProp](./types.md#dayselectorrenderprop) | Per-day configuration. Keys are day names (Sunday, Monday, etc.). Each can have isDisabled (boolean) and tip (object with content string) |
1223
1222
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1224
1223
  | `value` | no | [DaySelectorDefaultValue](./definitions.md#dayselectordefaultvalue) \| [DaySelectorDefaultValue](./definitions.md#dayselectordefaultvalue)[] | Selected day(s). Single string when isMulti is false, array when true |
1225
1224
 
@@ -1271,7 +1270,7 @@ No additional properties.
1271
1270
 
1272
1271
  A reorderable drag-and-drop list for dynamically rearranging items. Supports vertical and horizontal layouts; use when item order flexibility is crucial to the user experience.
1273
1272
 
1274
- The list prop should be bound to state. When items are reordered or removed, the updated list array is written back to state. The update event fires after reorder; the remove event fires after an item is removed. Each item in the list must have a unique id field. The labelKey prop specifies which field to use as the display label for the default chip renderer.
1273
+ The list prop should be bound to state. When items are reordered or removed, the updated list array is written back to state. The update event fires after reorder; the remove event fires after an item is removed. Each item in the list must have a unique id field and can include additional serializable keys. The labelKey prop specifies which field to use as the display label for the default chip renderer. Use tip.contentKey and tip.titleKey to read tooltip content from item fields.
1275
1274
 
1276
1275
  Catalog key: `DraggableList`
1277
1276
  Builder: `DraggableList`
@@ -1292,6 +1291,7 @@ Events: `update`, `remove`, `dragStart`, `dragEnd`
1292
1291
  | `limitDragToDragIcon` | no | boolean | Restrict dragging to only the drag icon. Only works when showDragIcon is true. Default: false |
1293
1292
  | `list` | yes | [DraggableListList](./types.md#draggablelistlist)[] | Array of draggable items. Each item must have an id (string or number). Additional keys are allowed. |
1294
1293
  | `showDragIcon` | no | boolean | Show drag icon for each item. Default: false |
1294
+ | `tip` | no | [DraggableListTip](./types.md#draggablelisttip) | Tooltip configuration for the default chip renderer |
1295
1295
  | `width` | no | string | Width of the list. Default: 100% |
1296
1296
 
1297
1297
  No additional properties.
@@ -1321,7 +1321,7 @@ Events: `close`
1321
1321
  | `shouldCloseOnEscape` | no | boolean | Close drawer on ESC key press |
1322
1322
  | `shouldNotAnimate` | no | boolean | Disables open/close animations. Default: false |
1323
1323
  | `theme` | no | [DrawerTheme](./definitions.md#drawertheme) | Visual style theme for the drawer |
1324
- | `title` | no | string | Title text displayed in the drawer header |
1324
+ | `title` | no | string \| [Title](./types.md#title) | Title displayed in the drawer header as text or breadcrumb config |
1325
1325
  | `width` | no | string \| number | Width of the drawer. Default: 80vw |
1326
1326
 
1327
1327
  No additional properties.
@@ -1330,29 +1330,31 @@ No additional properties.
1330
1330
 
1331
1331
  A popover menu that displays a list of actions or selectable options. Use for 3–15 choices triggered by a button; for form field selection, use Select instead.
1332
1332
 
1333
- Bind value to state to track the selected option. The change event fires when the user selects an item. The selected item value (string) is written to state. triggerLabel renders a Button as the dropdown trigger.
1333
+ Bind value to state to track the selected option. The change event fires when the user selects an item and the selected item value is written to state. Bind dropdownIsOpen to state to observe open/close; the toggle event fires after dropdownIsOpen is updated. The list supports flat items, nested items with a list field, and {isSeparator: true}. triggerLabel renders a Button as the dropdown trigger.
1334
1334
 
1335
1335
  Catalog key: `Dropdown`
1336
1336
  Builder: `Dropdown`
1337
1337
  Props type: `DropdownProps`
1338
1338
  Accepts children: no
1339
- Events: `change`
1339
+ Events: `change`, `toggle`
1340
1340
 
1341
1341
  ### Props
1342
1342
 
1343
1343
  | Name | Required | Type | Description |
1344
1344
  |---|---:|---|---|
1345
- | `defaultValue` | no | string | Initially selected value |
1345
+ | `defaultValue` | no | unknown | Initially selected value |
1346
+ | `dropdownIsOpen` | no | boolean | Bindable state written when the dropdown opens or closes |
1347
+ | `footer` | no | [DropdownFooter](./types.md#dropdownfooter) | Footer item rendered at the bottom of the list |
1346
1348
  | `isCompact` | no | boolean | Render in compact mode |
1347
1349
  | `isDisabled` | no | boolean | Disable the dropdown trigger |
1348
- | `list` | yes | [DropdownList2](./types.md#dropdownlist2)[] | Array of dropdown options: {label, value, isDisabled?} |
1350
+ | `list` | yes | [DropdownList2](./types.md#dropdownlist2) \| [DropdownList2](./types.md#dropdownlist2) \| [DropdownList2](./types.md#dropdownlist2)[] | Array of dropdown options: {label, value, isDisabled?} |
1349
1351
  | `maxHeight` | no | number | Max height of the dropdown list in px. Default: 224 |
1350
1352
  | `placement` | no | [DropdownPlacement](./definitions.md#dropdownplacement) | Popover position. Default: bottom-start |
1351
1353
  | `searchable` | no | boolean | Enable search within the dropdown list |
1352
1354
  | `shouldAutoClose` | no | boolean | Auto-close after item selection |
1353
1355
  | `shouldCloseOnScroll` | no | boolean | Close on document scroll |
1354
1356
  | `triggerLabel` | yes | string | Label for the dropdown trigger button |
1355
- | `value` | no | string | Currently selected value. Bind to state for selection tracking |
1357
+ | `value` | no | unknown | Currently selected value. Bind to state for selection tracking |
1356
1358
  | `width` | no | number | Width of the dropdown list in px. Default: 192 |
1357
1359
 
1358
1360
  No additional properties.
@@ -1408,8 +1410,8 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
1408
1410
  | `shrinkToValue` | no | boolean | Input spans as much as its value when true. Only applies when value is present |
1409
1411
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1410
1412
  | `spellCheck` | no | boolean | Enable spell checking |
1413
+ | `stringPadding` | no | [EmailStringPadding](./types.md#emailstringpadding) | Pads input value with character until reaching maxLength |
1411
1414
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
1412
- | `testId` | no | string | Test ID for automation |
1413
1415
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
1414
1416
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1415
1417
  | `value` | no | string | Current email value bound to state |
@@ -1420,7 +1422,7 @@ No additional properties.
1420
1422
 
1421
1423
  An emoji picker that lets users browse and select emojis by category or search. Can be rendered inline or in a popover. onChange emits the selected emoji data including native representation, name, and keywords.
1422
1424
 
1423
- onChange emits an object with emoji data: { id, name, native, shortcodes, keywords, unified }. The native property contains the actual emoji character to render. Use inline={true} to render directly in the layout; use inline={false} with a trigger for popover mode. Categories can be filtered with the categories prop.
1425
+ Bind selectedEmoji to state to receive selected emoji data before the change event emits: { id, name, native, shortcodes, keywords, unified }. The native property contains the actual emoji character to render. Use inline={true} to render directly in the layout; use inline={false} with a trigger for popover mode. Categories can be filtered with the categories prop. popperProps supports placement and shouldFlipIfNoSpace only; middleware functions are not serializable.
1424
1426
 
1425
1427
  Catalog key: `EmojiPicker`
1426
1428
  Builder: `EmojiPicker`
@@ -1434,16 +1436,52 @@ Events: `change`
1434
1436
  |---|---:|---|---|
1435
1437
  | `autoFocus` | no | boolean | If true, automatically focuses the search input. Default: false |
1436
1438
  | `categories` | no | [EmojiPickerCategories](./definitions.md#emojipickercategories)[] | Array of emoji categories to display |
1439
+ | `excludeIds` | no | string[] | Emoji IDs to hide from the picker |
1437
1440
  | `fluid` | no | boolean | If true, makes width 100% of container. Default: false |
1438
1441
  | `height` | no | string | Height CSS value of the emoji picker |
1439
1442
  | `inline` | no | boolean | If true, renders the emoji picker inline. Default: false |
1440
1443
  | `minHeight` | no | string | Minimum height CSS value of the emoji picker |
1441
1444
  | `minWidth` | no | string | Minimum width CSS value of the emoji picker |
1442
- | `testId` | no | string | Data test id for testing purposes |
1445
+ | `popperProps` | no | [PopperProp](./types.md#popperprop) | Serializable popover options; middleware functions are not supported |
1446
+ | `preventCloseOnSelect` | no | boolean | Prevents the popover from closing when an emoji is selected |
1447
+ | `selectedEmoji` | no | [SelectedEmoji](./types.md#selectedemoji) | Bindable selected emoji data written before the change event emits |
1448
+ | `triggerIcon` | no | string | Icon.TYPES name to render as the default popover trigger |
1443
1449
  | `width` | no | string | Width CSS value of the emoji picker |
1444
1450
 
1445
1451
  No additional properties.
1446
1452
 
1453
+ ## EmployeeSearch
1454
+
1455
+ Search for and select one or more employees outside of a registered form. Supports ACTIVE; GOOD (HIRED, ACCEPTED, and ACTIVE); ACCEPTED_AND_ACTIVE (excluding HIRED); NON_INIT (all employee states except INIT, including TERMINATED); INIT (hiring started but not completed; the backend preset is roleState INIT and is not employee-constrained); and TERMINATED. The change event is notification-only and has no payload.
1456
+
1457
+ Use value for a controlled selection or defaultValue for an uncontrolled initial selection. If both are provided, value takes precedence. roleTypes defaults to GOOD. Limits search results using backend role-type presets. ACTIVE selects active employees. GOOD selects HIRED, ACCEPTED, and ACTIVE employees. ACCEPTED_AND_ACTIVE selects ACCEPTED and ACTIVE employees and excludes HIRED. NON_INIT selects all employee states except INIT, including TERMINATED. INIT selects the backend roleState INIT preset (hiring started but not completed) and is not additionally constrained to employees. TERMINATED selects terminated employees. Requires at least one value; defaults to GOOD. Loading, empty, and error behavior is inherited from Core EmployeeSearch. The change event is notification-only and has no payload; observe the selected employee role id or role ids through bound value state.
1458
+
1459
+ Catalog key: `EmployeeSearch`
1460
+ Builder: `EmployeeSearch`
1461
+ Props type: `EmployeeSearchProps`
1462
+ Accepts children: no
1463
+ Events: `change`
1464
+
1465
+ ### Props
1466
+
1467
+ | Name | Required | Type | Description |
1468
+ |---|---:|---|---|
1469
+ | `canClear` | no | boolean | Controls whether the current selection can be cleared. When omitted, the underlying select default applies. |
1470
+ | `defaultValue` | no | string \| string[] | Initial uncontrolled selection as an employee role id for single select or role id array for multi-select. Defaults to no selection. |
1471
+ | `isDisabled` | no | boolean | When true, disables searching and selection changes. Defaults to false. |
1472
+ | `isMulti` | no | boolean | When true, allows multiple employee selections and uses role id arrays. Defaults to false (single select). |
1473
+ | `isReadOnly` | no | boolean | When true, displays the selection without allowing changes. Defaults to false. |
1474
+ | `isRequired` | no | boolean | When true, marks the field as required. Defaults to the form control default (not required). |
1475
+ | `label` | no | string | Label displayed for the search field. Defaults to no label. |
1476
+ | `placeholder` | no | string | Placeholder displayed when the search field is empty. When omitted, the component default placeholder is used. |
1477
+ | `roleIdsToExclude` | no | string[] | Removes the specified employee role ids from search results when no inclusion list is provided. When both lists are provided, inclusion takes precedence. When omitted, no role ids are explicitly excluded. |
1478
+ | `roleIdsToInclude` | no | string[] | Limits search results to the specified employee role ids. When both inclusion and exclusion lists are provided, inclusion takes precedence. When omitted, results are not restricted by an inclusion list. |
1479
+ | `roleTypes` | no | [EmployeeSearchRoleTypes](./definitions.md#employeesearchroletypes)[] | Limits search results using backend role-type presets. ACTIVE selects active employees. GOOD selects HIRED, ACCEPTED, and ACTIVE employees. ACCEPTED_AND_ACTIVE selects ACCEPTED and ACTIVE employees and excludes HIRED. NON_INIT selects all employee states except INIT, including TERMINATED. INIT selects the backend roleState INIT preset (hiring started but not completed) and is not additionally constrained to employees. TERMINATED selects terminated employees. Requires at least one value; defaults to GOOD. |
1480
+ | `tip` | no | string | Supplementary tip displayed with the label. Defaults to no tip. |
1481
+ | `value` | no | string \| string[] | Controlled selection as an employee role id for single select or role id array for multi-select. When omitted, the component is uncontrolled. When value and defaultValue are both provided, value takes precedence. |
1482
+
1483
+ No additional properties.
1484
+
1447
1485
  ## ExpansionPanel
1448
1486
 
1449
1487
  A collapsible panel that expands or contracts to reveal additional detailed information. Use to organize related content within limited space, such as FAQs, settings menus, or side panels. Prefer a full scrolling page when users need to read all content.
@@ -1482,6 +1520,7 @@ Events: `toggle`
1482
1520
  | `shouldNotUnmountChild` | no | boolean | Keep child mounted when collapsed. Default: false |
1483
1521
  | `theme` | no | [ExpansionPanelTheme](./definitions.md#expansionpaneltheme) | Visual style variant |
1484
1522
  | `title` | yes | string | Header text displayed in the expansion panel |
1523
+ | `toggleIcon` | no | [ExpansionPanelToggleIcon](./types.md#expansionpaneltoggleicon) | Toggle icon layout options |
1485
1524
 
1486
1525
  No additional properties.
1487
1526
 
@@ -1536,19 +1575,24 @@ No additional properties.
1536
1575
 
1537
1576
  A compact file upload input for selecting one or more files via browse or drag-and-drop. Supports file type restrictions, size limits, and upload progress. Use for inline file fields in forms; use FileDrop for larger drag-and-drop zones with labels and validation.
1538
1577
 
1539
- supportTypes accepts file extensions like [".pdf", ".jpg"]. Use Input.File.SUPPORTED_TYPES presets like IMAGES, DOCUMENTS, etc. for common groups. The change event fires when files are selected or removed.
1578
+ supportTypes accepts file extensions like [".pdf", ".jpg"]. Use Input.File.SUPPORTED_TYPES presets like IMAGES, DOCUMENTS, etc. for common groups. Bind value to state to receive serializable FileState metadata; Blob/File content is converted to a base64 data URL string in content. The change event fires when files are selected or removed. The delete event fires when a file is removed. Bind clickedFile to state to receive clicked file metadata before chipClick emits.
1540
1579
 
1541
1580
  Catalog key: `File`
1542
1581
  Builder: `File`
1543
1582
  Props type: `FileProps`
1544
1583
  Accepts children: no
1545
- Events: `change`, `delete`
1584
+ Events: `change`, `delete`, `chipClick`
1546
1585
 
1547
1586
  ### Props
1548
1587
 
1549
1588
  | Name | Required | Type | Description |
1550
1589
  |---|---:|---|---|
1551
1590
  | `name` | no | string | Unique identifier for the file input |
1591
+ | `allowCameraCapture` | no | boolean \| [FileAllowCameraCapture](./types.md#fileallowcameracapture) | Allow camera capture for image files; object form supports quality |
1592
+ | `clickedFile` | no | [ClickedFile](./types.md#clickedfile) | Bindable clicked file metadata written before chipClick emits |
1593
+ | `cropperConfig` | no | [FileCropperConfig](./types.md#filecropperconfig) | Image cropper configuration |
1594
+ | `defaultValue` | no | [FileDefaultValue](./types.md#filedefaultvalue)[] | Default files to show when no value is provided |
1595
+ | `icon` | no | string | Icon name from Icon.TYPES to show above placeholder |
1552
1596
  | `isDisabled` | no | boolean | Disables the file input |
1553
1597
  | `isInvalid` | no | boolean | Shows error styling on the input |
1554
1598
  | `isReadOnly` | no | boolean | Makes the file input read-only (download only) |
@@ -1560,6 +1604,7 @@ Events: `change`, `delete`
1560
1604
  | `showProgress` | no | boolean | Show upload progress bar. Default: false |
1561
1605
  | `supportTypes` | no | string[] | Array of supported file extensions, e.g. [".pdf", ".doc"] |
1562
1606
  | `type` | no | [FileType](./definitions.md#filetype) | File input display type. Default: DEFAULT |
1607
+ | `value` | no | [FileValue](./types.md#filevalue)[] | Array of file objects bound to state |
1563
1608
 
1564
1609
  No additional properties.
1565
1610
 
@@ -1567,7 +1612,7 @@ No additional properties.
1567
1612
 
1568
1613
  A file upload input that allows users to drag and drop files into a drop zone or click to browse. Supports single or multiple file uploads with configurable file type restrictions, size limits, and optional image cropping.
1569
1614
 
1570
- onChange stores an array of file objects in state, each with {name, type, content, progress, hasError} where content is a base64 data URL string. Use supportTypes with file extensions like [".pdf", ".png"] — NOT MIME types. When multiple is false, only one file is stored.
1615
+ onChange stores an array of file objects in state, each with {name, type, content, progress, hasError} where content is a base64 data URL string. Use supportTypes with file extensions like [".pdf", ".png"] — NOT MIME types. Custom extensions are allowed. module is deprecated but supported for upload bucket hints; prefer metadata.module when possible. When multiple is false, only one file is stored.
1571
1616
 
1572
1617
  Catalog key: `FileDrop`
1573
1618
  Builder: `FileDrop`
@@ -1580,7 +1625,7 @@ Events: `change`, `blur`
1580
1625
  | Name | Required | Type | Description |
1581
1626
  |---|---:|---|---|
1582
1627
  | `name` | no | string | Unique identifier for the file input |
1583
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
1628
+ | `allowCameraCapture` | no | boolean \| [FileDropAllowCameraCapture](./types.md#filedropallowcameracapture) | Allow camera capture for image files; object form supports quality |
1584
1629
  | `aria-describedby` | no | string | ID of element that describes this input |
1585
1630
  | `aria-label` | no | string | Accessible label for screen readers |
1586
1631
  | `aria-labelledby` | no | string | ID of element that labels this input |
@@ -1596,10 +1641,12 @@ Events: `change`, `blur`
1596
1641
  | `label` | no | string | Label text above the file drop area |
1597
1642
  | `maxFileSize` | no | number | Max file size in MB per attachment |
1598
1643
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
1644
+ | `metadata` | no | unknown | JSON-serializable metadata sent with upload requests |
1645
+ | `module` | no | string | Deprecated upload bucket hint; prefer metadata.module when possible |
1599
1646
  | `multiPartUpload` | no | boolean | Enables multipart upload flow for files larger than 100MB |
1600
1647
  | `multiple` | no | boolean | Allow selecting multiple files |
1601
1648
  | `placeholder` | no | string | Text shown when no files are selected |
1602
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
1649
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
1603
1650
  | `type` | no | [FileDropType](./definitions.md#filedroptype) | Type of file drop: upload (shows progress bars automatically) or content. Default: content |
1604
1651
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1605
1652
  | `value` | no | [FileDropValue](./types.md#filedropvalue)[] | Array of file objects bound to state |
@@ -1653,7 +1700,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
1653
1700
  | `shouldShowSpinner` | no | boolean | If true, shows loading spinner instead of icon |
1654
1701
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the button (XS, S, M, L). Default: M |
1655
1702
  | `tabIndex` | no | number | Tab order for keyboard navigation |
1656
- | `testId` | no | string | Sets data-testid attribute. Default: "button" |
1657
1703
  | `tip` | no | string \| [FloatingButtonTip](./types.md#floatingbuttontip) | Tooltip text or tooltip configuration object |
1658
1704
  | `to` | no | string \| [FloatingButtonTo](./types.md#floatingbuttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
1659
1705
  | `type` | no | [FloatingButtonType](./definitions.md#floatingbuttontype) | HTML button type attribute (button, submit, reset). Default: button |
@@ -1672,7 +1718,7 @@ Two binding surfaces (independent — use either, both, or neither):
1672
1718
 
1673
1719
  2. `values` ($bindState on Form) — PUSH-ONLY aggregate. Form writes the merged `{name: value}` map to the bound path on every change. External writes to that path do NOT propagate back into inputs. Use only when something outside the form needs to observe the whole map; do not use to control inputs.
1674
1720
 
1675
- `isSettings=true` renders the native edit/readonly toggle plus Save/Cancel buttons; pair with `isEdit` ($bindState) to control the mode. `onSubmit` fires with current values; use per-input `value` $state refs in the payload rather than relying on `values`.
1721
+ `isSettings=true` renders the native edit/readonly toggle plus Save/Cancel buttons; pair with `isEdit` ($bindState) to control the mode. `onSubmit` fires with current values; use per-input `value` $state refs in the payload rather than relying on `values`. `skipButton` renders a secondary footer action and emits `skip` when clicked.
1676
1722
 
1677
1723
  External `validationErrors` merge with input-reported errors; clear an error by writing a falsy value to that key.
1678
1724
 
@@ -1680,7 +1726,7 @@ Catalog key: `Form`
1680
1726
  Builder: `Form`
1681
1727
  Props type: `FormProps`
1682
1728
  Accepts children: yes
1683
- Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1729
+ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`, `skip`
1684
1730
 
1685
1731
  ### Props
1686
1732
 
@@ -1688,7 +1734,7 @@ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1688
1734
  |---|---:|---|---|
1689
1735
  | `bottomPadding` | no | boolean | Adds bottom padding to the form. Default: true |
1690
1736
  | `caption` | no | string | Subtext shown beneath the title |
1691
- | `editButton` | no | boolean | Show or hide the settings edit button. Default: true |
1737
+ | `editButton` | no | boolean \| [EditButton](./types.md#editbutton) | Settings edit button visibility/configuration. Default: true |
1692
1738
  | `inlineLabel` | no | boolean | Renders fields with inline labels (label and input side-by-side) |
1693
1739
  | `isDefaultEdit` | no | boolean | Initial edit state in settings mode. Requires isSettings: true |
1694
1740
  | `isDisabled` | no | boolean | Disables the entire form |
@@ -1702,6 +1748,8 @@ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1702
1748
  | `shouldStopFormPropagation` | no | boolean | Stops form-submit event from bubbling — for nested forms |
1703
1749
  | `shouldTriggerChangeOnInputUnmount` | no | boolean | Fires change event when an input unmounts. Default: false |
1704
1750
  | `shouldTrimOnSubmit` | no | boolean | Trims string values on submit. Default: false |
1751
+ | `skipButton` | no | [SkipButton](./types.md#skipbutton) | Secondary skip action. Click emits the skip event. |
1752
+ | `submitButtonLabel` | no | string | Deprecated submit button label. Prefer submitButtonProps.label for new specs |
1705
1753
  | `submitButtonProps` | no | [SubmitButtonProp](./types.md#submitbuttonprop) | Configuration for the form submit button |
1706
1754
  | `successMessage` | no | string | Message shown in a snackbar after a successful submit |
1707
1755
  | `theme` | no | [FormTheme](./definitions.md#formtheme) | Predefined form style theme |
@@ -1735,12 +1783,15 @@ Events: `change`
1735
1783
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1736
1784
  | `defaultValue` | no | boolean | Initial checked state when uncontrolled |
1737
1785
  | `isDisabled` | no | boolean | Disables the input |
1786
+ | `isIndeterminate` | no | boolean | Sets checkbox to indeterminate (neither checked nor unchecked) state |
1738
1787
  | `isReadOnly` | no | boolean | Makes the input read-only |
1739
1788
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1740
1789
  | `label` | no | string | Label text for the checkbox |
1741
1790
  | `secondaryLabel` | no | string | Secondary text below the label |
1791
+ | `shouldPreventFocus` | no | boolean | Prevent the checkbox from receiving focus |
1742
1792
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Visual theme variant |
1743
1793
  | `tip` | no | string | Tooltip text shown on hover |
1794
+ | `title` | no | string | Form field label shown outside the checkbox |
1744
1795
  | `validationErrors` | no | [FormCheckboxValidationError](./types.md#formcheckboxvalidationerror) | Map of rule name to error message |
1745
1796
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
1746
1797
  | `value` | no | boolean | Current value bound to state |
@@ -1770,12 +1821,13 @@ Events: `change`
1770
1821
  |---|---:|---|---|
1771
1822
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1772
1823
  | `defaultValue` | no | unknown[] | Initial array of selected values when uncontrolled |
1824
+ | `id` | no | string | HTML id attribute for the checkbox group |
1773
1825
  | `isDisabled` | no | boolean | Disables the input |
1774
1826
  | `isHorizontal` | no | boolean | Arrange options in a row |
1775
1827
  | `isReadOnly` | no | boolean | Makes the input read-only |
1776
1828
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1777
1829
  | `label` | no | string | Label text above the checkbox group |
1778
- | `options` | yes | [FormCheckboxGroupOption](./types.md#formcheckboxgroupoption)[] | Array of {label, value} checkbox items |
1830
+ | `list` | yes | [FormCheckboxGroupList](./types.md#formcheckboxgrouplist)[] | Array of {label, value} checkbox items |
1779
1831
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
1780
1832
  | `validationErrors` | no | [FormCheckboxGroupValidationError](./types.md#formcheckboxgroupvalidationerror) | Map of rule name to error message |
1781
1833
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -1830,16 +1882,21 @@ Events: `change`, `blur`
1830
1882
  |---|---:|---|---|
1831
1883
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1832
1884
  | `allowNegative` | no | boolean | Whether negative values are allowed. Default: true |
1885
+ | `canSelectCurrencyType` | no | boolean | If true, displays a dropdown to select currency type |
1886
+ | `currencyTypeProps` | no | [FormCurrencyCurrencyTypeProp](./types.md#formcurrencycurrencytypeprop) | Nested Select props for the currency selector |
1833
1887
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
1834
- | `defaultValue` | no | number | Initial numeric value set in Form on mount |
1888
+ | `defaultValue` | no | string \| number \| [FormCurrencyDefaultValue](./types.md#formcurrencydefaultvalue) \| null | Initial currency value set in Form on mount |
1835
1889
  | `isDisabled` | no | boolean | Disables the input |
1836
1890
  | `isReadOnly` | no | boolean | Makes the input read-only |
1837
1891
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1838
1892
  | `label` | no | string | Label text above the input |
1893
+ | `locale` | no | string | Locale string for number formatting (e.g. en-US). Overrides shouldLocalize when set. |
1894
+ | `placeholder` | no | string | Placeholder text when empty |
1839
1895
  | `prefix` | no | string | Currency symbol or code shown as prefix. Default: USD |
1896
+ | `shouldSendCurrencyType` | no | boolean | If true, onChange writes { value, type } using currencyTypeProps value/defaultValue |
1840
1897
  | `validationErrors` | no | [FormCurrencyValidationError](./types.md#formcurrencyvalidationerror) | Map of rule name to error message |
1841
1898
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
1842
- | `value` | no | unknown | Current value bound to state |
1899
+ | `value` | no | string \| number \| [FormCurrencyValue](./types.md#formcurrencyvalue) \| null | Current value bound to state |
1843
1900
 
1844
1901
  No additional properties.
1845
1902
 
@@ -1865,8 +1922,9 @@ Events: `change`
1865
1922
  |---|---:|---|---|
1866
1923
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1867
1924
  | `canClear` | no | boolean | Show clear button |
1868
- | `defaultValue` | no | string | Initial date value (yyyy-MM-dd) set in Form on mount |
1925
+ | `defaultValue` | no | string | Initial date value (yyyy-MM-dd) or null set in Form on mount |
1869
1926
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1927
+ | `id` | no | string | HTML id attribute for the input |
1870
1928
  | `isDisabled` | no | boolean | Disables the input |
1871
1929
  | `isReadOnly` | no | boolean | Makes the input read-only |
1872
1930
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
@@ -1874,8 +1932,10 @@ Events: `change`
1874
1932
  | `locale` | no | string | Locale for date formatting. Default: en-US |
1875
1933
  | `maxDate` | no | string | Latest selectable date as ISO string |
1876
1934
  | `minDate` | no | string | Earliest selectable date as ISO string |
1935
+ | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting. Default: false for explicit format control |
1877
1936
  | `shouldShowTime` | no | boolean | Include time selection |
1878
1937
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1938
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1879
1939
  | `timezone` | no | string | Timezone name (e.g. "America/New_York"). Used with shouldShowTime |
1880
1940
  | `tip` | no | string | Tooltip text shown alongside the field label |
1881
1941
  | `validationErrors` | no | [FormDateValidationError](./types.md#formdatevalidationerror) | Map of rule name to error message |
@@ -1906,11 +1966,12 @@ Events: `change`
1906
1966
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1907
1967
  | `alwaysShowTimezone` | no | boolean | If true, timezone abbreviation will always be shown when shouldShowTime is true. Default: false |
1908
1968
  | `canClear` | no | boolean | Show clear button |
1909
- | `defaultValue` | no | string[] | Initial date range value [start, end] set in Form on mount |
1969
+ | `defaultValue` | no | string[] | Initial date range value [start, end] or null set in Form on mount |
1910
1970
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1911
1971
  | `endDateLabel` | no | string | Label for the end date field |
1912
1972
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1913
1973
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
1974
+ | `id` | no | string | HTML id attribute for the date range input |
1914
1975
  | `isCalendarDefaultOpen` | no | boolean | If true, calendar will be open by default on mount |
1915
1976
  | `isDisabled` | no | boolean | Disables the input |
1916
1977
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
@@ -1926,6 +1987,7 @@ Events: `change`
1926
1987
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
1927
1988
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1928
1989
  | `startDateLabel` | no | string | Label for the start date field |
1990
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1929
1991
  | `timezone` | no | string | Timezone for date/time display and storage. Used with shouldShowTime |
1930
1992
  | `tip` | no | string | Tooltip text shown alongside the field label |
1931
1993
  | `validationErrors` | no | [FormDateRangeValidationError](./types.md#formdaterangevalidationerror) | Map of rule name to error message |
@@ -1962,6 +2024,7 @@ Events: `change`
1962
2024
  | `isReadOnly` | no | boolean | Makes the input read-only |
1963
2025
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1964
2026
  | `label` | no | string | Label text above the input |
2027
+ | `renderProps` | no | [FormDaySelectorRenderProp](./types.md#formdayselectorrenderprop) | Per-day configuration. Keys are day names (Sunday, Monday, etc.). Each can have isDisabled (boolean) and tip (object with content string) |
1965
2028
  | `validationErrors` | no | [FormDaySelectorValidationError](./types.md#formdayselectorvalidationerror) | Map of rule name to error message |
1966
2029
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
1967
2030
  | `value` | no | unknown | Current value bound to state |
@@ -1989,6 +2052,7 @@ Events: `change`, `blur`
1989
2052
  | Name | Required | Type | Description |
1990
2053
  |---|---:|---|---|
1991
2054
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2055
+ | `autoComplete` | no | string | Browser autocomplete hint |
1992
2056
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
1993
2057
  | `isDisabled` | no | boolean | Disables the input |
1994
2058
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -1996,6 +2060,8 @@ Events: `change`, `blur`
1996
2060
  | `label` | no | string | Label text above the input |
1997
2061
  | `maxLength` | no | number | Maximum character count |
1998
2062
  | `placeholder` | no | string | Placeholder text when empty |
2063
+ | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2064
+ | `stringPadding` | no | [FormEmailStringPadding](./types.md#formemailstringpadding) | Pads input value with character until reaching maxLength |
1999
2065
  | `tip` | no | string | Tooltip text shown alongside the field label |
2000
2066
  | `validationErrors` | no | [FormEmailValidationError](./types.md#formemailvalidationerror) | Map of rule name to error message |
2001
2067
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2003,6 +2069,39 @@ Events: `change`, `blur`
2003
2069
 
2004
2070
  No additional properties.
2005
2071
 
2072
+ ## FormEmployeeSearch
2073
+
2074
+ Search for and select one or more employees as a registered form field. Supports ACTIVE; GOOD (HIRED, ACCEPTED, and ACTIVE); ACCEPTED_AND_ACTIVE (excluding HIRED); NON_INIT (all employee states except INIT, including TERMINATED); INIT (hiring started but not completed; the backend preset is roleState INIT and is not employee-constrained); and TERMINATED. The change event is notification-only and has no payload.
2075
+
2076
+ Provide a non-empty name to register the field with its parent form. If value and defaultValue are both provided, value takes precedence. roleTypes defaults to GOOD. Limits search results using backend role-type presets. ACTIVE selects active employees. GOOD selects HIRED, ACCEPTED, and ACTIVE employees. ACCEPTED_AND_ACTIVE selects ACCEPTED and ACTIVE employees and excludes HIRED. NON_INIT selects all employee states except INIT, including TERMINATED. INIT selects the backend roleState INIT preset (hiring started but not completed) and is not additionally constrained to employees. TERMINATED selects terminated employees. Requires at least one value; defaults to GOOD. Loading, empty, and error behavior is inherited from Core EmployeeSearch. The change event is notification-only and has no payload; observe the selected employee role id or role ids through bound value state.
2077
+
2078
+ Catalog key: `FormEmployeeSearch`
2079
+ Builder: `FormEmployeeSearch`
2080
+ Props type: `FormEmployeeSearchProps`
2081
+ Accepts children: no
2082
+ Events: `change`
2083
+
2084
+ ### Props
2085
+
2086
+ | Name | Required | Type | Description |
2087
+ |---|---:|---|---|
2088
+ | `name` | yes | string | Non-empty field name used to register this employee role-id value with the parent form. |
2089
+ | `canClear` | no | boolean | Controls whether the current selection can be cleared. When omitted, the underlying select default applies. |
2090
+ | `defaultValue` | no | string \| string[] | Initial uncontrolled selection as an employee role id for single select or role id array for multi-select. Defaults to no selection. |
2091
+ | `isDisabled` | no | boolean | When true, disables searching and selection changes. Defaults to false. |
2092
+ | `isMulti` | no | boolean | When true, allows multiple employee selections and uses role id arrays. Defaults to false (single select). |
2093
+ | `isReadOnly` | no | boolean | When true, displays the selection without allowing changes. Defaults to false. |
2094
+ | `isRequired` | no | boolean | When true, marks the field as required. Defaults to the form control default (not required). |
2095
+ | `label` | no | string | Label displayed for the search field. Defaults to no label. |
2096
+ | `placeholder` | no | string | Placeholder displayed when the search field is empty. When omitted, the component default placeholder is used. |
2097
+ | `roleIdsToExclude` | no | string[] | Removes the specified employee role ids from search results when no inclusion list is provided. When both lists are provided, inclusion takes precedence. When omitted, no role ids are explicitly excluded. |
2098
+ | `roleIdsToInclude` | no | string[] | Limits search results to the specified employee role ids. When both inclusion and exclusion lists are provided, inclusion takes precedence. When omitted, results are not restricted by an inclusion list. |
2099
+ | `roleTypes` | no | [EmployeeSearchRoleTypes](./definitions.md#employeesearchroletypes)[] | Limits search results using backend role-type presets. ACTIVE selects active employees. GOOD selects HIRED, ACCEPTED, and ACTIVE employees. ACCEPTED_AND_ACTIVE selects ACCEPTED and ACTIVE employees and excludes HIRED. NON_INIT selects all employee states except INIT, including TERMINATED. INIT selects the backend roleState INIT preset (hiring started but not completed) and is not additionally constrained to employees. TERMINATED selects terminated employees. Requires at least one value; defaults to GOOD. |
2100
+ | `tip` | no | string | Supplementary tip displayed with the label. Defaults to no tip. |
2101
+ | `value` | no | string \| string[] | Controlled selection as an employee role id for single select or role id array for multi-select. When omitted, the component is uncontrolled. When value and defaultValue are both provided, value takes precedence. |
2102
+
2103
+ No additional properties.
2104
+
2006
2105
  ## FormFile
2007
2106
 
2008
2107
  A Form-registered file upload field for use inside a Form component.
@@ -2027,7 +2126,7 @@ Events: `change`, `blur`
2027
2126
  | Name | Required | Type | Description |
2028
2127
  |---|---:|---|---|
2029
2128
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2030
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
2129
+ | `allowCameraCapture` | no | boolean \| [FormFileAllowCameraCapture](./types.md#formfileallowcameracapture) | Allow camera capture for image files; object form supports quality |
2031
2130
  | `cropperConfig` | no | [FormFileCropperConfig](./types.md#formfilecropperconfig) | Cropper configuration |
2032
2131
  | `defaultValue` | no | [FormFileDefaultValue](./types.md#formfiledefaultvalue)[] | Default files to show when no value is provided |
2033
2132
  | `enableCropper` | no | boolean | Enable image cropping for selected images |
@@ -2040,11 +2139,13 @@ Events: `change`, `blur`
2040
2139
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
2041
2140
  | `multiple` | no | boolean | Allow selecting multiple files |
2042
2141
  | `placeholder` | no | string | Text shown when no files are selected |
2043
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2142
+ | `showProgress` | no | boolean | Show upload progress bar. Default: false |
2143
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2044
2144
  | `tip` | no | string | Tooltip text shown alongside the field label |
2145
+ | `type` | no | [FileType](./definitions.md#filetype) | File input display type. Default: DEFAULT |
2045
2146
  | `validationErrors` | no | [FormFileValidationError](./types.md#formfilevalidationerror) | Map of rule name to error message |
2046
2147
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2047
- | `value` | no | [FormFileValue](./types.md#formfilevalue)[] | Current value bound to state |
2148
+ | `value` | no | [FormFileValue](./types.md#formfilevalue)[] | Array of file objects bound to state |
2048
2149
 
2049
2150
  No additional properties.
2050
2151
 
@@ -2072,7 +2173,7 @@ Events: `change`, `blur`
2072
2173
  | Name | Required | Type | Description |
2073
2174
  |---|---:|---|---|
2074
2175
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2075
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
2176
+ | `allowCameraCapture` | no | boolean \| [FormFileDropAllowCameraCapture](./types.md#formfiledropallowcameracapture) | Allow camera capture for image files; object form supports quality |
2076
2177
  | `cropperConfig` | no | [FormFileDropCropperConfig](./types.md#formfiledropcropperconfig) | Cropper configuration |
2077
2178
  | `defaultValue` | no | [FormFileDropDefaultValue](./types.md#formfiledropdefaultvalue)[] | Default files to show when no value is provided |
2078
2179
  | `enableCropper` | no | boolean | Enable image cropping for selected images |
@@ -2086,12 +2187,12 @@ Events: `change`, `blur`
2086
2187
  | `multiPartUpload` | no | boolean | Enables multipart upload flow for files larger than 100MB |
2087
2188
  | `multiple` | no | boolean | Allow selecting multiple files |
2088
2189
  | `placeholder` | no | string | Text shown when no files are selected |
2089
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2190
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2090
2191
  | `tip` | no | string | Tooltip text shown alongside the field label |
2091
2192
  | `type` | no | [FileDropType](./definitions.md#filedroptype) | Type of file drop: upload (shows progress bars automatically) or content. Default: content |
2092
2193
  | `validationErrors` | no | [FormFileDropValidationError](./types.md#formfiledropvalidationerror) | Map of rule name to error message |
2093
2194
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2094
- | `value` | no | [FormFileDropValue](./types.md#formfiledropvalue)[] | Current value bound to state |
2195
+ | `value` | no | [FormFileDropValue](./types.md#formfiledropvalue)[] | Array of file objects bound to state |
2095
2196
 
2096
2197
  No additional properties.
2097
2198
 
@@ -2295,13 +2396,15 @@ Catalog key: `FormNumber`
2295
2396
  Builder: `FormNumber`
2296
2397
  Props type: `FormNumberProps`
2297
2398
  Accepts children: no
2298
- Events: `change`, `blur`
2399
+ Events: `change`, `blur`, `changeRaw`, `changeCalculationState`
2299
2400
 
2300
2401
  ### Props
2301
2402
 
2302
2403
  | Name | Required | Type | Description |
2303
2404
  |---|---:|---|---|
2304
2405
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2406
+ | `autoComplete` | no | string | Browser autocomplete hint. Default: "off" |
2407
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2305
2408
  | `decimalPlaces` | no | number | Number of decimal places. Default: 2 |
2306
2409
  | `defaultValue` | no | string \| number | Initial default value for uncontrolled usage |
2307
2410
  | `isDisabled` | no | boolean | Disables the input |
@@ -2309,13 +2412,22 @@ Events: `change`, `blur`
2309
2412
  | `isReadOnly` | no | boolean | Makes the input read-only |
2310
2413
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2311
2414
  | `label` | no | string | Label text above the input |
2415
+ | `locale` | no | string | Locale string for number formatting (e.g. "en-US", "de-DE") |
2312
2416
  | `max` | no | number | Maximum allowed value |
2417
+ | `maxLength` | no | number | Maximum character count |
2418
+ | `maxWidth` | no | string | Maximum width CSS value |
2313
2419
  | `min` | no | number | Minimum allowed value. Default: 0 |
2420
+ | `minLength` | no | number | Minimum character count |
2314
2421
  | `placeholder` | no | string | Placeholder text when empty |
2315
2422
  | `prefix` | no | string | Text prefix inside the input |
2316
2423
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates on blur |
2424
+ | `shouldDisableFormatting` | no | boolean | If true, number formatting will not be applied. Default: true |
2425
+ | `shouldDisableRedundantZeroFormatting` | no | boolean | If true, redundant zeros are preserved. Default: true |
2426
+ | `shouldStripLeadingZeros` | no | boolean | If true, leading zeros are stripped from the numeric value |
2317
2427
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2428
+ | `spellCheck` | no | boolean | Enable spell checking |
2318
2429
  | `step` | no | number | Increment/decrement step size. Default: 1 |
2430
+ | `stringPadding` | no | [FormNumberStringPadding](./types.md#formnumberstringpadding) | Adds padding characters to the input value |
2319
2431
  | `suffix` | no | string | Text suffix inside the input |
2320
2432
  | `tip` | no | string | Tooltip text shown alongside the field label |
2321
2433
  | `validationErrors` | no | [FormNumberValidationError](./types.md#formnumbervalidationerror) | Map of rule name to error message |
@@ -2345,14 +2457,28 @@ Events: `change`, `blur`
2345
2457
  | Name | Required | Type | Description |
2346
2458
  |---|---:|---|---|
2347
2459
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2460
+ | `autoCapitalize` | no | [EmailAutoCapitalize](./definitions.md#emailautocapitalize) | Auto-capitalization: off, none, on, sentences, words, or characters |
2461
+ | `autoComplete` | no | string | Browser autocomplete hint |
2462
+ | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
2463
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2348
2464
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
2465
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2349
2466
  | `isDisabled` | no | boolean | Disables the input |
2467
+ | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
2350
2468
  | `isReadOnly` | no | boolean | Makes the input read-only |
2351
2469
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2352
2470
  | `label` | no | string | Label text above the input |
2353
2471
  | `maxLength` | no | number | Maximum character count |
2472
+ | `minLength` | no | number | Minimum character count |
2354
2473
  | `placeholder` | no | string | Placeholder text when empty |
2474
+ | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
2475
+ | `readOnlyAffixSpacing` | no | boolean | Controls gap between affixes and value in read-only mode. Default: true. Set false to remove gap |
2476
+ | `shouldAllowReveal` | no | boolean | Show password reveal toggle. Default: true |
2477
+ | `shouldPersistCursorPosition` | no | boolean | Persist cursor position for controlled input. Default: false |
2355
2478
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2479
+ | `spellCheck` | no | boolean | Enable spell checking |
2480
+ | `stringPadding` | no | [FormPasswordStringPadding](./types.md#formpasswordstringpadding) | Pads input value with character until reaching maxLength |
2481
+ | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2356
2482
  | `tip` | no | string | Tooltip text shown alongside the field label |
2357
2483
  | `validationErrors` | no | [FormPasswordValidationError](./types.md#formpasswordvalidationerror) | Map of rule name to error message |
2358
2484
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2389,10 +2515,13 @@ Events: `change`, `blur`
2389
2515
  | `isReadOnly` | no | boolean | Makes the input read-only |
2390
2516
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2391
2517
  | `label` | no | string | Label text above the input |
2518
+ | `locale` | no | string | Locale string for percentage formatting (e.g. en-US) |
2392
2519
  | `lowerLimit` | no | number | Minimum allowed percentage value |
2393
2520
  | `placeholder` | no | string | Placeholder text when empty |
2521
+ | `shouldDisableFormatting` | no | boolean | If true, percentage formatting will not be applied |
2394
2522
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2395
2523
  | `step` | no | number | Increment/decrement step size. Default: 1 |
2524
+ | `tip` | no | string | Tooltip text shown alongside the field label |
2396
2525
  | `upperLimit` | no | number | Maximum allowed percentage value. Default: 100 |
2397
2526
  | `validationErrors` | no | [FormPercentageValidationError](./types.md#formpercentagevalidationerror) | Map of rule name to error message |
2398
2527
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2414,7 +2543,7 @@ Catalog key: `FormPhone`
2414
2543
  Builder: `FormPhone`
2415
2544
  Props type: `FormPhoneProps`
2416
2545
  Accepts children: no
2417
- Events: `change`, `blur`
2546
+ Events: `change`, `blur`, `countryCodeChange`
2418
2547
 
2419
2548
  ### Props
2420
2549
 
@@ -2422,15 +2551,27 @@ Events: `change`, `blur`
2422
2551
  |---|---:|---|---|
2423
2552
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2424
2553
  | `autoComplete` | no | string | Browser autocomplete hint, e.g. "tel" |
2425
- | `countryCode` | no | string | Country code as string (e.g. "91", "1") to add as fixed prefix. For dropdown, use countryCodeValue instead |
2554
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2555
+ | `countryCode` | no | string \| [FormPhoneCountryCode](./types.md#formphonecountrycode) | Either a fixed country code string or a country-code dropdown configuration object |
2556
+ | `countryCodeDefaultValue` | no | string | [Deprecated] Use countryCode.defaultValue instead. Initial selected country code for the legacy dropdown shape |
2557
+ | `countryCodeValue` | no | string | [Deprecated] Use countryCode.value instead. Bound selected country code for the legacy dropdown shape |
2426
2558
  | `defaultRegion` | no | string | Default country region code for formatting, e.g. "US", "IN", "CA". Default: US |
2427
2559
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
2560
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2561
+ | `isCountryCodeDisabled` | no | boolean | [Deprecated] Use countryCode.isDisabled instead for the legacy dropdown shape |
2562
+ | `isCountryCodeReadOnly` | no | boolean | [Deprecated] Use countryCode.isReadOnly instead for the legacy dropdown shape |
2563
+ | `isCountryCodeRequired` | no | boolean | [Deprecated] Use countryCode.isRequired instead for the legacy dropdown shape |
2428
2564
  | `isDisabled` | no | boolean | Disables the input |
2429
2565
  | `isReadOnly` | no | boolean | Makes the input read-only |
2430
2566
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2431
2567
  | `label` | no | string | Label text above the input |
2432
2568
  | `maxLength` | no | number | Maximum character count |
2569
+ | `minLength` | no | number | Minimum character count |
2433
2570
  | `placeholder` | no | string | Placeholder text when empty |
2571
+ | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
2572
+ | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2573
+ | `stringPadding` | no | [FormPhoneStringPadding](./types.md#formphonestringpadding) | Pads input value with character until reaching maxLength |
2574
+ | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2434
2575
  | `tip` | no | string | Tooltip text shown alongside the field label |
2435
2576
  | `validationErrors` | no | [FormPhoneValidationError](./types.md#formphonevalidationerror) | Map of rule name to error message |
2436
2577
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2464,7 +2605,7 @@ Events: `change`
2464
2605
  | `isReadOnly` | no | boolean | Makes the input read-only |
2465
2606
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2466
2607
  | `label` | no | string | Label text above the radio group |
2467
- | `options` | yes | [FormRadioOption](./types.md#formradiooption)[] | Array of {label, value} options |
2608
+ | `list` | yes | [FormRadioList](./types.md#formradiolist)[] | Array of {label, value} radio options |
2468
2609
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
2469
2610
  | `tip` | no | string | Tooltip text shown alongside the label |
2470
2611
  | `validationErrors` | no | [FormRadioValidationError](./types.md#formradiovalidationerror) | Map of rule name to error message |
@@ -2505,7 +2646,8 @@ Events: `change`
2505
2646
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2506
2647
  | `isVertical` | no | boolean | Renders options in a vertical layout |
2507
2648
  | `label` | no | string | Label text above the segmented control |
2508
- | `options` | yes | [FormSegmentedControlOption](./types.md#formsegmentedcontroloption)[] | Array of { label, value } option objects |
2649
+ | `list` | no | [FormSegmentedControlList](./types.md#formsegmentedcontrollist)[] | Array of { label, value } segmented control options |
2650
+ | `rangeLabels` | no | [FormSegmentedControlRangeLabel](./types.md#formsegmentedcontrolrangelabel) | Labels to display at the start and end of the control range |
2509
2651
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Control size variant. Default: M |
2510
2652
  | `validationErrors` | no | [FormSegmentedControlValidationError](./types.md#formsegmentedcontrolvalidationerror) | Map of rule name to error message |
2511
2653
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2536,14 +2678,28 @@ Events: `change`, `blur`
2536
2678
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2537
2679
  | `canClear` | no | boolean | Show clear button to deselect all |
2538
2680
  | `canSelectAll` | no | boolean | Show select-all toggle. Requires isMulti to be true |
2681
+ | `creatable` | no | boolean | Allow creating new options not in the list |
2682
+ | `defaultSearchQuery` | no | string | Initial search input value |
2683
+ | `defaultValue` | no | unknown[] \| unknown | Initial selected value or values when uncontrolled |
2684
+ | `dropdownHeight` | no | number | Sets dropdown menu height in pixels |
2685
+ | `emptyListPlaceholder` | no | string \| [FormSelectEmptyListPlaceholder](./types.md#formselectemptylistplaceholder) | Placeholder when dropdown list is empty. Can be string or object with state-specific placeholders |
2686
+ | `fuseOptions` | no | [FormSelectFuseOption](./types.md#formselectfuseoption) | Fuse.js search options for customizing fuzzy search behavior |
2539
2687
  | `isDisabled` | no | boolean | Disables the input |
2688
+ | `isMenuDefaultOpen` | no | boolean | If true, dropdown menu will be open by default |
2540
2689
  | `isMulti` | no | boolean | Allow multiple selections |
2690
+ | `isPositionFixed` | no | boolean | Position dropdown relative to viewport instead of parent |
2541
2691
  | `isReadOnly` | no | boolean | Makes the input read-only |
2542
2692
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2543
2693
  | `isSearchable` | no | boolean | Enable type-to-search filtering |
2544
2694
  | `label` | no | string | Label text above the select |
2545
- | `options` | no | [FormSelectOption](./types.md#formselectoption)[] \| [FormSelectOption](./types.md#formselectoption)[] | Flat array of {label, value} options, or nested array of {label, list} groups for grouped/submenu options |
2695
+ | `list` | no | [FormSelectList](./types.md#formselectlist)[] \| [FormSelectList](./types.md#formselectlist)[] | Flat array of {label, value} options, or nested array of {label, list} groups for grouped/submenu options |
2696
+ | `maxHeight` | no | string \| number | Max height of multi-select container (CSS value) |
2697
+ | `maxTruncationLines` | no | number | Max rows of chips visible before "+X" overflow chip appears (multi-select only) |
2546
2698
  | `placeholder` | no | string | Placeholder text when empty |
2699
+ | `placement` | no | [AppGroupSelectPlacement](./definitions.md#appgroupselectplacement) | Dropdown position relative to input. Default: bottom-start |
2700
+ | `shouldFocusFirstElement` | no | boolean | Auto-focus first menu item when dropdown opens |
2701
+ | `shouldShowSearchIcon` | no | boolean | Show search icon prefix when isSearchable is true |
2702
+ | `shouldUsePortal` | no | boolean | Render dropdown in a React Portal. Default: false |
2547
2703
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Select input size variant. Default: M |
2548
2704
  | `tip` | no | string | Tooltip text shown alongside the field label |
2549
2705
  | `validationErrors` | no | [FormSelectValidationError](./types.md#formselectvalidationerror) | Map of rule name to error message |
@@ -2583,8 +2739,8 @@ Events: `change`
2583
2739
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2584
2740
  | `label` | no | string | Label text above the input |
2585
2741
  | `list` | yes | [FormSelectableGroupList](./types.md#formselectablegrouplist)[] | Array of item objects to render as selectable cards |
2586
- | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | Card renderer type: BASIC_CARD or LOCATION_CARD |
2587
- | `testId` | no | string | Test identifier for automated testing |
2742
+ | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | JSON-only constrained renderer choice: BASIC_CARD or LOCATION_CARD |
2743
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
2588
2744
  | `tip` | no | string | Tooltip text shown alongside the field label |
2589
2745
  | `validationErrors` | no | [FormSelectableGroupValidationError](./types.md#formselectablegroupvalidationerror) | Map of rule name to error message |
2590
2746
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2703,7 +2859,7 @@ Events: `change`
2703
2859
  | `max` | no | number | Maximum value. Default: 100 |
2704
2860
  | `min` | no | number | Minimum value. Default: 0 |
2705
2861
  | `shouldShowMarker` | no | boolean | Controls visibility of marker. Default: true |
2706
- | `step` | no | number | Step size. Default: 1 |
2862
+ | `step` | no | number | Step size. Set to null to use marks as steps. Default: 1 |
2707
2863
  | `validationErrors` | no | [FormSliderValidationError](./types.md#formslidervalidationerror) | Map of rule name to error message |
2708
2864
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2709
2865
  | `value` | no | unknown | Current value bound to state |
@@ -2792,6 +2948,7 @@ Must be placed inside a Form element — it registers with Form and does not wor
2792
2948
  Stores a boolean (true/false) value keyed by `name` in the parent Form's values.
2793
2949
  Use `defaultValue: true` to pre-toggle the switch on.
2794
2950
  Use `onLabel` and `offLabel` to customize state text.
2951
+ Use `tip` as a plain string or Tip-like object with serializable fields such as `content`, `title`, and `appearance`.
2795
2952
  Bind `value` with `{ $bindState: "/path" }` to initialize the input from state and keep state in sync. Reads initial value from state (controlled); access current value in on.change actions via `{ $state: "/path" }`.
2796
2953
  onChange emits "change". Switch has no onBlur event.
2797
2954
 
@@ -2815,6 +2972,7 @@ Events: `change`
2815
2972
  | `offLabel` | no | string | Label text when switch is off |
2816
2973
  | `onLabel` | no | string | Label text when switch is on |
2817
2974
  | `rightAlign` | no | boolean | Align switch to the right |
2975
+ | `tip` | no | string \| [FormSwitchTip](./types.md#formswitchtip) | Tooltip text or serializable tip config shown alongside the switch labels |
2818
2976
  | `validationErrors` | no | [FormSwitchValidationError](./types.md#formswitchvalidationerror) | Map of rule name to error message |
2819
2977
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2820
2978
  | `value` | no | boolean | Current value bound to state |
@@ -2828,6 +2986,7 @@ A Form-registered text field for use inside a Form component.
2828
2986
  Must be placed inside a Form element — it registers with Form and does not work standalone.
2829
2987
  Individual values are not bound to state; they flow through the parent Form's `values` push-binding on submit/change.
2830
2988
  Use `validations` for Form rule strings: "isEmail", "minLength:5", "maxLength:100", "isNumeric", etc.
2989
+ Browser/input behavior props such as `minLength`, `autoCapitalize`, `autoCorrect`, `spellCheck`, `inputMode`, `stringPadding`, and `shouldPersistCursorPosition` preserve the underlying Text input API.
2831
2990
  Use `validationErrors` to override default error messages per rule.
2832
2991
  `isRequired` blocks form submission when empty and shows an error.
2833
2992
  Bind `value` with `{ $bindState: "/path" }` to initialize the input from state and keep state in sync. Reads initial value from state (controlled); access current value in on.change actions via `{ $state: "/path" }`.
@@ -2844,19 +3003,28 @@ Events: `change`, `blur`
2844
3003
  | Name | Required | Type | Description |
2845
3004
  |---|---:|---|---|
2846
3005
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3006
+ | `autoCapitalize` | no | [EmailAutoCapitalize](./definitions.md#emailautocapitalize) | Auto-capitalization: off, none, on, sentences, words, or characters |
2847
3007
  | `autoComplete` | no | string | Browser autocomplete hint |
3008
+ | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
2848
3009
  | `autoFocus` | no | boolean | Auto-focus on mount |
2849
3010
  | `canClear` | no | boolean | Show clear button |
2850
3011
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
3012
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2851
3013
  | `isDisabled` | no | boolean | Disables the input |
3014
+ | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
2852
3015
  | `isReadOnly` | no | boolean | Makes the input read-only |
2853
3016
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2854
3017
  | `label` | no | string | Label text above the input |
2855
3018
  | `maxLength` | no | number | Maximum character count |
2856
3019
  | `maxWidth` | no | string | Maximum width CSS value |
3020
+ | `minLength` | no | number | Minimum character count |
2857
3021
  | `placeholder` | no | string | Placeholder text when empty |
2858
3022
  | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
3023
+ | `readOnlyAffixSpacing` | no | boolean | Controls gap between affixes and value in read-only mode. Default: true. Set false to remove gap |
3024
+ | `shouldPersistCursorPosition` | no | boolean | Persist cursor position for controlled input. Default: false |
2859
3025
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
3026
+ | `spellCheck` | no | boolean | Enable spell checking |
3027
+ | `stringPadding` | no | [FormTextStringPadding](./types.md#formtextstringpadding) | Pads input value with character until reaching maxLength |
2860
3028
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2861
3029
  | `tip` | no | string | Tooltip text shown alongside the field label |
2862
3030
  | `validationErrors` | no | [FormTextValidationError](./types.md#formtextvalidationerror) | Map of rule name to error message |
@@ -2872,14 +3040,15 @@ A Form-registered multi-line textarea for use inside a Form component.
2872
3040
  Must be placed inside a Form element — registers with Form and does not work standalone.
2873
3041
  Values flow through the parent Form's `values` push-binding on submit/change.
2874
3042
  Set hasCharsLimit with maxLength to show a character counter.
3043
+ Use `maxHeight` to cap textarea growth in pixels.
2875
3044
  Bind `value` with `{ $bindState: "/path" }` to initialize the input from state and keep state in sync. Reads initial value from state (controlled); access current value in on.change actions via `{ $state: "/path" }`.
2876
- onChange emits "change"; onBlur emits "blur".
3045
+ onChange emits "change"; onBlur emits "blur"; onFocus emits "focus".
2877
3046
 
2878
3047
  Catalog key: `FormTextarea`
2879
3048
  Builder: `FormTextarea`
2880
3049
  Props type: `FormTextareaProps`
2881
3050
  Accepts children: no
2882
- Events: `change`, `blur`
3051
+ Events: `change`, `blur`, `focus`
2883
3052
 
2884
3053
  ### Props
2885
3054
 
@@ -2894,10 +3063,11 @@ Events: `change`, `blur`
2894
3063
  | `isReadOnly` | no | boolean | Makes the input read-only |
2895
3064
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2896
3065
  | `label` | no | string | Label text above the input |
3066
+ | `maxHeight` | no | number | Maximum height in pixels |
2897
3067
  | `maxLength` | no | number | Maximum character count. Default: 10000 |
2898
3068
  | `placeholder` | no | string | Placeholder text when empty |
2899
3069
  | `rows` | no | number | Number of visible text rows |
2900
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Visual theme variant |
3070
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant |
2901
3071
  | `tip` | no | string | Tooltip text shown alongside the field label |
2902
3072
  | `validationErrors` | no | [FormTextareaValidationError](./types.md#formtextareavalidationerror) | Map of rule name to error message |
2903
3073
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2911,7 +3081,7 @@ A Form-registered text field with auto-suggest dropdown for use inside a Form co
2911
3081
 
2912
3082
  Must be placed inside a Form element — it registers with Form and does not work standalone.
2913
3083
  Values flow through the parent Form's `values` push-binding on submit/change.
2914
- Pass `suggestions` as an array of {label, value} objects to populate the suggestion dropdown.
3084
+ Pass `list` as the React-style flat suggestion list. Common fields are `label`, `value`, and `isDisabled`; extra serializable item metadata is preserved.
2915
3085
  Use `shouldShowMenuOnFocus: true` to open the dropdown immediately on focus.
2916
3086
  Bind `value` with `{ $bindState: "/path" }` to initialize the input from state and keep state in sync. Reads initial value from state (controlled); access current value in on.change actions via `{ $state: "/path" }`.
2917
3087
  onChange emits "change"; onBlur emits "blur".
@@ -2928,19 +3098,21 @@ Events: `change`, `blur`
2928
3098
  |---|---:|---|---|
2929
3099
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2930
3100
  | `defaultValue` | no | string | Initial value set in Form on mount |
3101
+ | `fuseOptions` | no | [FormTextAutoSuggestFuseOption](./types.md#formtextautosuggestfuseoption) | Fuse.js search options for customizing suggestion filtering |
2931
3102
  | `isDisabled` | no | boolean | Disables the input |
3103
+ | `isPositionFixed` | no | boolean | Use fixed positioning for dropdown menu. Useful in scrollable containers |
2932
3104
  | `isReadOnly` | no | boolean | Makes the input read-only |
2933
3105
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2934
3106
  | `label` | no | string | Label text above the input |
3107
+ | `list` | yes | [FormTextAutoSuggestList](./types.md#formtextautosuggestlist)[] | Flat suggestion list matching the React `list` item shape |
2935
3108
  | `maxLength` | no | number | Maximum character count |
2936
3109
  | `placeholder` | no | string | Placeholder text when empty |
2937
3110
  | `shouldShowMenuOnFocus` | no | boolean | Show dropdown menu on input focus. Default: false |
2938
3111
  | `shouldShowSearchIcon` | no | boolean | Show search icon prefix. Default: false |
2939
3112
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2940
- | `suggestions` | yes | [FormTextAutoSuggestSuggestion](./types.md#formtextautosuggestsuggestion)[] | Array of { label, value } suggestion objects |
2941
3113
  | `validationErrors` | no | [FormTextAutoSuggestValidationError](./types.md#formtextautosuggestvalidationerror) | Map of rule name to error message |
2942
3114
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2943
- | `value` | no | string | Current value bound to state |
3115
+ | `value` | no | string \| number | Current value bound to state |
2944
3116
 
2945
3117
  No additional properties.
2946
3118
 
@@ -2966,17 +3138,26 @@ Events: `change`, `blur`
2966
3138
  | Name | Required | Type | Description |
2967
3139
  |---|---:|---|---|
2968
3140
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3141
+ | `alwaysShowTimezone` | no | boolean | If true, timezone abbreviation will always be shown. Default: false |
3142
+ | `defaultSelectionStartTime` | no | string | Time to start the selection scroll from when shouldAllowTimeSelection is true (e.g. "08:00 AM") |
2969
3143
  | `defaultValue` | no | string | Initial value — ISO 8601 or "HH:MM AM/PM" time string |
3144
+ | `isDateTimeInline` | no | boolean | Make input inline, removes border, padding and width fits input/placeholder content |
2970
3145
  | `isDisabled` | no | boolean | Disables the input |
2971
3146
  | `isReadOnly` | no | boolean | Makes the input read-only |
2972
3147
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2973
3148
  | `label` | no | string | Label text above the input |
2974
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times |
3149
+ | `locale` | no | string | Locale string for time formatting (e.g. en-US) |
3150
+ | `maxWidth` | no | string | Maximum width CSS value |
3151
+ | `pickClosestMeridiem` | no | boolean | When user does not enter AM/PM, pick the closest meridiem to the inputted hour value. Default: false |
3152
+ | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
3153
+ | `shouldAllowTimeSelection` | no | boolean \| [FormTimeShouldAllowTimeSelection](./types.md#formtimeshouldallowtimeselection) | Show a time selection dropdown for picking times |
2975
3154
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time input |
3155
+ | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly |
2976
3156
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
2977
3157
  | `shouldReturnISO` | no | boolean | Always return value in ISO 8601 format |
3158
+ | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
2978
3159
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2979
- | `timezone` | no | string | Show time relative to this timezone (IANA identifier) |
3160
+ | `timezone` | no | string \| [FormTimeTimezone](./types.md#formtimetimezone) | Show time relative to this timezone or configure the timezone selector |
2980
3161
  | `validationErrors` | no | [FormTimeValidationError](./types.md#formtimevalidationerror) | Map of rule name to error message |
2981
3162
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2982
3163
  | `value` | no | string | Current value bound to state |
@@ -3124,7 +3305,7 @@ Events: `change`
3124
3305
  | `shouldShowFolderStructure` | no | boolean | Renders folder structure view |
3125
3306
  | `shouldShowSelectionPath` | no | boolean | Show parent-to-child path in selected chips. Default: false |
3126
3307
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size. Default: M |
3127
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Custom theme styling |
3308
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Custom theme styling |
3128
3309
  | `validationErrors` | no | [FormTreeSelectValidationError](./types.md#formtreeselectvalidationerror) | Map of rule name to error message |
3129
3310
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
3130
3311
  | `value` | no | unknown | Current value bound to state |
@@ -3154,7 +3335,7 @@ Events: `change`, `blur`
3154
3335
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3155
3336
  | `autoComplete` | no | string | Browser autocomplete hint |
3156
3337
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
3157
- | `domainList` | no | unknown | Email domain list for selection. Can be: single string, array of strings ["acme.com"], array of {label, value, tag?} objects (FlatList), or array of {label, list} objects (NestedList) for grouped domains |
3338
+ | `domainList` | no | string \| string[] \| [FormWorkEmailDomainList](./types.md#formworkemaildomainlist)[] \| [FormWorkEmailDomainList](./types.md#formworkemaildomainlist)[] | Email domain list for selection. Can be: single string, array of strings ["acme.com"], array of {label, value, tag?} objects (FlatList), or array of {label, list} objects (NestedList) for grouped domains |
3158
3339
  | `isDisabled` | no | boolean | Disables the input |
3159
3340
  | `isReadOnly` | no | boolean | Makes the input read-only |
3160
3341
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
@@ -3272,7 +3453,7 @@ Events: _none_
3272
3453
  |---|---:|---|---|
3273
3454
  | `align` | no | [HStackAlign](./definitions.md#hstackalign) | Cross-axis alignment |
3274
3455
  | `alignSelf` | no | [HStackAlignSelf](./definitions.md#hstackalignself) | Align self override when inside a flex parent |
3275
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
3456
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
3276
3457
  | `basis` | no | number \| string | Flex basis value |
3277
3458
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | Box sizing model |
3278
3459
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Text/icon color token |
@@ -3298,7 +3479,7 @@ No additional properties.
3298
3479
 
3299
3480
  A standalone icon element from the Pebble icon set. Use for decorative or interactive icon displays — as clickable action triggers, status indicators, or visual accents. Supports tooltips and full ARIA attributes for accessibility.
3300
3481
 
3301
- Icon type values are uppercase strings matching Icon.TYPES constants (e.g. ADD, ARROW_DOWN, CHECK, CHEVRON_DOWN, CLOSE, COPY_OUTLINE, DELETE, DOWNLOAD, EDIT_OUTLINE, SEARCH, USER_OUTLINE). When press event is bound, ariaLabel is required for accessibility. Tip can be a simple string or an object with content, placement (e.g. TOP, BOTTOM, LEFT, RIGHT), and appearance (LIGHT or DARK). Interactive icons (with onClick) automatically show a backdrop on hover with 4px padding for better hit area. The isFocused and showCursor props should only be used with interactive icons to provide visual feedback. Skipped: backdropColor (internal/non-functional), fontFamily (internal), className (CSS override), shouldPreventFocus (internal), onMouseDown/onMouseUp (DOM events), testId (testing only).
3482
+ Icon type values are uppercase strings matching Icon.TYPES constants (e.g. ADD, ARROW_DOWN, CHECK, CHEVRON_DOWN, CLOSE, COPY_OUTLINE, DELETE, DOWNLOAD, EDIT_OUTLINE, SEARCH, USER_OUTLINE). When press event is bound, aria-label is required for accessibility. Tip can be a simple string or an object with content, placement (e.g. TOP, BOTTOM, LEFT, RIGHT), and appearance (LIGHT or DARK). Interactive icons (with onClick) automatically show a backdrop on hover with 4px padding for better hit area. The isFocused and showCursor props should only be used with interactive icons to provide visual feedback. Skipped: backdropColor (internal/non-functional), fontFamily (internal), className (CSS override), shouldPreventFocus (internal), onMouseDown/onMouseUp (DOM events), testId (testing only).
3302
3483
 
3303
3484
  Catalog key: `Icon`
3304
3485
  Builder: `Icon`
@@ -3310,12 +3491,12 @@ Events: `press`
3310
3491
 
3311
3492
  | Name | Required | Type | Description |
3312
3493
  |---|---:|---|---|
3313
- | `ariaControls` | no | string | ID of element controlled by this icon |
3314
- | `ariaDescribedby` | no | string | ID of element that describes this icon |
3315
- | `ariaExpanded` | no | boolean | Indicates if controlled element is expanded |
3316
- | `ariaHaspopup` | no | [IconAriaHaspopup](./definitions.md#iconariahaspopup) | Indicates the icon triggers a popup |
3317
- | `ariaLabel` | no | string | Accessible label. Required when onClick is used |
3318
- | `ariaLabelledby` | no | string | ID of element that labels this icon |
3494
+ | `aria-controls` | no | string | ID of element controlled by this icon |
3495
+ | `aria-describedby` | no | string | ID of element that describes this icon |
3496
+ | `aria-expanded` | no | boolean | Indicates if controlled element is expanded |
3497
+ | `aria-haspopup` | no | [IconAriaHaspopup](./definitions.md#iconariahaspopup) | Indicates the icon triggers a popup |
3498
+ | `aria-label` | no | string | Accessible label. Required when onClick is used |
3499
+ | `aria-labelledby` | no | string | ID of element that labels this icon |
3319
3500
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Pebble text/icon color token |
3320
3501
  | `isDisabled` | no | boolean | Disable the icon. Default: false |
3321
3502
  | `isFocused` | no | boolean | Show icon backdrop when focused. Use only with interactive icons (onClick). Default: false |
@@ -3374,7 +3555,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
3374
3555
  | `shouldShowSpinner` | no | boolean | If true, shows loading spinner instead of icon |
3375
3556
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the button (XS, S, M, L). Default: M |
3376
3557
  | `tabIndex` | no | number | Tab order for keyboard navigation |
3377
- | `testId` | no | string | Sets data-testid attribute. Default: "icon-button" |
3378
3558
  | `tip` | no | string \| [IconButtonTip](./types.md#iconbuttontip) | Tooltip text or tooltip configuration object |
3379
3559
  | `to` | no | string \| [IconButtonTo](./types.md#iconbuttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
3380
3560
  | `type` | no | [FloatingButtonType](./definitions.md#floatingbuttontype) | HTML button type attribute (button, submit, reset). Default: button |
@@ -3402,7 +3582,7 @@ Events: `press`, `load`, `error`
3402
3582
  | `borderRadius` | no | [BoxRadius](./definitions.md#boxradius) | Border radius token, e.g. "shapeCornerMd" |
3403
3583
  | `height` | no | number \| string | Image height in px or CSS string |
3404
3584
  | `loading` | no | [ImageLoading](./definitions.md#imageloading) | Loading strategy. Default: eager |
3405
- | `src` | yes | string \| [Src](./types.md#src) | Image URL or theme-aware source object with light/dark variants |
3585
+ | `src` | no | string \| [Src](./types.md#src) | Image URL or theme-aware source object with light/dark variants |
3406
3586
  | `theme` | no | [ImageTheme](./definitions.md#imagetheme) | Image theme. COVER for cover positioning |
3407
3587
  | `width` | no | number \| string | Image width in px or CSS string |
3408
3588
 
@@ -3513,7 +3693,7 @@ Events: _none_
3513
3693
  | `leftIcon` | no | string \| [LabelLeftIcon](./types.md#labellefticon) | Icon displayed on the left side of the label |
3514
3694
  | `maxWidth` | no | string | Maximum width CSS value for truncation |
3515
3695
  | `rightIcon` | no | string \| [LabelRightIcon](./types.md#labelrighticon) | Icon displayed on the right side of the label |
3516
- | `size` | no | [LabelSize](./definitions.md#labelsize) | Size of the label. Default: LARGE |
3696
+ | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the label. Default: LARGE |
3517
3697
  | `text` | yes | string | Text content of the label |
3518
3698
  | `tip` | no | string \| [LabelTip](./types.md#labeltip) | Tooltip shown on hover. Can be simple string or object with appearance, placement, and other options |
3519
3699
 
@@ -3570,7 +3750,7 @@ Events: _none_
3570
3750
  |---|---:|---|---|
3571
3751
  | `align` | no | string | CSS align-items value for flex children alignment |
3572
3752
  | `alignSelf` | no | string | CSS align-self value to override parent align |
3573
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
3753
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
3574
3754
  | `basis` | no | number \| string | CSS flex-basis value |
3575
3755
  | `border` | no | string \| [LayoutBorder](./types.md#layoutborder) \| [LayoutBorder](./types.md#layoutborder) | Border. CSS string, strict token parts, or directional border object |
3576
3756
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | CSS box-sizing model |
@@ -3618,7 +3798,7 @@ Events: `press`
3618
3798
  | Name | Required | Type | Description |
3619
3799
  |---|---:|---|---|
3620
3800
  | `padding` | no | [LayoutCardPadding](./definitions.md#layoutcardpadding) | Card padding size. Default: PX_24 |
3621
- | `theme` | no | [LayoutCardTheme](./definitions.md#layoutcardtheme) | Card theme. SELECTABLE adds 2px tertiary border for selection UI. Default: DEFAULT |
3801
+ | `theme` | no | [CardTheme](./definitions.md#cardtheme) | Card theme. SELECTABLE adds 2px tertiary border for selection UI. Default: DEFAULT |
3622
3802
 
3623
3803
  No additional properties.
3624
3804
 
@@ -3724,9 +3904,9 @@ No additional properties.
3724
3904
 
3725
3905
  ## LottiePlayer
3726
3906
 
3727
- Plays Lottie animations (JSON-based vector animations). Use for animated illustrations, loading states, or decorative motion graphics. Supports SVG, Canvas, and HTML rendering. Provide either a path to a Lottie JSON file or the animation data directly.
3907
+ Plays Lottie animations (JSON-based vector animations). Use for animated illustrations, loading states, or decorative motion graphics. Supports SVG, Canvas, and HTML rendering. Provide either a path to a Lottie JSON file or the animation data directly through loadConfig.
3728
3908
 
3729
- Either path or animationData must be provided. Use path for external JSON files; use animationData for inline animation objects. The renderer prop controls how the animation is rendered: svg (default, best quality), canvas (better performance for complex animations), or html (rarely used). Loop can be true (infinite), false (play once), or a number (play N times).
3909
+ Use loadConfig to preserve the underlying React prop shape. Provide either loadConfig.path for an external JSON file or loadConfig.animationData for inline animation data. loadConfig.renderer controls how the animation is rendered: svg (default, best quality), canvas (better performance for complex animations), or html (rarely used). loadConfig.loop can be true (infinite), false (play once), or a number (play N times).
3730
3910
 
3731
3911
  Catalog key: `LottiePlayer`
3732
3912
  Builder: `LottiePlayer`
@@ -3738,13 +3918,8 @@ Events: _none_
3738
3918
 
3739
3919
  | Name | Required | Type | Description |
3740
3920
  |---|---:|---|---|
3741
- | `animationData` | no | [AnimationData](./types.md#animationdata) | Lottie animation JSON object. Required if path not provided |
3742
- | `autoplay` | no | boolean | Start playing automatically on load. Default: true |
3743
3921
  | `height` | no | string | Height of the animation container |
3744
- | `loop` | no | boolean \| number | Loop animation. true for infinite, false for once, or number for specific count |
3745
- | `path` | no | string | URL or relative path to the Lottie JSON animation file. Required if animationData not provided |
3746
- | `renderer` | no | [LottiePlayerRenderer](./definitions.md#lottieplayerrenderer) | Rendering method for the animation. Default: svg |
3747
- | `testId` | no | string | Data test id for testing purposes |
3922
+ | `loadConfig` | no | [LoadConfig](./types.md#loadconfig) | Semantic Lottie load configuration object |
3748
3923
  | `width` | no | string | Width of the animation container |
3749
3924
 
3750
3925
  No additional properties.
@@ -3824,7 +3999,7 @@ No additional properties.
3824
3999
 
3825
4000
  An interactive overlay that demands user attention and input, isolating specific tasks or information above the main page content. Use for confirmations, urgent notifications, or brief focused tasks that require an immediate response.
3826
4001
 
3827
- Place ModalFooter component as the last child for action buttons. On close event, update isOpen binding to false to dismiss the modal.
4002
+ Place ModalFooter component as the last child for action buttons. On close event, update isVisible binding to false to dismiss the modal.
3828
4003
 
3829
4004
  Catalog key: `Modal`
3830
4005
  Builder: `Modal`
@@ -3838,15 +4013,15 @@ Events: `close`
3838
4013
  |---|---:|---|---|
3839
4014
  | `animation` | no | string | Modal animation type (e.g., "zoom", "fade"). Default: zoom |
3840
4015
  | `backdropAnimation` | no | string | Backdrop animation type (e.g., "fade"). Default: fade |
3841
- | `hasCloseButton` | no | boolean | Shows close button in header. Default: true |
3842
4016
  | `isFullScreen` | no | boolean | If true, modal renders full screen. Default: false |
3843
- | `isOpen` | no | boolean | Controls modal visibility |
4017
+ | `isVisible` | no | boolean | Controls modal visibility |
3844
4018
  | `shouldCloseOnBackdropClick` | no | boolean | If true, modal closes when backdrop is clicked. Default: true |
3845
4019
  | `shouldCloseOnEscape` | no | boolean | If true, modal closes on Escape key press. Defaults to shouldCloseOnBackdropClick value |
4020
+ | `shouldHideCancelIcon` | no | boolean | If true, hides the close button in the header. Default: false |
3846
4021
  | `shouldNotAnimate` | no | boolean | Disables open/close animation. Should be true if DataGrid is rendered as content |
3847
- | `size` | no | [ModalSize](./definitions.md#modalsize) | Modal width size. Default: medium |
3848
4022
  | `theme` | no | [ModalTheme](./definitions.md#modaltheme) | Pre-defined modal styles. GRAY: gray background. NO_PADDING: removes body padding |
3849
4023
  | `title` | no | string | Modal header title text |
4024
+ | `width` | no | number \| string | Custom modal width in px (number) or CSS string |
3850
4025
 
3851
4026
  No additional properties.
3852
4027
 
@@ -3919,7 +4094,7 @@ Events: `toggle`, `select`
3919
4094
  | `showMore` | no | [ShowMoreValue](./types.md#showmorevalue) | Configuration for show more behavior |
3920
4095
  | `theme` | no | [NestedListTheme](./definitions.md#nestedlisttheme) | ExpansionPanel theme variant |
3921
4096
  | `title` | no | string | Title for the nested list |
3922
- | `toggleIcon` | no | [ToggleIcon](./types.md#toggleicon) | Toggle icon configuration |
4097
+ | `toggleIcon` | no | [NestedListToggleIcon](./types.md#nestedlisttoggleicon) | Toggle icon configuration |
3923
4098
 
3924
4099
  No additional properties.
3925
4100
 
@@ -3961,6 +4136,7 @@ Events: `change`, `blur`, `changeRaw`, `changeCalculationState`
3961
4136
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates on blur |
3962
4137
  | `shouldDisableFormatting` | no | boolean | If true, number formatting will not be applied. Default: true |
3963
4138
  | `shouldDisableRedundantZeroFormatting` | no | boolean | If true, redundant zeros are preserved. Default: true |
4139
+ | `shouldStripLeadingZeros` | no | boolean | If true, leading zeros are stripped from the numeric value |
3964
4140
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
3965
4141
  | `spellCheck` | no | boolean | Enable spell checking |
3966
4142
  | `step` | no | number | Increment/decrement step size. Default: 1 |
@@ -4035,15 +4211,15 @@ No additional properties.
4035
4211
 
4036
4212
  ## ObjectUIHeader
4037
4213
 
4038
- Header section of an entity overview (person, organization, device) displaying an avatar, title, and caption. Used at the top of ObjectUI layouts to identify the entity at a glance.
4214
+ Header section of an entity overview (person, organization, device) displaying an avatar, title, caption, optional label chip, and an optional primary action. Used at the top of ObjectUI layouts to identify the entity at a glance.
4039
4215
 
4040
- ObjectUIHeader renders the header section of an ObjectUI layout with an avatar, title, and caption. Use within ObjectUITemplate. Complex actions (buttons, dropdowns) are not supported — use separate Button components for actions.
4216
+ ObjectUIHeader renders the header section of an ObjectUI layout with an avatar, title, caption, optional label chip, and optional primary action. Clicking primaryAction emits the primaryAction event. primaryActionLabel is deprecated and kept only for backward compatibility; prefer primaryAction.label for new specs. Complex actions (button dropdowns, select actions, responsive action groups) are not supported — compose those with separate JSON-render components outside ObjectUIHeader.
4041
4217
 
4042
4218
  Catalog key: `ObjectUIHeader`
4043
4219
  Builder: `ObjectUIHeader`
4044
4220
  Props type: `ObjectUIHeaderProps`
4045
4221
  Accepts children: no
4046
- Events: _none_
4222
+ Events: `primaryAction`
4047
4223
 
4048
4224
  ### Props
4049
4225
 
@@ -4051,7 +4227,9 @@ Events: _none_
4051
4227
  |---|---:|---|---|
4052
4228
  | `avatarProps` | no | [ObjectUIHeaderAvatarProp](./types.md#objectuiheaderavatarprop) | Avatar configuration for the header |
4053
4229
  | `caption` | no | string | Header caption text below the title |
4054
- | `primaryActionLabel` | no | string | Label for the primary action button displayed in the header |
4230
+ | `label` | no | [LabelValue](./types.md#labelvalue) | Label chip displayed next to the title |
4231
+ | `primaryAction` | no | [ObjectUIHeaderPrimaryAction](./types.md#objectuiheaderprimaryaction) | Primary action button. Clicking it emits the primaryAction event |
4232
+ | `primaryActionLabel` | no | string | Deprecated. Use primaryAction.label instead for the primary action button text |
4055
4233
  | `title` | no | string | Header title text |
4056
4234
 
4057
4235
  No additional properties.
@@ -4191,7 +4369,7 @@ No additional properties.
4191
4369
 
4192
4370
  A top-of-page header displaying a title and optional caption, used inside a page layout alongside PageContent and PageFooter. Use size to match the PageContent width.
4193
4371
 
4194
- PageHeader renders a page-level header with title and caption text. Use size to match the PageContent width. Use shouldBeLeftAligned to align the header to the left instead of center. Add action buttons via the actions prop — each action emits an "action" event on click with its ID written to actionClickedId state. When actions are present, the header is automatically underlined unless shouldBeUnderlined is set to false.
4372
+ PageHeader renders a page-level header with title and caption text. Use size to match the PageContent width. Use shouldBeLeftAligned to align the header to the left instead of center. The React actions prop is a ReactNode slot and is not JSON-serializable. For backward compatibility, SDUI keeps actions as a JSON-only extension that renders Button actions; each action emits the action event on click with its ID written to actionClickedId state. When JSON-only actions are present, the header is automatically underlined unless shouldBeUnderlined is set to false.
4195
4373
 
4196
4374
  Catalog key: `PageHeader`
4197
4375
  Builder: `PageHeader`
@@ -4204,7 +4382,7 @@ Events: `action`
4204
4382
  | Name | Required | Type | Description |
4205
4383
  |---|---:|---|---|
4206
4384
  | `actionClickedId` | no | string | Bind to state to receive the clicked action ID when an action is clicked |
4207
- | `actions` | no | [PageHeaderAction](./types.md#pageheaderaction)[] | Action buttons to display in the header. Each action emits an "action" event on click. |
4385
+ | `actions` | no | [PageHeaderAction](./types.md#pageheaderaction)[] | JSON-only extension for serializable button actions. React Page.Header actions is a ReactNode slot; this array renders Button actions and emits an action event on click. |
4208
4386
  | `caption` | no | string | Caption text displayed below the title |
4209
4387
  | `id` | no | string | HTML id attribute for the title/caption container |
4210
4388
  | `shouldBeLeftAligned` | no | boolean | If true, header is left-aligned instead of centered. Default: false |
@@ -4245,7 +4423,7 @@ No additional properties.
4245
4423
 
4246
4424
  A paginated list that divides items across pages with built-in navigation controls. Use when displaying a client-side list that is too long for a single view and needs page-by-page browsing.
4247
4425
 
4248
- The list prop should be bound to state. Each item must have a unique id and a label field. The pageSize prop controls how many items appear per page (default 10). Unlike Paginate (standalone pagination control), PaginateList manages both list rendering and pagination state together.
4426
+ PaginateList intentionally exposes a JSON-only subset of the React list/listItemRenderer model. Each list item must provide id and label so SDUI can use its built-in renderer. The pageSize prop controls how many items appear per page (default 10). Unlike Paginate (standalone pagination control), PaginateList manages both list rendering and pagination state together.
4249
4427
 
4250
4428
  Catalog key: `PaginateList`
4251
4429
  Builder: `PaginateList`
@@ -4258,7 +4436,7 @@ Events: `change`
4258
4436
  | Name | Required | Type | Description |
4259
4437
  |---|---:|---|---|
4260
4438
  | `initialPage` | no | number | Initial page number to display (0-indexed) |
4261
- | `list` | yes | [PaginateListList](./types.md#paginatelistlist)[] | Array of items to paginate. Each item must have an id and a label. Additional keys are allowed. |
4439
+ | `list` | yes | [PaginateListList](./types.md#paginatelistlist)[] | JSON-only subset of the React list prop. Each item must have an id and label for the built-in renderer. |
4262
4440
  | `pageSize` | no | number | Number of items displayed per page. Default: 10 |
4263
4441
 
4264
4442
  No additional properties.
@@ -4320,7 +4498,7 @@ Events: `collapsedChange`, `dismiss`, `resize`
4320
4498
 
4321
4499
  | Name | Required | Type | Description |
4322
4500
  |---|---:|---|---|
4323
- | `ariaLabel` | yes | string | Accessible label for the pane region. Used by screen readers to identify the pane. Also used to construct labels for collapse/expand/dismiss buttons. Example: "File Explorer", "Properties Panel" |
4501
+ | `aria-label` | yes | string | Accessible label for the pane region. Used by screen readers to identify the pane. Also used to construct labels for collapse/expand/dismiss buttons. Example: "File Explorer", "Properties Panel" |
4324
4502
  | `collapsed` | no | boolean | Controlled collapsed state. Bind to state for controlled mode |
4325
4503
  | `collapsible` | no | boolean | Whether pane can be collapsed by the user. When undefined, infers from size/verticalSize/dismissible props |
4326
4504
  | `containerName` | no | string | CSS container name for container queries. When set, enables @container queries for content inside this pane |
@@ -4344,7 +4522,7 @@ A secure input field for entering or creating passwords, with automatic characte
4344
4522
 
4345
4523
  onChange writes password value to state path bound to `value`, then emits "change"
4346
4524
  onBlur validates if checks are provided, then emits "blur"
4347
- onRevealChange emits "reveal" event - bind state to capture reveal status (true when password is visible)
4525
+ onRevealChange emits "revealChange" when the reveal state toggles
4348
4526
  Keyboard events (keydown, keyup, paste) and mouse events (click, mouseenter, mouseleave, focus) emit without parameters
4349
4527
  Use prefix/suffix for icons - pass Icon.TYPES names like "LOCK_OUTLINE" or text
4350
4528
  Use inputMode to hint the virtual keyboard type on mobile devices
@@ -4356,7 +4534,7 @@ Catalog key: `Password`
4356
4534
  Builder: `Password`
4357
4535
  Props type: `PasswordProps`
4358
4536
  Accepts children: no
4359
- Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mouseenter`, `mouseleave`, `reveal`
4537
+ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mouseenter`, `mouseleave`, `revealChange`
4360
4538
 
4361
4539
  ### Props
4362
4540
 
@@ -4374,6 +4552,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4374
4552
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
4375
4553
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
4376
4554
  | `isDisabled` | no | boolean | Disables the input |
4555
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4377
4556
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
4378
4557
  | `isReadOnly` | no | boolean | Makes the input read-only |
4379
4558
  | `isRequired` | no | boolean | Marks the field as required |
@@ -4392,7 +4571,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4392
4571
  | `spellCheck` | no | boolean | Enable spell checking |
4393
4572
  | `stringPadding` | no | [PasswordStringPadding](./types.md#passwordstringpadding) | Pads input value with character until reaching maxLength |
4394
4573
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
4395
- | `testId` | no | string | Test ID for automation |
4396
4574
  | `theme` | no | string | Theme name from Input.Password.THEMES or custom theme |
4397
4575
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4398
4576
  | `value` | no | string | Current password value bound to state |
@@ -4420,7 +4598,9 @@ Events: `change`, `blur`
4420
4598
  | `checks` | no | [PercentageCheck](./types.md#percentagecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4421
4599
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
4422
4600
  | `defaultValue` | no | number | Default percentage value when uncontrolled |
4601
+ | `id` | no | string | HTML id attribute for the input |
4423
4602
  | `isDisabled` | no | boolean | Disables the input |
4603
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4424
4604
  | `isReadOnly` | no | boolean | Makes the input read-only |
4425
4605
  | `isRequired` | no | boolean | Marks the field as required |
4426
4606
  | `label` | no | string | Label text above the input |
@@ -4444,14 +4624,15 @@ A specialized input for entering and editing phone numbers with automatic region
4444
4624
  onChange writes formatted phone number to state path bound to `value`, then emits "change"
4445
4625
  onBlur validates if checks are provided, then emits "blur"
4446
4626
  Keyboard events (keydown, keyup, paste) and mouse events (click, mouseenter, mouseleave, focus) emit without parameters
4447
- For fixed country code prefix, use countryCode as string (e.g., "91", "1")
4448
- For country code dropdown, bind countryCodeValue to state - emits "countryCodeChange" when dropdown changes
4627
+ countryCode preserves the React API shape: pass a string for a fixed prefix or an object for the dropdown branch. countryCodeChange emits when the dropdown selection changes.
4628
+ countryCodeValue, countryCodeDefaultValue, isCountryCodeDisabled, isCountryCodeReadOnly, and isCountryCodeRequired are deprecated legacy aliases kept for backward compatibility; prefer the nested countryCode object fields for new specs.
4449
4629
  Use defaultRegion to specify formatting region (US, IN, CA, etc.) - defaults to US
4450
4630
  Use prefix/suffix for icons - pass Icon.TYPES names like "PHONE_OUTLINE" or text
4451
4631
  Use inputMode to hint the virtual keyboard type on mobile devices - defaults to "tel"
4452
4632
  Use stringPadding to automatically pad values
4453
4633
  Basic ARIA attributes (aria-label, aria-labelledby, aria-describedby) support accessibility
4454
4634
  The region prop is deprecated - use defaultRegion instead
4635
+ testId is a deprecated testing-only prop kept only for backward compatibility.
4455
4636
  Standalone — does not register with Form; use FormPhone inside a Form instead.
4456
4637
 
4457
4638
  Catalog key: `Phone`
@@ -4473,18 +4654,18 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4473
4654
  | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
4474
4655
  | `autoFocus` | no | boolean | Auto-focus on mount |
4475
4656
  | `checks` | no | [PhoneCheck](./types.md#phonecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4476
- | `countryCode` | no | string | Country code as string (e.g. "91", "1") to add as fixed prefix. For dropdown, use countryCodeValue instead |
4477
- | `countryCodeDefaultValue` | no | string | Default country code for dropdown mode |
4478
- | `countryCodeValue` | no | string | Country code value bound to state for dropdown mode. Bind to state to enable country code dropdown |
4657
+ | `countryCode` | no | string \| [PhoneCountryCode](./types.md#phonecountrycode) | Either a fixed country code string or a country-code dropdown configuration object |
4658
+ | `countryCodeDefaultValue` | no | string | [Deprecated] Use countryCode.defaultValue instead. Initial selected country code for the legacy dropdown shape |
4659
+ | `countryCodeValue` | no | string | [Deprecated] Use countryCode.value instead. Bound selected country code for the legacy dropdown shape |
4479
4660
  | `defaultRegion` | no | string | Default country region code for formatting, e.g. "US", "IN", "CA". Default: US |
4480
4661
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
4481
4662
  | `fixedCharsPrefix` | no | string | Fixed characters at the beginning of value |
4482
4663
  | `fixedCharsSuffix` | no | string | Fixed characters at the end of value |
4483
4664
  | `id` | no | string | HTML element ID |
4484
4665
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
4485
- | `isCountryCodeDisabled` | no | boolean | Disable country code dropdown |
4486
- | `isCountryCodeReadOnly` | no | boolean | Make country code dropdown read-only |
4487
- | `isCountryCodeRequired` | no | boolean | Mark country code dropdown as required |
4666
+ | `isCountryCodeDisabled` | no | boolean | [Deprecated] Use countryCode.isDisabled instead for the legacy dropdown shape |
4667
+ | `isCountryCodeReadOnly` | no | boolean | [Deprecated] Use countryCode.isReadOnly instead for the legacy dropdown shape |
4668
+ | `isCountryCodeRequired` | no | boolean | [Deprecated] Use countryCode.isRequired instead for the legacy dropdown shape |
4488
4669
  | `isDisabled` | no | boolean | Disables the input |
4489
4670
  | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4490
4671
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
@@ -4510,7 +4691,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4510
4691
  | `spellCheck` | no | boolean | Enable spell checking |
4511
4692
  | `stringPadding` | no | [PhoneStringPadding](./types.md#phonestringpadding) | Pads input value with character until reaching maxLength |
4512
4693
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
4513
- | `testId` | no | string | Test ID for automation |
4694
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
4514
4695
  | `theme` | no | string | Theme name from Input.Phone.THEMES or custom theme |
4515
4696
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4516
4697
  | `value` | no | string | Current phone number value bound to state |
@@ -4521,7 +4702,7 @@ No additional properties.
4521
4702
 
4522
4703
  Communicates the status of an ongoing process, like downloading or uploading files, to inform the user of the remaining wait time. Use determinate mode when progress percentage is known, or indeterminate when wait time cannot be calculated. For multi-step processes requiring user action, use ProgressSteps instead; for a simple busy indicator, use Spinner.
4523
4704
 
4524
- Set isIndeterminate=true when the progress amount is unknown; the bar animates continuously. When progress becomes known, switch to determinate by setting value (0-100) and isIndeterminate=false. Use appearance to convey semantic meaning: SUCCESS for completed operations, ERROR for failed ones, WARNING for operations needing attention. The value prop supports $state/$bindState for real-time updates from backend processes. Always provide an aria-label describing the process (e.g. "Downloading PDF") since the bar is a visual-only cue.
4705
+ Set isIndeterminate=true when the progress amount is unknown; the bar animates continuously. When progress becomes known, set completedPercent (0-100) and isIndeterminate=false. Use appearance to convey semantic meaning: SUCCESS for completed operations, ERROR for failed ones, WARNING for operations needing attention. completedPercent supports $state/$bindState for real-time updates from backend processes. Always provide an aria-label describing the process (e.g. "Downloading PDF") since the bar is a visual-only cue. The legacy value, label, showPercentage, and testId props are kept only for backward compatibility with older SDUI specs.
4525
4706
 
4526
4707
  Catalog key: `ProgressBar`
4527
4708
  Builder: `ProgressBar`
@@ -4538,11 +4719,12 @@ Events: _none_
4538
4719
  | `aria-label` | no | string | Accessibility label for screen readers |
4539
4720
  | `aria-labelledby` | no | string | ID of element that labels this progress bar |
4540
4721
  | `aria-valuetext` | no | string | Human-readable text alternative for the current value |
4722
+ | `completedPercent` | no | number | Progress percentage (0-100). Canonical ProgressBar value prop |
4541
4723
  | `isIndeterminate` | no | boolean | Shows indeterminate loading animation |
4542
- | `label` | no | string | Label text displayed above the progress bar |
4543
- | `showPercentage` | no | boolean | Displays the percentage value as text |
4544
- | `testId` | no | string | Test identifier for automated testing. Default: progress-bar |
4545
- | `value` | no | number | Progress percentage (0-100) |
4724
+ | `label` | no | string | Deprecated compatibility prop for wrapper-level label text outside ProgressBar |
4725
+ | `showPercentage` | no | boolean | Deprecated compatibility prop for wrapper-level percentage text outside ProgressBar |
4726
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility. Default: progress-bar |
4727
+ | `value` | no | number | Deprecated. Use completedPercent instead |
4546
4728
 
4547
4729
  No additional properties.
4548
4730
 
@@ -4550,7 +4732,7 @@ No additional properties.
4550
4732
 
4551
4733
  A multi-step progress indicator that visually shows completed, current, and upcoming steps in a sequential workflow. Use for onboarding flows, form wizards, or any multi-part process where users need to see their progress.
4552
4734
 
4553
- stepsCompleted starts at 1. Use isNumeric for numbered steps. Use isHorizontal for compact horizontal layouts.
4735
+ stepsCompleted starts at 1. Use isNumeric for numbered steps. Use isHorizontal for compact horizontal layouts. SDUI does not support the React onStepAdd callback affordance, so add-step nodes are not rendered from JSON.
4554
4736
 
4555
4737
  Catalog key: `ProgressSteps`
4556
4738
  Builder: `ProgressSteps`
@@ -4574,7 +4756,7 @@ No additional properties.
4574
4756
 
4575
4757
  Radio buttons let users choose a single option from two or more mutually exclusive options. Prefer over Select when showing 5 or fewer options that need to be immediately visible. Use Checkbox instead when multiple selections are allowed.
4576
4758
 
4577
- onChange stores the selected option value in state. The stored value matches the value field of the selected option object. onMouseEnter and onMouseLeave write the hovered option value to hoveredValue state path before emitting events. Prefer over Select when showing 5 or fewer options that need to be immediately visible. Standalone — does not register with Form; use FormRadio inside a Form instead.
4759
+ onChange stores the selected option value in state. The stored value matches the value field of the selected option object. onMouseEnter and onMouseLeave write the hovered option value to hoveredValue state path before emitting events. Pass list as an array of {label, value} option objects. Prefer over Select when showing 5 or fewer options that need to be immediately visible. Standalone — does not register with Form; use FormRadio inside a Form instead.
4578
4760
 
4579
4761
  Catalog key: `Radio`
4580
4762
  Builder: `Radio`
@@ -4596,10 +4778,11 @@ Events: `change`, `blur`, `mouseenter`, `mouseleave`
4596
4778
  | `id` | no | string | HTML id attribute for the radio group |
4597
4779
  | `isDisabled` | no | boolean | Disables all radio options |
4598
4780
  | `isHorizontal` | no | boolean | Arrange options in a row |
4781
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4599
4782
  | `isReadOnly` | no | boolean | Makes the radio group read-only |
4600
4783
  | `isRequired` | no | boolean | Marks the field as required |
4601
4784
  | `label` | no | string | Label text above the radio group |
4602
- | `options` | no | [RadioOption](./types.md#radiooption)[] | Array of { label, value } option objects |
4785
+ | `list` | no | [RadioList](./types.md#radiolist)[] | Array of { label, value } option objects |
4603
4786
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
4604
4787
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4605
4788
  | `value` | no | unknown | Currently selected value bound to state |
@@ -4665,6 +4848,28 @@ _No fields._
4665
4848
 
4666
4849
  No additional properties.
4667
4850
 
4851
+ ## Reports
4852
+
4853
+ Embeds a saved Rippling Analytics Report by id. Mounts the EmbeddedReport viewer in STANDALONE mode; the viewer owns fetch, loading, and 403–404 surfaces.
4854
+
4855
+ reportId: id of the saved Analytics Report. The viewer fetches the report itself, derives grid-vs-chart from the saved config, and handles its own loading stencil and error boundary (forbidden / not-found surfaces from inside the tile).
4856
+
4857
+ The tile owns a local <Suspense> boundary so the viewer's internal version-create suspense is contained to this tile and does not bubble up to the page-level Suspense.
4858
+
4859
+ Catalog key: `Reports`
4860
+ Builder: `Reports`
4861
+ Props type: `ReportsProps`
4862
+ Accepts children: no
4863
+ Events: _none_
4864
+
4865
+ ### Props
4866
+
4867
+ | Name | Required | Type | Description |
4868
+ |---|---:|---|---|
4869
+ | `reportId` | yes | string | Id of a saved Rippling Analytics Report. The viewer fetches the report and derives grid-vs-chart from its saved configuration. |
4870
+
4871
+ No additional properties.
4872
+
4668
4873
  ## ReportShareLoader
4669
4874
 
4670
4875
  A skeleton placeholder shown while report sharing content is loading. Use when the report share dialog or page layout is known and you want to reduce perceived loading time and prevent layout shift. Renders a header, description, and two side-by-side content blocks (stacking on mobile).
@@ -4761,7 +4966,7 @@ No additional properties.
4761
4966
 
4762
4967
  A linear set of buttons for toggling between closely related choices (2-5 short-label options) and instantly applying a selection. Supports single, multi, and range selection modes. NOT suitable for binary (2-option) choices — use Toggle or ToggleButton instead. Prefer over Radio when options are short labels needing a compact inline layout; use Radio for longer phrases, Tabs for content navigation.
4763
4968
 
4764
- onChange stores the selected value (single mode) or an array of selected values (isMulti mode) in state. Pass options as an array of {label, value} objects — these map to the internal `list` prop. Prefer over Radio when options are short labels (2-5 items) and need a compact inline layout. Standalone — does not register with Form; use FormSegmentedControl inside a Form instead.
4969
+ onChange stores the selected value (single mode) or an array of selected values (isMulti mode) in state. Pass list as an array of {label, value} objects. Prefer over Radio when options are short labels (2-5 items) and need a compact inline layout. Standalone — does not register with Form; use FormSegmentedControl inside a Form instead.
4765
4970
 
4766
4971
  Catalog key: `SegmentedControl`
4767
4972
  Builder: `SegmentedControl`
@@ -4779,12 +4984,14 @@ Events: `change`, `blur`
4779
4984
  | `defaultValue` | no | string \| string[] | Initial value when uncontrolled |
4780
4985
  | `isDisabled` | no | boolean | Disables the entire control |
4781
4986
  | `isFluid` | no | boolean | Stretches control to fill container width |
4987
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4782
4988
  | `isMulti` | no | boolean | Allows selecting multiple options |
4783
4989
  | `isReadOnly` | no | boolean | Makes the control read-only |
4784
4990
  | `isRequired` | no | boolean | Marks the field as required |
4785
4991
  | `isVertical` | no | boolean | Renders options in a vertical layout |
4786
4992
  | `label` | no | string | Label text above the segmented control |
4787
- | `options` | yes | [SegmentedControlOption](./types.md#segmentedcontroloption)[] | Array of { label, value } option objects |
4993
+ | `list` | yes | [SegmentedControlList](./types.md#segmentedcontrollist)[] | Array of { label, value } option objects |
4994
+ | `options` | no | [SegmentedControlOption](./types.md#segmentedcontroloption)[] | [Deprecated] Use list. Legacy alias for segmented control options |
4788
4995
  | `rangeLabels` | no | [SegmentedControlRangeLabel](./types.md#segmentedcontrolrangelabel) | Labels to display at the start and end of the control range |
4789
4996
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Control size variant. Default: M |
4790
4997
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
@@ -4797,6 +5004,7 @@ No additional properties.
4797
5004
  A dropdown input that lets users choose one or more options from a predefined list. Use for long lists, searchable lists, or constrained spaces. Use Radio or Checkbox cards instead when there are few options and the selection is a key part of the flow.
4798
5005
 
4799
5006
  onChange stores the selected option value in state (single mode) or an array of selected values (isMulti mode).
5007
+ Use list for the React-aligned static option branches. list supports either a flat array of options or nested groups of {label, list}. The legacy options prop is kept only for backward compatibility.
4800
5008
  Options support rich metadata: secondaryLabel/tertiaryLabel/quaternaryLabel for multi-line text, leftIconType/labelIcon for icons (use Icon.TYPES glyph names like 'CHECK_CIRCLE_OUTLINE'), avatarProps for user options, flag for country codes, isRecommended for badges, isSeparator for dividers.
4801
5009
  Set isMulti=true for multi-select with token chips. Set creatable=true to allow creating new options.
4802
5010
  Multi-select chip overflow: use maxTruncationLines to cap the number of visible chip rows before a "+X" overflow chip appears. Do not use rows for this — rows sets the minimum row count, not the max.
@@ -4823,12 +5031,14 @@ Events: `change`, `blur`, `focus`, `paste`, `menuToggle`
4823
5031
  | `checks` | no | [SelectCheck](./types.md#selectcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4824
5032
  | `creatable` | no | boolean | Allow creating new options not in the list |
4825
5033
  | `defaultSearchQuery` | no | string | Initial search input value |
5034
+ | `defaultValue` | no | unknown[] \| unknown | Initial selected value or values when uncontrolled |
4826
5035
  | `dropdownHeight` | no | number | Sets dropdown menu height in pixels |
4827
5036
  | `emptyListPlaceholder` | no | string \| [SelectEmptyListPlaceholder](./types.md#selectemptylistplaceholder) | Placeholder when dropdown list is empty. Can be string or object with state-specific placeholders |
4828
5037
  | `footer` | no | [SelectFooter](./types.md#selectfooter) | Fixed footer at bottom of dropdown menu |
4829
5038
  | `fuseOptions` | no | [SelectFuseOption](./types.md#selectfuseoption) | Fuse.js search options for customizing fuzzy search behavior |
4830
5039
  | `id` | no | string | HTML id attribute for the select input |
4831
5040
  | `isDisabled` | no | boolean | Disables the select |
5041
+ | `isInvalid` | no | boolean | Shows invalid styling on the select |
4832
5042
  | `isMenuDefaultOpen` | no | boolean | If true, dropdown menu will be open by default |
4833
5043
  | `isMulti` | no | boolean | Allow multiple selections |
4834
5044
  | `isPositionFixed` | no | boolean | Position dropdown relative to viewport instead of parent |
@@ -4836,9 +5046,10 @@ Events: `change`, `blur`, `focus`, `paste`, `menuToggle`
4836
5046
  | `isRequired` | no | boolean | Marks the field as required |
4837
5047
  | `isSearchable` | no | boolean | Enable type-to-search filtering |
4838
5048
  | `label` | no | string | Label text above the select |
5049
+ | `list` | no | [SelectList](./types.md#selectlist)[] \| [SelectList](./types.md#selectlist)[] | Selectable options. Supports a flat array of options or a nested array of {label, list} groups |
4839
5050
  | `maxHeight` | no | string \| number | Max height of multi-select container (CSS value) |
4840
5051
  | `maxTruncationLines` | no | number | Max rows of chips visible before "+X" overflow chip appears (multi-select only) |
4841
- | `options` | no | [SelectOption](./types.md#selectoption)[] | Array of option objects with label, value, and optional metadata |
5052
+ | `options` | no | [SelectOption](./types.md#selectoption)[] \| [SelectOption](./types.md#selectoption)[] | Deprecated alias for list. Use list for new specs |
4842
5053
  | `placeholder` | no | string | Placeholder text when empty |
4843
5054
  | `placement` | no | [AppGroupSelectPlacement](./definitions.md#appgroupselectplacement) | Dropdown position relative to input. Default: bottom-start |
4844
5055
  | `rows` | no | number | Minimum number of rows to show |
@@ -4858,7 +5069,7 @@ No additional properties.
4858
5069
 
4859
5070
  A card-based selection input that renders a group of selectable cards for single or multi-choice picking. Use when users need to choose from a small set of visually rich options displayed as cards (e.g. plans, locations, tiers). Use Radio for simple text-only single choice, or Select for long option lists in a dropdown.
4860
5071
 
4861
- onChange stores a single value when isMulti is false, or an array of values when isMulti is true. The list prop must be an array of objects; each object should have a key matching valueIdentifier (default "value") for unique identification, plus title and content keys for BASIC_CARD renderer display. LOCATION_CARD renderer is for location/address-type items. This component does not accept children — use a layout wrapper (VStack) to place multiple SelectableGroup elements together.
5072
+ onChange stores a single value when isMulti is false, or an array of values when isMulti is true. The list prop must be an array of objects; each object should have a key matching valueIdentifier (default "value") for unique identification, plus title and content keys for BASIC_CARD renderer display. renderer is a JSON-only constrained rendering model that chooses between the built-in BASIC_CARD and LOCATION_CARD renderers because the React renderer function prop is not serializable. testId is a deprecated testing-only prop kept only for backward compatibility. This component does not accept children — use a layout wrapper (VStack) to place multiple SelectableGroup elements together.
4862
5073
 
4863
5074
  Catalog key: `SelectableGroup`
4864
5075
  Builder: `SelectableGroup`
@@ -4878,13 +5089,14 @@ Events: `change`
4878
5089
  | `defaultValue` | no | string \| number \| string \| number[] | Initial selection when uncontrolled |
4879
5090
  | `id` | no | string | Unique DOM id for the input element |
4880
5091
  | `isDisabled` | no | boolean | Disables all items in the group |
5092
+ | `isInvalid` | no | boolean | Shows invalid styling on the group |
4881
5093
  | `isMulti` | no | boolean | Allow multiple selection. Default: false |
4882
5094
  | `isReadOnly` | no | boolean | Makes the group read-only |
4883
5095
  | `isRequired` | no | boolean | Marks as required. In multi-select, prevents deselecting the last item |
4884
5096
  | `label` | no | string | Label text above the input |
4885
5097
  | `list` | yes | [SelectableGroupList](./types.md#selectablegrouplist)[] | Array of item objects to render as selectable cards |
4886
- | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | Card renderer type: BASIC_CARD or LOCATION_CARD |
4887
- | `testId` | no | string | Test identifier for automated testing |
5098
+ | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | JSON-only constrained renderer choice: BASIC_CARD or LOCATION_CARD |
5099
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
4888
5100
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4889
5101
  | `value` | no | string \| number \| string \| number[] | Selected value(s). Single value when isMulti is false, array when true |
4890
5102
  | `valueIdentifier` | no | string | Key name to extract unique value from each list item. Default: "value" |
@@ -4993,6 +5205,7 @@ Events: `change`
4993
5205
  | `defaultValue` | no | string | Initial default signature value |
4994
5206
  | `id` | no | string | Unique DOM element ID |
4995
5207
  | `isDisabled` | no | boolean | Disables the signature input |
5208
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4996
5209
  | `isReadOnly` | no | boolean | Shows signature image only, no input |
4997
5210
  | `isRequired` | no | boolean | Marks the field as required |
4998
5211
  | `isTypeSignatureDisabled` | no | boolean | Only show draw input, hide type input. Default: false |
@@ -5026,10 +5239,12 @@ Events: `change`, `blur`
5026
5239
  | `autoComplete` | no | string | Browser autocomplete hint. Default: off |
5027
5240
  | `autoFocus` | no | boolean | Auto-focus input on mount |
5028
5241
  | `checks` | no | [SinCheck](./types.md#sincheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5242
+ | `defaultValue` | no | string | Initial unmasked SIN value |
5029
5243
  | `fixedCharsPrefix` | no | string | Fixes characters at the beginning of the value |
5030
5244
  | `fixedCharsSuffix` | no | string | Fixes characters at the end of the value |
5031
5245
  | `id` | no | string | Explicit HTML element id |
5032
5246
  | `isDisabled` | no | boolean | Disables the input |
5247
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5033
5248
  | `isReadOnly` | no | boolean | Makes the input read-only |
5034
5249
  | `isRequired` | no | boolean | Marks the field as required |
5035
5250
  | `label` | no | string | Label text above the input |
@@ -5049,7 +5264,7 @@ No additional properties.
5049
5264
 
5050
5265
  An animated placeholder that mimics the shape of content while it loads, available in text (lines), circle, and box variants.
5051
5266
 
5052
- Variant determines which size props apply: TEXT uses width/lines/gap/lineHeight, CIRCLE uses size, BOX uses width/height/borderRadius. For TEXT variant, lineHeight should be provided (e.g. "1.5em", "20px") to ensure proper height - without it the skeleton will have 0 height and be invisible. Skipped: typestyle (complex theme Typestyle object — use gap and lineHeight directly instead).
5267
+ Variant determines which size props apply: text uses width/lines/gap/lineHeight, circle uses size, box uses width/height/borderRadius. For the text variant, gap accepts Pebble spacing tokens, numbers, or CSS strings. For text, lineHeight should be provided (e.g. "1.5em", "20px") to ensure proper height - without it the skeleton will have 0 height and be invisible. Skipped: typestyle (complex theme Typestyle object — use gap and lineHeight directly instead).
5053
5268
 
5054
5269
  Catalog key: `Skeleton`
5055
5270
  Builder: `Skeleton`
@@ -5061,16 +5276,16 @@ Events: _none_
5061
5276
 
5062
5277
  | Name | Required | Type | Description |
5063
5278
  |---|---:|---|---|
5064
- | `animation` | no | [SkeletonAnimation](./definitions.md#skeletonanimation) | Loading animation style. Default: WAVE |
5279
+ | `animation` | no | [SkeletonAnimation](./definitions.md#skeletonanimation) | Loading animation style. Default: wave |
5065
5280
  | `borderRadius` | no | [BoxRadius](./definitions.md#boxradius) | Border radius token (BOX variant) |
5066
- | `gap` | no | [BoxGap](./definitions.md#boxgap) | Gap between lines when lines > 1 (TEXT variant). Spacing token. Default: 4px |
5067
- | `height` | no | number | Height in px (BOX variant) |
5281
+ | `gap` | no | [BoxGap](./definitions.md#boxgap) \| string \| number | Gap between lines when lines > 1 (TEXT variant). Spacing token, CSS string, or number. Default: 4px |
5282
+ | `height` | no | number \| string | Height in px or CSS string (BOX variant) |
5068
5283
  | `initialTimestamp` | no | number | Initial mount timestamp for animation delay calculation. Used to coordinate animations across multiple skeletons. Default: Date.now() |
5069
5284
  | `lineHeight` | no | string \| number | Line height of text skeleton for pixel-perfect match (TEXT variant). Default: 15px |
5070
5285
  | `lines` | no | number | Number of text lines (TEXT variant). Default: 1 |
5071
5286
  | `show` | no | boolean | Whether the skeleton is loading. true renders the skeleton, false renders nothing. Default: true |
5072
- | `size` | no | number | Diameter in px (CIRCLE variant). Default: 40 |
5073
- | `variant` | no | [SkeletonVariant](./definitions.md#skeletonvariant) | Skeleton shape variant. Default: TEXT |
5287
+ | `size` | no | number \| string | Diameter in px or CSS string (CIRCLE variant). Default: 40 |
5288
+ | `variant` | no | [SkeletonVariant](./definitions.md#skeletonvariant) | Skeleton shape variant. Default: text |
5074
5289
  | `width` | no | string \| number | Width of the skeleton (number in px or CSS string) |
5075
5290
 
5076
5291
  No additional properties.
@@ -5264,10 +5479,12 @@ Events: `change`, `blur`
5264
5479
  | `autoComplete` | no | string | Browser autocomplete hint. Default: off |
5265
5480
  | `autoFocus` | no | boolean | Auto-focus input on mount |
5266
5481
  | `checks` | no | [SsnCheck](./types.md#ssncheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5482
+ | `defaultValue` | no | string | Initial unmasked SSN value |
5267
5483
  | `fixedCharsPrefix` | no | string | Fixes characters at the beginning of the value |
5268
5484
  | `fixedCharsSuffix` | no | string | Fixes characters at the end of the value |
5269
5485
  | `id` | no | string | Explicit HTML element id |
5270
5486
  | `isDisabled` | no | boolean | Disables the input |
5487
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5271
5488
  | `isReadOnly` | no | boolean | Makes the input read-only |
5272
5489
  | `isRequired` | no | boolean | Marks the field as required |
5273
5490
  | `label` | no | string | Label text above the input |
@@ -5301,8 +5518,7 @@ Events: _none_
5301
5518
  |---|---:|---|---|
5302
5519
  | `appearance` | yes | [StatusAppearance](./definitions.md#statusappearance) | Semantic appearance: PRIMARY/TERTIARY for neutral information, SUCCESS for positive outcomes, ERROR for failures or critical issues, WARNING for preemptive alerts, DISABLED for inactive or non-current states. |
5303
5520
  | `outlined` | no | boolean | When true, renders status with a border outline. Default: false |
5304
- | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the status indicator (S, M, L, XL). Default: L |
5305
- | `testId` | no | string | Test identifier for automated testing. Default: status |
5521
+ | `size` | no | [StatusSize](./definitions.md#statussize) | Size of the status indicator (S, M, L, XL). Default: L |
5306
5522
  | `text` | yes | string | Text label to display in the status indicator. Required. |
5307
5523
 
5308
5524
  No additional properties.
@@ -5356,8 +5572,7 @@ Events: `press`
5356
5572
  | `icon` | no | string | Icon type from Icon.TYPES. Default: HEADPHONES_FILLED |
5357
5573
  | `id` | no | string | DOM id selector for the button element |
5358
5574
  | `image` | no | string | Image URL displayed instead of an icon in the avatar |
5359
- | `imageBackground` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Surface color token for the avatar when using an image |
5360
- | `testId` | no | string | Sets data-testid attribute. Default: test_support_button |
5575
+ | `imageBackground` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Surface color token for the avatar when using an image |
5361
5576
  | `title` | yes | string | Primary text label displayed on the button |
5362
5577
  | `to` | no | string \| [SupportButtonTo](./types.md#supportbuttonto) | Navigation destination. When provided, button handles navigation automatically |
5363
5578
 
@@ -5367,7 +5582,7 @@ No additional properties.
5367
5582
 
5368
5583
  A button-group input for collecting ratings or opinions on a Likert scale (e.g. 1–5 or 1–10). Renders each option as a clickable button with optional range labels for the endpoints. Supports single or multi-select. Use for satisfaction surveys, NPS scores, or opinion scales. Use Radio for mutually exclusive text choices, SegmentedControl for toggling between named options, or Slider for continuous numeric ranges.
5369
5584
 
5370
- onChange stores a single value when isMulti is false, or an array of values when isMulti is true. The list prop must be an array of objects with value (required) and label (optional) keys. Use rangeLabels to add descriptive labels for the lowest and highest options.
5585
+ onChange stores a single value when isMulti is false, or an array of values when isMulti is true. Use defaultValue for uncontrolled initial selection. The list prop must be an array of objects with value (required) and label (optional) keys; icon and selectionColor are also supported per item. Use rangeLabels to add descriptive labels for the lowest and highest options.
5371
5586
 
5372
5587
  Catalog key: `Survey`
5373
5588
  Builder: `Survey`
@@ -5382,7 +5597,9 @@ Events: `change`
5382
5597
  | `name` | no | string | Unique identifier for the input |
5383
5598
  | `caption` | no | string | Caption text displayed below the survey |
5384
5599
  | `checks` | no | [SurveyCheck](./types.md#surveycheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5600
+ | `defaultValue` | no | string \| number \| string \| number[] | Initial selected value(s) when uncontrolled |
5385
5601
  | `isDisabled` | no | boolean | Disables all survey buttons |
5602
+ | `isInvalid` | no | boolean | Marks the survey as invalid |
5386
5603
  | `isMulti` | no | boolean | Allow multiple selections. Default: false |
5387
5604
  | `isReadOnly` | no | boolean | Makes the survey read-only |
5388
5605
  | `isRequired` | no | boolean | Marks the field as required |
@@ -5425,7 +5642,7 @@ Events: `change`, `blur`
5425
5642
  | `offLabel` | no | string | Label text when switch is off |
5426
5643
  | `onLabel` | no | string | Label text when switch is on |
5427
5644
  | `rightAlign` | no | boolean | Align switch to the right |
5428
- | `tip` | no | string | Tooltip text to display |
5645
+ | `tip` | no | string \| [SwitchTip](./types.md#switchtip) | Tooltip text or basic tooltip configuration to display |
5429
5646
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5430
5647
  | `value` | no | boolean | Toggle state bound to state |
5431
5648
 
@@ -5435,7 +5652,7 @@ No additional properties.
5435
5652
 
5436
5653
  Labeled controls for alternating between related views within the same page or context. Use to organize groups of related content at the same hierarchy level; for selection within a single view, use a segmented control instead.
5437
5654
 
5438
- Use for view switching and entry path selection. Tab content is managed separately via conditional rendering based on the selected value in state. Type options: BASIC (standard tabs), SWITCH (toggle-style), LINK (navigation-style), SWITCH_WITH_ICON_ONLY (icon-only toggles). Tab items can include icon, badge, tip, and disabled props. onChange stores the selected tab value in state.
5655
+ Use for view switching and entry path selection. Provide `list` to mirror the React LINK-tab list branch, or `items` for the JSON-only selection model that writes `value` metadata to bound state. `activeIndex` mirrors the React controlled selection prop; when `items` are used, `value` remains available as JSON-only state metadata. Type options: BASIC (standard tabs), SWITCH (toggle-style), LINK (navigation-style), SWITCH_WITH_ICON_ONLY (icon-only toggles). Item entries use the React `title` and `isDisabled` prop names. onChange stores the selected tab value in state when `items` are used.
5439
5656
 
5440
5657
  Catalog key: `Tab`
5441
5658
  Builder: `Tab`
@@ -5447,24 +5664,25 @@ Events: `change`
5447
5664
 
5448
5665
  | Name | Required | Type | Description |
5449
5666
  |---|---:|---|---|
5667
+ | `activeIndex` | no | number | Controlled active tab index |
5450
5668
  | `aria-label` | no | string | Accessible label for the tabs |
5451
5669
  | `aria-labelledby` | no | string | ID of element that labels the tabs |
5452
5670
  | `defaultActiveIndex` | no | number | Tab index to be active by default |
5453
5671
  | `isCompact` | no | boolean | Use compact spacing |
5454
5672
  | `isLogoRound` | no | boolean | Whether to display logo with rounded corners |
5455
5673
  | `isVertical` | no | boolean | Display tabs in vertical orientation (only for LINK type) |
5456
- | `items` | yes | [TabItem](./types.md#tabitem)[] | Array of tab items with label, value, and optional icon/badge/tip |
5674
+ | `items` | no | [TabItem](./types.md#tabitem)[] | JSON-only selection model for state-bound tabs with title, value, and optional icon/badge/tip |
5675
+ | `list` | no | [TabList](./types.md#tablist)[] | React Tabs list branch for LINK tabs, including optional nested links |
5457
5676
  | `logoUrl` | no | string | URL of logo image to display with title |
5458
5677
  | `stretchH` | no | boolean | Stretch tabs horizontally |
5459
5678
  | `stretchV` | no | boolean | Stretch tabs vertically to fill available height |
5460
5679
  | `subtitle` | no | string | Subtitle text |
5461
- | `supportLink` | no | string | URL for support/help link |
5462
- | `testId` | no | string | Test ID for the tabs container |
5680
+ | `supportLink` | no | string \| [SupportLink](./types.md#supportlink) | Support/help link as a URL string or a serializable object branch |
5463
5681
  | `theme` | no | [TabTheme](./definitions.md#tabtheme) | Visual theme: BOX, BOX_HEADER, CENTER, GREY_OVERFLOW_GRADIENT, WHITE_OVERFLOW_GRADIENT, NO_PADDING |
5464
5682
  | `title` | no | string | Title text to display above tabs |
5465
5683
  | `titleContent` | no | string | Subtitle or additional content below the title |
5466
5684
  | `type` | no | [TabType](./definitions.md#tabtype) | Visual style: BASIC, SWITCH, LINK, or SWITCH_WITH_ICON_ONLY |
5467
- | `value` | no | unknown | Currently selected tab value bound to state |
5685
+ | `value` | no | unknown | JSON-only selected tab value metadata bound to state when using items |
5468
5686
  | `width` | no | number | Width of the tab container in pixels |
5469
5687
 
5470
5688
  No additional properties.
@@ -5473,7 +5691,7 @@ No additional properties.
5473
5691
 
5474
5692
  A read-only data table for displaying moderately large amounts of information in rows and columns. Use for structured, text-based data that benefits from systematic organization and easy scanning. For sorting, filtering, or cell-level interaction, use Grid instead; for simple vertical lists without column headings, use ListItem.
5475
5693
 
5476
- Data-driven table: columns define headers and keys, rows are objects keyed by column key. Cell values are rendered as text. Use align on columns to control text alignment. Set wrapText on columns to wrap long text. Use rowHeight to customize row heights.
5694
+ TableBasic does not mirror the React children API in SDUI. Instead, use the documented JSON-only columns/rows table abstraction: columns define headers and keys, and rows are objects keyed by column key. Cell values are rendered as text. Use align on columns to control text alignment. Set wrapText on columns to wrap long text. Use rowHeight to customize row heights.
5477
5695
 
5478
5696
  Catalog key: `TableBasic`
5479
5697
  Builder: `TableBasic`
@@ -5485,9 +5703,9 @@ Events: _none_
5485
5703
 
5486
5704
  | Name | Required | Type | Description |
5487
5705
  |---|---:|---|---|
5488
- | `columns` | yes | [Column](./types.md#column)[] | Column definitions: {header, key, align?, width?, wrapText?} |
5706
+ | `columns` | yes | [Column](./types.md#column)[] | JSON-only table abstraction: column definitions {header, key, align?, width?, wrapText?} |
5489
5707
  | `rowHeight` | no | number | Custom height in px for all table rows |
5490
- | `rows` | yes | [Row](./types.md#row)[] | Array of row objects keyed by column key |
5708
+ | `rows` | yes | [Row](./types.md#row)[] | JSON-only table abstraction: row objects keyed by column key |
5491
5709
  | `title` | no | string | Title displayed above the table |
5492
5710
  | `width` | no | number | Table container width in px |
5493
5711
 
@@ -5525,13 +5743,13 @@ No additional properties.
5525
5743
 
5526
5744
  A multi-line text input for entering longer free-form text such as comments, descriptions, or paragraphs. Use TextInput instead for short single-line entries.
5527
5745
 
5528
- onChange stores the text content as a plain string in state. Set hasCharsLimit with maxLength to display a character counter. Use theme="NO_BOX" for a borderless variant. Standalone — does not register with Form; use FormTextarea inside a Form instead.
5746
+ onChange stores the text content as a plain string in state. onKeyDown emits "keydown" without the DOM event payload. Set hasCharsLimit with maxLength to display a character counter. Use theme="NO_BOX" for a borderless variant. Standalone — does not register with Form; use FormTextarea inside a Form instead.
5529
5747
 
5530
5748
  Catalog key: `Textarea`
5531
5749
  Builder: `Textarea`
5532
5750
  Props type: `TextareaProps`
5533
5751
  Accepts children: no
5534
- Events: `change`, `blur`, `focus`
5752
+ Events: `change`, `blur`, `focus`, `keydown`
5535
5753
 
5536
5754
  ### Props
5537
5755
 
@@ -5548,6 +5766,7 @@ Events: `change`, `blur`, `focus`
5548
5766
  | `height` | no | number | Fixed height in pixels |
5549
5767
  | `id` | no | string | Unique DOM id for the textarea element |
5550
5768
  | `isDisabled` | no | boolean | Disables the input |
5769
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5551
5770
  | `isReadOnly` | no | boolean | Makes the input read-only |
5552
5771
  | `isRequired` | no | boolean | Marks the field as required |
5553
5772
  | `label` | no | string | Label text above the input |
@@ -5555,7 +5774,7 @@ Events: `change`, `blur`, `focus`
5555
5774
  | `maxLength` | no | number | Maximum character count. Default: 10000 |
5556
5775
  | `placeholder` | no | string | Placeholder text when empty |
5557
5776
  | `rows` | no | number | Number of visible text rows |
5558
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Visual theme variant |
5777
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant |
5559
5778
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5560
5779
  | `value` | no | string | Current text value bound to state |
5561
5780
 
@@ -5565,13 +5784,14 @@ No additional properties.
5565
5784
 
5566
5785
  An autocomplete input that offers text suggestions in a dropdown menu as the user types. Unlike Select, users can either manually type free-form text or pick from the suggestions list.
5567
5786
 
5568
- For dynamic suggestions from an API: bind suggestions to state, then on "change" event fetch results and write to that state path
5787
+ For dynamic suggestions from an API: bind list to state, then on "change" event fetch results and write to that state path
5569
5788
  Emits "change" on every keystroke and when a suggestion is selected, allowing you to filter/fetch suggestions as user types
5570
5789
  When user selects a suggestion from the dropdown, the value is updated to the selected option's value
5571
5790
  Use prefix/suffix for icons or text - pass Icon.TYPES names like "SEARCH_OUTLINE" or text like "@"
5572
5791
  Use inputMode to hint the virtual keyboard type on mobile devices
5573
5792
  Use stringPadding to automatically pad values (e.g., "1" → "001" with {position: "start", maxLength: 3, character: "0"})
5574
5793
  ARIA attributes support accessibility - use aria-label, aria-labelledby, or aria-describedby for screen reader labels
5794
+ Use defaultValue for uncontrolled initial content, and fuseOptions to customize Fuse.js matching.
5575
5795
  Standalone — does not register with Form; use FormTextAutoSuggest inside a Form instead.
5576
5796
 
5577
5797
  Catalog key: `TextAutoSuggest`
@@ -5593,6 +5813,8 @@ Events: `change`, `blur`, `focus`, `click`
5593
5813
  | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
5594
5814
  | `autoFocus` | no | boolean | Auto-focus on mount |
5595
5815
  | `checks` | no | [TextAutoSuggestCheck](./types.md#textautosuggestcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5816
+ | `defaultValue` | no | string \| number | Initial value when uncontrolled |
5817
+ | `fuseOptions` | no | [TextAutoSuggestFuseOption](./types.md#textautosuggestfuseoption) | Fuse.js search options for customizing suggestion filtering |
5596
5818
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
5597
5819
  | `isDisabled` | no | boolean | Disables the input |
5598
5820
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
@@ -5600,6 +5822,7 @@ Events: `change`, `blur`, `focus`, `click`
5600
5822
  | `isReadOnly` | no | boolean | Makes the input read-only |
5601
5823
  | `isRequired` | no | boolean | Marks the field as required |
5602
5824
  | `label` | no | string | Label text above the input |
5825
+ | `list` | no | [TextAutoSuggestList](./types.md#textautosuggestlist)[] | Array of { label, value } suggestion objects matching the React list prop |
5603
5826
  | `maxLength` | no | number | Maximum character count |
5604
5827
  | `maxWidth` | no | string | Maximum width CSS value |
5605
5828
  | `minLength` | no | number | Minimum character count |
@@ -5617,8 +5840,6 @@ Events: `change`, `blur`, `focus`, `click`
5617
5840
  | `spellCheck` | no | boolean | Enable spell checking |
5618
5841
  | `stringPadding` | no | [TextAutoSuggestStringPadding](./types.md#textautosuggeststringpadding) | Pads input value with character until reaching maxLength |
5619
5842
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
5620
- | `suggestions` | no | [TextAutoSuggestSuggestion](./types.md#textautosuggestsuggestion)[] | Array of { label, value } suggestion objects |
5621
- | `testId` | no | string | Test ID for automation |
5622
5843
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
5623
5844
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5624
5845
  | `value` | no | string \| number | Current value bound to state |
@@ -5641,8 +5862,7 @@ Events: _none_
5641
5862
 
5642
5863
  | Name | Required | Type | Description |
5643
5864
  |---|---:|---|---|
5644
- | `collapseLabel` | no | string | Label for the collapse button. Default: Show less |
5645
- | `expandLabel` | no | string | Label for the expand button. Default: Show more |
5865
+ | `buttonLabels` | no | [ButtonLabel](./types.md#buttonlabel) | Labels for the expand and collapse buttons |
5646
5866
  | `maxHeight` | yes | number | Max height in px before content is clipped and expand/collapse is shown |
5647
5867
  | `theme` | no | [TextClipTheme](./definitions.md#textcliptheme) | Visual theme variant. NO_CARD removes the card styling |
5648
5868
 
@@ -5691,6 +5911,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
5691
5911
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
5692
5912
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
5693
5913
  | `isDisabled` | no | boolean | Disables the input |
5914
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5694
5915
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
5695
5916
  | `isReadOnly` | no | boolean | Makes the input read-only |
5696
5917
  | `isRequired` | no | boolean | Marks the field as required |
@@ -5711,7 +5932,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
5711
5932
  | `spellCheck` | no | boolean | Enable spell checking |
5712
5933
  | `stringPadding` | no | [TextInputStringPadding](./types.md#textinputstringpadding) | Pads input value with character until reaching maxLength |
5713
5934
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
5714
- | `testId` | no | string | Test ID for automation |
5715
5935
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
5716
5936
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5717
5937
  | `value` | no | string | Current text value bound to state |
@@ -5746,13 +5966,13 @@ No additional properties.
5746
5966
 
5747
5967
  A form input for entering or selecting a specific time of day. Supports typed entry, optional dropdown time selection, timezone display, and locale-aware formatting.
5748
5968
 
5749
- onChange stores a time string in state. The format depends on shouldReturnISO — when true, an ISO 8601 string is stored; otherwise the component returns the value as-is. Use timezone to display the time relative to a specific IANA timezone. Standalone — does not register with Form; use FormTime inside a Form instead.
5969
+ onChange stores a time string in state. The format depends on shouldReturnISO — when true, an ISO 8601 string is stored; otherwise the component returns the value as-is. Use defaultValue for uncontrolled initial state. Use timezone to display the time relative to a specific IANA timezone or to configure the built-in timezone selector. inferredTimeChange writes inferredTime metadata before emitting. Standalone — does not register with Form; use FormTime inside a Form instead.
5750
5970
 
5751
5971
  Catalog key: `Time`
5752
5972
  Builder: `Time`
5753
5973
  Props type: `TimeProps`
5754
5974
  Accepts children: no
5755
- Events: `change`, `blur`
5975
+ Events: `change`, `blur`, `inferredTimeChange`
5756
5976
 
5757
5977
  ### Props
5758
5978
 
@@ -5765,8 +5985,12 @@ Events: `change`, `blur`
5765
5985
  | `aria-labelledby` | no | string | ARIA labelledby reference for accessibility |
5766
5986
  | `checks` | no | [TimeCheck](./types.md#timecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5767
5987
  | `defaultSelectionStartTime` | no | string | Time to start the selection scroll from when shouldAllowTimeSelection is true (e.g. "08:00 AM") |
5988
+ | `defaultValue` | no | string | Initial time value when uncontrolled |
5989
+ | `id` | no | string | HTML id attribute for the input |
5990
+ | `inferredTime` | no | string | JSON-only inferred time metadata written before inferredTimeChange emits |
5768
5991
  | `isDateTimeInline` | no | boolean | Make input inline, removes border, padding and width fits input/placeholder content |
5769
5992
  | `isDisabled` | no | boolean | Disables the input |
5993
+ | `isInvalid` | no | boolean | Marks the input as invalid |
5770
5994
  | `isReadOnly` | no | boolean | Makes the input read-only |
5771
5995
  | `isRequired` | no | boolean | Marks the field as required |
5772
5996
  | `label` | no | string | Label text above the input |
@@ -5774,7 +5998,7 @@ Events: `change`, `blur`
5774
5998
  | `maxWidth` | no | string | Maximum width CSS value |
5775
5999
  | `pickClosestMeridiem` | no | boolean | When user does not enter AM/PM, pick the closest meridiem to the inputted hour value. Default: false |
5776
6000
  | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
5777
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times |
6001
+ | `shouldAllowTimeSelection` | no | boolean \| [TimeShouldAllowTimeSelection](./types.md#timeshouldallowtimeselection) | Show a time selection dropdown for picking times |
5778
6002
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time input |
5779
6003
  | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly |
5780
6004
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
@@ -5782,7 +6006,7 @@ Events: `change`, `blur`
5782
6006
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
5783
6007
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
5784
6008
  | `theme` | no | string | Custom theme to apply to the input |
5785
- | `timezone` | no | string | Show time relative to this timezone (IANA identifier) |
6009
+ | `timezone` | no | string \| [TimeTimezone](./types.md#timetimezone) | Show time relative to this timezone or configure the timezone selector |
5786
6010
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5787
6011
  | `value` | no | string | Time value bound to state (ISO 8601 or HH:mm format) |
5788
6012
 
@@ -5815,13 +6039,15 @@ Events: `change`, `blur`
5815
6039
  | `defaultValue` | no | unknown[] | Initial time range when uncontrolled [startTime, endTime] |
5816
6040
  | `hideDayDifference` | no | boolean | Hides the next day indicator when end time is on the next day. Default: false (indicator is shown) |
5817
6041
  | `hideTimeIcon` | no | boolean | Hides the prefix clock icon in the input. Default: false |
6042
+ | `id` | no | string | HTML id attribute for the input |
5818
6043
  | `isDisabled` | no | boolean | Disables the input |
6044
+ | `isInvalid` | no | boolean | Marks the input as invalid |
5819
6045
  | `isReadOnly` | no | boolean | Makes the input read-only |
5820
6046
  | `isRequired` | no | boolean | Marks the field as required |
5821
6047
  | `label` | no | string | Label text above the input |
5822
6048
  | `locale` | no | string | Locale string for time formatting (e.g. en-US) |
5823
6049
  | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
5824
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times. Default: true |
6050
+ | `shouldAllowTimeSelection` | no | boolean \| [TimeRangeShouldAllowTimeSelection](./types.md#timerangeshouldallowtimeselection) | Show a time selection dropdown for picking times. Default: true |
5825
6051
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time inputs |
5826
6052
  | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly. Default: true |
5827
6053
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
@@ -5857,6 +6083,7 @@ Events: `change`, `blur`, `focus`
5857
6083
  | `dropdownHeight` | no | number | Height of the dropdown menu in pixels |
5858
6084
  | `emptyListPlaceholder` | no | string | Placeholder text shown when no timezone matches the search |
5859
6085
  | `isDisabled` | no | boolean | Disables the input |
6086
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5860
6087
  | `isMenuDefaultOpen` | no | boolean | If true, the dropdown menu will be open by default on mount |
5861
6088
  | `isPositionFixed` | no | boolean | Use fixed positioning for dropdown (useful in scrollable containers) |
5862
6089
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -5912,13 +6139,13 @@ No additional properties.
5912
6139
 
5913
6140
  A compact title-and-caption pair for displaying a primary label with an optional secondary descriptor, such as a person's name with their job title or a heading with a subtitle.
5914
6141
 
5915
- TitleCaption renders a title with an optional caption below it. Use captionColor to override the caption text color with a Pebble text/icon color token. The component automatically shows a tooltip when text overflows.
6142
+ TitleCaption renders a title with an optional caption below it. Use captionColor to override the caption text color with a Pebble text/icon color token. When clicked, it emits "press". The component automatically shows a tooltip when text overflows.
5916
6143
 
5917
6144
  Catalog key: `TitleCaption`
5918
6145
  Builder: `TitleCaption`
5919
6146
  Props type: `TitleCaptionProps`
5920
6147
  Accepts children: no
5921
- Events: _none_
6148
+ Events: `press`
5922
6149
 
5923
6150
  ### Props
5924
6151
 
@@ -5934,13 +6161,13 @@ No additional properties.
5934
6161
 
5935
6162
  A chevron arrow indicator that toggles between down (collapsed) and up (expanded) directions. Use as a standalone expand/collapse affordance, such as in custom collapsible sections or tree nodes.
5936
6163
 
5937
- ToggleableArrow wraps Atoms.ToggleableArrow from Pebble. It renders a chevron icon that visually toggles between pointing down (collapsed) and up (expanded). Use isArrowDown to control the direction. When used without onChange, the component manages its own toggle state on click. Supply arrowDownColor and arrowUpColor to customize the icon color per state. Use horizontalCollapsedPosition to show the arrow horizontally when collapsed.
6164
+ ToggleableArrow wraps Atoms.ToggleableArrow from Pebble. It renders a chevron icon that visually toggles between pointing down (collapsed) and up (expanded). Bind isArrowDown to state to observe and control the current direction. onChange writes the toggled boolean to the isArrowDown binding before emitting "change". Supply arrowDownColor and arrowUpColor to customize the icon color per state. Use horizontalCollapsedPosition to show the arrow horizontally when collapsed.
5938
6165
 
5939
6166
  Catalog key: `ToggleableArrow`
5940
6167
  Builder: `ToggleableArrow`
5941
6168
  Props type: `ToggleableArrowProps`
5942
6169
  Accepts children: no
5943
- Events: _none_
6170
+ Events: `change`
5944
6171
 
5945
6172
  ### Props
5946
6173
 
@@ -5965,7 +6192,7 @@ No additional properties.
5965
6192
 
5966
6193
  A hierarchical selector for choosing from a tree-structured list of parent-child relationships with expand/collapse navigation. Use for selecting from deeply nested data like org structures, file systems, directories, or classification hierarchies.
5967
6194
 
5968
- onChange stores a single value string when isMulti is false, or an array of value strings when isMulti is true. The list prop must be a flat array where each item has a value (unique ID) and parent (parent value or null for root). The tree builds its hierarchy from these parent references. When footer is provided, clicking the footer button emits footerAction event. Use aria-* props for accessibility labeling.
6195
+ onChange stores a single value string when isMulti is false, or an array of value strings when isMulti is true. Use defaultValue for uncontrolled initial selection. The list prop must be a flat array where each item has a value (unique ID) and parent (parent value or null for root); set isLeaf when a node should be treated as terminal. The tree builds its hierarchy from these parent references. When footer is provided, clicking the footer button emits footerAction event. Use aria-* props for accessibility labeling.
5969
6196
 
5970
6197
  Catalog key: `Tree`
5971
6198
  Builder: `Tree`
@@ -5983,6 +6210,7 @@ Events: `change`, `footerAction`
5983
6210
  | `aria-labelledby` | no | string | ID of element that labels this tree |
5984
6211
  | `canSelectAll` | no | boolean | Show select all toggle in multi mode |
5985
6212
  | `checks` | no | [TreeCheck](./types.md#treecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
6213
+ | `defaultValue` | no | string \| string[] | Initial selected value(s) when uncontrolled |
5986
6214
  | `dropdownWidth` | no | number | Override internal dropdown width in pixels |
5987
6215
  | `emptyListPlaceholder` | no | string | Placeholder text when list is empty |
5988
6216
  | `footer` | no | [TreeFooter](./types.md#treefooter) | Fixed footer with clickable action at bottom of tree |
@@ -6012,7 +6240,7 @@ No additional properties.
6012
6240
 
6013
6241
  A dropdown select component with a hierarchical tree structure for choosing from nested parent-child options. Use when users need to pick from deeply nested data like org structures, file systems, or classification hierarchies, but the tree should stay collapsed behind a dropdown trigger. Use Tree instead when the hierarchy should be visible at all times.
6014
6242
 
6015
- onChange stores a single value string when isMulti is false, or an array of value strings when isMulti is true. The list prop must be a flat array where each item has a value (unique ID) and parent (parent value or null for root). Unlike Tree, TreeSelect renders as a dropdown trigger with search built in.
6243
+ onChange stores a single value string when isMulti is false, or an array of value strings when isMulti is true. The list prop must be a flat array where each item has a value (unique ID) and parent (parent value or null for root); set isLeaf when a node should be treated as terminal. Unlike Tree, TreeSelect renders as a dropdown trigger with search built in.
6016
6244
 
6017
6245
  Catalog key: `TreeSelect`
6018
6246
  Builder: `TreeSelect`
@@ -6055,7 +6283,7 @@ Events: `change`
6055
6283
  | `shouldShowFolderStructure` | no | boolean | Renders folder structure view |
6056
6284
  | `shouldShowSelectionPath` | no | boolean | Show parent-to-child path in selected chips. Default: false |
6057
6285
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size. Default: M |
6058
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Custom theme styling |
6286
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Custom theme styling |
6059
6287
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
6060
6288
  | `value` | no | string \| string[] \| null | Selected value(s). Single string when isMulti is false, array when true |
6061
6289
 
@@ -6101,7 +6329,7 @@ Events: _none_
6101
6329
  |---|---:|---|---|
6102
6330
  | `align` | no | [HStackAlign](./definitions.md#hstackalign) | Cross-axis alignment |
6103
6331
  | `alignSelf` | no | [HStackAlignSelf](./definitions.md#hstackalignself) | Align self override when inside a flex parent |
6104
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
6332
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
6105
6333
  | `basis` | no | number \| string | Flex basis value |
6106
6334
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | Box sizing model |
6107
6335
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Text/icon color token |
@@ -6157,9 +6385,10 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
6157
6385
  | `autoFocus` | no | boolean | Auto-focus on mount |
6158
6386
  | `checks` | no | [WorkEmailCheck](./types.md#workemailcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
6159
6387
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
6160
- | `domainList` | no | unknown | Email domain list for selection. Can be: single string, array of strings ["acme.com"], array of {label, value, tag?} objects (FlatList), or array of {label, list} objects (NestedList) for grouped domains |
6388
+ | `domainList` | no | string \| string[] \| [WorkEmailDomainList](./types.md#workemaildomainlist)[] \| [WorkEmailDomainList](./types.md#workemaildomainlist)[] | Email domain list for selection. Can be: single string, array of strings ["acme.com"], array of {label, value, tag?} objects (FlatList), or array of {label, list} objects (NestedList) for grouped domains |
6161
6389
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
6162
6390
  | `isDisabled` | no | boolean | Disables the input |
6391
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
6163
6392
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
6164
6393
  | `isReadOnly` | no | boolean | Makes the input read-only |
6165
6394
  | `isRequired` | no | boolean | Marks the field as required |
@@ -6178,7 +6407,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
6178
6407
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
6179
6408
  | `spellCheck` | no | boolean | Enable spell checking |
6180
6409
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
6181
- | `testId` | no | string | Test ID for automation |
6182
6410
  | `theme` | no | string | Theme name from Input.WorkEmail.THEMES or custom theme |
6183
6411
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
6184
6412
  | `value` | no | string | Current work email value bound to state |