@cube-dev/ui-kit 0.0.0-canary-7544b7f → 0.0.0-canary-03bd4af

package/docs/components/actions/Button.md

@@ -41,6 +41,7 @@ Supports [Base properties](../../BaseProperties.md)
 Customises the root element of the component.
 
 **Sub-elements:**
+
 - `Icon` – wrapper around the leading icon
 - `RightIcon` – wrapper around the trailing icon
 - `Label` – the button text content
@@ -114,27 +115,35 @@ The `mods` prop accepts the following modifiers you can override:
 ```jsx
 import { IconPlus } from '@tabler/icons-react';
 
-{/* Standard icon */}
-<Button icon={<IconPlus />} aria-label="Add item" />
-
-{/* Empty slot (reserves space but shows nothing) */}
-<Button icon={true} aria-label="Empty slot" />
-
-{/* Dynamic icon based on mods */}
-<Button 
-  icon={({ loading }) => loading ? <SpinnerIcon /> : <IconPlus />}
+{
+  /* Standard icon */
+}
+<Button icon={<IconPlus />} aria-label="Add item" />;
+
+{
+  /* Empty slot (reserves space but shows nothing) */
+}
+<Button icon={true} aria-label="Empty slot" />;
+
+{
+  /* Dynamic icon based on mods */
+}
+<Button
+  icon={({ loading }) => (loading ? <SpinnerIcon /> : <IconPlus />)}
   aria-label="Dynamic icon"
 >
   Save
-</Button>
+</Button>;
 
-{/* Return true from function for empty slot */}
-<Button 
-  icon={({ selected }) => selected ? <CheckIcon /> : true}
+{
+  /* Return true from function for empty slot */
+}
+<Button
+  icon={({ selected }) => (selected ? <CheckIcon /> : true)}
   aria-label="Conditional icon"
 >
   Option
-</Button>
+</Button>;
 ```
 
 ### Link Button
@@ -159,21 +168,31 @@ import { IconPlus } from '@tabler/icons-react';
 ### With Tooltip
 
 ```jsx
-{/* Simple tooltip text */}
-<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />
-
-{/* Auto tooltip on overflow */}
-<Button tooltip={true} width="100px">This text will be truncated</Button>
+{
+  /* Simple tooltip text */
+}
+<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />;
+
+{
+  /* Auto tooltip on overflow */
+}
+<Button tooltip={true} width="100px">
+  This text will be truncated
+</Button>;
 ```
 
 ### Custom Size
 
 ```jsx
-{/* Using a number (pixels) */}
-<Button size={64}>Large Custom</Button>
-
-{/* Using a string multiplier */}
-<Button size="8x">8x Size</Button>
+{
+  /* Using a number (pixels) */
+}
+<Button size={64}>Large Custom</Button>;
+
+{
+  /* Using a string multiplier */
+}
+<Button size="8x">8x Size</Button>;
 ```
 
 ## Accessibility
@@ -195,6 +214,65 @@ import { IconPlus } from '@tabler/icons-react';
 - `aria-pressed` – Managed automatically when `isSelected` is used.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 
+## Behaviour Inside Popovers
+
+By default, pressing a `Button` inside an open popover (any overlay that
+uses `usePopoverSync` — including the popovers rendered by `FilterPicker`,
+`Picker`, `ComboBox`, `Select`, `MenuTrigger`, and
+`DialogTrigger type="popover"`) **dismisses that popover** after the user's
+`onPress` runs. This matches the common UX where a popover is a transient
+surface: any action inside it should close it.
+
+Modal / tray / fullscreen Dialogs are **not** affected — a Button inside a
+modal Dialog does not auto-close it.
+
+### Opt-outs
+
+There are three ways to keep the popover open when a Button is pressed:
+
+1. **Automatic for popover triggers.** Buttons that act as popover triggers
+   already carry `data-popover-trigger` (applied by `MenuTrigger`,
+   `DialogTrigger type="popover"`, `FilterPicker`, `Picker`, `ComboBox`,
+   `Select`). Modal-type `DialogTrigger` children are **not** marked, so they
+   correctly dismiss the parent popover and let the modal take over.
+2. **Manual via `data-popover-keep`.** Add the attribute to the button
+   (toggle case) or to any ancestor element (subtree case — useful when a
+   custom inline editor inside a popover footer should not collapse on
+   every interaction):
+
+   ```jsx
+   <Button data-popover-keep onPress={() => setMode((m) => !m)}>
+     Toggle
+   </Button>
+
+   <div data-popover-keep>
+     {/* All Buttons inside this wrapper opt out. */}
+   </div>
+   ```
+
+3. **Custom non-Cube triggers.** Call `useDismissParentPopover()` yourself if
+   your control should dismiss the popover but does not extend `Button` /
+   `ItemButton`:
+   ```jsx
+   const dismiss = useDismissParentPopover();
+   <MyCustomPressable
+     onPress={(e) => {
+       doThing();
+       dismiss(e.currentTarget);
+     }}
+   />;
+   ```
+
+### Async `onPress`
+
+The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`.
+This means synchronous `onPress` handlers (and any React state updates they
+trigger) flush **before** the popover closes — including the common case of
+opening a hoisted modal via `useDialogContainer` from a popover footer (the
+modal mounts first, then the popover closes behind it). If your `onPress` is
+async and `await`s before opening another overlay, the popover will close
+first and the new overlay will appear after — usually fine, but worth noting.
+
 ## Best Practices
 
 1. **Do**: Provide a label for icon-only buttons

package/docs/components/actions/ItemButton.md

@@ -74,7 +74,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Sizes
 
 - `xsmall` - Extra small size for compact interfaces
-- `small` - Small size for dense layouts  
+- `small` - Small size for dense layouts
 - `medium` - Default size for most use cases
 - `large` - Large size for prominent actions
 - `xlarge` - Extra large size for hero actions
@@ -84,15 +84,13 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Basic Button
 
 ```jsx
-<ItemButton onPress={() => console.log('Clicked')}>
-  Click me
-</ItemButton>
+<ItemButton onPress={() => console.log('Clicked')}>Click me</ItemButton>
 ```
 
 ### Button with Icons
 
 ```jsx
-<ItemButton 
+<ItemButton
   icon={<IconFile />}
   rightIcon={<IconExternalLink />}
   onPress={handleOpen}
@@ -104,19 +102,13 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Link Button
 
 ```jsx
-<ItemButton to="/docs">
-  Go to Documentation
-</ItemButton>
+<ItemButton to="/docs">Go to Documentation</ItemButton>
 ```
 
 ### Button with Hotkey
 
 ```jsx
-<ItemButton 
-  hotkeys="cmd+s"
-  onPress={handleSave}
-  type="primary"
->
+<ItemButton hotkeys="cmd+s" onPress={handleSave} type="primary">
   Save Document
 </ItemButton>
 ```
@@ -124,11 +116,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Form Submit Button
 
 ```jsx
-<ItemButton 
-  htmlType="submit"
-  type="primary"
-  icon={<IconCheck />}
->
+<ItemButton htmlType="submit" type="primary" icon={<IconCheck />}>
   Submit Form
 </ItemButton>
 ```
@@ -136,10 +124,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Button with Selection State
 
 ```jsx
-<ItemButton 
-  isSelected={isSelected}
-  onPress={() => setIsSelected(!isSelected)}
->
+<ItemButton isSelected={isSelected} onPress={() => setIsSelected(!isSelected)}>
   Toggle Selection
 </ItemButton>
 ```
