@rippling/pebble-sdui-web 0.15.1 → 0.18.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.
@@ -3,6 +3,34 @@
3
3
 
4
4
  Import action creators from `@rippling/pebble-sdui-web/catalogs/custom-apps`. Read [definitions.md](./definitions.md) for enum values linked from param tables.
5
5
 
6
+ ## invalidateSuperGridData
7
+
8
+ Invalidate cached SuperGrid data for a grid and request a backend cache bust.
9
+
10
+ Use after an SDUI mutation changes rows displayed by a SuperGrid.
11
+ Run this after any prerequisite actions, such as triggerApi, in an ordered event action array or runActions chain.
12
+ The action invalidates SuperGrid data and dropdown queries for gridId. Backend cache bust is attempted when the grid supports it.
13
+
14
+ Catalog key: `invalidateSuperGridData`
15
+ Creator: `invalidateSuperGridData`
16
+ Params type: `InvalidateSuperGridDataParams`
17
+
18
+ ### Params
19
+
20
+ | Name | Required | Type | Description |
21
+ |---|---:|---|---|
22
+ | `gridId` | yes | string | SuperGrid id whose cached data and dropdown queries should be invalidated. |
23
+
24
+ No additional properties.
25
+
26
+ ### Usage Shape
27
+
28
+ ```ts
29
+ on: {
30
+ press: invalidateSuperGridData({ ... })
31
+ }
32
+ ```
33
+
6
34
  ## navigate
7
35
 
8
36
  Navigate to a URL path.
@@ -201,9 +201,9 @@ No additional properties.
201
201
 
202
202
  ## AppNavBar
203
203
 
204
- Application navigation bar with routing support. Displays a horizontal tab bar or vertical sidebar with links, icons, badges, and optional nested sub-navigation. Use for top-level page navigation.
204
+ Application navigation bar with optional routing. Displays a header without tabs when links are omitted or empty. With links, it displays a horizontal tab bar or vertical sidebar with icons, badges, and optional nested sub-navigation.
205
205
 
206
- AppNavBar renders a navigation bar using Tabs.LINK internally. Links can be flat or nested (via the links field on each nav item). In vertical mode, items with isSection: true render as non-interactive section headers. Use $bindState on activeUrl to two-way bind the active tab path to state — it updates automatically when the user clicks a nav item. Use baseURL to prefix all paths. Use theme to control padding and borders.
206
+ AppNavBar renders a navigation bar using Tabs.LINK internally. Links can be flat or nested (via the links field on each nav item). In vertical mode, items with isSection: true render as non-interactive section headers. Use $bindState on activeUrl to two-way bind the active tab path to state — it updates automatically when the user clicks a nav item. Use baseURL to prefix all paths. Use theme to control padding and borders.Omit links or pass an empty array to render the title, actions, and children without a tab list
207
207
 
208
208
  Catalog key: `AppNavBar`
209
209
  Builder: `AppNavBar`
@@ -221,7 +221,7 @@ Events: `navigate`, `action`
221
221
  | `baseURL` | no | string | Base URL prefix prepended to all link paths |
222
222
  | `isLogoRound` | no | boolean | If true, logo has rounded corners |
223
223
  | `isVertical` | no | boolean | If true, renders a vertical sidebar navigation instead of horizontal tabs |
224
- | `links` | yes | Record<string, unknown>[] | Array of navigation items defining the nav structure |
224
+ | `links` | no | Record<string, unknown>[] | Navigation items. Omit or pass an empty array to render the header without tabs |
225
225
  | `logoUrl` | no | string | URL for a logo image in the header area |
226
226
  | `shouldPersistQueryParams` | no | boolean | If true, existing query parameters are preserved across navigation |
227
227
  | `size` | no | number | Fixed width in pixels for horizontal layout. 0 or omitted for fluid width |
@@ -1367,18 +1367,19 @@ No additional properties.
1367
1367
 
1368
1368
  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.
1369
1369
 
1370
- 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.
1370
+ 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 clickedValue to state to capture the last clicked item value for action-menu usage; the action event fires after clickedValue is updated. 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}. The trigger supports three modes: label-only with triggerLabel, icon-only with triggerIcon, and icon-plus-label with both triggerIcon and triggerLabel. Provide triggerAriaLabel for icon-only triggers. Use triggerSize to control the trigger button size. Set showSelectedLabel to true to replace the visible trigger label with the selected option label; when triggerIcon is provided without triggerLabel, the trigger stays icon-only.
1371
1371
 
1372
1372
  Catalog key: `Dropdown`
1373
1373
  Builder: `Dropdown`
1374
1374
  Props type: `DropdownProps`
1375
1375
  Accepts children: no
1376
- Events: `change`, `toggle`
1376
+ Events: `change`, `toggle`, `action`
1377
1377
 
1378
1378
  ### Props
1379
1379
 
1380
1380
  | Name | Required | Type | Description |
1381
1381
  |---|---:|---|---|
1382
+ | `clickedValue` | no | unknown | Bindable last clicked item value, written before the action event emits |
1382
1383
  | `defaultValue` | no | unknown | Initially selected value |
1383
1384
  | `dropdownIsOpen` | no | boolean | Bindable state written when the dropdown opens or closes |
1384
1385
  | `footer` | no | [DropdownFooter](./types.md#dropdownfooter) | Footer item rendered at the bottom of the list |
@@ -1391,7 +1392,10 @@ Events: `change`, `toggle`
1391
1392
  | `shouldAutoClose` | no | boolean | Auto-close after item selection |
1392
1393
  | `shouldCloseOnScroll` | no | boolean | Close on document scroll |
1393
1394
  | `showSelectedLabel` | no | boolean | Display the selected option label in the trigger. Defaults to false; empty or unmatched values use triggerLabel |
1394
- | `triggerLabel` | yes | string | Label for the dropdown trigger button |
1395
+ | `triggerAriaLabel` | no | string | Accessible label for the trigger button. Recommended for icon-only triggers. |
1396
+ | `triggerIcon` | no | string | Icon.TYPES name to render in the dropdown trigger button. Provide it for icon-only or icon-plus-label triggers. |
1397
+ | `triggerLabel` | no | string | Visible label for the dropdown trigger button. Omit it for an icon-only trigger. |
1398
+ | `triggerSize` | no | [AppGroupSelectSize](./definitions.md#appgroupselectsize) | Size of the trigger button (XS, S, M, L). Default: M |
1395
1399
  | `value` | no | unknown | Currently selected value. Bind to state for selection tracking |
1396
1400
  | `width` | no | number | Width of the dropdown list in px. Default: 192 |
1397
1401
 
@@ -1650,7 +1654,7 @@ No additional properties.
1650
1654
 
1651
1655
  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.
1652
1656
 
1653
- 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.
1657
+ 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. maxFiles limits the total selected files across the current value plus new picks; extra files are ignored and the user is told to remove a file before adding another. When multiple is false, only one file is stored.
1654
1658
 
1655
1659
  Catalog key: `FileDrop`
1656
1660
  Builder: `FileDrop`
@@ -1677,6 +1681,7 @@ Events: `change`, `blur`
1677
1681
  | `isReadOnly` | no | boolean | Makes the file input read-only |
1678
1682
  | `isRequired` | no | boolean | Marks the field as required |
1679
1683
  | `label` | no | string | Label text above the file drop area |
1684
+ | `maxFiles` | no | number | Max number of files allowed in total |
1680
1685
  | `maxFileSize` | no | number | Max file size in MB per attachment |
1681
1686
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
1682
1687
  | `metadata` | no | unknown | JSON-serializable metadata sent with upload requests |
@@ -2200,6 +2205,8 @@ Use `validationErrors` to override default error messages per rule.
2200
2205
  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" }`.
2201
2206
  onChange emits "change"; onBlur emits "blur".
2202
2207
  supportTypes expects file extensions with dot prefix, e.g. [".pdf", ".png", ".jpg"]. Do NOT use MIME types.
2208
+ maxFiles counts files already in the field and newly selected files together; extra files are ignored until a file is removed.
2209
+ Use metadata to pass JSON-serializable upload context through to the underlying FileDrop upload flow.
2203
2210
 
2204
2211
  Catalog key: `FormFileDrop`
2205
2212
  Builder: `FormFileDrop`
@@ -2221,8 +2228,10 @@ Events: `change`, `blur`
2221
2228
  | `isReadOnly` | no | boolean | Makes the input read-only |
2222
2229
  | `isRequired` | no | boolean | Marks field required and blocks form submit when empty |
2223
2230
  | `label` | no | string | Label text above the file drop area |
2231
+ | `maxFiles` | no | number | Max number of files allowed in total |
2224
2232
  | `maxFileSize` | no | number | Max file size in MB per attachment |
2225
2233
  | `maxTotalFileSize` | no | number | Max total size in MB for all attachments |
2234
+ | `metadata` | no | unknown | JSON-serializable metadata sent with upload requests |
2226
2235
  | `multiPartUpload` | no | boolean | Enables multipart upload flow for files larger than 100MB |
2227
2236
  | `multiple` | no | boolean | Allow selecting multiple files |
2228
2237
  | `placeholder` | no | string | Text shown when no files are selected |
@@ -3678,6 +3687,26 @@ Events: _none_
3678
3687
 
3679
3688
  No additional properties.
3680
3689
 
3690
+ ## Interval
3691
+
3692
+ Emits a tick event repeatedly after the configured delay. Renders no UI and stops when unmounted.
3693
+
3694
+ Bind an action to on.tick. The first tick fires after delay milliseconds, matching window.setInterval.
3695
+
3696
+ Catalog key: `Interval`
3697
+ Builder: `Interval`
3698
+ Props type: `IntervalProps`
3699
+ Accepts children: no
3700
+ Events: `tick`
3701
+
3702
+ ### Props
3703
+
3704
+ | Name | Required | Type | Description |
3705
+ |---|---:|---|---|
3706
+ | `delay` | yes | number | Time in milliseconds between tick events. |
3707
+
3708
+ No additional properties.
3709
+
3681
3710
  ## ItemNavigator
3682
3711
 
3683
3712
  A compact control for stepping through items one at a time, with either an "X of Y items" label or clickable position dots. Use for sequential item-by-item navigation such as cycling through detail views, carousel items, search results, or review queues — not for page-based navigation (use Pagination instead).
@@ -4928,7 +4957,7 @@ A responsive 12-column grid for dashboard widgets that supports drag-to-rearrang
4928
4957
 
4929
4958
  **Children:** Each direct child element's spec id must match an entry in this board's `layouts` array. Children with no matching layout entry are dropped silently — keep the two in sync.
4930
4959
 
4931
- **Layouts:** Each layout entry carries a unique `identifier` (= the matched child's spec id), optional `x`/`y` position in grid units, the size in grid units (width 1–12, height in row-height multiples), optional `minWidth`/`maxWidth`/`minHeight`/`maxHeight` constraints, and optional per-block styling (`border`, `shadow`, `shapeCorner`). When `x` or `y` is omitted, the board auto-calculates that coordinate.
4960
+ **Layouts:** Each layout entry carries a unique `identifier` (= the matched child's spec id), optional `x`/`y` position in grid units, the size in grid units (width 1–12 with a default of 3, height in row-height multiples), optional `minWidth`/`maxWidth`/`minHeight`/`maxHeight` constraints, and optional per-block styling (`border`, `shadow`, `shapeCorner`). `minWidth` defaults to 1. When `x` or `y` is omitted, the board auto-calculates that coordinate.
4932
4961
 
4933
4962
  **Uniform styling:** Use top-level `blockShapeCorner` when every block should share the same border-radius; per-entry `shapeCorner` overrides it for that block only.
4934
4963
 
@@ -5555,6 +5584,43 @@ Events: `click`
5555
5584
 
5556
5585
  No additional properties.
5557
5586
 
5587
+ ## SuperGrid
5588
+
5589
+ Server-configured data grid. The backend owns column definitions, sorting, search, quick filters, and empty-state messaging — only `gridId` is required. Use `contextFilters` to scope rows and filter options from external page state (e.g. a record selector).
5590
+
5591
+ gridId: required. Must match a registered SuperGrid id on the backend. The frontend fetches column config and data automatically.
5592
+ configContext: optional query context sent when fetching config. Use it for backend-owned dynamic config variants such as title, caption, or empty-state text.
5593
+ contextFilters: optional array of { field, operation, value } filters merged into every data and filter-dropdown query. Use to pre-scope the grid from page-level state without requiring the user to apply filters manually.
5594
+ width: optional CSS width string or pixel number passed to the underlying Grid.
5595
+ height: optional CSS height string. Omit to let the grid auto-size. Pass an explicit value (e.g. "500px") when embedding inside a fixed-height container.
5596
+ caption: optional sub-title rendered beneath the grid title. Falls back to the backend-configured caption when omitted.
5597
+ rowActions: optional static row action configs. Dynamic per-row factories are not supported in SDUI; use booleans for isDisabled/isHidden.
5598
+ Events do not receive payload arguments. Bind rowClickedData, rowActionClickedId, or rowActionClickedData with $bindState, then read those paths with $state inside rowClick or rowActionClick actions.
5599
+ SuperGrid writes the bound clicked state before emitting rowClick or rowActionClick.
5600
+
5601
+ Catalog key: `SuperGrid`
5602
+ Builder: `SuperGrid`
5603
+ Props type: `SuperGridProps`
5604
+ Accepts children: no
5605
+ Events: `rowClick`, `rowActionClick`
5606
+
5607
+ ### Props
5608
+
5609
+ | Name | Required | Type | Description |
5610
+ |---|---:|---|---|
5611
+ | `caption` | no | string | Optional caption rendered below the grid title. |
5612
+ | `configContext` | no | [ConfigContext](./types.md#configcontext) | Query context sent to dynamic config modifiers for backend-owned variants. |
5613
+ | `contextFilters` | no | [ContextFilter](./types.md#contextfilter)[] | Filters derived from external state that scope data and filter-dropdown queries. Applied in addition to any user-applied filters. |
5614
+ | `gridId` | yes | string | Unique identifier for the grid configuration fetched from the backend. |
5615
+ | `height` | no | string | Any CSS height string (e.g. "400px", "60vh"). When omitted the grid auto-sizes to its rows. |
5616
+ | `rowActionClickedData` | no | unknown | Bind to state with $bindState to receive clicked row action row data before rowActionClick emits. |
5617
+ | `rowActionClickedId` | no | string | Bind to state with $bindState to receive the clicked row action id before rowActionClick emits. |
5618
+ | `rowActions` | no | [RowAction](./types.md#rowaction)[] | Static row action buttons. On click, SuperGrid writes rowActionClickedId and rowActionClickedData before emitting rowActionClick. |
5619
+ | `rowClickedData` | no | unknown | Bind to state with $bindState to receive clicked row data before rowClick emits. |
5620
+ | `width` | no | string \| number | Grid width as a CSS width string or pixel number. |
5621
+
5622
+ No additional properties.
5623
+
5558
5624
  ## SupportButton
5559
5625
 
5560
5626
  A prominent card-like action button with title, caption, icon or image, and optional badge for dashboard entry points.
@@ -281,6 +281,7 @@ Referenced by:
281
281
  | component | `Currency` | `size` |
282
282
  | component | `Date` | `size` |
283
283
  | component | `DateRange` | `size` |
284
+ | component | `Dropdown` | `triggerSize` |
284
285
  | component | `Email` | `size` |
285
286
  | component | `FloatingButton` | `size` |
286
287
  | component | `FormDate` | `size` |
@@ -1598,6 +1599,38 @@ Referenced by:
1598
1599
  | type | `LabelValue` | `size` |
1599
1600
  | type | `ObjectUIStatsProp` | `size` |
1600
1601
 
1602
+ ## ContextFilterOperation
1603
+
1604
+ TypeScript type:
1605
+
1606
+ ```ts
1607
+ "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "in" | "ni" | "contains" | "starts_with" | "ends_with" | "is_empty" | "is_not_empty"
1608
+ ```
1609
+
1610
+ Allowed values:
1611
+
1612
+ | Value |
1613
+ |---|
1614
+ | `eq` |
1615
+ | `ne` |
1616
+ | `gt` |
1617
+ | `ge` |
1618
+ | `lt` |
1619
+ | `le` |
1620
+ | `in` |
1621
+ | `ni` |
1622
+ | `contains` |
1623
+ | `starts_with` |
1624
+ | `ends_with` |
1625
+ | `is_empty` |
1626
+ | `is_not_empty` |
1627
+
1628
+ Referenced by:
1629
+
1630
+ | Kind | Entity | Field |
1631
+ |---|---|---|
1632
+ | type | `ContextFilter` | `operation` |
1633
+
1601
1634
  ## CountryIconAlignment
1602
1635
 
1603
1636
  TypeScript type:
@@ -3544,6 +3577,69 @@ Referenced by:
3544
3577
  |---|---|---|
3545
3578
  | component | `Responsive` | `mode` |
3546
3579
 
3580
+ ## RowActionAppearance
3581
+
3582
+ TypeScript type:
3583
+
3584
+ ```ts
3585
+ "OUTLINE" | "GHOST"
3586
+ ```
3587
+
3588
+ Allowed values:
3589
+
3590
+ | Value |
3591
+ |---|
3592
+ | `OUTLINE` |
3593
+ | `GHOST` |
3594
+
3595
+ Referenced by:
3596
+
3597
+ | Kind | Entity | Field |
3598
+ |---|---|---|
3599
+ | type | `RowAction` | `appearance` |
3600
+
3601
+ ## RowActionPlacement
3602
+
3603
+ TypeScript type:
3604
+
3605
+ ```ts
3606
+ "inline" | "menu"
3607
+ ```
3608
+
3609
+ Allowed values:
3610
+
3611
+ | Value |
3612
+ |---|
3613
+ | `inline` |
3614
+ | `menu` |
3615
+
3616
+ Referenced by:
3617
+
3618
+ | Kind | Entity | Field |
3619
+ |---|---|---|
3620
+ | type | `RowAction` | `placement` |
3621
+
3622
+ ## RowActionType
3623
+
3624
+ TypeScript type:
3625
+
3626
+ ```ts
3627
+ "Button" | "IconButton"
3628
+ ```
3629
+
3630
+ Allowed values:
3631
+
3632
+ | Value |
3633
+ |---|
3634
+ | `Button` |
3635
+ | `IconButton` |
3636
+
3637
+ Referenced by:
3638
+
3639
+ | Kind | Entity | Field |
3640
+ |---|---|---|
3641
+ | type | `RowAction` | `type` |
3642
+
3547
3643
  ## SegmentSegmentColor
3548
3644
 
3549
3645
  TypeScript type:
@@ -2,7 +2,7 @@
2
2
  # custom-apps Catalog
3
3
 
4
4
  Catalog: `custom-apps`
5
- Version: `1.5.3`
5
+ Version: `1.9.1`
6
6
  SDK language: `typescript`
7
7
 
8
8
  Use this catalog index after you have chosen this catalog for the spec. Do not mix components, actions, computed functions, or render helpers from another catalog unless that catalog explicitly documents compatibility.
@@ -693,6 +693,28 @@ No additional properties.
693
693
 
694
694
  No additional properties.
695
695
 
696
+ ## ConfigContext
697
+
698
+ Query context sent to dynamic config modifiers for backend-owned variants.
699
+
700
+ ### Fields
701
+
702
+ _No fields._
703
+
704
+ Additional properties: string.
705
+
706
+ ## ContextFilter
707
+
708
+ ### Fields
709
+
710
+ | Name | Required | Type | Description |
711
+ |---|---:|---|---|
712
+ | `field` | yes | string | |
713
+ | `operation` | yes | [ContextFilterOperation](./definitions.md#contextfilteroperation) | |
714
+ | `value` | yes | unknown | |
715
+
716
+ No additional properties.
717
+
696
718
  ## CountryIcon
697
719
 
698
720
  ### Fields
@@ -2901,7 +2923,7 @@ No additional properties.
2901
2923
  | `maxHeight` | no | number | Maximum height in grid units |
2902
2924
  | `maxWidth` | no | number | Maximum width in grid units |
2903
2925
  | `minHeight` | no | number | Minimum height in grid units |
2904
- | `minWidth` | no | number | Minimum width in grid units |
2926
+ | `minWidth` | no | number | Minimum width in grid units. Default: 1 |
2905
2927
  | `shadow` | no | [LayoutValueShadow](./definitions.md#layoutvalueshadow) | Shadow token applied to the block wrapper, e.g. "shadowSm". |
2906
2928
  | `shapeCorner` | no | [BoxRadius](./definitions.md#boxradius) | Shape-corner radius token for this block, e.g. "shapeCornerMd". Overrides the parent board `blockShapeCorner` for this entry only. |
2907
2929
  | `width` | no | number | Width in grid units (1–12). Default: 3 |
@@ -3632,6 +3654,25 @@ _No fields._
3632
3654
 
3633
3655
  Additional properties: string | number | boolean | null.
3634
3656
 
3657
+ ## RowAction
3658
+
3659
+ ### Fields
3660
+
3661
+ | Name | Required | Type | Description |
3662
+ |---|---:|---|---|
3663
+ | `appearance` | no | [RowActionAppearance](./definitions.md#rowactionappearance) | Button appearance. Defaults to GHOST. |
3664
+ | `icon` | no | string | Icon name from Icon.TYPES, such as EDIT_OUTLINE. |
3665
+ | `iconColor` | no | string | Icon color token or CSS color string. |
3666
+ | `id` | yes | string | Unique identifier for the row action. |
3667
+ | `isDisabled` | no | boolean | Disable the action for every row. |
3668
+ | `isHidden` | no | boolean | Hide the action for every row. |
3669
+ | `label` | yes | string | Visible label for the row action. |
3670
+ | `placement` | no | [RowActionPlacement](./definitions.md#rowactionplacement) | Where the action is rendered. Defaults to the Grid row-actions behavior. |
3671
+ | `tip` | no | string | Tooltip text for the action. |
3672
+ | `type` | no | [RowActionType](./definitions.md#rowactiontype) | Button style to render. Defaults to Button. |
3673
+
3674
+ No additional properties.
3675
+
3635
3676
  ## Segment
3636
3677
 
3637
3678
  ### Fields
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rippling/pebble-sdui-web",
3
- "version": "0.15.1",
3
+ "version": "0.18.1",
4
4
  "description": "Type-safe TypeScript web SDK for authoring json-render specs",
5
5
  "repository": {
6
6
  "type": "git",