@cube-dev/ui-kit 0.0.0-canary-bef9600 → 0.0.0-canary-e3f8a1a

package/docs/components/overlays/Dialog.md

@@ -183,16 +183,16 @@ The body is the `Content` that is a direct child of the dialog or of a direct-ch
 
 ### Screen Reader Support
 
-- Dialog announces as "dialog" or "alertdialog" based on role
-- Focus is trapped within the dialog when open
+- Dialog announces as "dialog" or "alertdialog" based on role, with its title as its name
+- An alert dialog also reads its `Content`, the message, as its description. A plain dialog reads only its title on open, so a form inside it is not read field by field; link a short description with `aria-describedby` when the title alone is not enough
+- Focus moves into the dialog when it opens: to an input marked `data-autofocus`, or to a submit or primary button, otherwise to the dialog itself. In an alert dialog this never picks a destructive (`danger`) button
+- Focus is contained within the dialog from the moment it opens, including while it animates in. A `panel` dialog does not contain focus, nor does a popover opened by a `DialogTrigger` with `isDismissable={false}`
 - Focus returns to the trigger element when dialog closes
-- Dialog title and content are properly announced
-- State changes and actions are communicated to screen readers
 
 ### ARIA Properties
 
 - `aria-labelledby` - Links dialog to its title element automatically
-- `aria-describedby` - Links dialog to its description content
+- `aria-describedby` - Set automatically only for `role="alertdialog"`, where it links the dialog to its `Content`. A plain dialog links nothing unless you pass `aria-describedby` with the id of the element that describes it. An explicit `aria-describedby` always wins
 - `aria-modal` - Not set. While a modal, fullscreen or tray dialog is open, the page behind it is `aria-hidden` instead, so a screen reader's reading cursor stays in the dialog. Lists, menus and popovers opened from the dialog render outside it and stay readable, which `aria-modal` would prevent. Popover and panel dialogs leave the page readable
 - `role` - Set to "dialog" or "alertdialog" based on content type
 

package/docs/components/overlays/DialogTrigger.md

@@ -19,13 +19,13 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`type`** `'modal' | 'popover' | 'tray' | 'fullscreen' | 'fullscreenTakeover' | 'panel'` (default: `modal`) — The type of Dialog that should be rendered
 - **`mobileType`** `'modal' | 'tray' | 'fullscreen' | 'fullscreenTakeover' | 'panel' | 'popover'` (default: same as `type`) — The Dialog type on mobile
 - **`placement`** `'top' | 'bottom' | 'left' | 'right' | 'top start' | 'top end' | 'bottom start' | 'bottom end' | 'left top' | 'left bottom' | 'right top' | 'right bottom'` — The placement of the dialog relative to its trigger
-- **`hideArrow`** `boolean` (default: `false`) — Whether a popover type Dialog's arrow should be hidden
+- **`hideArrow`** `boolean` — **Deprecated.** Has no effect: popovers render no arrow, so there is nothing to hide
 - **`mobileViewport`** `number` (default: `700`) — The screen breakpoint for the mobile type
-- **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it.
+- **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it. A popover that is not dismissable leaves outside presses alone: the control pressed still receives the press, and a text field there can take focus, because such a popover does not hold focus. It stays open when another popover opens, and closes when a modal, tray, fullscreen or panel dialog opens from another `DialogTrigger`.
 - **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
 - **`isOpen`** `boolean` — Whether the dialog is open (controlled)
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the dialog is open by default (uncontrolled)
-- **`offset`** `number` (default: `8`) — The additional offset applied along the main axis
+- **`offset`** `number` (default: `8`) — The gap between the trigger and a popover, along the main axis. `0` places the popover flush against the trigger
 - **`crossOffset`** `number` (default: `0`) — The additional offset applied along the cross axis
 - **`containerPadding`** `number` (default: `12`) — The padding between the edge of the overlay and the boundary
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the overlay should flip positions when insufficient space
@@ -33,7 +33,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`hideOnClose`** `boolean` — Whether to hide the overlay instead of unmounting on close
 - **`onOpenChange`** `function` — Callback fired when the dialog open state changes
 - **`onDismiss`** `function` — Callback fired when the dialog is dismissed