@@ -149,12 +134,20 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ItemButton supports inline actions that appear on the right side. Use the `ItemButton.Action` compound component for consistent styling:
 
 ```jsx
-<ItemButton 
+<ItemButton
   icon={<IconFile />}
   actions={
     <>
-      <ItemButton.Action icon={<IconEdit />} aria-label="Edit" onPress={handleEdit} />
-      <ItemButton.Action icon={<IconTrash />} aria-label="Delete" onPress={handleDelete} />
+      <ItemButton.Action
+        icon={<IconEdit />}
+        aria-label="Edit"
+        onPress={handleEdit}
+      />
+      <ItemButton.Action
+        icon={<IconTrash />}
+        aria-label="Delete"
+        onPress={handleDelete}
+      />
     </>
   }
   onPress={handleOpen}
@@ -188,9 +181,41 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
 - `aria-pressed` - Indicates toggle state for toggle buttons
 - `role` - Automatically set to "button" or "link" based on props
 
+## Behaviour Inside Popovers
+
+Like `Button`, an `ItemButton` press inside an open popover **dismisses
+that popover** by default — popovers are transient surfaces and any action
+inside them should close them. Modals/trays/fullscreen Dialogs are not
+affected.
+
+### Opt-outs
+
+- **Automatic for popover triggers** — `MenuTrigger`, `DialogTrigger
+type="popover"`, and the picker components (`FilterPicker`, `Picker`,
+  `ComboBox`, `Select`) mark their trigger ItemButtons with
+  `data-popover-trigger` so they don't dismiss the popover they themselves
+  live in.
+- **Manual via `data-popover-keep`** — add to the ItemButton (toggle) or
+  any ancestor (whole subtree):
+  ```jsx
+  <ItemButton data-popover-keep onPress={() => setMode((m) => !m)}>
+    Toggle Mode
+  </ItemButton>
+  ```
+- **Custom non-Cube triggers** — call `useDismissParentPopover()` directly
+  if you build a control on top of something other than `Button` /
+  `ItemButton`.
+
+The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`
+— so synchronous `onPress` handlers (and the React state updates they
+trigger) flush BEFORE the popover closes. This makes the "open a hoisted
+modal from a popover footer" pattern work without flicker: the modal mounts
+first, then the popover closes behind it.
+
 ## Best Practices
 
 1. **Do**: Use clear, action-oriented text
+
    ```jsx
    <ItemButton onPress={handleSave} type="primary">
      Save Changes
@@ -198,6 +223,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 2. **Do**: Add hotkeys for frequently used actions
+
    ```jsx
    <ItemButton hotkeys="cmd+s" onPress={handleSave}>
      Save Document
@@ -205,6 +231,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 3. **Do**: Use appropriate button types for forms
+
    ```jsx
    <ItemButton htmlType="submit" type="primary">
      Submit Form
@@ -212,8 +239,9 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 4. **Do**: Use `ItemButton.Action` for inline actions
+
    ```jsx
-   <ItemButton 
+   <ItemButton
      icon={<IconFile />}
      actions={
        <>
@@ -228,15 +256,21 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 5. **Don't**: Use vague or unclear button text
+
    ```jsx
-   {/* Avoid this - unclear what "OK" does */}
-   <ItemButton onPress={handleAction}>OK</ItemButton>
+   {
+     /* Avoid this - unclear what "OK" does */
+   }
+   <ItemButton onPress={handleAction}>OK</ItemButton>;
    ```
 
 6. **Don't**: Add too many actions (limit to 2-3 for clarity)
+
    ```jsx
-   {/* Avoid this - too many action buttons */}
-   <ItemButton 
+   {
+     /* Avoid this - too many action buttons */
+   }
+   <ItemButton
      actions={
        <>
          <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
@@ -247,13 +281,16 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
      }
    >
      Button with too many actions
-   </ItemButton>
+   </ItemButton>;
    ```
 
 7. **Don't**: Overcrowd buttons with too many visual elements
+
    ```jsx
-   {/* Avoid this - too many competing elements */}
-   <ItemButton 
+   {
+     /* Avoid this - too many competing elements */
+   }
+   <ItemButton
      icon={<IconA />}
      rightIcon={<IconB />}
      prefix="Pre"
@@ -261,7 +298,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
      description="Long description"
    >
      Overcrowded Button
-   </ItemButton>
+   </ItemButton>;
    ```
 
 8. **Accessibility**: Always ensure buttons have clear, descriptive labels, proper keyboard support, and provide `aria-label` for action buttons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-7544b7f",
+  "version": "0.0.0-canary-03bd4af",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {