@rippling/pebble-sdui-web 0.8.0 → 0.9.1

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 (49) hide show
  1. package/dist/catalogs/custom-apps/action-params.d.ts +4 -0
  2. package/dist/catalogs/custom-apps/actions.d.ts +2 -1
  3. package/dist/catalogs/custom-apps/catalog.d.ts +2 -2
  4. package/dist/catalogs/custom-apps/component-events.d.ts +16 -14
  5. package/dist/catalogs/custom-apps/component-props.d.ts +1041 -260
  6. package/dist/catalogs/custom-apps/components.d.ts +5 -3
  7. package/dist/catalogs/custom-apps/index.cjs +4 -2
  8. package/dist/catalogs/custom-apps/index.cjs.map +1 -1
  9. package/dist/catalogs/custom-apps/index.d.ts +5 -5
  10. package/dist/catalogs/custom-apps/index.js +5983 -1661
  11. package/dist/catalogs/custom-apps/index.js.map +1 -1
  12. package/dist/catalogs/hub_platform/catalog.d.ts +1 -1
  13. package/dist/catalogs/hub_platform/component-props.d.ts +14 -6
  14. package/dist/catalogs/hub_platform/index.cjs +1 -1
  15. package/dist/catalogs/hub_platform/index.cjs.map +1 -1
  16. package/dist/catalogs/hub_platform/index.d.ts +1 -1
  17. package/dist/catalogs/hub_platform/index.js +86 -137
  18. package/dist/catalogs/hub_platform/index.js.map +1 -1
  19. package/dist/core/catalog-validation.cjs +2 -0
  20. package/dist/core/catalog-validation.cjs.map +1 -0
  21. package/dist/core/catalog-validation.d.ts +21 -0
  22. package/dist/core/catalog-validation.js +245 -0
  23. package/dist/core/catalog-validation.js.map +1 -0
  24. package/dist/core/directives.cjs +2 -0
  25. package/dist/core/directives.cjs.map +1 -0
  26. package/dist/core/directives.d.ts +72 -0
  27. package/dist/core/directives.js +35 -0
  28. package/dist/core/directives.js.map +1 -0
  29. package/dist/core/expressions.d.ts +5 -15
  30. package/dist/core/index.cjs +1 -1
  31. package/dist/core/index.d.ts +2 -0
  32. package/dist/core/index.js +28 -20
  33. package/dist/core/index.js.map +1 -1
  34. package/dist/docs/typescript/web/catalogs/custom-apps/actions.md +31 -2
  35. package/dist/docs/typescript/web/catalogs/custom-apps/components.md +468 -291
  36. package/dist/docs/typescript/web/catalogs/custom-apps/definitions.md +250 -288
  37. package/dist/docs/typescript/web/catalogs/custom-apps/readme.md +1 -1
  38. package/dist/docs/typescript/web/catalogs/custom-apps/types.md +1362 -148
  39. package/dist/docs/typescript/web/catalogs/hub_platform/components.md +1 -1
  40. package/dist/docs/typescript/web/catalogs/hub_platform/types.md +14 -0
  41. package/dist/index.cjs +1 -1
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +25 -17
  44. package/dist/index.js.map +1 -1
  45. package/dist/sdk-docs.cjs +208 -1
  46. package/dist/sdk-docs.cjs.map +1 -1
  47. package/dist/sdk-docs.js +213 -0
  48. package/dist/sdk-docs.js.map +1 -1
  49. package/package.json +1 -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) \| [AppGroupSelectListVariant2](./types.md#appgroupselectlistvariant2)[] | 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
 
@@ -379,12 +366,16 @@ Box is a flexible layout container built on CSS flexbox. It provides extensive s
379
366
  - Colors (backgroundColor, color)
380
367
  - Border radius (uniform or per-corner)
381
368
  - Dimension props support both number (pixels) and string (CSS) values
369
+ - containerType can define the Box as a CSS query container
382
370
 
383
371
  **Complex prop formats:**
384
372
  - padding/margin/gap/radius: Use strict spacing or radius token names, or object forms with token values
385
373
  - border: Can be string or object with top/right/bottom/left
386
374
  - Number values on dimension props automatically get 'px' suffix
387
375
 
376
+ **Native props:**
377
+ - Supports id, role, aria-label, aria-labelledby, aria-describedby, aria-hidden, and aria-disabled
378
+
388
379
  Catalog key: `Box`
389
380
  Builder: `Box`
390
381
  Props type: `BoxProps`
@@ -397,7 +388,12 @@ Events: _none_
397
388
  |---|---:|---|---|
398
389
  | `align` | no | string | Align items on cross axis. CSS align-items value (e.g., "center", "flex-start") |
399
390
  | `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 |
391
+ | `aria-describedby` | no | string | ID of element that describes this Box |
392
+ | `aria-disabled` | no | boolean | Marks this Box as disabled for assistive technology |
393
+ | `aria-hidden` | no | boolean | Hide this Box from assistive technology |
394
+ | `aria-label` | no | string | Accessible label |
395
+ | `aria-labelledby` | no | string | ID of element that labels this Box |
396
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
401
397
  | `basis` | no | number \| string | Flex basis value. Number (pixels) or CSS string |
402
398
  | `border` | no | string \| [BoxBorder](./types.md#boxborder) \| [BoxBorder](./types.md#boxborder) | Border value. CSS string, strict token parts, or directional border object |
403
399
  | `boxSizing` | no | string | CSS box-sizing value. "content-box" or "border-box". Default: content-box |
@@ -405,6 +401,7 @@ Events: _none_
405
401
  | `child` | no | boolean | Whether this Box is a flex child. Changes display to initial |
406
402
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Text/icon color token |
407
403
  | `container` | no | boolean \| string | Container query target. true for unnamed container, string for named container. Used with changeDirectionAbove |
404
+ | `containerType` | no | string | CSS container-type value. Defines the element as a query container |
408
405
  | `direction` | no | string | Flex direction. CSS flex-direction value (e.g., "row", "column") |
409
406
  | `flex` | no | string | CSS flex shorthand (e.g., "1", "0 1 auto") |
410
407
  | `gap` | no | [BoxGap](./definitions.md#boxgap) \| [BoxGap](./types.md#boxgap) | Gap between flex children. Spacing token or {row, column} spacing-token object |
@@ -469,9 +466,13 @@ Events: `select`
469
466
  | Name | Required | Type | Description |
470
467
  |---|---:|---|---|
471
468
  | `active` | no | string | Value of the active breadcrumb item. Default: last item |
469
+ | `aria-describedby` | no | string | ID of element that describes the breadcrumb nav |
470
+ | `aria-label` | no | string | Accessible label for the breadcrumb nav |
471
+ | `aria-labelledby` | no | string | ID of element that labels the breadcrumb nav |
472
472
  | `items` | yes | [BreadcrumbItem](./types.md#breadcrumbitem)[] | Array of breadcrumb items: {title, value, isDisabled?, href?} |
473
473
  | `noMargin` | no | boolean | Remove default margin from the component. Default: false |
474
474
  | `shouldCollapseMiddle` | no | boolean | Collapse middle items into a dropdown on desktop. Default: false |
475
+ | `shouldTruncateItems` | no | boolean | Truncate breadcrumb item text to one line at 128px and show full text in a tooltip on overflow. Default: false |
475
476
 
476
477
  No additional properties.
477
478
 
@@ -542,7 +543,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
542
543
  | `shouldShowSpinner` | no | boolean | Show loading spinner explicitly. Default: false |
543
544
  | `size` | no | [ButtonSize](./definitions.md#buttonsize) | Button size. Default: M |
544
545
  | `tabIndex` | no | number | Tab order index for keyboard navigation |
545
- | `testId` | no | string | Sets data-testid attribute. Default: "test_button" |
546
546
  | `tip` | no | string \| [ButtonTip](./types.md#buttontip) | Tooltip configuration. Can be simple string content or object with appearance/placement |
547
547
  | `to` | no | string \| [ButtonTo](./types.md#buttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
548
548
  | `type` | no | [ButtonType](./definitions.md#buttontype) | HTML button type attribute. Default: button |
@@ -578,27 +578,29 @@ No additional properties.
578
578
 
579
579
  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
580
 
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).
581
+ 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
582
 
583
583
  Catalog key: `Calendar`
584
584
  Builder: `Calendar`
585
585
  Props type: `CalendarProps`
586
586
  Accepts children: no
587
- Events: `click`, `clear`
587
+ Events: `click`, `clear`, `confirmMobile`
588
588
 
589
589
  ### Props
590
590
 
591
591
  | Name | Required | Type | Description |
592
592
  |---|---:|---|---|
593
+ | `displayDate` | no | string | Month to show initially as an ISO date string |
593
594
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
594
595
  | `isDisabled` | no | boolean | Disables the calendar |
595
596
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
597
+ | `locale` | no | string | Locale string used to determine the start of week |
596
598
  | `maxDate` | no | string | Latest selectable date as ISO string |
597
599
  | `minDate` | no | string | Earliest selectable date as ISO string |
598
600
  | `shouldShowFooter` | no | boolean | Controls footer visibility. Default: true |
599
601
  | `shouldShowHeader` | no | boolean \| [ShouldShowHeader](./types.md#shouldshowheader) | Controls header visibility. Default: true |
600
602
  | `shouldShowWeekDayInitials` | no | boolean | If false, hides week day initials. Default: true |
601
- | `testId` | no | string | Data test id for testing purposes |
603
+ | `showMonthYearPicker` | no | boolean | Show month and year picker in the calendar header. Default: false |
602
604
  | `value` | no | string \| string[] | Selected date(s) as ISO string(s). Single date or array for multi-select |
603
605
 
604
606
  No additional properties.
@@ -607,7 +609,7 @@ No additional properties.
607
609
 
608
610
  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
611
 
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.
612
+ 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
613
 
612
614
  Catalog key: `Card`
613
615
  Builder: `Card`
@@ -625,9 +627,11 @@ Events: `edit`, `delete`, `add`, `click`, `action`
625
627
  | `isAddCard` | no | boolean | Render as add card with plus icon. Emits "add" event when clicked. Default: false |
626
628
  | `isDisabled` | no | boolean | Whether the card is disabled. Default: false |
627
629
  | `minCardHeight` | no | number | Minimum height of card in pixels. Default: 150 |
630
+ | `padding` | no | 0 \| 8 \| 16 \| 24 \| 32 \| string | Padding for layout mode. Supports Card.Layout PADDINGS values or CSS string |
628
631
  | `selectedActionId` | no | string | Bound state path for the selected action id. Written before "action" event fires |
629
632
  | `showDelete` | no | boolean | Show delete button. Emits "delete" event when clicked. Default: false |
630
633
  | `showEdit` | no | boolean | Show edit button. Emits "edit" event when clicked. Default: false |
634
+ | `theme` | no | [CardTheme](./definitions.md#cardtheme) | Visual theme for layout mode. DEFAULT or SELECTABLE |
631
635
  | `title` | no | string | Card header title text |
632
636
  | `to` | no | string \| [CardTo](./types.md#cardto) | Route destination. String URL or object with {path, openInNewTab}. Card renders as anchor when provided |
633
637
  | `value` | no | unknown | Identifier value for the card, passed to event handlers |
@@ -737,7 +741,7 @@ No additional properties.
737
741
 
738
742
  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
743
 
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.
744
+ 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
745
 
742
746
  Catalog key: `CheckboxGroup`
743
747
  Builder: `CheckboxGroup`
@@ -761,7 +765,7 @@ Events: `change`, `blur`
761
765
  | `isReadOnly` | no | boolean | Makes the checkbox group read-only (displays as chips) |
762
766
  | `isRequired` | no | boolean | Marks the field as required |
763
767
  | `label` | no | string | Label text above the checkbox group |
764
- | `options` | no | [CheckboxGroupOption](./types.md#checkboxgroupoption)[] | Array of { label, value } checkbox option objects |
768
+ | `list` | no | [CheckboxGroupList](./types.md#checkboxgrouplist)[] | Array of { label, value } checkbox option objects |
765
769
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
766
770
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
767
771
  | `value` | no | unknown[] | Currently selected values bound to state |
@@ -836,11 +840,11 @@ Events: `dismiss`, `press`
836
840
  | `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
841
  | `icon` | no | string \| [ChipIcon](./types.md#chipicon) | Icon to display. Can be string name or object with type/color/alignment |
838
842
  | `isActive` | no | boolean | If true, applies active/selected styling (used inside SelectableGroup) |
843
+ | `isCloseable` | no | boolean | Shows close button when true. Default: false |
839
844
  | `isDisabled` | no | boolean | If true, the chip is visually and functionally disabled |
840
- | `isDismissible` | no | boolean | Shows close button when true. Default: false |
841
845
  | `isFluid` | no | boolean | If true, the chip takes all available width. Default: false |
842
846
  | `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 |
847
+ | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the chip (SMALL, MEDIUM, LARGE, EXTRA_LARGE). Default: LARGE |
844
848
  | `text` | no | string | Text content to display in the chip |
845
849
  | `tip` | no | [ChipTip](./types.md#chiptip) | Tooltip configuration. Chip has default overflow tooltip behavior |
846
850
  | `to` | no | string \| [ChipTo](./types.md#chipto) | Navigation destination. Renders chip as anchor with router integration. Use for guaranteed navigation |
@@ -856,10 +860,10 @@ A layout container for grouping multiple Chip components (tags, filters, attribu
856
860
  **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
861
 
858
862
  **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.
863
+ - overflowChange: Emitted when the overflow modal opens or closes. The overflowModalIsOpen state (boolean) is written before the event fires.
860
864
 
861
865
  **State shape:**
862
- - onOverflowModalStateChange writes a boolean to state (true when modal opens, false when closes)
866
+ - onOverflowModalStateChange writes a boolean to overflowModalIsOpen (true when modal opens, false when closes)
863
867
 
864
868
  **Children:** Should contain Chip components.
865
869
 
@@ -876,8 +880,8 @@ Events: `overflowChange`
876
880
  | `batchSize` | no | number | Number of elements rendered in each incremental step, optimizing performance for large datasets |
877
881
  | `gap` | no | [BoxGap](./definitions.md#boxgap) | Spacing token for the flex gap between chip items. Default: theme default spacing |
878
882
  | `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 |
883
+ | `overflowModalIsOpen` | no | boolean | Bindable state value written when the overflow modal opens or closes. True when open, false when closed |
879
884
  | `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
885
 
882
886
  No additional properties.
883
887
 
@@ -938,48 +942,6 @@ Events: `change`, `blur`
938
942
 
939
943
  No additional properties.
940
944
 
941
- ## Comments
942
-
943
- Comments surface for a product object or a set of product threads. Supports single-thread and multithread comment chains.
944
-
945
- For single-thread comments, pass productName and productId.
946
- For multithreaded comments, pass productName and a non-empty productThreads array. Each thread must include productId.
947
- Callback props are exposed as events. Use statePaths when the spec needs the callback payload written to SDUI state before the event handler runs.
948
-
949
- Catalog key: `Comments`
950
- Builder: `Comments`
951
- Props type: `CommentsProps`
952
- Accepts children: no
953
- Events: `commentChainCreation`, `commentAddition`, `commentEdit`, `commentRemoval`
954
-
955
- ### Props
956
-
957
- | Name | Required | Type | Description |
958
- |---|---:|---|---|
959
- | `commentsOrder` | no | [CommentsCommentsOrder](./definitions.md#commentscommentsorder) | Order in which comments render. Defaults to NEWEST_FIRST. |
960
- | `dataTestId` | no | string | Test id on the comments root. |
961
- | `enableReactions` | no | boolean | When true, enables platform comment reactions. |
962
- | `groupId` | no | string | Groups related comment chains. |
963
- | `headerText` | no | string | Optional string header. Defaults to the translated Comments label. |
964
- | `hideNewCommentEditor` | no | boolean | When true, hides the new-comment editor. |
965
- | `maxHeight` | no | string \| number | Maximum height for the scrollable comments container. |
966
- | `productId` | no | string | Product object id for single-thread comments. Required unless productThreads is provided. |
967
- | `productMetadata` | no | [ProductMetadata](./types.md#productmetadata) | Product metadata for a single comment chain. |
968
- | `productName` | yes | string | Product name used to identify the comment chain. |
969
- | `productSubCategory` | no | string | Optional product subcategory. |
970
- | `productThreads` | no | [ProductThread](./types.md#productthread)[] | Non-empty thread list for multithreaded comments. When provided, renders the multithread view. |
971
- | `readOnly` | no | boolean | When true, hides editing controls and shows a read-only badge. |
972
- | `requestOptions` | no | [RequestOption](./types.md#requestoption) | Request options passed to the comments API calls. |
973
- | `rumExcluded` | no | boolean | When true, excludes initial API calls from RUM metrics. |
974
- | `scrollToTop` | no | boolean | When true, scrolls the top comment into view after load. |
975
- | `showHeaderText` | no | boolean | When false, hides the comments header. |
976
- | `showInlineAttachments` | no | boolean | When false, hides the inline attachment affordance. |
977
- | `showUnreadCountBadge` | no | boolean | When false, hides the unread-count badge in the header. |
978
- | `statePaths` | no | [StatePath](./types.md#statepath) | Optional state paths written before emitting comment events. |
979
- | `theme` | no | [CommentsTheme](./definitions.md#commentstheme) | Visual theme override for embedding comments in tight layouts. |
980
-
981
- No additional properties.
982
-
983
945
  ## ContentLoader
984
946
 
985
947
  A low-level SVG shimmer placeholder used to indicate loading state. Renders a plain animated rectangle whose dimensions you control. For shaped placeholders (text lines, circles, boxes), use Skeleton instead.
@@ -997,7 +959,7 @@ Events: _none_
997
959
  | Name | Required | Type | Description |
998
960
  |---|---:|---|---|
999
961
  | `animate` | no | boolean | Enable animation. Default: true |
1000
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token. Default: #f5f6f7 |
962
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token. Default: #f5f6f7 |
1001
963
  | `backgroundOpacity` | no | number | Opacity of background color. Default: 1 |
1002
964
  | `foregroundColor` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Foreground shimmer color token. Default: #eee |
1003
965
  | `foregroundOpacity` | no | number | Opacity of foreground shimmer. Default: 1 |
@@ -1035,7 +997,7 @@ No additional properties.
1035
997
 
1036
998
  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.
1037
999
 
1038
- 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.
1000
+ 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.
1039
1001
 
1040
1002
  Catalog key: `Country`
1041
1003
  Builder: `Country`
@@ -1048,11 +1010,11 @@ Events: _none_
1048
1010
  | Name | Required | Type | Description |
1049
1011
  |---|---:|---|---|
1050
1012
  | `countryCode` | yes | string | ISO country code (e.g. "US", "IN", "GB"). Used to display the country flag and name. |
1051
- | `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. |
1013
+ | `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. |
1052
1014
  | `onlyFlag` | no | boolean | When true, shows only the flag without rendering the country name. Default: false |
1053
1015
  | `shouldShowFlag` | no | boolean | When false, hides the country flag and shows only the country name. Default: true |
1054
1016
  | `shouldShowTipOnOverflow` | no | boolean | When false, disables the tooltip that appears when the country name overflows. Default: true |
1055
- | `size` | no | [CountrySize](./definitions.md#countrysize) | Size of the country flag. "S" = small, "M" = medium, "L" = large. Default: "L" |
1017
+ | `size` | no | [AiIconSize](./definitions.md#aiiconsize) | Size of the country flag. SMALL, MEDIUM, or LARGE. Default: LARGE |
1056
1018
 
1057
1019
  No additional properties.
1058
1020
 
@@ -1060,7 +1022,7 @@ No additional properties.
1060
1022
 
1061
1023
  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.
1062
1024
 
1063
- 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.
1025
+ 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.
1064
1026
 
1065
1027
  Catalog key: `Currency`
1066
1028
  Builder: `Currency`
@@ -1081,10 +1043,9 @@ Events: `change`, `blur`
1081
1043
  | `autoFocus` | no | boolean | If true, input will be focused on mount |
1082
1044
  | `canSelectCurrencyType` | no | boolean | If true, displays a dropdown to select currency type |
1083
1045
  | `checks` | no | [CurrencyCheck](./types.md#currencycheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1084
- | `currencyType` | no | string | Currency code for the selector when canSelectCurrencyType is true (e.g. USD, EUR) |
1085
- | `currencyTypeDefaultValue` | no | string | Default currency code for uncontrolled selector. Default: USD |
1046
+ | `currencyTypeProps` | no | [CurrencyCurrencyTypeProp](./types.md#currencycurrencytypeprop) | Nested Select props for the currency selector |
1086
1047
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
1087
- | `defaultValue` | no | string \| number | Initial value for uncontrolled component |
1048
+ | `defaultValue` | no | string \| number \| [CurrencyDefaultValue](./types.md#currencydefaultvalue) | Initial value for uncontrolled component. Use { value, type } with shouldSendCurrencyType |
1088
1049
  | `isDisabled` | no | boolean | Disables the input |
1089
1050
  | `isIntegerOnly` | no | boolean | If true, only integer values will be allowed. Default: false |
1090
1051
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -1101,10 +1062,31 @@ Events: `change`, `blur`
1101
1062
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates equation on blur |
1102
1063
  | `shouldDisableRedundantZeroFormatting` | no | boolean | If false, redundant zeros are removed using parseFloat. If true (default), zeros are preserved. Default: true |
1103
1064
  | `shouldLocalize` | no | boolean | If true, currency format is determined from user locale setting. Default: true |
1065
+ | `shouldSendCurrencyType` | no | boolean | If true, onChange writes { value, type } using currencyTypeProps value/defaultValue |
1104
1066
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1105
1067
  | `step` | no | number | Value to add/subtract on pressing arrow up/down respectively. Default: 1 |
1106
1068
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1107
- | `value` | no | string \| number | Current currency value bound to state |
1069
+ | `value` | no | string \| number \| [CurrencyValue](./types.md#currencyvalue) | Current currency value bound to state. Use { value, type } with shouldSendCurrencyType |
1070
+
1071
+ No additional properties.
1072
+
1073
+ ## Dashboard
1074
+
1075
+ Embeds a saved Rippling Analytics dashboard by id. Loading, permissions, missing-dashboard, and widget behavior are handled by the dashboard viewer.
1076
+
1077
+ dashboardId: id of the saved Analytics dashboard. The dashboard loads its own data and handles loading, access, missing, and widget states.
1078
+
1079
+ Catalog key: `Dashboard`
1080
+ Builder: `Dashboard`
1081
+ Props type: `DashboardProps`
1082
+ Accepts children: no
1083
+ Events: _none_
1084
+
1085
+ ### Props
1086
+
1087
+ | Name | Required | Type | Description |
1088
+ |---|---:|---|---|
1089
+ | `dashboardId` | yes | string | Id of a saved Rippling Analytics dashboard. The dashboard loads its own data and handles loading, access, missing, and widget behavior. |
1108
1090
 
1109
1091
  No additional properties.
1110
1092
 
@@ -1112,7 +1094,7 @@ No additional properties.
1112
1094
 
1113
1095
  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.
1114
1096
 
1115
- 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.
1097
+ 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.
1116
1098
 
1117
1099
  Catalog key: `Date`
1118
1100
  Builder: `Date`
@@ -1131,6 +1113,7 @@ Events: `change`, `blur`
1131
1113
  | `aria-labelledby` | no | string | ID of element that labels this input |
1132
1114
  | `canClear` | no | boolean | Show clear button |
1133
1115
  | `checks` | no | [DateCheck](./types.md#datecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1116
+ | `defaultValue` | no | string | Initial ISO date string or null for uncontrolled usage |
1134
1117
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1135
1118
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1136
1119
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
@@ -1151,10 +1134,11 @@ Events: `change`, `blur`
1151
1134
  | `shouldShowTime` | no | boolean | Include time selection |
1152
1135
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
1153
1136
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1137
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1154
1138
  | `timeProps` | no | [TimeProp](./types.md#timeprop) | Configuration for time picker. Sets initial time value independently of date input |
1155
1139
  | `timezone` | no | string | Timezone name (e.g. "America/New_York"). Used with shouldShowTime |
1156
1140
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1157
- | `value` | no | string | ISO date string bound to state |
1141
+ | `value` | no | string | ISO date string or null bound to state |
1158
1142
 
1159
1143
  No additional properties.
1160
1144
 
@@ -1162,7 +1146,7 @@ No additional properties.
1162
1146
 
1163
1147
  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.
1164
1148
 
1165
- 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.
1149
+ 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.
1166
1150
 
1167
1151
  Catalog key: `DateInlineMulti`
1168
1152
  Builder: `DateInlineMulti`
@@ -1176,6 +1160,7 @@ Events: `change`, `blur`
1176
1160
  |---|---:|---|---|
1177
1161
  | `name` | no | string | Unique identifier for the input |
1178
1162
  | `checks` | no | [DateInlineMultiCheck](./types.md#dateinlinemulticheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1163
+ | `defaultValue` | no | string[] | Initial array of selected ISO 8601 date strings |
1179
1164
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: yyyy-MM-dd |
1180
1165
  | `isDisabled` | no | boolean | Disables the calendar |
1181
1166
  | `isReadOnly` | no | boolean | Makes the calendar read-only |
@@ -1185,7 +1170,7 @@ Events: `change`, `blur`
1185
1170
  | `maxDate` | no | string | Latest selectable date as ISO string |
1186
1171
  | `minDate` | no | string | Earliest selectable date as ISO string |
1187
1172
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1188
- | `value` | no | string[] | Array of selected ISO 8601 date strings bound to state |
1173
+ | `value` | no | string[] | Array of selected ISO 8601 date strings or null bound to state |
1189
1174
 
1190
1175
  No additional properties.
1191
1176
 
@@ -1193,7 +1178,7 @@ No additional properties.
1193
1178
 
1194
1179
  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.
1195
1180
 
1196
- 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.
1181
+ 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.
1197
1182
 
1198
1183
  Catalog key: `DateRange`
1199
1184
  Builder: `DateRange`
@@ -1212,10 +1197,12 @@ Events: `change`, `blur`
1212
1197
  | `aria-labelledby` | no | string | ID of element that labels the date range picker |
1213
1198
  | `canClear` | no | boolean | Show clear button |
1214
1199
  | `checks` | no | [DateRangeCheck](./types.md#daterangecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
1200
+ | `defaultValue` | no | string[] | Initial null or array of ISO date strings/null entries [start, end] |
1215
1201
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1216
1202
  | `endDateLabel` | no | string | Label for the end date field |
1217
1203
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1218
1204
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
1205
+ | `id` | no | string | HTML id attribute for the date range input |
1219
1206
  | `isCalendarDefaultOpen` | no | boolean | If true, calendar will be open by default on mount |
1220
1207
  | `isDisabled` | no | boolean | Disables the date range picker |
1221
1208
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
@@ -1232,9 +1219,10 @@ Events: `change`, `blur`
1232
1219
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
1233
1220
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1234
1221
  | `startDateLabel` | no | string | Label for the start date field |
1222
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1235
1223
  | `timezone` | no | string | Timezone for date/time display and storage. Used with shouldShowTime |
1236
1224
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1237
- | `value` | no | string[] | Array of two ISO date strings [start, end] |
1225
+ | `value` | no | string[] | Null or array of ISO date strings/null entries [start, end] bound to state |
1238
1226
 
1239
1227
  No additional properties.
1240
1228
 
@@ -1261,7 +1249,7 @@ Events: `change`
1261
1249
  | `isReadOnly` | no | boolean | Makes the input read-only |
1262
1250
  | `isRequired` | no | boolean | Marks the field as required |
1263
1251
  | `label` | no | string | Label text above the input |
1264
- | `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) |
1252
+ | `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) |
1265
1253
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1266
1254
  | `value` | no | [DaySelectorDefaultValue](./definitions.md#dayselectordefaultvalue) \| [DaySelectorDefaultValue](./definitions.md#dayselectordefaultvalue)[] | Selected day(s). Single string when isMulti is false, array when true |
1267
1255
 
@@ -1313,7 +1301,7 @@ No additional properties.
1313
1301
 
1314
1302
  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.
1315
1303
 
1316
- 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.
1304
+ 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.
1317
1305
 
1318
1306
  Catalog key: `DraggableList`
1319
1307
  Builder: `DraggableList`
@@ -1334,6 +1322,7 @@ Events: `update`, `remove`, `dragStart`, `dragEnd`
1334
1322
  | `limitDragToDragIcon` | no | boolean | Restrict dragging to only the drag icon. Only works when showDragIcon is true. Default: false |
1335
1323
  | `list` | yes | [DraggableListList](./types.md#draggablelistlist)[] | Array of draggable items. Each item must have an id (string or number). Additional keys are allowed. |
1336
1324
  | `showDragIcon` | no | boolean | Show drag icon for each item. Default: false |
1325
+ | `tip` | no | [DraggableListTip](./types.md#draggablelisttip) | Tooltip configuration for the default chip renderer |
1337
1326
  | `width` | no | string | Width of the list. Default: 100% |
1338
1327
 
1339
1328
  No additional properties.
@@ -1363,7 +1352,7 @@ Events: `close`
1363
1352
  | `shouldCloseOnEscape` | no | boolean | Close drawer on ESC key press |
1364
1353
  | `shouldNotAnimate` | no | boolean | Disables open/close animations. Default: false |
1365
1354
  | `theme` | no | [DrawerTheme](./definitions.md#drawertheme) | Visual style theme for the drawer |
1366
- | `title` | no | string | Title text displayed in the drawer header |
1355
+ | `title` | no | string \| [Title](./types.md#title) | Title displayed in the drawer header as text or breadcrumb config |
1367
1356
  | `width` | no | string \| number | Width of the drawer. Default: 80vw |
1368
1357
 
1369
1358
  No additional properties.
@@ -1372,29 +1361,32 @@ No additional properties.
1372
1361
 
1373
1362
  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.
1374
1363
 
1375
- 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.
1364
+ 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. Set showSelectedLabel to true to display the selected option label in the trigger; empty and unmatched values fall back to triggerLabel.
1376
1365
 
1377
1366
  Catalog key: `Dropdown`
1378
1367
  Builder: `Dropdown`
1379
1368
  Props type: `DropdownProps`
1380
1369
  Accepts children: no
1381
- Events: `change`
1370
+ Events: `change`, `toggle`
1382
1371
 
1383
1372
  ### Props
1384
1373
 
1385
1374
  | Name | Required | Type | Description |
1386
1375
  |---|---:|---|---|
1387
- | `defaultValue` | no | string | Initially selected value |
1376
+ | `defaultValue` | no | unknown | Initially selected value |
1377
+ | `dropdownIsOpen` | no | boolean | Bindable state written when the dropdown opens or closes |
1378
+ | `footer` | no | [DropdownFooter](./types.md#dropdownfooter) | Footer item rendered at the bottom of the list |
1388
1379
  | `isCompact` | no | boolean | Render in compact mode |
1389
1380
  | `isDisabled` | no | boolean | Disable the dropdown trigger |
1390
- | `list` | yes | [DropdownList2](./types.md#dropdownlist2)[] | Array of dropdown options: {label, value, isDisabled?} |
1381
+ | `list` | yes | [DropdownList2](./types.md#dropdownlist2) \| [DropdownListVariant2](./types.md#dropdownlistvariant2) \| [ListVariant3](./types.md#listvariant3)[] | Array of dropdown options: {label, value, isDisabled?} |
1391
1382
  | `maxHeight` | no | number | Max height of the dropdown list in px. Default: 224 |
1392
1383
  | `placement` | no | [DropdownPlacement](./definitions.md#dropdownplacement) | Popover position. Default: bottom-start |
1393
1384
  | `searchable` | no | boolean | Enable search within the dropdown list |
1394
1385
  | `shouldAutoClose` | no | boolean | Auto-close after item selection |
1395
1386
  | `shouldCloseOnScroll` | no | boolean | Close on document scroll |
1387
+ | `showSelectedLabel` | no | boolean | Display the selected option label in the trigger. Defaults to false; empty or unmatched values use triggerLabel |
1396
1388
  | `triggerLabel` | yes | string | Label for the dropdown trigger button |
1397
- | `value` | no | string | Currently selected value. Bind to state for selection tracking |
1389
+ | `value` | no | unknown | Currently selected value. Bind to state for selection tracking |
1398
1390
  | `width` | no | number | Width of the dropdown list in px. Default: 192 |
1399
1391
 
1400
1392
  No additional properties.
@@ -1450,8 +1442,8 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
1450
1442
  | `shrinkToValue` | no | boolean | Input spans as much as its value when true. Only applies when value is present |
1451
1443
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1452
1444
  | `spellCheck` | no | boolean | Enable spell checking |
1445
+ | `stringPadding` | no | [EmailStringPadding](./types.md#emailstringpadding) | Pads input value with character until reaching maxLength |
1453
1446
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
1454
- | `testId` | no | string | Test ID for automation |
1455
1447
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
1456
1448
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1457
1449
  | `value` | no | string | Current email value bound to state |
@@ -1462,7 +1454,7 @@ No additional properties.
1462
1454
 
1463
1455
  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.
1464
1456
 
1465
- 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.
1457
+ 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.
1466
1458
 
1467
1459
  Catalog key: `EmojiPicker`
1468
1460
  Builder: `EmojiPicker`
@@ -1476,24 +1468,25 @@ Events: `change`
1476
1468
  |---|---:|---|---|
1477
1469
  | `autoFocus` | no | boolean | If true, automatically focuses the search input. Default: false |
1478
1470
  | `categories` | no | [EmojiPickerCategories](./definitions.md#emojipickercategories)[] | Array of emoji categories to display |
1471
+ | `excludeIds` | no | string[] | Emoji IDs to hide from the picker |
1479
1472
  | `fluid` | no | boolean | If true, makes width 100% of container. Default: false |
1480
1473
  | `height` | no | string | Height CSS value of the emoji picker |
1481
1474
  | `inline` | no | boolean | If true, renders the emoji picker inline. Default: false |
1482
1475
  | `minHeight` | no | string | Minimum height CSS value of the emoji picker |
1483
1476
  | `minWidth` | no | string | Minimum width CSS value of the emoji picker |
1484
- | `testId` | no | string | Data test id for testing purposes |
1477
+ | `popperProps` | no | [PopperProp](./types.md#popperprop) | Serializable popover options; middleware functions are not supported |
1478
+ | `preventCloseOnSelect` | no | boolean | Prevents the popover from closing when an emoji is selected |
1479
+ | `selectedEmoji` | no | [SelectedEmoji](./types.md#selectedemoji) | Bindable selected emoji data written before the change event emits |
1480
+ | `triggerIcon` | no | string | Icon.TYPES name to render as the default popover trigger |
1485
1481
  | `width` | no | string | Width CSS value of the emoji picker |
1486
1482
 
1487
1483
  No additional properties.
1488
1484
 
1489
1485
  ## EmployeeSearch
1490
1486
 
1491
- Employee search input powered by a backend role search API. Supports single and multi-select modes with type-ahead search. Use for any field that picks one or more employees.
1487
+ 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.
1492
1488
 
1493
- The component hits a backend role search API on each keystroke (or on mount when enableEmptySearch is true). Results are cached per search term for the session.
1494
- For large employee lists, set isInfiniteScroll: true and enableEmptySearch: true so the dropdown pre-populates without requiring the user to type first.
1495
- value supports $bindState for two-way binding. On change, value is set to the selected role id (string) or ids (string[]) and onChange fires.
1496
- defaultValue is the uncontrolled initial value; value is the controlled prop. Do not mix both — use one or the other.
1489
+ 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.
1497
1490
 
1498
1491
  Catalog key: `EmployeeSearch`
1499
1492
  Builder: `EmployeeSearch`
@@ -1505,24 +1498,19 @@ Events: `change`
1505
1498
 
1506
1499
  | Name | Required | Type | Description |
1507
1500
  |---|---:|---|---|
1508
- | `name` | no | string | Form field name. Defaults to "role". |
1509
- | `canClear` | no | boolean | When true, shows a clear button to reset the selection. |
1510
- | `defaultValue` | no | string \| string[] | Initial uncontrolled value — a role id (string) or array of role ids. |
1511
- | `enableEmptySearch` | no | boolean | When true and isInfiniteScroll is true, loads an initial list without requiring a search query. |
1512
- | `helperMessage` | no | string | Helper message displayed below the input. |
1513
- | `isDisabled` | no | boolean | When true, disables the input. |
1514
- | `isInfiniteScroll` | no | boolean | When true, uses paginated backend search. Recommended for large employee lists. |
1515
- | `isMulti` | no | boolean | When true, allows selecting multiple employees. |
1516
- | `isRequired` | no | boolean | Marks the field as required in a form context. |
1517
- | `nullPlaceholder` | no | string | Placeholder text displayed when no value is selected (distinct from the search placeholder). |
1518
- | `placeholder` | no | string | Placeholder text shown inside the input when empty. |
1519
- | `roleIdsToIgnore` | no | string[] | Role ids to exclude from search results. |
1520
- | `roleIdsToInclude` | no | string[] | When set, only these role ids appear in results. |
1521
- | `roleTypes` | no | [EmployeeSearchRoleTypes](./definitions.md#employeesearchroletypes)[] | Filters employees by role type. Defaults to ["ACCEPTED_AND_ACTIVE"]. |
1522
- | `shouldShowSearchIcon` | no | boolean | When true, renders a search icon inside the input. |
1523
- | `tip` | no | string | Helper tip text displayed below the title. |
1524
- | `title` | no | string | Label displayed above the search input. |
1525
- | `value` | no | string \| string[] | Controlled value — a role id (string) or array of role ids. Use $bindState for two-way binding. |
1501
+ | `canClear` | no | boolean | Controls whether the current selection can be cleared. When omitted, the underlying select default applies. |
1502
+ | `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. |
1503
+ | `isDisabled` | no | boolean | When true, disables searching and selection changes. Defaults to false. |
1504
+ | `isMulti` | no | boolean | When true, allows multiple employee selections and uses role id arrays. Defaults to false (single select). |
1505
+ | `isReadOnly` | no | boolean | When true, displays the selection without allowing changes. Defaults to false. |
1506
+ | `isRequired` | no | boolean | When true, marks the field as required. Defaults to the form control default (not required). |
1507
+ | `label` | no | string | Label displayed for the search field. Defaults to no label. |
1508
+ | `placeholder` | no | string | Placeholder displayed when the search field is empty. When omitted, the component default placeholder is used. |
1509
+ | `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. |
1510
+ | `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. |
1511
+ | `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. |
1512
+ | `tip` | no | string | Supplementary tip displayed with the label. Defaults to no tip. |
1513
+ | `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. |
1526
1514
 
1527
1515
  No additional properties.
1528
1516
 
@@ -1564,6 +1552,7 @@ Events: `toggle`
1564
1552
  | `shouldNotUnmountChild` | no | boolean | Keep child mounted when collapsed. Default: false |
1565
1553
  | `theme` | no | [ExpansionPanelTheme](./definitions.md#expansionpaneltheme) | Visual style variant |
1566
1554
  | `title` | yes | string | Header text displayed in the expansion panel |
1555
+ | `toggleIcon` | no | [ExpansionPanelToggleIcon](./types.md#expansionpaneltoggleicon) | Toggle icon layout options |
1567
1556
 
1568
1557
  No additional properties.
1569
1558
 
@@ -1618,19 +1607,24 @@ No additional properties.
1618
1607
 
1619
1608
  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.
1620
1609
 
1621
- 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.
1610
+ 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.
1622
1611
 
1623
1612
  Catalog key: `File`
1624
1613
  Builder: `File`
1625
1614
  Props type: `FileProps`
1626
1615
  Accepts children: no
1627
- Events: `change`, `delete`
1616
+ Events: `change`, `delete`, `chipClick`
1628
1617
 
1629
1618
  ### Props
1630
1619
 
1631
1620
  | Name | Required | Type | Description |
1632
1621
  |---|---:|---|---|
1633
1622
  | `name` | no | string | Unique identifier for the file input |
1623
+ | `allowCameraCapture` | no | boolean \| [FileAllowCameraCapture](./types.md#fileallowcameracapture) | Allow camera capture for image files; object form supports quality |
1624
+ | `clickedFile` | no | [ClickedFile](./types.md#clickedfile) | Bindable clicked file metadata written before chipClick emits |
1625
+ | `cropperConfig` | no | [FileCropperConfig](./types.md#filecropperconfig) | Image cropper configuration |
1626
+ | `defaultValue` | no | [FileDefaultValue](./types.md#filedefaultvalue)[] | Default files to show when no value is provided |
1627
+ | `icon` | no | string | Icon name from Icon.TYPES to show above placeholder |
1634
1628
  | `isDisabled` | no | boolean | Disables the file input |
1635
1629
  | `isInvalid` | no | boolean | Shows error styling on the input |
1636
1630
  | `isReadOnly` | no | boolean | Makes the file input read-only (download only) |
@@ -1642,6 +1636,7 @@ Events: `change`, `delete`
1642
1636
  | `showProgress` | no | boolean | Show upload progress bar. Default: false |
1643
1637
  | `supportTypes` | no | string[] | Array of supported file extensions, e.g. [".pdf", ".doc"] |
1644
1638
  | `type` | no | [FileType](./definitions.md#filetype) | File input display type. Default: DEFAULT |
1639
+ | `value` | no | [FileValue](./types.md#filevalue)[] | Array of file objects bound to state |
1645
1640
 
1646
1641
  No additional properties.
1647
1642
 
@@ -1649,7 +1644,7 @@ No additional properties.
1649
1644
 
1650
1645
  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.
1651
1646
 
1652
- 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.
1647
+ 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.
1653
1648
 
1654
1649
  Catalog key: `FileDrop`
1655
1650
  Builder: `FileDrop`
@@ -1662,7 +1657,7 @@ Events: `change`, `blur`
1662
1657
  | Name | Required | Type | Description |
1663
1658
  |---|---:|---|---|
1664
1659
  | `name` | no | string | Unique identifier for the file input |
1665
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
1660
+ | `allowCameraCapture` | no | boolean \| [FileDropAllowCameraCapture](./types.md#filedropallowcameracapture) | Allow camera capture for image files; object form supports quality |
1666
1661
  | `aria-describedby` | no | string | ID of element that describes this input |
1667
1662
  | `aria-label` | no | string | Accessible label for screen readers |
1668
1663
  | `aria-labelledby` | no | string | ID of element that labels this input |
@@ -1678,10 +1673,12 @@ Events: `change`, `blur`
1678
1673
  | `label` | no | string | Label text above the file drop area |
1679
1674
  | `maxFileSize` | no | number | Max file size in MB per attachment |
1680
1675
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
1676
+ | `metadata` | no | unknown | JSON-serializable metadata sent with upload requests |
1677
+ | `module` | no | string | Deprecated upload bucket hint; prefer metadata.module when possible |
1681
1678
  | `multiPartUpload` | no | boolean | Enables multipart upload flow for files larger than 100MB |
1682
1679
  | `multiple` | no | boolean | Allow selecting multiple files |
1683
1680
  | `placeholder` | no | string | Text shown when no files are selected |
1684
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
1681
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
1685
1682
  | `type` | no | [FileDropType](./definitions.md#filedroptype) | Type of file drop: upload (shows progress bars automatically) or content. Default: content |
1686
1683
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
1687
1684
  | `value` | no | [FileDropValue](./types.md#filedropvalue)[] | Array of file objects bound to state |
@@ -1735,7 +1732,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
1735
1732
  | `shouldShowSpinner` | no | boolean | If true, shows loading spinner instead of icon |
1736
1733
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the button (XS, S, M, L). Default: M |
1737
1734
  | `tabIndex` | no | number | Tab order for keyboard navigation |
1738
- | `testId` | no | string | Sets data-testid attribute. Default: "button" |
1739
1735
  | `tip` | no | string \| [FloatingButtonTip](./types.md#floatingbuttontip) | Tooltip text or tooltip configuration object |
1740
1736
  | `to` | no | string \| [FloatingButtonTo](./types.md#floatingbuttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
1741
1737
  | `type` | no | [FloatingButtonType](./definitions.md#floatingbuttontype) | HTML button type attribute (button, submit, reset). Default: button |
@@ -1754,7 +1750,7 @@ Two binding surfaces (independent — use either, both, or neither):
1754
1750
 
1755
1751
  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.
1756
1752
 
1757
- `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`.
1753
+ `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.
1758
1754
 
1759
1755
  External `validationErrors` merge with input-reported errors; clear an error by writing a falsy value to that key.
1760
1756
 
@@ -1762,7 +1758,7 @@ Catalog key: `Form`
1762
1758
  Builder: `Form`
1763
1759
  Props type: `FormProps`
1764
1760
  Accepts children: yes
1765
- Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1761
+ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`, `skip`
1766
1762
 
1767
1763
  ### Props
1768
1764
 
@@ -1770,7 +1766,7 @@ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1770
1766
  |---|---:|---|---|
1771
1767
  | `bottomPadding` | no | boolean | Adds bottom padding to the form. Default: true |
1772
1768
  | `caption` | no | string | Subtext shown beneath the title |
1773
- | `editButton` | no | boolean | Show or hide the settings edit button. Default: true |
1769
+ | `editButton` | no | boolean \| [EditButton](./types.md#editbutton) | Settings edit button visibility/configuration. Default: true |
1774
1770
  | `inlineLabel` | no | boolean | Renders fields with inline labels (label and input side-by-side) |
1775
1771
  | `isDefaultEdit` | no | boolean | Initial edit state in settings mode. Requires isSettings: true |
1776
1772
  | `isDisabled` | no | boolean | Disables the entire form |
@@ -1784,6 +1780,8 @@ Events: `change`, `submit`, `valid`, `invalid`, `cancel`, `edit`
1784
1780
  | `shouldStopFormPropagation` | no | boolean | Stops form-submit event from bubbling — for nested forms |
1785
1781
  | `shouldTriggerChangeOnInputUnmount` | no | boolean | Fires change event when an input unmounts. Default: false |
1786
1782
  | `shouldTrimOnSubmit` | no | boolean | Trims string values on submit. Default: false |
1783
+ | `skipButton` | no | [SkipButton](./types.md#skipbutton) | Secondary skip action. Click emits the skip event. |
1784
+ | `submitButtonLabel` | no | string | Deprecated submit button label. Prefer submitButtonProps.label for new specs |
1787
1785
  | `submitButtonProps` | no | [SubmitButtonProp](./types.md#submitbuttonprop) | Configuration for the form submit button |
1788
1786
  | `successMessage` | no | string | Message shown in a snackbar after a successful submit |
1789
1787
  | `theme` | no | [FormTheme](./definitions.md#formtheme) | Predefined form style theme |
@@ -1817,12 +1815,15 @@ Events: `change`
1817
1815
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1818
1816
  | `defaultValue` | no | boolean | Initial checked state when uncontrolled |
1819
1817
  | `isDisabled` | no | boolean | Disables the input |
1818
+ | `isIndeterminate` | no | boolean | Sets checkbox to indeterminate (neither checked nor unchecked) state |
1820
1819
  | `isReadOnly` | no | boolean | Makes the input read-only |
1821
1820
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1822
1821
  | `label` | no | string | Label text for the checkbox |
1823
1822
  | `secondaryLabel` | no | string | Secondary text below the label |
1823
+ | `shouldPreventFocus` | no | boolean | Prevent the checkbox from receiving focus |
1824
1824
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Visual theme variant |
1825
1825
  | `tip` | no | string | Tooltip text shown on hover |
1826
+ | `title` | no | string | Form field label shown outside the checkbox |
1826
1827
  | `validationErrors` | no | [FormCheckboxValidationError](./types.md#formcheckboxvalidationerror) | Map of rule name to error message |
1827
1828
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
1828
1829
  | `value` | no | boolean | Current value bound to state |
@@ -1852,12 +1853,13 @@ Events: `change`
1852
1853
  |---|---:|---|---|
1853
1854
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1854
1855
  | `defaultValue` | no | unknown[] | Initial array of selected values when uncontrolled |
1856
+ | `id` | no | string | HTML id attribute for the checkbox group |
1855
1857
  | `isDisabled` | no | boolean | Disables the input |
1856
1858
  | `isHorizontal` | no | boolean | Arrange options in a row |
1857
1859
  | `isReadOnly` | no | boolean | Makes the input read-only |
1858
1860
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1859
1861
  | `label` | no | string | Label text above the checkbox group |
1860
- | `options` | yes | [FormCheckboxGroupOption](./types.md#formcheckboxgroupoption)[] | Array of {label, value} checkbox items |
1862
+ | `list` | yes | [FormCheckboxGroupList](./types.md#formcheckboxgrouplist)[] | Array of {label, value} checkbox items |
1861
1863
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
1862
1864
  | `validationErrors` | no | [FormCheckboxGroupValidationError](./types.md#formcheckboxgroupvalidationerror) | Map of rule name to error message |
1863
1865
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -1912,16 +1914,21 @@ Events: `change`, `blur`
1912
1914
  |---|---:|---|---|
1913
1915
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1914
1916
  | `allowNegative` | no | boolean | Whether negative values are allowed. Default: true |
1917
+ | `canSelectCurrencyType` | no | boolean | If true, displays a dropdown to select currency type |
1918
+ | `currencyTypeProps` | no | [FormCurrencyCurrencyTypeProp](./types.md#formcurrencycurrencytypeprop) | Nested Select props for the currency selector |
1915
1919
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
1916
- | `defaultValue` | no | number | Initial numeric value set in Form on mount |
1920
+ | `defaultValue` | no | string \| number \| [FormCurrencyDefaultValue](./types.md#formcurrencydefaultvalue) \| null | Initial currency value set in Form on mount |
1917
1921
  | `isDisabled` | no | boolean | Disables the input |
1918
1922
  | `isReadOnly` | no | boolean | Makes the input read-only |
1919
1923
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
1920
1924
  | `label` | no | string | Label text above the input |
1925
+ | `locale` | no | string | Locale string for number formatting (e.g. en-US). Overrides shouldLocalize when set. |
1926
+ | `placeholder` | no | string | Placeholder text when empty |
1921
1927
  | `prefix` | no | string | Currency symbol or code shown as prefix. Default: USD |
1928
+ | `shouldSendCurrencyType` | no | boolean | If true, onChange writes { value, type } using currencyTypeProps value/defaultValue |
1922
1929
  | `validationErrors` | no | [FormCurrencyValidationError](./types.md#formcurrencyvalidationerror) | Map of rule name to error message |
1923
1930
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
1924
- | `value` | no | unknown | Current value bound to state |
1931
+ | `value` | no | string \| number \| [FormCurrencyValue](./types.md#formcurrencyvalue) \| null | Current value bound to state |
1925
1932
 
1926
1933
  No additional properties.
1927
1934
 
@@ -1947,8 +1954,9 @@ Events: `change`
1947
1954
  |---|---:|---|---|
1948
1955
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1949
1956
  | `canClear` | no | boolean | Show clear button |
1950
- | `defaultValue` | no | string | Initial date value (yyyy-MM-dd) set in Form on mount |
1957
+ | `defaultValue` | no | string | Initial date value (yyyy-MM-dd) or null set in Form on mount |
1951
1958
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1959
+ | `id` | no | string | HTML id attribute for the input |
1952
1960
  | `isDisabled` | no | boolean | Disables the input |
1953
1961
  | `isReadOnly` | no | boolean | Makes the input read-only |
1954
1962
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
@@ -1956,8 +1964,10 @@ Events: `change`
1956
1964
  | `locale` | no | string | Locale for date formatting. Default: en-US |
1957
1965
  | `maxDate` | no | string | Latest selectable date as ISO string |
1958
1966
  | `minDate` | no | string | Earliest selectable date as ISO string |
1967
+ | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting. Default: false for explicit format control |
1959
1968
  | `shouldShowTime` | no | boolean | Include time selection |
1960
1969
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
1970
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
1961
1971
  | `timezone` | no | string | Timezone name (e.g. "America/New_York"). Used with shouldShowTime |
1962
1972
  | `tip` | no | string | Tooltip text shown alongside the field label |
1963
1973
  | `validationErrors` | no | [FormDateValidationError](./types.md#formdatevalidationerror) | Map of rule name to error message |
@@ -1988,11 +1998,12 @@ Events: `change`
1988
1998
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
1989
1999
  | `alwaysShowTimezone` | no | boolean | If true, timezone abbreviation will always be shown when shouldShowTime is true. Default: false |
1990
2000
  | `canClear` | no | boolean | Show clear button |
1991
- | `defaultValue` | no | string[] | Initial date range value [start, end] set in Form on mount |
2001
+ | `defaultValue` | no | string[] | Initial date range value [start, end] or null set in Form on mount |
1992
2002
  | `divider` | no | string | Separator between date units (e.g. "/" or "-") |
1993
2003
  | `endDateLabel` | no | string | Label for the end date field |
1994
2004
  | `format` | no | [CalendarFormat](./definitions.md#calendarformat) | Date display format. Default: MM/dd/yyyy |
1995
2005
  | `hideStepper` | no | boolean | If true, arrow navigation key to increment/decrement date will be hidden. Default: false |
2006
+ | `id` | no | string | HTML id attribute for the date range input |
1996
2007
  | `isCalendarDefaultOpen` | no | boolean | If true, calendar will be open by default on mount |
1997
2008
  | `isDisabled` | no | boolean | Disables the input |
1998
2009
  | `isLarge` | no | boolean | Renders large calendar when true. Default: false |
@@ -2008,6 +2019,7 @@ Events: `change`
2008
2019
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
2009
2020
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2010
2021
  | `startDateLabel` | no | string | Label for the start date field |
2022
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant. NO_BOX removes input box styling |
2011
2023
  | `timezone` | no | string | Timezone for date/time display and storage. Used with shouldShowTime |
2012
2024
  | `tip` | no | string | Tooltip text shown alongside the field label |
2013
2025
  | `validationErrors` | no | [FormDateRangeValidationError](./types.md#formdaterangevalidationerror) | Map of rule name to error message |
@@ -2044,6 +2056,7 @@ Events: `change`
2044
2056
  | `isReadOnly` | no | boolean | Makes the input read-only |
2045
2057
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2046
2058
  | `label` | no | string | Label text above the input |
2059
+ | `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) |
2047
2060
  | `validationErrors` | no | [FormDaySelectorValidationError](./types.md#formdayselectorvalidationerror) | Map of rule name to error message |
2048
2061
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2049
2062
  | `value` | no | unknown | Current value bound to state |
@@ -2071,6 +2084,7 @@ Events: `change`, `blur`
2071
2084
  | Name | Required | Type | Description |
2072
2085
  |---|---:|---|---|
2073
2086
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2087
+ | `autoComplete` | no | string | Browser autocomplete hint |
2074
2088
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
2075
2089
  | `isDisabled` | no | boolean | Disables the input |
2076
2090
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -2078,6 +2092,8 @@ Events: `change`, `blur`
2078
2092
  | `label` | no | string | Label text above the input |
2079
2093
  | `maxLength` | no | number | Maximum character count |
2080
2094
  | `placeholder` | no | string | Placeholder text when empty |
2095
+ | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2096
+ | `stringPadding` | no | [FormEmailStringPadding](./types.md#formemailstringpadding) | Pads input value with character until reaching maxLength |
2081
2097
  | `tip` | no | string | Tooltip text shown alongside the field label |
2082
2098
  | `validationErrors` | no | [FormEmailValidationError](./types.md#formemailvalidationerror) | Map of rule name to error message |
2083
2099
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2085,6 +2101,39 @@ Events: `change`, `blur`
2085
2101
 
2086
2102
  No additional properties.
2087
2103
 
2104
+ ## FormEmployeeSearch
2105
+
2106
+ 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.
2107
+
2108
+ 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.
2109
+
2110
+ Catalog key: `FormEmployeeSearch`
2111
+ Builder: `FormEmployeeSearch`
2112
+ Props type: `FormEmployeeSearchProps`
2113
+ Accepts children: no
2114
+ Events: `change`
2115
+
2116
+ ### Props
2117
+
2118
+ | Name | Required | Type | Description |
2119
+ |---|---:|---|---|
2120
+ | `name` | yes | string | Non-empty field name used to register this employee role-id value with the parent form. |
2121
+ | `canClear` | no | boolean | Controls whether the current selection can be cleared. When omitted, the underlying select default applies. |
2122
+ | `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. |
2123
+ | `isDisabled` | no | boolean | When true, disables searching and selection changes. Defaults to false. |
2124
+ | `isMulti` | no | boolean | When true, allows multiple employee selections and uses role id arrays. Defaults to false (single select). |
2125
+ | `isReadOnly` | no | boolean | When true, displays the selection without allowing changes. Defaults to false. |
2126
+ | `isRequired` | no | boolean | When true, marks the field as required. Defaults to the form control default (not required). |
2127
+ | `label` | no | string | Label displayed for the search field. Defaults to no label. |
2128
+ | `placeholder` | no | string | Placeholder displayed when the search field is empty. When omitted, the component default placeholder is used. |
2129
+ | `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. |
2130
+ | `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. |
2131
+ | `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. |
2132
+ | `tip` | no | string | Supplementary tip displayed with the label. Defaults to no tip. |
2133
+ | `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. |
2134
+
2135
+ No additional properties.
2136
+
2088
2137
  ## FormFile
2089
2138
 
2090
2139
  A Form-registered file upload field for use inside a Form component.
@@ -2109,7 +2158,7 @@ Events: `change`, `blur`
2109
2158
  | Name | Required | Type | Description |
2110
2159
  |---|---:|---|---|
2111
2160
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2112
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
2161
+ | `allowCameraCapture` | no | boolean \| [FormFileAllowCameraCapture](./types.md#formfileallowcameracapture) | Allow camera capture for image files; object form supports quality |
2113
2162
  | `cropperConfig` | no | [FormFileCropperConfig](./types.md#formfilecropperconfig) | Cropper configuration |
2114
2163
  | `defaultValue` | no | [FormFileDefaultValue](./types.md#formfiledefaultvalue)[] | Default files to show when no value is provided |
2115
2164
  | `enableCropper` | no | boolean | Enable image cropping for selected images |
@@ -2122,11 +2171,13 @@ Events: `change`, `blur`
2122
2171
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
2123
2172
  | `multiple` | no | boolean | Allow selecting multiple files |
2124
2173
  | `placeholder` | no | string | Text shown when no files are selected |
2125
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2174
+ | `showProgress` | no | boolean | Show upload progress bar. Default: false |
2175
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2126
2176
  | `tip` | no | string | Tooltip text shown alongside the field label |
2177
+ | `type` | no | [FileType](./definitions.md#filetype) | File input display type. Default: DEFAULT |
2127
2178
  | `validationErrors` | no | [FormFileValidationError](./types.md#formfilevalidationerror) | Map of rule name to error message |
2128
2179
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2129
- | `value` | no | [FormFileValue](./types.md#formfilevalue)[] | Current value bound to state |
2180
+ | `value` | no | [FormFileValue](./types.md#formfilevalue)[] | Array of file objects bound to state |
2130
2181
 
2131
2182
  No additional properties.
2132
2183
 
@@ -2154,7 +2205,7 @@ Events: `change`, `blur`
2154
2205
  | Name | Required | Type | Description |
2155
2206
  |---|---:|---|---|
2156
2207
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2157
- | `allowCameraCapture` | no | boolean | Allow camera capture for image files on mobile devices |
2208
+ | `allowCameraCapture` | no | boolean \| [FormFileDropAllowCameraCapture](./types.md#formfiledropallowcameracapture) | Allow camera capture for image files; object form supports quality |
2158
2209
  | `cropperConfig` | no | [FormFileDropCropperConfig](./types.md#formfiledropcropperconfig) | Cropper configuration |
2159
2210
  | `defaultValue` | no | [FormFileDropDefaultValue](./types.md#formfiledropdefaultvalue)[] | Default files to show when no value is provided |
2160
2211
  | `enableCropper` | no | boolean | Enable image cropping for selected images |
@@ -2168,12 +2219,12 @@ Events: `change`, `blur`
2168
2219
  | `multiPartUpload` | no | boolean | Enables multipart upload flow for files larger than 100MB |
2169
2220
  | `multiple` | no | boolean | Allow selecting multiple files |
2170
2221
  | `placeholder` | no | string | Text shown when no files are selected |
2171
- | `supportTypes` | no | [FileDropSupportTypes](./definitions.md#filedropsupporttypes)[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2222
+ | `supportTypes` | no | string[] | Supported file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types. |
2172
2223
  | `tip` | no | string | Tooltip text shown alongside the field label |
2173
2224
  | `type` | no | [FileDropType](./definitions.md#filedroptype) | Type of file drop: upload (shows progress bars automatically) or content. Default: content |
2174
2225
  | `validationErrors` | no | [FormFileDropValidationError](./types.md#formfiledropvalidationerror) | Map of rule name to error message |
2175
2226
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2176
- | `value` | no | [FormFileDropValue](./types.md#formfiledropvalue)[] | Current value bound to state |
2227
+ | `value` | no | [FormFileDropValue](./types.md#formfiledropvalue)[] | Array of file objects bound to state |
2177
2228
 
2178
2229
  No additional properties.
2179
2230
 
@@ -2377,13 +2428,15 @@ Catalog key: `FormNumber`
2377
2428
  Builder: `FormNumber`
2378
2429
  Props type: `FormNumberProps`
2379
2430
  Accepts children: no
2380
- Events: `change`, `blur`
2431
+ Events: `change`, `blur`, `changeRaw`, `changeCalculationState`
2381
2432
 
2382
2433
  ### Props
2383
2434
 
2384
2435
  | Name | Required | Type | Description |
2385
2436
  |---|---:|---|---|
2386
2437
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2438
+ | `autoComplete` | no | string | Browser autocomplete hint. Default: "off" |
2439
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2387
2440
  | `decimalPlaces` | no | number | Number of decimal places. Default: 2 |
2388
2441
  | `defaultValue` | no | string \| number | Initial default value for uncontrolled usage |
2389
2442
  | `isDisabled` | no | boolean | Disables the input |
@@ -2391,13 +2444,22 @@ Events: `change`, `blur`
2391
2444
  | `isReadOnly` | no | boolean | Makes the input read-only |
2392
2445
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2393
2446
  | `label` | no | string | Label text above the input |
2447
+ | `locale` | no | string | Locale string for number formatting (e.g. "en-US", "de-DE") |
2394
2448
  | `max` | no | number | Maximum allowed value |
2449
+ | `maxLength` | no | number | Maximum character count |
2450
+ | `maxWidth` | no | string | Maximum width CSS value |
2395
2451
  | `min` | no | number | Minimum allowed value. Default: 0 |
2452
+ | `minLength` | no | number | Minimum character count |
2396
2453
  | `placeholder` | no | string | Placeholder text when empty |
2397
2454
  | `prefix` | no | string | Text prefix inside the input |
2398
2455
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates on blur |
2456
+ | `shouldDisableFormatting` | no | boolean | If true, number formatting will not be applied. Default: true |
2457
+ | `shouldDisableRedundantZeroFormatting` | no | boolean | If true, redundant zeros are preserved. Default: true |
2458
+ | `shouldStripLeadingZeros` | no | boolean | If true, leading zeros are stripped from the numeric value |
2399
2459
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2460
+ | `spellCheck` | no | boolean | Enable spell checking |
2400
2461
  | `step` | no | number | Increment/decrement step size. Default: 1 |
2462
+ | `stringPadding` | no | [FormNumberStringPadding](./types.md#formnumberstringpadding) | Adds padding characters to the input value |
2401
2463
  | `suffix` | no | string | Text suffix inside the input |
2402
2464
  | `tip` | no | string | Tooltip text shown alongside the field label |
2403
2465
  | `validationErrors` | no | [FormNumberValidationError](./types.md#formnumbervalidationerror) | Map of rule name to error message |
@@ -2427,14 +2489,28 @@ Events: `change`, `blur`
2427
2489
  | Name | Required | Type | Description |
2428
2490
  |---|---:|---|---|
2429
2491
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2492
+ | `autoCapitalize` | no | [EmailAutoCapitalize](./definitions.md#emailautocapitalize) | Auto-capitalization: off, none, on, sentences, words, or characters |
2493
+ | `autoComplete` | no | string | Browser autocomplete hint |
2494
+ | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
2495
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2430
2496
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
2497
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2431
2498
  | `isDisabled` | no | boolean | Disables the input |
2499
+ | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
2432
2500
  | `isReadOnly` | no | boolean | Makes the input read-only |
2433
2501
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2434
2502
  | `label` | no | string | Label text above the input |
2435
2503
  | `maxLength` | no | number | Maximum character count |
2504
+ | `minLength` | no | number | Minimum character count |
2436
2505
  | `placeholder` | no | string | Placeholder text when empty |
2506
+ | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
2507
+ | `readOnlyAffixSpacing` | no | boolean | Controls gap between affixes and value in read-only mode. Default: true. Set false to remove gap |
2508
+ | `shouldAllowReveal` | no | boolean | Show password reveal toggle. Default: true |
2509
+ | `shouldPersistCursorPosition` | no | boolean | Persist cursor position for controlled input. Default: false |
2437
2510
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2511
+ | `spellCheck` | no | boolean | Enable spell checking |
2512
+ | `stringPadding` | no | [FormPasswordStringPadding](./types.md#formpasswordstringpadding) | Pads input value with character until reaching maxLength |
2513
+ | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2438
2514
  | `tip` | no | string | Tooltip text shown alongside the field label |
2439
2515
  | `validationErrors` | no | [FormPasswordValidationError](./types.md#formpasswordvalidationerror) | Map of rule name to error message |
2440
2516
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2471,10 +2547,13 @@ Events: `change`, `blur`
2471
2547
  | `isReadOnly` | no | boolean | Makes the input read-only |
2472
2548
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2473
2549
  | `label` | no | string | Label text above the input |
2550
+ | `locale` | no | string | Locale string for percentage formatting (e.g. en-US) |
2474
2551
  | `lowerLimit` | no | number | Minimum allowed percentage value |
2475
2552
  | `placeholder` | no | string | Placeholder text when empty |
2553
+ | `shouldDisableFormatting` | no | boolean | If true, percentage formatting will not be applied |
2476
2554
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2477
2555
  | `step` | no | number | Increment/decrement step size. Default: 1 |
2556
+ | `tip` | no | string | Tooltip text shown alongside the field label |
2478
2557
  | `upperLimit` | no | number | Maximum allowed percentage value. Default: 100 |
2479
2558
  | `validationErrors` | no | [FormPercentageValidationError](./types.md#formpercentagevalidationerror) | Map of rule name to error message |
2480
2559
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2496,7 +2575,7 @@ Catalog key: `FormPhone`
2496
2575
  Builder: `FormPhone`
2497
2576
  Props type: `FormPhoneProps`
2498
2577
  Accepts children: no
2499
- Events: `change`, `blur`
2578
+ Events: `change`, `blur`, `countryCodeChange`
2500
2579
 
2501
2580
  ### Props
2502
2581
 
@@ -2504,15 +2583,27 @@ Events: `change`, `blur`
2504
2583
  |---|---:|---|---|
2505
2584
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2506
2585
  | `autoComplete` | no | string | Browser autocomplete hint, e.g. "tel" |
2507
- | `countryCode` | no | string | Country code as string (e.g. "91", "1") to add as fixed prefix. For dropdown, use countryCodeValue instead |
2586
+ | `autoFocus` | no | boolean | Auto-focus on mount |
2587
+ | `countryCode` | no | string \| [FormPhoneCountryCode](./types.md#formphonecountrycode) | Either a fixed country code string or a country-code dropdown configuration object |
2588
+ | `countryCodeDefaultValue` | no | string | [Deprecated] Use countryCode.defaultValue instead. Initial selected country code for the legacy dropdown shape |
2589
+ | `countryCodeValue` | no | string | [Deprecated] Use countryCode.value instead. Bound selected country code for the legacy dropdown shape |
2508
2590
  | `defaultRegion` | no | string | Default country region code for formatting, e.g. "US", "IN", "CA". Default: US |
2509
2591
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
2592
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2593
+ | `isCountryCodeDisabled` | no | boolean | [Deprecated] Use countryCode.isDisabled instead for the legacy dropdown shape |
2594
+ | `isCountryCodeReadOnly` | no | boolean | [Deprecated] Use countryCode.isReadOnly instead for the legacy dropdown shape |
2595
+ | `isCountryCodeRequired` | no | boolean | [Deprecated] Use countryCode.isRequired instead for the legacy dropdown shape |
2510
2596
  | `isDisabled` | no | boolean | Disables the input |
2511
2597
  | `isReadOnly` | no | boolean | Makes the input read-only |
2512
2598
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2513
2599
  | `label` | no | string | Label text above the input |
2514
2600
  | `maxLength` | no | number | Maximum character count |
2601
+ | `minLength` | no | number | Minimum character count |
2515
2602
  | `placeholder` | no | string | Placeholder text when empty |
2603
+ | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
2604
+ | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
2605
+ | `stringPadding` | no | [FormPhoneStringPadding](./types.md#formphonestringpadding) | Pads input value with character until reaching maxLength |
2606
+ | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2516
2607
  | `tip` | no | string | Tooltip text shown alongside the field label |
2517
2608
  | `validationErrors` | no | [FormPhoneValidationError](./types.md#formphonevalidationerror) | Map of rule name to error message |
2518
2609
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2546,7 +2637,7 @@ Events: `change`
2546
2637
  | `isReadOnly` | no | boolean | Makes the input read-only |
2547
2638
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2548
2639
  | `label` | no | string | Label text above the radio group |
2549
- | `options` | yes | [FormRadioOption](./types.md#formradiooption)[] | Array of {label, value} options |
2640
+ | `list` | yes | [FormRadioList](./types.md#formradiolist)[] | Array of {label, value} radio options |
2550
2641
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
2551
2642
  | `tip` | no | string | Tooltip text shown alongside the label |
2552
2643
  | `validationErrors` | no | [FormRadioValidationError](./types.md#formradiovalidationerror) | Map of rule name to error message |
@@ -2587,7 +2678,8 @@ Events: `change`
2587
2678
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2588
2679
  | `isVertical` | no | boolean | Renders options in a vertical layout |
2589
2680
  | `label` | no | string | Label text above the segmented control |
2590
- | `options` | yes | [FormSegmentedControlOption](./types.md#formsegmentedcontroloption)[] | Array of { label, value } option objects |
2681
+ | `list` | no | [FormSegmentedControlList](./types.md#formsegmentedcontrollist)[] | Array of { label, value } segmented control options |
2682
+ | `rangeLabels` | no | [FormSegmentedControlRangeLabel](./types.md#formsegmentedcontrolrangelabel) | Labels to display at the start and end of the control range |
2591
2683
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Control size variant. Default: M |
2592
2684
  | `validationErrors` | no | [FormSegmentedControlValidationError](./types.md#formsegmentedcontrolvalidationerror) | Map of rule name to error message |
2593
2685
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2618,14 +2710,28 @@ Events: `change`, `blur`
2618
2710
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
2619
2711
  | `canClear` | no | boolean | Show clear button to deselect all |
2620
2712
  | `canSelectAll` | no | boolean | Show select-all toggle. Requires isMulti to be true |
2713
+ | `creatable` | no | boolean | Allow creating new options not in the list |
2714
+ | `defaultSearchQuery` | no | string | Initial search input value |
2715
+ | `defaultValue` | no | unknown[] \| unknown | Initial selected value or values when uncontrolled |
2716
+ | `dropdownHeight` | no | number | Sets dropdown menu height in pixels |
2717
+ | `emptyListPlaceholder` | no | string \| [FormSelectEmptyListPlaceholder](./types.md#formselectemptylistplaceholder) | Placeholder when dropdown list is empty. Can be string or object with state-specific placeholders |
2718
+ | `fuseOptions` | no | [FormSelectFuseOption](./types.md#formselectfuseoption) | Fuse.js search options for customizing fuzzy search behavior |
2621
2719
  | `isDisabled` | no | boolean | Disables the input |
2720
+ | `isMenuDefaultOpen` | no | boolean | If true, dropdown menu will be open by default |
2622
2721
  | `isMulti` | no | boolean | Allow multiple selections |
2722
+ | `isPositionFixed` | no | boolean | Position dropdown relative to viewport instead of parent |
2623
2723
  | `isReadOnly` | no | boolean | Makes the input read-only |
2624
2724
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2625
2725
  | `isSearchable` | no | boolean | Enable type-to-search filtering |
2626
2726
  | `label` | no | string | Label text above the select |
2627
- | `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 |
2727
+ | `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 |
2728
+ | `maxHeight` | no | string \| number | Max height of multi-select container (CSS value) |
2729
+ | `maxTruncationLines` | no | number | Max rows of chips visible before "+X" overflow chip appears (multi-select only) |
2628
2730
  | `placeholder` | no | string | Placeholder text when empty |
2731
+ | `placement` | no | [AppGroupSelectPlacement](./definitions.md#appgroupselectplacement) | Dropdown position relative to input. Default: bottom-start |
2732
+ | `shouldFocusFirstElement` | no | boolean | Auto-focus first menu item when dropdown opens |
2733
+ | `shouldShowSearchIcon` | no | boolean | Show search icon prefix when isSearchable is true |
2734
+ | `shouldUsePortal` | no | boolean | Render dropdown in a React Portal. Default: false |
2629
2735
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Select input size variant. Default: M |
2630
2736
  | `tip` | no | string | Tooltip text shown alongside the field label |
2631
2737
  | `validationErrors` | no | [FormSelectValidationError](./types.md#formselectvalidationerror) | Map of rule name to error message |
@@ -2665,8 +2771,8 @@ Events: `change`
2665
2771
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2666
2772
  | `label` | no | string | Label text above the input |
2667
2773
  | `list` | yes | [FormSelectableGroupList](./types.md#formselectablegrouplist)[] | Array of item objects to render as selectable cards |
2668
- | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | Card renderer type: BASIC_CARD or LOCATION_CARD |
2669
- | `testId` | no | string | Test identifier for automated testing |
2774
+ | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | JSON-only constrained renderer choice: BASIC_CARD or LOCATION_CARD |
2775
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
2670
2776
  | `tip` | no | string | Tooltip text shown alongside the field label |
2671
2777
  | `validationErrors` | no | [FormSelectableGroupValidationError](./types.md#formselectablegroupvalidationerror) | Map of rule name to error message |
2672
2778
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2785,7 +2891,7 @@ Events: `change`
2785
2891
  | `max` | no | number | Maximum value. Default: 100 |
2786
2892
  | `min` | no | number | Minimum value. Default: 0 |
2787
2893
  | `shouldShowMarker` | no | boolean | Controls visibility of marker. Default: true |
2788
- | `step` | no | number | Step size. Default: 1 |
2894
+ | `step` | no | number | Step size. Set to null to use marks as steps. Default: 1 |
2789
2895
  | `validationErrors` | no | [FormSliderValidationError](./types.md#formslidervalidationerror) | Map of rule name to error message |
2790
2896
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2791
2897
  | `value` | no | unknown | Current value bound to state |
@@ -2874,6 +2980,7 @@ Must be placed inside a Form element — it registers with Form and does not wor
2874
2980
  Stores a boolean (true/false) value keyed by `name` in the parent Form's values.
2875
2981
  Use `defaultValue: true` to pre-toggle the switch on.
2876
2982
  Use `onLabel` and `offLabel` to customize state text.
2983
+ Use `tip` as a plain string or Tip-like object with serializable fields such as `content`, `title`, and `appearance`.
2877
2984
  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" }`.
2878
2985
  onChange emits "change". Switch has no onBlur event.
2879
2986
 
@@ -2897,6 +3004,7 @@ Events: `change`
2897
3004
  | `offLabel` | no | string | Label text when switch is off |
2898
3005
  | `onLabel` | no | string | Label text when switch is on |
2899
3006
  | `rightAlign` | no | boolean | Align switch to the right |
3007
+ | `tip` | no | string \| [FormSwitchTip](./types.md#formswitchtip) | Tooltip text or serializable tip config shown alongside the switch labels |
2900
3008
  | `validationErrors` | no | [FormSwitchValidationError](./types.md#formswitchvalidationerror) | Map of rule name to error message |
2901
3009
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
2902
3010
  | `value` | no | boolean | Current value bound to state |
@@ -2910,6 +3018,7 @@ A Form-registered text field for use inside a Form component.
2910
3018
  Must be placed inside a Form element — it registers with Form and does not work standalone.
2911
3019
  Individual values are not bound to state; they flow through the parent Form's `values` push-binding on submit/change.
2912
3020
  Use `validations` for Form rule strings: "isEmail", "minLength:5", "maxLength:100", "isNumeric", etc.
3021
+ Browser/input behavior props such as `minLength`, `autoCapitalize`, `autoCorrect`, `spellCheck`, `inputMode`, `stringPadding`, and `shouldPersistCursorPosition` preserve the underlying Text input API.
2913
3022
  Use `validationErrors` to override default error messages per rule.
2914
3023
  `isRequired` blocks form submission when empty and shows an error.
2915
3024
  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" }`.
@@ -2926,19 +3035,28 @@ Events: `change`, `blur`
2926
3035
  | Name | Required | Type | Description |
2927
3036
  |---|---:|---|---|
2928
3037
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3038
+ | `autoCapitalize` | no | [EmailAutoCapitalize](./definitions.md#emailautocapitalize) | Auto-capitalization: off, none, on, sentences, words, or characters |
2929
3039
  | `autoComplete` | no | string | Browser autocomplete hint |
3040
+ | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
2930
3041
  | `autoFocus` | no | boolean | Auto-focus on mount |
2931
3042
  | `canClear` | no | boolean | Show clear button |
2932
3043
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
3044
+ | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
2933
3045
  | `isDisabled` | no | boolean | Disables the input |
3046
+ | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
2934
3047
  | `isReadOnly` | no | boolean | Makes the input read-only |
2935
3048
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2936
3049
  | `label` | no | string | Label text above the input |
2937
3050
  | `maxLength` | no | number | Maximum character count |
2938
3051
  | `maxWidth` | no | string | Maximum width CSS value |
3052
+ | `minLength` | no | number | Minimum character count |
2939
3053
  | `placeholder` | no | string | Placeholder text when empty |
2940
3054
  | `prefix` | no | string | Text or icon name from Icon.TYPES to show before the input value |
3055
+ | `readOnlyAffixSpacing` | no | boolean | Controls gap between affixes and value in read-only mode. Default: true. Set false to remove gap |
3056
+ | `shouldPersistCursorPosition` | no | boolean | Persist cursor position for controlled input. Default: false |
2941
3057
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
3058
+ | `spellCheck` | no | boolean | Enable spell checking |
3059
+ | `stringPadding` | no | [FormTextStringPadding](./types.md#formtextstringpadding) | Pads input value with character until reaching maxLength |
2942
3060
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
2943
3061
  | `tip` | no | string | Tooltip text shown alongside the field label |
2944
3062
  | `validationErrors` | no | [FormTextValidationError](./types.md#formtextvalidationerror) | Map of rule name to error message |
@@ -2954,14 +3072,15 @@ A Form-registered multi-line textarea for use inside a Form component.
2954
3072
  Must be placed inside a Form element — registers with Form and does not work standalone.
2955
3073
  Values flow through the parent Form's `values` push-binding on submit/change.
2956
3074
  Set hasCharsLimit with maxLength to show a character counter.
3075
+ Use `maxHeight` to cap textarea growth in pixels.
2957
3076
  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" }`.
2958
- onChange emits "change"; onBlur emits "blur".
3077
+ onChange emits "change"; onBlur emits "blur"; onFocus emits "focus".
2959
3078
 
2960
3079
  Catalog key: `FormTextarea`
2961
3080
  Builder: `FormTextarea`
2962
3081
  Props type: `FormTextareaProps`
2963
3082
  Accepts children: no
2964
- Events: `change`, `blur`
3083
+ Events: `change`, `blur`, `focus`
2965
3084
 
2966
3085
  ### Props
2967
3086
 
@@ -2976,10 +3095,11 @@ Events: `change`, `blur`
2976
3095
  | `isReadOnly` | no | boolean | Makes the input read-only |
2977
3096
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2978
3097
  | `label` | no | string | Label text above the input |
3098
+ | `maxHeight` | no | number | Maximum height in pixels |
2979
3099
  | `maxLength` | no | number | Maximum character count. Default: 10000 |
2980
3100
  | `placeholder` | no | string | Placeholder text when empty |
2981
3101
  | `rows` | no | number | Number of visible text rows |
2982
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Visual theme variant |
3102
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant |
2983
3103
  | `tip` | no | string | Tooltip text shown alongside the field label |
2984
3104
  | `validationErrors` | no | [FormTextareaValidationError](./types.md#formtextareavalidationerror) | Map of rule name to error message |
2985
3105
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
@@ -2993,7 +3113,7 @@ A Form-registered text field with auto-suggest dropdown for use inside a Form co
2993
3113
 
2994
3114
  Must be placed inside a Form element — it registers with Form and does not work standalone.
2995
3115
  Values flow through the parent Form's `values` push-binding on submit/change.
2996
- Pass `suggestions` as an array of {label, value} objects to populate the suggestion dropdown.
3116
+ Pass `list` as the React-style flat suggestion list. Common fields are `label`, `value`, and `isDisabled`; extra serializable item metadata is preserved.
2997
3117
  Use `shouldShowMenuOnFocus: true` to open the dropdown immediately on focus.
2998
3118
  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" }`.
2999
3119
  onChange emits "change"; onBlur emits "blur".
@@ -3010,19 +3130,21 @@ Events: `change`, `blur`
3010
3130
  |---|---:|---|---|
3011
3131
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3012
3132
  | `defaultValue` | no | string | Initial value set in Form on mount |
3133
+ | `fuseOptions` | no | [FormTextAutoSuggestFuseOption](./types.md#formtextautosuggestfuseoption) | Fuse.js search options for customizing suggestion filtering |
3013
3134
  | `isDisabled` | no | boolean | Disables the input |
3135
+ | `isPositionFixed` | no | boolean | Use fixed positioning for dropdown menu. Useful in scrollable containers |
3014
3136
  | `isReadOnly` | no | boolean | Makes the input read-only |
3015
3137
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
3016
3138
  | `label` | no | string | Label text above the input |
3139
+ | `list` | yes | [FormTextAutoSuggestList](./types.md#formtextautosuggestlist)[] | Flat suggestion list matching the React `list` item shape |
3017
3140
  | `maxLength` | no | number | Maximum character count |
3018
3141
  | `placeholder` | no | string | Placeholder text when empty |
3019
3142
  | `shouldShowMenuOnFocus` | no | boolean | Show dropdown menu on input focus. Default: false |
3020
3143
  | `shouldShowSearchIcon` | no | boolean | Show search icon prefix. Default: false |
3021
3144
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
3022
- | `suggestions` | yes | [FormTextAutoSuggestSuggestion](./types.md#formtextautosuggestsuggestion)[] | Array of { label, value } suggestion objects |
3023
3145
  | `validationErrors` | no | [FormTextAutoSuggestValidationError](./types.md#formtextautosuggestvalidationerror) | Map of rule name to error message |
3024
3146
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
3025
- | `value` | no | string | Current value bound to state |
3147
+ | `value` | no | string \| number | Current value bound to state |
3026
3148
 
3027
3149
  No additional properties.
3028
3150
 
@@ -3048,17 +3170,26 @@ Events: `change`, `blur`
3048
3170
  | Name | Required | Type | Description |
3049
3171
  |---|---:|---|---|
3050
3172
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3173
+ | `alwaysShowTimezone` | no | boolean | If true, timezone abbreviation will always be shown. Default: false |
3174
+ | `defaultSelectionStartTime` | no | string | Time to start the selection scroll from when shouldAllowTimeSelection is true (e.g. "08:00 AM") |
3051
3175
  | `defaultValue` | no | string | Initial value — ISO 8601 or "HH:MM AM/PM" time string |
3176
+ | `isDateTimeInline` | no | boolean | Make input inline, removes border, padding and width fits input/placeholder content |
3052
3177
  | `isDisabled` | no | boolean | Disables the input |
3053
3178
  | `isReadOnly` | no | boolean | Makes the input read-only |
3054
3179
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
3055
3180
  | `label` | no | string | Label text above the input |
3056
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times |
3181
+ | `locale` | no | string | Locale string for time formatting (e.g. en-US) |
3182
+ | `maxWidth` | no | string | Maximum width CSS value |
3183
+ | `pickClosestMeridiem` | no | boolean | When user does not enter AM/PM, pick the closest meridiem to the inputted hour value. Default: false |
3184
+ | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
3185
+ | `shouldAllowTimeSelection` | no | boolean \| [FormTimeShouldAllowTimeSelection](./types.md#formtimeshouldallowtimeselection) | Show a time selection dropdown for picking times |
3057
3186
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time input |
3187
+ | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly |
3058
3188
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
3059
3189
  | `shouldReturnISO` | no | boolean | Always return value in ISO 8601 format |
3190
+ | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
3060
3191
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
3061
- | `timezone` | no | string | Show time relative to this timezone (IANA identifier) |
3192
+ | `timezone` | no | string \| [FormTimeTimezone](./types.md#formtimetimezone) | Show time relative to this timezone or configure the timezone selector |
3062
3193
  | `validationErrors` | no | [FormTimeValidationError](./types.md#formtimevalidationerror) | Map of rule name to error message |
3063
3194
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
3064
3195
  | `value` | no | string | Current value bound to state |
@@ -3206,7 +3337,7 @@ Events: `change`
3206
3337
  | `shouldShowFolderStructure` | no | boolean | Renders folder structure view |
3207
3338
  | `shouldShowSelectionPath` | no | boolean | Show parent-to-child path in selected chips. Default: false |
3208
3339
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size. Default: M |
3209
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Custom theme styling |
3340
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Custom theme styling |
3210
3341
  | `validationErrors` | no | [FormTreeSelectValidationError](./types.md#formtreeselectvalidationerror) | Map of rule name to error message |
3211
3342
  | `validations` | no | string | Comma-separated Form rule string example: "isEmail,minLength:5" |
3212
3343
  | `value` | no | unknown | Current value bound to state |
@@ -3236,7 +3367,7 @@ Events: `change`, `blur`
3236
3367
  | `name` | yes | string | Field name — drives the Form value key inside the parent Form |
3237
3368
  | `autoComplete` | no | string | Browser autocomplete hint |
3238
3369
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
3239
- | `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 |
3370
+ | `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 |
3240
3371
  | `isDisabled` | no | boolean | Disables the input |
3241
3372
  | `isReadOnly` | no | boolean | Makes the input read-only |
3242
3373
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
@@ -3284,7 +3415,7 @@ Events: `actionClick`
3284
3415
  |---|---:|---|---|
3285
3416
  | `actionClickedId` | no | string | Stores the id of the clicked action. Bind to state path to access in actionClick event handler |
3286
3417
  | `actions` | no | [GridAction](./types.md#gridaction)[] | Array of action buttons displayed at the bottom of the grid. Each action emits actionClick event with id in state |
3287
- | `list` | yes | [GridList](./types.md#gridlist) \| [GridList](./types.md#gridlist)[] | Array of cells to display in the grid. Each cell has a label and renderer with props |
3418
+ | `list` | yes | [GridList](./types.md#gridlist) \| [GridListVariant2](./types.md#gridlistvariant2)[] | Array of cells to display in the grid. Each cell has a label and renderer with props |
3288
3419
  | `theme` | no | [GridTheme](./definitions.md#gridtheme) | Visual theme variant. NO_CARD removes card styling, TRANSPARENT uses transparent theme, NO_PADDING removes padding. Default: card with padding |
3289
3420
 
3290
3421
  No additional properties.
@@ -3354,7 +3485,7 @@ Events: _none_
3354
3485
  |---|---:|---|---|
3355
3486
  | `align` | no | [HStackAlign](./definitions.md#hstackalign) | Cross-axis alignment |
3356
3487
  | `alignSelf` | no | [HStackAlignSelf](./definitions.md#hstackalignself) | Align self override when inside a flex parent |
3357
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
3488
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
3358
3489
  | `basis` | no | number \| string | Flex basis value |
3359
3490
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | Box sizing model |
3360
3491
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Text/icon color token |
@@ -3380,7 +3511,7 @@ No additional properties.
3380
3511
 
3381
3512
  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.
3382
3513
 
3383
- 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).
3514
+ 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).
3384
3515
 
3385
3516
  Catalog key: `Icon`
3386
3517
  Builder: `Icon`
@@ -3392,12 +3523,12 @@ Events: `press`
3392
3523
 
3393
3524
  | Name | Required | Type | Description |
3394
3525
  |---|---:|---|---|
3395
- | `ariaControls` | no | string | ID of element controlled by this icon |
3396
- | `ariaDescribedby` | no | string | ID of element that describes this icon |
3397
- | `ariaExpanded` | no | boolean | Indicates if controlled element is expanded |
3398
- | `ariaHaspopup` | no | [IconAriaHaspopup](./definitions.md#iconariahaspopup) | Indicates the icon triggers a popup |
3399
- | `ariaLabel` | no | string | Accessible label. Required when onClick is used |
3400
- | `ariaLabelledby` | no | string | ID of element that labels this icon |
3526
+ | `aria-controls` | no | string | ID of element controlled by this icon |
3527
+ | `aria-describedby` | no | string | ID of element that describes this icon |
3528
+ | `aria-expanded` | no | boolean | Indicates if controlled element is expanded |
3529
+ | `aria-haspopup` | no | [IconAriaHaspopup](./definitions.md#iconariahaspopup) | Indicates the icon triggers a popup |
3530
+ | `aria-label` | no | string | Accessible label. Required when onClick is used |
3531
+ | `aria-labelledby` | no | string | ID of element that labels this icon |
3401
3532
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Pebble text/icon color token |
3402
3533
  | `isDisabled` | no | boolean | Disable the icon. Default: false |
3403
3534
  | `isFocused` | no | boolean | Show icon backdrop when focused. Use only with interactive icons (onClick). Default: false |
@@ -3456,7 +3587,6 @@ Events: `press`, `pressWhileDisabled`, `mouseEnter`, `mouseLeave`
3456
3587
  | `shouldShowSpinner` | no | boolean | If true, shows loading spinner instead of icon |
3457
3588
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the button (XS, S, M, L). Default: M |
3458
3589
  | `tabIndex` | no | number | Tab order for keyboard navigation |
3459
- | `testId` | no | string | Sets data-testid attribute. Default: "icon-button" |
3460
3590
  | `tip` | no | string \| [IconButtonTip](./types.md#iconbuttontip) | Tooltip text or tooltip configuration object |
3461
3591
  | `to` | no | string \| [IconButtonTo](./types.md#iconbuttonto) | Navigation destination. When provided, button renders as anchor and handles navigation automatically |
3462
3592
  | `type` | no | [FloatingButtonType](./definitions.md#floatingbuttontype) | HTML button type attribute (button, submit, reset). Default: button |
@@ -3484,7 +3614,7 @@ Events: `press`, `load`, `error`
3484
3614
  | `borderRadius` | no | [BoxRadius](./definitions.md#boxradius) | Border radius token, e.g. "shapeCornerMd" |
3485
3615
  | `height` | no | number \| string | Image height in px or CSS string |
3486
3616
  | `loading` | no | [ImageLoading](./definitions.md#imageloading) | Loading strategy. Default: eager |
3487
- | `src` | yes | string \| [Src](./types.md#src) | Image URL or theme-aware source object with light/dark variants |
3617
+ | `src` | no | string \| [Src](./types.md#src) | Image URL or theme-aware source object with light/dark variants |
3488
3618
  | `theme` | no | [ImageTheme](./definitions.md#imagetheme) | Image theme. COVER for cover positioning |
3489
3619
  | `width` | no | number \| string | Image width in px or CSS string |
3490
3620
 
@@ -3595,7 +3725,7 @@ Events: _none_
3595
3725
  | `leftIcon` | no | string \| [LabelLeftIcon](./types.md#labellefticon) | Icon displayed on the left side of the label |
3596
3726
  | `maxWidth` | no | string | Maximum width CSS value for truncation |
3597
3727
  | `rightIcon` | no | string \| [LabelRightIcon](./types.md#labelrighticon) | Icon displayed on the right side of the label |
3598
- | `size` | no | [LabelSize](./definitions.md#labelsize) | Size of the label. Default: LARGE |
3728
+ | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the label. Default: LARGE |
3599
3729
  | `text` | yes | string | Text content of the label |
3600
3730
  | `tip` | no | string \| [LabelTip](./types.md#labeltip) | Tooltip shown on hover. Can be simple string or object with appearance, placement, and other options |
3601
3731
 
@@ -3652,7 +3782,7 @@ Events: _none_
3652
3782
  |---|---:|---|---|
3653
3783
  | `align` | no | string | CSS align-items value for flex children alignment |
3654
3784
  | `alignSelf` | no | string | CSS align-self value to override parent align |
3655
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
3785
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
3656
3786
  | `basis` | no | number \| string | CSS flex-basis value |
3657
3787
  | `border` | no | string \| [LayoutBorder](./types.md#layoutborder) \| [LayoutBorder](./types.md#layoutborder) | Border. CSS string, strict token parts, or directional border object |
3658
3788
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | CSS box-sizing model |
@@ -3700,7 +3830,7 @@ Events: `press`
3700
3830
  | Name | Required | Type | Description |
3701
3831
  |---|---:|---|---|
3702
3832
  | `padding` | no | [LayoutCardPadding](./definitions.md#layoutcardpadding) | Card padding size. Default: PX_24 |
3703
- | `theme` | no | [LayoutCardTheme](./definitions.md#layoutcardtheme) | Card theme. SELECTABLE adds 2px tertiary border for selection UI. Default: DEFAULT |
3833
+ | `theme` | no | [CardTheme](./definitions.md#cardtheme) | Card theme. SELECTABLE adds 2px tertiary border for selection UI. Default: DEFAULT |
3704
3834
 
3705
3835
  No additional properties.
3706
3836
 
@@ -3806,9 +3936,9 @@ No additional properties.
3806
3936
 
3807
3937
  ## LottiePlayer
3808
3938
 
3809
- 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.
3939
+ 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.
3810
3940
 
3811
- 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).
3941
+ 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).
3812
3942
 
3813
3943
  Catalog key: `LottiePlayer`
3814
3944
  Builder: `LottiePlayer`
@@ -3820,13 +3950,8 @@ Events: _none_
3820
3950
 
3821
3951
  | Name | Required | Type | Description |
3822
3952
  |---|---:|---|---|
3823
- | `animationData` | no | [AnimationData](./types.md#animationdata) | Lottie animation JSON object. Required if path not provided |
3824
- | `autoplay` | no | boolean | Start playing automatically on load. Default: true |
3825
3953
  | `height` | no | string | Height of the animation container |
3826
- | `loop` | no | boolean \| number | Loop animation. true for infinite, false for once, or number for specific count |
3827
- | `path` | no | string | URL or relative path to the Lottie JSON animation file. Required if animationData not provided |
3828
- | `renderer` | no | [LottiePlayerRenderer](./definitions.md#lottieplayerrenderer) | Rendering method for the animation. Default: svg |
3829
- | `testId` | no | string | Data test id for testing purposes |
3954
+ | `loadConfig` | no | [LoadConfig](./types.md#loadconfig) | Semantic Lottie load configuration object |
3830
3955
  | `width` | no | string | Width of the animation container |
3831
3956
 
3832
3957
  No additional properties.
@@ -3906,7 +4031,7 @@ No additional properties.
3906
4031
 
3907
4032
  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.
3908
4033
 
3909
- Place ModalFooter component as the last child for action buttons. On close event, update isOpen binding to false to dismiss the modal.
4034
+ Place ModalFooter component as the last child for action buttons. On close event, update isVisible binding to false to dismiss the modal.
3910
4035
 
3911
4036
  Catalog key: `Modal`
3912
4037
  Builder: `Modal`
@@ -3920,15 +4045,15 @@ Events: `close`
3920
4045
  |---|---:|---|---|
3921
4046
  | `animation` | no | string | Modal animation type (e.g., "zoom", "fade"). Default: zoom |
3922
4047
  | `backdropAnimation` | no | string | Backdrop animation type (e.g., "fade"). Default: fade |
3923
- | `hasCloseButton` | no | boolean | Shows close button in header. Default: true |
3924
4048
  | `isFullScreen` | no | boolean | If true, modal renders full screen. Default: false |
3925
- | `isOpen` | no | boolean | Controls modal visibility |
4049
+ | `isVisible` | no | boolean | Controls modal visibility |
3926
4050
  | `shouldCloseOnBackdropClick` | no | boolean | If true, modal closes when backdrop is clicked. Default: true |
3927
4051
  | `shouldCloseOnEscape` | no | boolean | If true, modal closes on Escape key press. Defaults to shouldCloseOnBackdropClick value |
4052
+ | `shouldHideCancelIcon` | no | boolean | If true, hides the close button in the header. Default: false |
3928
4053
  | `shouldNotAnimate` | no | boolean | Disables open/close animation. Should be true if DataGrid is rendered as content |
3929
- | `size` | no | [ModalSize](./definitions.md#modalsize) | Modal width size. Default: medium |
3930
4054
  | `theme` | no | [ModalTheme](./definitions.md#modaltheme) | Pre-defined modal styles. GRAY: gray background. NO_PADDING: removes body padding |
3931
4055
  | `title` | no | string | Modal header title text |
4056
+ | `width` | no | number \| string | Custom modal width in px (number) or CSS string |
3932
4057
 
3933
4058
  No additional properties.
3934
4059
 
@@ -4001,7 +4126,7 @@ Events: `toggle`, `select`
4001
4126
  | `showMore` | no | [ShowMoreValue](./types.md#showmorevalue) | Configuration for show more behavior |
4002
4127
  | `theme` | no | [NestedListTheme](./definitions.md#nestedlisttheme) | ExpansionPanel theme variant |
4003
4128
  | `title` | no | string | Title for the nested list |
4004
- | `toggleIcon` | no | [ToggleIcon](./types.md#toggleicon) | Toggle icon configuration |
4129
+ | `toggleIcon` | no | [NestedListToggleIcon](./types.md#nestedlisttoggleicon) | Toggle icon configuration |
4005
4130
 
4006
4131
  No additional properties.
4007
4132
 
@@ -4043,6 +4168,7 @@ Events: `change`, `blur`, `changeRaw`, `changeCalculationState`
4043
4168
  | `shouldAllowCalculation` | no | boolean | If true, input allows arithmetic operators and evaluates on blur |
4044
4169
  | `shouldDisableFormatting` | no | boolean | If true, number formatting will not be applied. Default: true |
4045
4170
  | `shouldDisableRedundantZeroFormatting` | no | boolean | If true, redundant zeros are preserved. Default: true |
4171
+ | `shouldStripLeadingZeros` | no | boolean | If true, leading zeros are stripped from the numeric value |
4046
4172
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
4047
4173
  | `spellCheck` | no | boolean | Enable spell checking |
4048
4174
  | `step` | no | number | Increment/decrement step size. Default: 1 |
@@ -4056,7 +4182,7 @@ No additional properties.
4056
4182
 
4057
4183
  ## ObjectListView
4058
4184
 
4059
- Full-featured object list page with list view management. Supports multiple list views, view switching, inline editing, bulk actions, and record management. Use objectApiName to specify the object. Optionally set defaultListViewId to pre-select a specific list view.
4185
+ Full-featured object list page with list view management. Supports multiple list views, view switching, inline editing, bulk actions, and record management. Use objectApiName to specify the object.
4060
4186
 
4061
4187
  Wraps ObjectListPage which provides list view selector, manage views, add/delete records, CSV export, and RQL filtering.
4062
4188
 
@@ -4070,7 +4196,6 @@ Events: _none_
4070
4196
 
4071
4197
  | Name | Required | Type | Description |
4072
4198
  |---|---:|---|---|
4073
- | `defaultListViewId` | no | string | |
4074
4199
  | `objectApiName` | yes | string | |
4075
4200
 
4076
4201
  No additional properties.
@@ -4117,15 +4242,15 @@ No additional properties.
4117
4242
 
4118
4243
  ## ObjectUIHeader
4119
4244
 
4120
- 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.
4245
+ 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.
4121
4246
 
4122
- 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.
4247
+ 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.
4123
4248
 
4124
4249
  Catalog key: `ObjectUIHeader`
4125
4250
  Builder: `ObjectUIHeader`
4126
4251
  Props type: `ObjectUIHeaderProps`
4127
4252
  Accepts children: no
4128
- Events: _none_
4253
+ Events: `primaryAction`
4129
4254
 
4130
4255
  ### Props
4131
4256
 
@@ -4133,7 +4258,9 @@ Events: _none_
4133
4258
  |---|---:|---|---|
4134
4259
  | `avatarProps` | no | [ObjectUIHeaderAvatarProp](./types.md#objectuiheaderavatarprop) | Avatar configuration for the header |
4135
4260
  | `caption` | no | string | Header caption text below the title |
4136
- | `primaryActionLabel` | no | string | Label for the primary action button displayed in the header |
4261
+ | `label` | no | [LabelValue](./types.md#labelvalue) | Label chip displayed next to the title |
4262
+ | `primaryAction` | no | [ObjectUIHeaderPrimaryAction](./types.md#objectuiheaderprimaryaction) | Primary action button. Clicking it emits the primaryAction event |
4263
+ | `primaryActionLabel` | no | string | Deprecated. Use primaryAction.label instead for the primary action button text |
4137
4264
  | `title` | no | string | Header title text |
4138
4265
 
4139
4266
  No additional properties.
@@ -4173,7 +4300,7 @@ Events: `actionClick`
4173
4300
  |---|---:|---|---|
4174
4301
  | `actionClickedId` | no | string | Stores the id of the clicked action. Bind to state path to access in actionClick event handler |
4175
4302
  | `actions` | no | [ObjectUIStatsAction](./types.md#objectuistatsaction)[] | Array of action buttons displayed at the bottom of the grid. Each action emits actionClick event with id in state |
4176
- | `list` | yes | [ObjectUIStatsList](./types.md#objectuistatslist) \| [ObjectUIStatsList](./types.md#objectuistatslist)[] | Array of cells to display in the stats grid. Each cell has a label and renderer with props |
4303
+ | `list` | yes | [ObjectUIStatsList](./types.md#objectuistatslist) \| [ObjectUIStatsListVariant2](./types.md#objectuistatslistvariant2)[] | Array of cells to display in the stats grid. Each cell has a label and renderer with props |
4177
4304
 
4178
4305
  No additional properties.
4179
4306
 
@@ -4273,7 +4400,7 @@ No additional properties.
4273
4400
 
4274
4401
  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.
4275
4402
 
4276
- 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.
4403
+ 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.
4277
4404
 
4278
4405
  Catalog key: `PageHeader`
4279
4406
  Builder: `PageHeader`
@@ -4286,7 +4413,7 @@ Events: `action`
4286
4413
  | Name | Required | Type | Description |
4287
4414
  |---|---:|---|---|
4288
4415
  | `actionClickedId` | no | string | Bind to state to receive the clicked action ID when an action is clicked |
4289
- | `actions` | no | [PageHeaderAction](./types.md#pageheaderaction)[] | Action buttons to display in the header. Each action emits an "action" event on click. |
4416
+ | `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. |
4290
4417
  | `caption` | no | string | Caption text displayed below the title |
4291
4418
  | `id` | no | string | HTML id attribute for the title/caption container |
4292
4419
  | `shouldBeLeftAligned` | no | boolean | If true, header is left-aligned instead of centered. Default: false |
@@ -4327,7 +4454,7 @@ No additional properties.
4327
4454
 
4328
4455
  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.
4329
4456
 
4330
- 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.
4457
+ 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.
4331
4458
 
4332
4459
  Catalog key: `PaginateList`
4333
4460
  Builder: `PaginateList`
@@ -4340,7 +4467,7 @@ Events: `change`
4340
4467
  | Name | Required | Type | Description |
4341
4468
  |---|---:|---|---|
4342
4469
  | `initialPage` | no | number | Initial page number to display (0-indexed) |
4343
- | `list` | yes | [PaginateListList](./types.md#paginatelistlist)[] | Array of items to paginate. Each item must have an id and a label. Additional keys are allowed. |
4470
+ | `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. |
4344
4471
  | `pageSize` | no | number | Number of items displayed per page. Default: 10 |
4345
4472
 
4346
4473
  No additional properties.
@@ -4402,7 +4529,7 @@ Events: `collapsedChange`, `dismiss`, `resize`
4402
4529
 
4403
4530
  | Name | Required | Type | Description |
4404
4531
  |---|---:|---|---|
4405
- | `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" |
4532
+ | `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" |
4406
4533
  | `collapsed` | no | boolean | Controlled collapsed state. Bind to state for controlled mode |
4407
4534
  | `collapsible` | no | boolean | Whether pane can be collapsed by the user. When undefined, infers from size/verticalSize/dismissible props |
4408
4535
  | `containerName` | no | string | CSS container name for container queries. When set, enables @container queries for content inside this pane |
@@ -4426,7 +4553,7 @@ A secure input field for entering or creating passwords, with automatic characte
4426
4553
 
4427
4554
  onChange writes password value to state path bound to `value`, then emits "change"
4428
4555
  onBlur validates if checks are provided, then emits "blur"
4429
- onRevealChange emits "reveal" event - bind state to capture reveal status (true when password is visible)
4556
+ onRevealChange emits "revealChange" when the reveal state toggles
4430
4557
  Keyboard events (keydown, keyup, paste) and mouse events (click, mouseenter, mouseleave, focus) emit without parameters
4431
4558
  Use prefix/suffix for icons - pass Icon.TYPES names like "LOCK_OUTLINE" or text
4432
4559
  Use inputMode to hint the virtual keyboard type on mobile devices
@@ -4438,7 +4565,7 @@ Catalog key: `Password`
4438
4565
  Builder: `Password`
4439
4566
  Props type: `PasswordProps`
4440
4567
  Accepts children: no
4441
- Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mouseenter`, `mouseleave`, `reveal`
4568
+ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mouseenter`, `mouseleave`, `revealChange`
4442
4569
 
4443
4570
  ### Props
4444
4571
 
@@ -4456,6 +4583,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4456
4583
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
4457
4584
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
4458
4585
  | `isDisabled` | no | boolean | Disables the input |
4586
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4459
4587
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
4460
4588
  | `isReadOnly` | no | boolean | Makes the input read-only |
4461
4589
  | `isRequired` | no | boolean | Marks the field as required |
@@ -4474,7 +4602,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4474
4602
  | `spellCheck` | no | boolean | Enable spell checking |
4475
4603
  | `stringPadding` | no | [PasswordStringPadding](./types.md#passwordstringpadding) | Pads input value with character until reaching maxLength |
4476
4604
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
4477
- | `testId` | no | string | Test ID for automation |
4478
4605
  | `theme` | no | string | Theme name from Input.Password.THEMES or custom theme |
4479
4606
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4480
4607
  | `value` | no | string | Current password value bound to state |
@@ -4502,7 +4629,9 @@ Events: `change`, `blur`
4502
4629
  | `checks` | no | [PercentageCheck](./types.md#percentagecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4503
4630
  | `decimalPlaces` | no | number | Number of decimal places allowed. Default: 2 |
4504
4631
  | `defaultValue` | no | number | Default percentage value when uncontrolled |
4632
+ | `id` | no | string | HTML id attribute for the input |
4505
4633
  | `isDisabled` | no | boolean | Disables the input |
4634
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4506
4635
  | `isReadOnly` | no | boolean | Makes the input read-only |
4507
4636
  | `isRequired` | no | boolean | Marks the field as required |
4508
4637
  | `label` | no | string | Label text above the input |
@@ -4526,14 +4655,15 @@ A specialized input for entering and editing phone numbers with automatic region
4526
4655
  onChange writes formatted phone number to state path bound to `value`, then emits "change"
4527
4656
  onBlur validates if checks are provided, then emits "blur"
4528
4657
  Keyboard events (keydown, keyup, paste) and mouse events (click, mouseenter, mouseleave, focus) emit without parameters
4529
- For fixed country code prefix, use countryCode as string (e.g., "91", "1")
4530
- For country code dropdown, bind countryCodeValue to state - emits "countryCodeChange" when dropdown changes
4658
+ 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.
4659
+ countryCodeValue, countryCodeDefaultValue, isCountryCodeDisabled, isCountryCodeReadOnly, and isCountryCodeRequired are deprecated legacy aliases kept for backward compatibility; prefer the nested countryCode object fields for new specs.
4531
4660
  Use defaultRegion to specify formatting region (US, IN, CA, etc.) - defaults to US
4532
4661
  Use prefix/suffix for icons - pass Icon.TYPES names like "PHONE_OUTLINE" or text
4533
4662
  Use inputMode to hint the virtual keyboard type on mobile devices - defaults to "tel"
4534
4663
  Use stringPadding to automatically pad values
4535
4664
  Basic ARIA attributes (aria-label, aria-labelledby, aria-describedby) support accessibility
4536
4665
  The region prop is deprecated - use defaultRegion instead
4666
+ testId is a deprecated testing-only prop kept only for backward compatibility.
4537
4667
  Standalone — does not register with Form; use FormPhone inside a Form instead.
4538
4668
 
4539
4669
  Catalog key: `Phone`
@@ -4555,18 +4685,18 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4555
4685
  | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
4556
4686
  | `autoFocus` | no | boolean | Auto-focus on mount |
4557
4687
  | `checks` | no | [PhoneCheck](./types.md#phonecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4558
- | `countryCode` | no | string | Country code as string (e.g. "91", "1") to add as fixed prefix. For dropdown, use countryCodeValue instead |
4559
- | `countryCodeDefaultValue` | no | string | Default country code for dropdown mode |
4560
- | `countryCodeValue` | no | string | Country code value bound to state for dropdown mode. Bind to state to enable country code dropdown |
4688
+ | `countryCode` | no | string \| [PhoneCountryCode](./types.md#phonecountrycode) | Either a fixed country code string or a country-code dropdown configuration object |
4689
+ | `countryCodeDefaultValue` | no | string | [Deprecated] Use countryCode.defaultValue instead. Initial selected country code for the legacy dropdown shape |
4690
+ | `countryCodeValue` | no | string | [Deprecated] Use countryCode.value instead. Bound selected country code for the legacy dropdown shape |
4561
4691
  | `defaultRegion` | no | string | Default country region code for formatting, e.g. "US", "IN", "CA". Default: US |
4562
4692
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
4563
4693
  | `fixedCharsPrefix` | no | string | Fixed characters at the beginning of value |
4564
4694
  | `fixedCharsSuffix` | no | string | Fixed characters at the end of value |
4565
4695
  | `id` | no | string | HTML element ID |
4566
4696
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
4567
- | `isCountryCodeDisabled` | no | boolean | Disable country code dropdown |
4568
- | `isCountryCodeReadOnly` | no | boolean | Make country code dropdown read-only |
4569
- | `isCountryCodeRequired` | no | boolean | Mark country code dropdown as required |
4697
+ | `isCountryCodeDisabled` | no | boolean | [Deprecated] Use countryCode.isDisabled instead for the legacy dropdown shape |
4698
+ | `isCountryCodeReadOnly` | no | boolean | [Deprecated] Use countryCode.isReadOnly instead for the legacy dropdown shape |
4699
+ | `isCountryCodeRequired` | no | boolean | [Deprecated] Use countryCode.isRequired instead for the legacy dropdown shape |
4570
4700
  | `isDisabled` | no | boolean | Disables the input |
4571
4701
  | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4572
4702
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
@@ -4592,7 +4722,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
4592
4722
  | `spellCheck` | no | boolean | Enable spell checking |
4593
4723
  | `stringPadding` | no | [PhoneStringPadding](./types.md#phonestringpadding) | Pads input value with character until reaching maxLength |
4594
4724
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
4595
- | `testId` | no | string | Test ID for automation |
4725
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
4596
4726
  | `theme` | no | string | Theme name from Input.Phone.THEMES or custom theme |
4597
4727
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4598
4728
  | `value` | no | string | Current phone number value bound to state |
@@ -4603,7 +4733,7 @@ No additional properties.
4603
4733
 
4604
4734
  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.
4605
4735
 
4606
- 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.
4736
+ 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.
4607
4737
 
4608
4738
  Catalog key: `ProgressBar`
4609
4739
  Builder: `ProgressBar`
@@ -4620,11 +4750,12 @@ Events: _none_
4620
4750
  | `aria-label` | no | string | Accessibility label for screen readers |
4621
4751
  | `aria-labelledby` | no | string | ID of element that labels this progress bar |
4622
4752
  | `aria-valuetext` | no | string | Human-readable text alternative for the current value |
4753
+ | `completedPercent` | no | number | Progress percentage (0-100). Canonical ProgressBar value prop |
4623
4754
  | `isIndeterminate` | no | boolean | Shows indeterminate loading animation |
4624
- | `label` | no | string | Label text displayed above the progress bar |
4625
- | `showPercentage` | no | boolean | Displays the percentage value as text |
4626
- | `testId` | no | string | Test identifier for automated testing. Default: progress-bar |
4627
- | `value` | no | number | Progress percentage (0-100) |
4755
+ | `label` | no | string | Deprecated compatibility prop for wrapper-level label text outside ProgressBar |
4756
+ | `showPercentage` | no | boolean | Deprecated compatibility prop for wrapper-level percentage text outside ProgressBar |
4757
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility. Default: progress-bar |
4758
+ | `value` | no | number | Deprecated. Use completedPercent instead |
4628
4759
 
4629
4760
  No additional properties.
4630
4761
 
@@ -4632,7 +4763,7 @@ No additional properties.
4632
4763
 
4633
4764
  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.
4634
4765
 
4635
- stepsCompleted starts at 1. Use isNumeric for numbered steps. Use isHorizontal for compact horizontal layouts.
4766
+ 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.
4636
4767
 
4637
4768
  Catalog key: `ProgressSteps`
4638
4769
  Builder: `ProgressSteps`
@@ -4656,7 +4787,7 @@ No additional properties.
4656
4787
 
4657
4788
  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.
4658
4789
 
4659
- 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.
4790
+ 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.
4660
4791
 
4661
4792
  Catalog key: `Radio`
4662
4793
  Builder: `Radio`
@@ -4678,10 +4809,11 @@ Events: `change`, `blur`, `mouseenter`, `mouseleave`
4678
4809
  | `id` | no | string | HTML id attribute for the radio group |
4679
4810
  | `isDisabled` | no | boolean | Disables all radio options |
4680
4811
  | `isHorizontal` | no | boolean | Arrange options in a row |
4812
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4681
4813
  | `isReadOnly` | no | boolean | Makes the radio group read-only |
4682
4814
  | `isRequired` | no | boolean | Marks the field as required |
4683
4815
  | `label` | no | string | Label text above the radio group |
4684
- | `options` | no | [RadioOption](./types.md#radiooption)[] | Array of { label, value } option objects |
4816
+ | `list` | no | [RadioList](./types.md#radiolist)[] | Array of { label, value } option objects |
4685
4817
  | `theme` | no | [CheckboxTheme](./definitions.md#checkboxtheme) | Theme styling: FLUID_WIDTH for full-width options, REVERSE for reversed theme |
4686
4818
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4687
4819
  | `value` | no | unknown | Currently selected value bound to state |
@@ -4747,6 +4879,28 @@ _No fields._
4747
4879
 
4748
4880
  No additional properties.
4749
4881
 
4882
+ ## Reports
4883
+
4884
+ Embeds a saved Rippling Analytics Report by id. Mounts the EmbeddedReport viewer in STANDALONE mode; the viewer owns fetch, loading, and 403–404 surfaces.
4885
+
4886
+ 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).
4887
+
4888
+ 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.
4889
+
4890
+ Catalog key: `Reports`
4891
+ Builder: `Reports`
4892
+ Props type: `ReportsProps`
4893
+ Accepts children: no
4894
+ Events: _none_
4895
+
4896
+ ### Props
4897
+
4898
+ | Name | Required | Type | Description |
4899
+ |---|---:|---|---|
4900
+ | `reportId` | yes | string | Id of a saved Rippling Analytics Report. The viewer fetches the report and derives grid-vs-chart from its saved configuration. |
4901
+
4902
+ No additional properties.
4903
+
4750
4904
  ## ReportShareLoader
4751
4905
 
4752
4906
  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).
@@ -4843,7 +4997,7 @@ No additional properties.
4843
4997
 
4844
4998
  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.
4845
4999
 
4846
- 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.
5000
+ 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.
4847
5001
 
4848
5002
  Catalog key: `SegmentedControl`
4849
5003
  Builder: `SegmentedControl`
@@ -4861,12 +5015,14 @@ Events: `change`, `blur`
4861
5015
  | `defaultValue` | no | string \| string[] | Initial value when uncontrolled |
4862
5016
  | `isDisabled` | no | boolean | Disables the entire control |
4863
5017
  | `isFluid` | no | boolean | Stretches control to fill container width |
5018
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
4864
5019
  | `isMulti` | no | boolean | Allows selecting multiple options |
4865
5020
  | `isReadOnly` | no | boolean | Makes the control read-only |
4866
5021
  | `isRequired` | no | boolean | Marks the field as required |
4867
5022
  | `isVertical` | no | boolean | Renders options in a vertical layout |
4868
5023
  | `label` | no | string | Label text above the segmented control |
4869
- | `options` | yes | [SegmentedControlOption](./types.md#segmentedcontroloption)[] | Array of { label, value } option objects |
5024
+ | `list` | yes | [SegmentedControlList](./types.md#segmentedcontrollist)[] | Array of { label, value } option objects |
5025
+ | `options` | no | [SegmentedControlOption](./types.md#segmentedcontroloption)[] | [Deprecated] Use list. Legacy alias for segmented control options |
4870
5026
  | `rangeLabels` | no | [SegmentedControlRangeLabel](./types.md#segmentedcontrolrangelabel) | Labels to display at the start and end of the control range |
4871
5027
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Control size variant. Default: M |
4872
5028
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
@@ -4879,6 +5035,7 @@ No additional properties.
4879
5035
  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.
4880
5036
 
4881
5037
  onChange stores the selected option value in state (single mode) or an array of selected values (isMulti mode).
5038
+ 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.
4882
5039
  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.
4883
5040
  Set isMulti=true for multi-select with token chips. Set creatable=true to allow creating new options.
4884
5041
  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.
@@ -4905,12 +5062,14 @@ Events: `change`, `blur`, `focus`, `paste`, `menuToggle`
4905
5062
  | `checks` | no | [SelectCheck](./types.md#selectcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
4906
5063
  | `creatable` | no | boolean | Allow creating new options not in the list |
4907
5064
  | `defaultSearchQuery` | no | string | Initial search input value |
5065
+ | `defaultValue` | no | unknown[] \| unknown | Initial selected value or values when uncontrolled |
4908
5066
  | `dropdownHeight` | no | number | Sets dropdown menu height in pixels |
4909
5067
  | `emptyListPlaceholder` | no | string \| [SelectEmptyListPlaceholder](./types.md#selectemptylistplaceholder) | Placeholder when dropdown list is empty. Can be string or object with state-specific placeholders |
4910
5068
  | `footer` | no | [SelectFooter](./types.md#selectfooter) | Fixed footer at bottom of dropdown menu |
4911
5069
  | `fuseOptions` | no | [SelectFuseOption](./types.md#selectfuseoption) | Fuse.js search options for customizing fuzzy search behavior |
4912
5070
  | `id` | no | string | HTML id attribute for the select input |
4913
5071
  | `isDisabled` | no | boolean | Disables the select |
5072
+ | `isInvalid` | no | boolean | Shows invalid styling on the select |
4914
5073
  | `isMenuDefaultOpen` | no | boolean | If true, dropdown menu will be open by default |
4915
5074
  | `isMulti` | no | boolean | Allow multiple selections |
4916
5075
  | `isPositionFixed` | no | boolean | Position dropdown relative to viewport instead of parent |
@@ -4918,9 +5077,10 @@ Events: `change`, `blur`, `focus`, `paste`, `menuToggle`
4918
5077
  | `isRequired` | no | boolean | Marks the field as required |
4919
5078
  | `isSearchable` | no | boolean | Enable type-to-search filtering |
4920
5079
  | `label` | no | string | Label text above the select |
5080
+ | `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 |
4921
5081
  | `maxHeight` | no | string \| number | Max height of multi-select container (CSS value) |
4922
5082
  | `maxTruncationLines` | no | number | Max rows of chips visible before "+X" overflow chip appears (multi-select only) |
4923
- | `options` | no | [SelectOption](./types.md#selectoption)[] | Array of option objects with label, value, and optional metadata |
5083
+ | `options` | no | [SelectOption](./types.md#selectoption)[] \| [SelectOption](./types.md#selectoption)[] | Deprecated alias for list. Use list for new specs |
4924
5084
  | `placeholder` | no | string | Placeholder text when empty |
4925
5085
  | `placement` | no | [AppGroupSelectPlacement](./definitions.md#appgroupselectplacement) | Dropdown position relative to input. Default: bottom-start |
4926
5086
  | `rows` | no | number | Minimum number of rows to show |
@@ -4940,7 +5100,7 @@ No additional properties.
4940
5100
 
4941
5101
  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.
4942
5102
 
4943
- 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.
5103
+ 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.
4944
5104
 
4945
5105
  Catalog key: `SelectableGroup`
4946
5106
  Builder: `SelectableGroup`
@@ -4960,13 +5120,14 @@ Events: `change`
4960
5120
  | `defaultValue` | no | string \| number \| string \| number[] | Initial selection when uncontrolled |
4961
5121
  | `id` | no | string | Unique DOM id for the input element |
4962
5122
  | `isDisabled` | no | boolean | Disables all items in the group |
5123
+ | `isInvalid` | no | boolean | Shows invalid styling on the group |
4963
5124
  | `isMulti` | no | boolean | Allow multiple selection. Default: false |
4964
5125
  | `isReadOnly` | no | boolean | Makes the group read-only |
4965
5126
  | `isRequired` | no | boolean | Marks as required. In multi-select, prevents deselecting the last item |
4966
5127
  | `label` | no | string | Label text above the input |
4967
5128
  | `list` | yes | [SelectableGroupList](./types.md#selectablegrouplist)[] | Array of item objects to render as selectable cards |
4968
- | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | Card renderer type: BASIC_CARD or LOCATION_CARD |
4969
- | `testId` | no | string | Test identifier for automated testing |
5129
+ | `renderer` | yes | [FormSelectableGroupRenderer](./definitions.md#formselectablegrouprenderer) | JSON-only constrained renderer choice: BASIC_CARD or LOCATION_CARD |
5130
+ | `testId` | no | string | Deprecated testing-only prop kept for backward compatibility |
4970
5131
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
4971
5132
  | `value` | no | string \| number \| string \| number[] | Selected value(s). Single value when isMulti is false, array when true |
4972
5133
  | `valueIdentifier` | no | string | Key name to extract unique value from each list item. Default: "value" |
@@ -5075,6 +5236,7 @@ Events: `change`
5075
5236
  | `defaultValue` | no | string | Initial default signature value |
5076
5237
  | `id` | no | string | Unique DOM element ID |
5077
5238
  | `isDisabled` | no | boolean | Disables the signature input |
5239
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5078
5240
  | `isReadOnly` | no | boolean | Shows signature image only, no input |
5079
5241
  | `isRequired` | no | boolean | Marks the field as required |
5080
5242
  | `isTypeSignatureDisabled` | no | boolean | Only show draw input, hide type input. Default: false |
@@ -5108,10 +5270,12 @@ Events: `change`, `blur`
5108
5270
  | `autoComplete` | no | string | Browser autocomplete hint. Default: off |
5109
5271
  | `autoFocus` | no | boolean | Auto-focus input on mount |
5110
5272
  | `checks` | no | [SinCheck](./types.md#sincheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5273
+ | `defaultValue` | no | string | Initial unmasked SIN value |
5111
5274
  | `fixedCharsPrefix` | no | string | Fixes characters at the beginning of the value |
5112
5275
  | `fixedCharsSuffix` | no | string | Fixes characters at the end of the value |
5113
5276
  | `id` | no | string | Explicit HTML element id |
5114
5277
  | `isDisabled` | no | boolean | Disables the input |
5278
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5115
5279
  | `isReadOnly` | no | boolean | Makes the input read-only |
5116
5280
  | `isRequired` | no | boolean | Marks the field as required |
5117
5281
  | `label` | no | string | Label text above the input |
@@ -5131,7 +5295,7 @@ No additional properties.
5131
5295
 
5132
5296
  An animated placeholder that mimics the shape of content while it loads, available in text (lines), circle, and box variants.
5133
5297
 
5134
- 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).
5298
+ 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).
5135
5299
 
5136
5300
  Catalog key: `Skeleton`
5137
5301
  Builder: `Skeleton`
@@ -5143,16 +5307,16 @@ Events: _none_
5143
5307
 
5144
5308
  | Name | Required | Type | Description |
5145
5309
  |---|---:|---|---|
5146
- | `animation` | no | [SkeletonAnimation](./definitions.md#skeletonanimation) | Loading animation style. Default: WAVE |
5310
+ | `animation` | no | [SkeletonAnimation](./definitions.md#skeletonanimation) | Loading animation style. Default: wave |
5147
5311
  | `borderRadius` | no | [BoxRadius](./definitions.md#boxradius) | Border radius token (BOX variant) |
5148
- | `gap` | no | [BoxGap](./definitions.md#boxgap) | Gap between lines when lines > 1 (TEXT variant). Spacing token. Default: 4px |
5149
- | `height` | no | number | Height in px (BOX variant) |
5312
+ | `gap` | no | [BoxGap](./definitions.md#boxgap) \| string \| number | Gap between lines when lines > 1 (TEXT variant). Spacing token, CSS string, or number. Default: 4px |
5313
+ | `height` | no | number \| string | Height in px or CSS string (BOX variant) |
5150
5314
  | `initialTimestamp` | no | number | Initial mount timestamp for animation delay calculation. Used to coordinate animations across multiple skeletons. Default: Date.now() |
5151
5315
  | `lineHeight` | no | string \| number | Line height of text skeleton for pixel-perfect match (TEXT variant). Default: 15px |
5152
5316
  | `lines` | no | number | Number of text lines (TEXT variant). Default: 1 |
5153
5317
  | `show` | no | boolean | Whether the skeleton is loading. true renders the skeleton, false renders nothing. Default: true |
5154
- | `size` | no | number | Diameter in px (CIRCLE variant). Default: 40 |
5155
- | `variant` | no | [SkeletonVariant](./definitions.md#skeletonvariant) | Skeleton shape variant. Default: TEXT |
5318
+ | `size` | no | number \| string | Diameter in px or CSS string (CIRCLE variant). Default: 40 |
5319
+ | `variant` | no | [SkeletonVariant](./definitions.md#skeletonvariant) | Skeleton shape variant. Default: text |
5156
5320
  | `width` | no | string \| number | Width of the skeleton (number in px or CSS string) |
5157
5321
 
5158
5322
  No additional properties.
@@ -5346,10 +5510,12 @@ Events: `change`, `blur`
5346
5510
  | `autoComplete` | no | string | Browser autocomplete hint. Default: off |
5347
5511
  | `autoFocus` | no | boolean | Auto-focus input on mount |
5348
5512
  | `checks` | no | [SsnCheck](./types.md#ssncheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5513
+ | `defaultValue` | no | string | Initial unmasked SSN value |
5349
5514
  | `fixedCharsPrefix` | no | string | Fixes characters at the beginning of the value |
5350
5515
  | `fixedCharsSuffix` | no | string | Fixes characters at the end of the value |
5351
5516
  | `id` | no | string | Explicit HTML element id |
5352
5517
  | `isDisabled` | no | boolean | Disables the input |
5518
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5353
5519
  | `isReadOnly` | no | boolean | Makes the input read-only |
5354
5520
  | `isRequired` | no | boolean | Marks the field as required |
5355
5521
  | `label` | no | string | Label text above the input |
@@ -5383,8 +5549,7 @@ Events: _none_
5383
5549
  |---|---:|---|---|
5384
5550
  | `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. |
5385
5551
  | `outlined` | no | boolean | When true, renders status with a border outline. Default: false |
5386
- | `size` | no | [ChipSize](./definitions.md#chipsize) | Size of the status indicator (S, M, L, XL). Default: L |
5387
- | `testId` | no | string | Test identifier for automated testing. Default: status |
5552
+ | `size` | no | [StatusSize](./definitions.md#statussize) | Size of the status indicator (S, M, L, XL). Default: L |
5388
5553
  | `text` | yes | string | Text label to display in the status indicator. Required. |
5389
5554
 
5390
5555
  No additional properties.
@@ -5438,8 +5603,7 @@ Events: `press`
5438
5603
  | `icon` | no | string | Icon type from Icon.TYPES. Default: HEADPHONES_FILLED |
5439
5604
  | `id` | no | string | DOM id selector for the button element |
5440
5605
  | `image` | no | string | Image URL displayed instead of an icon in the avatar |
5441
- | `imageBackground` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Surface color token for the avatar when using an image |
5442
- | `testId` | no | string | Sets data-testid attribute. Default: test_support_button |
5606
+ | `imageBackground` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Surface color token for the avatar when using an image |
5443
5607
  | `title` | yes | string | Primary text label displayed on the button |
5444
5608
  | `to` | no | string \| [SupportButtonTo](./types.md#supportbuttonto) | Navigation destination. When provided, button handles navigation automatically |
5445
5609
 
@@ -5449,7 +5613,7 @@ No additional properties.
5449
5613
 
5450
5614
  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.
5451
5615
 
5452
- 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.
5616
+ 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.
5453
5617
 
5454
5618
  Catalog key: `Survey`
5455
5619
  Builder: `Survey`
@@ -5464,7 +5628,9 @@ Events: `change`
5464
5628
  | `name` | no | string | Unique identifier for the input |
5465
5629
  | `caption` | no | string | Caption text displayed below the survey |
5466
5630
  | `checks` | no | [SurveyCheck](./types.md#surveycheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5631
+ | `defaultValue` | no | string \| number \| string \| number[] | Initial selected value(s) when uncontrolled |
5467
5632
  | `isDisabled` | no | boolean | Disables all survey buttons |
5633
+ | `isInvalid` | no | boolean | Marks the survey as invalid |
5468
5634
  | `isMulti` | no | boolean | Allow multiple selections. Default: false |
5469
5635
  | `isReadOnly` | no | boolean | Makes the survey read-only |
5470
5636
  | `isRequired` | no | boolean | Marks the field as required |
@@ -5507,7 +5673,7 @@ Events: `change`, `blur`
5507
5673
  | `offLabel` | no | string | Label text when switch is off |
5508
5674
  | `onLabel` | no | string | Label text when switch is on |
5509
5675
  | `rightAlign` | no | boolean | Align switch to the right |
5510
- | `tip` | no | string | Tooltip text to display |
5676
+ | `tip` | no | string \| [SwitchTip](./types.md#switchtip) | Tooltip text or basic tooltip configuration to display |
5511
5677
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5512
5678
  | `value` | no | boolean | Toggle state bound to state |
5513
5679
 
@@ -5517,7 +5683,7 @@ No additional properties.
5517
5683
 
5518
5684
  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.
5519
5685
 
5520
- 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.
5686
+ 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.
5521
5687
 
5522
5688
  Catalog key: `Tab`
5523
5689
  Builder: `Tab`
@@ -5529,24 +5695,25 @@ Events: `change`
5529
5695
 
5530
5696
  | Name | Required | Type | Description |
5531
5697
  |---|---:|---|---|
5698
+ | `activeIndex` | no | number | Controlled active tab index |
5532
5699
  | `aria-label` | no | string | Accessible label for the tabs |
5533
5700
  | `aria-labelledby` | no | string | ID of element that labels the tabs |
5534
5701
  | `defaultActiveIndex` | no | number | Tab index to be active by default |
5535
5702
  | `isCompact` | no | boolean | Use compact spacing |
5536
5703
  | `isLogoRound` | no | boolean | Whether to display logo with rounded corners |
5537
5704
  | `isVertical` | no | boolean | Display tabs in vertical orientation (only for LINK type) |
5538
- | `items` | yes | [TabItem](./types.md#tabitem)[] | Array of tab items with label, value, and optional icon/badge/tip |
5705
+ | `items` | no | [TabItem](./types.md#tabitem)[] | JSON-only selection model for state-bound tabs with title, value, and optional icon/badge/tip |
5706
+ | `list` | no | [TabList](./types.md#tablist)[] | React Tabs list branch for LINK tabs, including optional nested links |
5539
5707
  | `logoUrl` | no | string | URL of logo image to display with title |
5540
5708
  | `stretchH` | no | boolean | Stretch tabs horizontally |
5541
5709
  | `stretchV` | no | boolean | Stretch tabs vertically to fill available height |
5542
5710
  | `subtitle` | no | string | Subtitle text |
5543
- | `supportLink` | no | string | URL for support/help link |
5544
- | `testId` | no | string | Test ID for the tabs container |
5711
+ | `supportLink` | no | string \| [SupportLink](./types.md#supportlink) | Support/help link as a URL string or a serializable object branch |
5545
5712
  | `theme` | no | [TabTheme](./definitions.md#tabtheme) | Visual theme: BOX, BOX_HEADER, CENTER, GREY_OVERFLOW_GRADIENT, WHITE_OVERFLOW_GRADIENT, NO_PADDING |
5546
5713
  | `title` | no | string | Title text to display above tabs |
5547
5714
  | `titleContent` | no | string | Subtitle or additional content below the title |
5548
5715
  | `type` | no | [TabType](./definitions.md#tabtype) | Visual style: BASIC, SWITCH, LINK, or SWITCH_WITH_ICON_ONLY |
5549
- | `value` | no | unknown | Currently selected tab value bound to state |
5716
+ | `value` | no | unknown | JSON-only selected tab value metadata bound to state when using items |
5550
5717
  | `width` | no | number | Width of the tab container in pixels |
5551
5718
 
5552
5719
  No additional properties.
@@ -5555,7 +5722,7 @@ No additional properties.
5555
5722
 
5556
5723
  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.
5557
5724
 
5558
- 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.
5725
+ 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.
5559
5726
 
5560
5727
  Catalog key: `TableBasic`
5561
5728
  Builder: `TableBasic`
@@ -5567,9 +5734,9 @@ Events: _none_
5567
5734
 
5568
5735
  | Name | Required | Type | Description |
5569
5736
  |---|---:|---|---|
5570
- | `columns` | yes | [Column](./types.md#column)[] | Column definitions: {header, key, align?, width?, wrapText?} |
5737
+ | `columns` | yes | [Column](./types.md#column)[] | JSON-only table abstraction: column definitions {header, key, align?, width?, wrapText?} |
5571
5738
  | `rowHeight` | no | number | Custom height in px for all table rows |
5572
- | `rows` | yes | [Row](./types.md#row)[] | Array of row objects keyed by column key |
5739
+ | `rows` | yes | [Row](./types.md#row)[] | JSON-only table abstraction: row objects keyed by column key |
5573
5740
  | `title` | no | string | Title displayed above the table |
5574
5741
  | `width` | no | number | Table container width in px |
5575
5742
 
@@ -5607,13 +5774,13 @@ No additional properties.
5607
5774
 
5608
5775
  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.
5609
5776
 
5610
- 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.
5777
+ 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.
5611
5778
 
5612
5779
  Catalog key: `Textarea`
5613
5780
  Builder: `Textarea`
5614
5781
  Props type: `TextareaProps`
5615
5782
  Accepts children: no
5616
- Events: `change`, `blur`, `focus`
5783
+ Events: `change`, `blur`, `focus`, `keydown`
5617
5784
 
5618
5785
  ### Props
5619
5786
 
@@ -5630,6 +5797,7 @@ Events: `change`, `blur`, `focus`
5630
5797
  | `height` | no | number | Fixed height in pixels |
5631
5798
  | `id` | no | string | Unique DOM id for the textarea element |
5632
5799
  | `isDisabled` | no | boolean | Disables the input |
5800
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5633
5801
  | `isReadOnly` | no | boolean | Makes the input read-only |
5634
5802
  | `isRequired` | no | boolean | Marks the field as required |
5635
5803
  | `label` | no | string | Label text above the input |
@@ -5637,7 +5805,7 @@ Events: `change`, `blur`, `focus`
5637
5805
  | `maxLength` | no | number | Maximum character count. Default: 10000 |
5638
5806
  | `placeholder` | no | string | Placeholder text when empty |
5639
5807
  | `rows` | no | number | Number of visible text rows |
5640
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Visual theme variant |
5808
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Visual theme variant |
5641
5809
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5642
5810
  | `value` | no | string | Current text value bound to state |
5643
5811
 
@@ -5647,13 +5815,14 @@ No additional properties.
5647
5815
 
5648
5816
  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.
5649
5817
 
5650
- For dynamic suggestions from an API: bind suggestions to state, then on "change" event fetch results and write to that state path
5818
+ For dynamic suggestions from an API: bind list to state, then on "change" event fetch results and write to that state path
5651
5819
  Emits "change" on every keystroke and when a suggestion is selected, allowing you to filter/fetch suggestions as user types
5652
5820
  When user selects a suggestion from the dropdown, the value is updated to the selected option's value
5653
5821
  Use prefix/suffix for icons or text - pass Icon.TYPES names like "SEARCH_OUTLINE" or text like "@"
5654
5822
  Use inputMode to hint the virtual keyboard type on mobile devices
5655
5823
  Use stringPadding to automatically pad values (e.g., "1" → "001" with {position: "start", maxLength: 3, character: "0"})
5656
5824
  ARIA attributes support accessibility - use aria-label, aria-labelledby, or aria-describedby for screen reader labels
5825
+ Use defaultValue for uncontrolled initial content, and fuseOptions to customize Fuse.js matching.
5657
5826
  Standalone — does not register with Form; use FormTextAutoSuggest inside a Form instead.
5658
5827
 
5659
5828
  Catalog key: `TextAutoSuggest`
@@ -5675,6 +5844,8 @@ Events: `change`, `blur`, `focus`, `click`
5675
5844
  | `autoCorrect` | no | [EmailAutoCorrect](./definitions.md#emailautocorrect) | Auto-correct: off or on |
5676
5845
  | `autoFocus` | no | boolean | Auto-focus on mount |
5677
5846
  | `checks` | no | [TextAutoSuggestCheck](./types.md#textautosuggestcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5847
+ | `defaultValue` | no | string \| number | Initial value when uncontrolled |
5848
+ | `fuseOptions` | no | [TextAutoSuggestFuseOption](./types.md#textautosuggestfuseoption) | Fuse.js search options for customizing suggestion filtering |
5678
5849
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
5679
5850
  | `isDisabled` | no | boolean | Disables the input |
5680
5851
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
@@ -5682,6 +5853,7 @@ Events: `change`, `blur`, `focus`, `click`
5682
5853
  | `isReadOnly` | no | boolean | Makes the input read-only |
5683
5854
  | `isRequired` | no | boolean | Marks the field as required |
5684
5855
  | `label` | no | string | Label text above the input |
5856
+ | `list` | no | [TextAutoSuggestList](./types.md#textautosuggestlist)[] | Array of { label, value } suggestion objects matching the React list prop |
5685
5857
  | `maxLength` | no | number | Maximum character count |
5686
5858
  | `maxWidth` | no | string | Maximum width CSS value |
5687
5859
  | `minLength` | no | number | Minimum character count |
@@ -5699,8 +5871,6 @@ Events: `change`, `blur`, `focus`, `click`
5699
5871
  | `spellCheck` | no | boolean | Enable spell checking |
5700
5872
  | `stringPadding` | no | [TextAutoSuggestStringPadding](./types.md#textautosuggeststringpadding) | Pads input value with character until reaching maxLength |
5701
5873
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
5702
- | `suggestions` | no | [TextAutoSuggestSuggestion](./types.md#textautosuggestsuggestion)[] | Array of { label, value } suggestion objects |
5703
- | `testId` | no | string | Test ID for automation |
5704
5874
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
5705
5875
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5706
5876
  | `value` | no | string \| number | Current value bound to state |
@@ -5723,8 +5893,7 @@ Events: _none_
5723
5893
 
5724
5894
  | Name | Required | Type | Description |
5725
5895
  |---|---:|---|---|
5726
- | `collapseLabel` | no | string | Label for the collapse button. Default: Show less |
5727
- | `expandLabel` | no | string | Label for the expand button. Default: Show more |
5896
+ | `buttonLabels` | no | [ButtonLabel](./types.md#buttonlabel) | Labels for the expand and collapse buttons |
5728
5897
  | `maxHeight` | yes | number | Max height in px before content is clipped and expand/collapse is shown |
5729
5898
  | `theme` | no | [TextClipTheme](./definitions.md#textcliptheme) | Visual theme variant. NO_CARD removes the card styling |
5730
5899
 
@@ -5773,6 +5942,7 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
5773
5942
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
5774
5943
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
5775
5944
  | `isDisabled` | no | boolean | Disables the input |
5945
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5776
5946
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
5777
5947
  | `isReadOnly` | no | boolean | Makes the input read-only |
5778
5948
  | `isRequired` | no | boolean | Marks the field as required |
@@ -5793,7 +5963,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
5793
5963
  | `spellCheck` | no | boolean | Enable spell checking |
5794
5964
  | `stringPadding` | no | [TextInputStringPadding](./types.md#textinputstringpadding) | Pads input value with character until reaching maxLength |
5795
5965
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
5796
- | `testId` | no | string | Test ID for automation |
5797
5966
  | `theme` | no | string | Theme name from Input.Text.THEMES or custom theme |
5798
5967
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5799
5968
  | `value` | no | string | Current text value bound to state |
@@ -5828,13 +5997,13 @@ No additional properties.
5828
5997
 
5829
5998
  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.
5830
5999
 
5831
- 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.
6000
+ 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.
5832
6001
 
5833
6002
  Catalog key: `Time`
5834
6003
  Builder: `Time`
5835
6004
  Props type: `TimeProps`
5836
6005
  Accepts children: no
5837
- Events: `change`, `blur`
6006
+ Events: `change`, `blur`, `inferredTimeChange`
5838
6007
 
5839
6008
  ### Props
5840
6009
 
@@ -5847,8 +6016,12 @@ Events: `change`, `blur`
5847
6016
  | `aria-labelledby` | no | string | ARIA labelledby reference for accessibility |
5848
6017
  | `checks` | no | [TimeCheck](./types.md#timecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
5849
6018
  | `defaultSelectionStartTime` | no | string | Time to start the selection scroll from when shouldAllowTimeSelection is true (e.g. "08:00 AM") |
6019
+ | `defaultValue` | no | string | Initial time value when uncontrolled |
6020
+ | `id` | no | string | HTML id attribute for the input |
6021
+ | `inferredTime` | no | string | JSON-only inferred time metadata written before inferredTimeChange emits |
5850
6022
  | `isDateTimeInline` | no | boolean | Make input inline, removes border, padding and width fits input/placeholder content |
5851
6023
  | `isDisabled` | no | boolean | Disables the input |
6024
+ | `isInvalid` | no | boolean | Marks the input as invalid |
5852
6025
  | `isReadOnly` | no | boolean | Makes the input read-only |
5853
6026
  | `isRequired` | no | boolean | Marks the field as required |
5854
6027
  | `label` | no | string | Label text above the input |
@@ -5856,7 +6029,7 @@ Events: `change`, `blur`
5856
6029
  | `maxWidth` | no | string | Maximum width CSS value |
5857
6030
  | `pickClosestMeridiem` | no | boolean | When user does not enter AM/PM, pick the closest meridiem to the inputted hour value. Default: false |
5858
6031
  | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
5859
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times |
6032
+ | `shouldAllowTimeSelection` | no | boolean \| [TimeShouldAllowTimeSelection](./types.md#timeshouldallowtimeselection) | Show a time selection dropdown for picking times |
5860
6033
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time input |
5861
6034
  | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly |
5862
6035
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
@@ -5864,7 +6037,7 @@ Events: `change`, `blur`
5864
6037
  | `shouldShowTimezoneLabel` | no | boolean | If false, timezone label will not be shown. Default: true |
5865
6038
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
5866
6039
  | `theme` | no | string | Custom theme to apply to the input |
5867
- | `timezone` | no | string | Show time relative to this timezone (IANA identifier) |
6040
+ | `timezone` | no | string \| [TimeTimezone](./types.md#timetimezone) | Show time relative to this timezone or configure the timezone selector |
5868
6041
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
5869
6042
  | `value` | no | string | Time value bound to state (ISO 8601 or HH:mm format) |
5870
6043
 
@@ -5897,13 +6070,15 @@ Events: `change`, `blur`
5897
6070
  | `defaultValue` | no | unknown[] | Initial time range when uncontrolled [startTime, endTime] |
5898
6071
  | `hideDayDifference` | no | boolean | Hides the next day indicator when end time is on the next day. Default: false (indicator is shown) |
5899
6072
  | `hideTimeIcon` | no | boolean | Hides the prefix clock icon in the input. Default: false |
6073
+ | `id` | no | string | HTML id attribute for the input |
5900
6074
  | `isDisabled` | no | boolean | Disables the input |
6075
+ | `isInvalid` | no | boolean | Marks the input as invalid |
5901
6076
  | `isReadOnly` | no | boolean | Makes the input read-only |
5902
6077
  | `isRequired` | no | boolean | Marks the field as required |
5903
6078
  | `label` | no | string | Label text above the input |
5904
6079
  | `locale` | no | string | Locale string for time formatting (e.g. en-US) |
5905
6080
  | `referenceDate` | no | string | ISO date string used as reference for timezone calculations and DST determination. Defaults to current date. |
5906
- | `shouldAllowTimeSelection` | no | boolean | Show a time selection dropdown for picking times. Default: true |
6081
+ | `shouldAllowTimeSelection` | no | boolean \| [TimeRangeShouldAllowTimeSelection](./types.md#timerangeshouldallowtimeselection) | Show a time selection dropdown for picking times. Default: true |
5907
6082
  | `shouldDisplaySeconds` | no | boolean | Display seconds in the time inputs |
5908
6083
  | `shouldFormatInTimezone` | no | boolean | If true, values will transform according to global timezone when timezone prop is not passed explicitly. Default: true |
5909
6084
  | `shouldLocalize` | no | boolean | If true, display format will be determined from user locale setting |
@@ -5939,6 +6114,7 @@ Events: `change`, `blur`, `focus`
5939
6114
  | `dropdownHeight` | no | number | Height of the dropdown menu in pixels |
5940
6115
  | `emptyListPlaceholder` | no | string | Placeholder text shown when no timezone matches the search |
5941
6116
  | `isDisabled` | no | boolean | Disables the input |
6117
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
5942
6118
  | `isMenuDefaultOpen` | no | boolean | If true, the dropdown menu will be open by default on mount |
5943
6119
  | `isPositionFixed` | no | boolean | Use fixed positioning for dropdown (useful in scrollable containers) |
5944
6120
  | `isReadOnly` | no | boolean | Makes the input read-only |
@@ -5994,13 +6170,13 @@ No additional properties.
5994
6170
 
5995
6171
  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.
5996
6172
 
5997
- 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.
6173
+ 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.
5998
6174
 
5999
6175
  Catalog key: `TitleCaption`
6000
6176
  Builder: `TitleCaption`
6001
6177
  Props type: `TitleCaptionProps`
6002
6178
  Accepts children: no
6003
- Events: _none_
6179
+ Events: `press`
6004
6180
 
6005
6181
  ### Props
6006
6182
 
@@ -6016,13 +6192,13 @@ No additional properties.
6016
6192
 
6017
6193
  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.
6018
6194
 
6019
- 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.
6195
+ 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.
6020
6196
 
6021
6197
  Catalog key: `ToggleableArrow`
6022
6198
  Builder: `ToggleableArrow`
6023
6199
  Props type: `ToggleableArrowProps`
6024
6200
  Accepts children: no
6025
- Events: _none_
6201
+ Events: `change`
6026
6202
 
6027
6203
  ### Props
6028
6204
 
@@ -6047,7 +6223,7 @@ No additional properties.
6047
6223
 
6048
6224
  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.
6049
6225
 
6050
- 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.
6226
+ 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.
6051
6227
 
6052
6228
  Catalog key: `Tree`
6053
6229
  Builder: `Tree`
@@ -6065,6 +6241,7 @@ Events: `change`, `footerAction`
6065
6241
  | `aria-labelledby` | no | string | ID of element that labels this tree |
6066
6242
  | `canSelectAll` | no | boolean | Show select all toggle in multi mode |
6067
6243
  | `checks` | no | [TreeCheck](./types.md#treecheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
6244
+ | `defaultValue` | no | string \| string[] | Initial selected value(s) when uncontrolled |
6068
6245
  | `dropdownWidth` | no | number | Override internal dropdown width in pixels |
6069
6246
  | `emptyListPlaceholder` | no | string | Placeholder text when list is empty |
6070
6247
  | `footer` | no | [TreeFooter](./types.md#treefooter) | Fixed footer with clickable action at bottom of tree |
@@ -6094,7 +6271,7 @@ No additional properties.
6094
6271
 
6095
6272
  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.
6096
6273
 
6097
- 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.
6274
+ 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.
6098
6275
 
6099
6276
  Catalog key: `TreeSelect`
6100
6277
  Builder: `TreeSelect`
@@ -6137,7 +6314,7 @@ Events: `change`
6137
6314
  | `shouldShowFolderStructure` | no | boolean | Renders folder structure view |
6138
6315
  | `shouldShowSelectionPath` | no | boolean | Show parent-to-child path in selected chips. Default: false |
6139
6316
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size. Default: M |
6140
- | `theme` | no | [FormTextareaTheme](./definitions.md#formtextareatheme) | Custom theme styling |
6317
+ | `theme` | no | [DateTheme](./definitions.md#datetheme) | Custom theme styling |
6141
6318
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
6142
6319
  | `value` | no | string \| string[] \| null | Selected value(s). Single string when isMulti is false, array when true |
6143
6320
 
@@ -6183,7 +6360,7 @@ Events: _none_
6183
6360
  |---|---:|---|---|
6184
6361
  | `align` | no | [HStackAlign](./definitions.md#hstackalign) | Cross-axis alignment |
6185
6362
  | `alignSelf` | no | [HStackAlignSelf](./definitions.md#hstackalignself) | Align self override when inside a flex parent |
6186
- | `backgroundColor` | no | [AvatarFlagSurfaceColor](./definitions.md#avatarflagsurfacecolor) | Background surface color token |
6363
+ | `backgroundColor` | no | [AvatarImageBackground](./definitions.md#avatarimagebackground) | Background surface color token |
6187
6364
  | `basis` | no | number \| string | Flex basis value |
6188
6365
  | `boxSizing` | no | [HStackBoxSizing](./definitions.md#hstackboxsizing) | Box sizing model |
6189
6366
  | `color` | no | [ActionCardIconColor](./definitions.md#actioncardiconcolor) | Text/icon color token |
@@ -6239,9 +6416,10 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
6239
6416
  | `autoFocus` | no | boolean | Auto-focus on mount |
6240
6417
  | `checks` | no | [WorkEmailCheck](./types.md#workemailcheck)[] | Array of {type, message, args?} validation rule objects. Requires validateOn to be set |
6241
6418
  | `defaultValue` | no | string | Initial default value for uncontrolled usage |
6242
- | `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 |
6419
+ | `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 |
6243
6420
  | `inputMode` | no | [EmailInputMode](./definitions.md#emailinputmode) | Virtual keyboard type hint |
6244
6421
  | `isDisabled` | no | boolean | Disables the input |
6422
+ | `isInvalid` | no | boolean | Shows invalid styling (in addition to validation) |
6245
6423
  | `isOriginalInputReadOnly` | no | boolean | Sets readonly mode directly on input HTML element |
6246
6424
  | `isReadOnly` | no | boolean | Makes the input read-only |
6247
6425
  | `isRequired` | no | boolean | Marks the field as required |
@@ -6260,7 +6438,6 @@ Events: `change`, `blur`, `focus`, `click`, `keydown`, `keyup`, `paste`, `mousee
6260
6438
  | `size` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Input size variant. Default: M |
6261
6439
  | `spellCheck` | no | boolean | Enable spell checking |
6262
6440
  | `suffix` | no | string | Text or icon name from Icon.TYPES to show after the input value |
6263
- | `testId` | no | string | Test ID for automation |
6264
6441
  | `theme` | no | string | Theme name from Input.WorkEmail.THEMES or custom theme |
6265
6442
  | `validateOn` | no | [AppGroupSelectValidateOn](./definitions.md#appgroupselectvalidateon) | When to run validation checks. Requires checks to be set |
6266
6443
  | `value` | no | string | Current work email value bound to state |