-- **`targetRef`** — The ref of the element the Dialog should visually attach itself to
+- **`targetRef`** — The ref of the element the Dialog should visually attach itself to. A popover closes when this element scrolls, as one attached to its trigger does
 - **`styles`** — The style map for the overlay
 - **`shouldCloseOnInteractOutside`** `(element: Element) => boolean` — Function to determine if a popover type Dialog should close on outside interaction. Asked before every built-in dismiss behaviour, so returning `false` keeps the popover open even for a `Button` / `ItemButton` that would otherwise dismiss it, or for a control the trigger itself owns (a picker's clear button, its custom `actions`) that would otherwise be read as a press on the trigger — and the pressed control still receives its own click. The element passed is the deepest node under the pointer (for a `Button` that is the label inside it, not the `<button>`), so guard with `contains()` rather than an identity check
 - **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the dialog closes. Only needed for a surface that claims focus _later_ than the restore (async load, entry animation); an action that focuses the surface it opens is already left alone — see [Focus Management](#best-practices)
@@ -158,7 +158,7 @@ function ControlledDialog() {
 ### Screen Reader Support
 
 - Dialog announces as "dialog" to screen readers
-- Focus is trapped within the dialog when open
+- Focus is contained within the dialog from the moment it opens, including while it animates in. A popover with `isDismissable={false}` does not contain focus, so focus can follow a press outside it
 - Focus returns to trigger element when dialog closes
 - The page behind a modal, fullscreen or tray dialog is hidden from screen readers while it is open; lists, menus and popovers opened from the dialog stay readable. Popover and panel dialogs leave the page readable
 - Proper ARIA attributes are applied automatically
@@ -168,7 +168,7 @@ function ControlledDialog() {
 - `aria-haspopup` - Automatically applied to trigger element
 - `aria-expanded` - Indicates dialog open state
 - `aria-labelledby` - Links dialog to its title
-- `aria-describedby` - Links dialog to its description
+- `aria-describedby` - Set for an alert dialog, linking its message; see [Dialog](./Dialog.md#aria-properties)
 
 ## Best Practices
 

package/docs/components/overlays/Tooltip.md

@@ -39,14 +39,14 @@ Display container for tooltip content. Has a directional arrow dependent on its
 ### Properties
 
 - **`tipStyles`** `Styles` — Custom styles for the tooltip arrow (tip) element
-- **`showIcon`** `boolean` — Controls whether an icon should be displayed in the tooltip
+- **`showIcon`** `boolean` — Deprecated. Has no effect
 - **`placement`** `PlacementAxis` (default: `'top'`) — Position of the tooltip relative to its trigger. Options: `top`, `bottom`, `left`, `right`
 - **`isMaterial`** `boolean` — Enables material-style tooltip with auto pointer events
 - **`isLight`** `boolean` — Uses light color scheme for the tooltip
 - **`isOpen`** `boolean` — Controlled open state of the tooltip
 - **`defaultOpen`** `boolean` — Whether the tooltip is open by default (uncontrolled)
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback when the tooltip open state changes
-- **`shouldFlip`** `boolean` — Whether the tooltip should flip position when there is insufficient space
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the tooltip moves to the opposite side of its trigger when there is not enough room on the requested one
 
 ### Base Properties
 
@@ -214,14 +214,22 @@ function ControlledExample() {
 
 ### Conditional Tooltip
 
-Show a tooltip only when certain conditions are met:
+Show a tooltip only when certain conditions are met. Empty content (`null`, `undefined` or `''`) turns the tooltip off: nothing opens and the trigger gets no `aria-describedby`.
 
 ```jsx
-<TooltipProvider title={hasError ? "Fix errors first" : null}>
-  <Button isDisabled={hasError}>Submit</Button>
+<TooltipProvider title={isShared ? 'Visible to your whole team' : null}>
+  <Button>Share</Button>
 </TooltipProvider>
 ```
 
+A disabled `Button` receives neither hover nor focus, so a `TooltipProvider` around it never opens. Give the button its own `tooltip` instead; it then stays hoverable and focusable while disabled:
+
+```jsx
+<Button isDisabled={hasError} tooltip={hasError ? 'Fix errors first' : undefined}>
+  Submit
+</Button>
+```
+
 ### Focus-Only Trigger
 
 Show tooltip only on focus, not on hover:
@@ -238,7 +246,10 @@ Show tooltip only on focus, not on hover:
 
 - `Tab` - Moves focus to the trigger element, showing the tooltip after the delay
 - `Shift + Tab` - Moves focus away from the trigger, hiding the tooltip
+- `Escape` - Hides the tooltip
 - Tooltips automatically appear on focus for keyboard users
+- Pressing the trigger hides the tooltip, unless `shouldCloseOnPress` is `false`
+- When the page or an element containing the trigger scrolls, the tooltip follows the trigger while it stays in view, and hides once it is scrolled out of view
 
 ### Screen Reader Support
 
@@ -249,7 +260,7 @@ Show tooltip only on focus, not on hover:
 
 ### ARIA Properties
 
-- `aria-describedby` - Automatically set on the trigger to reference the tooltip
+- `aria-describedby` - Automatically set on the trigger to reference the tooltip while it is open. `Button`, `ItemBadge`, `ItemAction`, `Checkbox`, `Radio` and `Item` rows (`ItemButton`, list and menu items) add it after their own `aria-describedby` rather than replacing it
 - All standard ARIA labeling props are supported
 
 ### Best Practices

package/docs/components/overlays/TooltipTrigger.md

@@ -24,6 +24,8 @@ Lower-level component that wraps a trigger element and a `Tooltip`. Use when you
 - **`trigger`** `'focus'` — When set, opens the tooltip only on focus instead of both focus and hover
 - **`shouldCloseOnPress`** `boolean` (default: `true`) — Whether the tooltip closes when the trigger is pressed
 
+A `Tooltip` with empty content (`null`, `undefined` or `''`) never opens. When the page or an element containing the trigger scrolls, an open tooltip follows its trigger while the trigger stays in view, and closes once it is scrolled out of view. Set `shouldFlip` on the `Tooltip` itself.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).

package/package.json

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