@cube-dev/ui-kit 0.186.1 → 0.187.0

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.187.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.187.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.186.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.187.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.186.1";
+const VERSION = "0.187.0";
 const TASTY_VERSION = "3.9.3";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/fields/ComboBox.md

@@ -35,6 +35,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or false to disable filtering. If not provided, uses default contains filter
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`necessityIndicator`** `'label' | 'icon'` — How the required state should be indicated
 - **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes
 - **`onInputChange`** `(value: string) => void` — Callback fired when the input text changes

package/docs/components/fields/CommandTextArea.md

@@ -61,6 +61,7 @@ Supports all [Field properties](../../FieldProperties.md) (`label`, `name`, `isR
 - **`optionStyles`** — Styles for individual options.
 - **`sectionStyles`** — Styles for section containers.
 - **`headingStyles`** — Styles for section headings.
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 
 ### Style Properties
 

package/docs/components/fields/FilterListBox.md

@@ -26,6 +26,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — FilterListBox size
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`searchPlaceholder`** `string` (default: `Search...`) — Placeholder text in the search input
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or `false` to disable filtering
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state

package/docs/components/fields/FilterPicker.md

@@ -41,6 +41,7 @@ Choose a different component when the interaction has another shape:
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Button styling type
 - **`theme`** `'default' | 'special'` (default: `default`) — Button theme
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`searchPlaceholder`** `string` — Placeholder text in the search input
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results

package/docs/components/fields/ListBox.md

@@ -29,12 +29,14 @@ A versatile list selection component that allows users to select one or more ite
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ListBox size
 - **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`filter`** `(nodes: Iterable<Node>) => Iterable<Node>` — Filter function for the list items
 - **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
 - **`focusOnHover`** `boolean` (default: `true`) — Whether moving the pointer over an option will move DOM focus to that option
 - **`shouldUseVirtualFocus`** `boolean` (default: `false`) — Whether to use virtual focus instead of DOM focus
+- **`isFocusWithin`** `boolean` — For a list whose focused option is moved from an input outside it: whether focus is within that input's component
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection mode
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
 - **`description`** `string` — Field description
@@ -69,7 +71,7 @@ Customizes the root wrapper element of the component.
 
 #### listStyles
 
-Customizes the list container element.
+Customizes the list container element. The list keeps `.5x` of padding below its last option; `listStyles={{ padding: 0 }}` takes it away.
 
 #### optionStyles
 
@@ -180,6 +182,13 @@ The `mods` property accepts the following modifiers you can override:
 - Use `plain` when embedding ListBox directly into another component
 - Use `popover` when using ListBox inside overlays (Dialog, ComboBox, Picker)
 
+**listGap** (`number`, default: a hairline, `1bw`)
+
+- The space between options, in pixels
+- Use it rather than a margin in `optionStyles`: a flat list is virtualized and positions its options itself, so it ignores their margins
+- Card-like options (`type="outline"`, `shape="card"`) usually want `4` or more, so each one reads as its own choice
+- FilterListBox, Picker, FilterPicker, ComboBox, SearchComboBox, TagInput and CommandTextArea pass it to their ListBox. Select takes it too
+
 ### Focus and Interaction
 
 **focusOnHover** (`boolean`, default: `true`)
@@ -192,6 +201,12 @@ The `mods` property accepts the following modifiers you can override:
 - When `true`, uses virtual focus for keyboard navigation
 - DOM focus stays outside individual option elements (useful for searchable lists)
 
+**isFocusWithin** (`boolean`)
+
+- For a list whose focused option is moved from an input outside it, as FilterListBox's search input does
+- The focused option shows as focused only while this is `true`
+- Unset, the list's own focus decides; with `shouldUseVirtualFocus`, the focused option always shows
+
 **shouldFocusWrap** (`boolean`, default: `false`)
 
 - When `true`, keyboard navigation wraps around when reaching the end of the list
@@ -592,6 +607,22 @@ const [selectedKey, setSelectedKey] = useState('apple');
 </ListBox>
 ```
 
+### Option Gap
+
+```jsx
+<ListBox label="Permission" listGap={4} defaultSelectedKey="read">
+  <ListBox.Item key="read" type="outline" shape="card" description="View content and data">
+    Read
+  </ListBox.Item>
+  <ListBox.Item key="write" type="outline" shape="card" description="Create and edit content">
+    Write
+  </ListBox.Item>
+  <ListBox.Item key="delete" type="outline" shape="card" description="Remove content permanently">
+    Delete
+  </ListBox.Item>
+</ListBox>
+```
+
 ### Custom Escape Handling
 
 ```jsx
@@ -668,7 +699,7 @@ const [keyOrder, setKeyOrder] = useState([
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to/from the ListBox
+- `Tab` - Moves focus to/from the ListBox. A disabled ListBox is not in the Tab order
 - `Arrow Keys` - Navigate between options
 - `Space/Enter` - Select/deselect the focused option
 - `Home/End` - Move to first/last option

package/docs/components/fields/Picker.md

@@ -34,6 +34,7 @@ Choose a different component when the interaction has another shape:
 - **`defaultSelectedKeys`** `string[] | 'all'` — The default selected keys in uncontrolled multiple mode
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Trigger button styling type
 - **`theme`** `'default' | 'danger'` (default: `default`) — Trigger button color theme
 - **`icon`** `ReactNode` — Icon displayed in the trigger button

package/docs/components/fields/SearchComboBox.md

@@ -37,6 +37,7 @@ Choose a different component when the interaction has another outcome:
 - **`isLoading`** `boolean` (default: `false`) — Whether items are being loaded (e.g. from a server)
 - **`loadingDelay`** `number` (default: `1000`) — Delay in ms before the loading indicator appears
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the component
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`disabledKeys`** `Iterable<Key>` — Keys of suggestions that cannot be selected
 - **`onSelect`** `(key: string, textValue: string) => void` — Fired when a suggestion is picked; the input clears afterwards
 - **`onSubmit`** `(value: string) => void` — Opt-in. Fired when Enter is pressed with no focused/available option; the input clears afterwards

package/docs/components/fields/Select.md

@@ -56,6 +56,7 @@ Choose a different component when the interaction has another shape:
 - **`inputStyles`** `Styles` — Styles for the input trigger element
 - **`listBoxStyles`** `Styles` — Styles for the dropdown list container
 - **`optionStyles`** `Styles` — Styles for individual option items
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`overlayStyles`** `Styles` — Styles for the dropdown overlay wrapper
 - **`triggerStyles`** `Styles` — Styles for the trigger button element
 - **`inputProps`** `Props` — Additional props for the input element

package/docs/components/fields/TagInput.md

@@ -39,6 +39,7 @@ A multi-value field. The user types a value into a single-line input and commits
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the button that toggles the popover
 - **`disabledKeys`** `Iterable<Key>` — Keys of options that cannot be picked
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the input. The chips follow it
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`direction`** `'bottom' | 'top'` (default: `bottom`) — Where the suggestions popover opens
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover flips when there is no room
 - **`overlayOffset`** `number` (default: `8`) — Distance between the input and the popover, in pixels

package/docs/components/helpers/DisplayTransition.md

@@ -155,6 +155,8 @@ The component automatically respects the `prefers-reduced-motion` media query wh
 
 By default (`preserveContent={true}`), the component stores the children render function when content is visible and uses the stored version during exit transitions. This ensures the exiting content remains consistent even if the parent stops providing content immediately after hiding.
 
+Preservation ends when the phase reaches `unmounted`. With `exposeUnmounted={true}`, the render prop then uses the current children, including updates made while fully hidden. Controls kept mounted this way can stay reachable by keyboard and reveal their container on focus.
+
 ```jsx
 <DisplayTransition isShown={isVisible} preserveContent>
   {({ phase }) => (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.186.1",
+  "version": "0.187.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {