@cube-dev/ui-kit 0.183.0 → 0.185.0

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { c } from "react-compiler-runtime";
 import { useEffect } from "react";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { c } from "react-compiler-runtime";
 import { useEffect, useRef, useState } from "react";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { c } from "react-compiler-runtime";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react-compiler-runtime";
 import { useSyncExternalStore } from "react";

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useOverlayEscapeGuard.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react-compiler-runtime";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { c } from "react-compiler-runtime";
 import { useContext, useEffect, useRef } from "react";

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 
 //#region src/utils/react/useScheme.ts

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 import { c } from "react-compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,10 +1,9 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
-import { isValidElement } from "react";
-import { isFragment } from "react-is";
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
+import { Fragment, isValidElement } from "react";
 
 //#region src/utils/react/wrapNodeIfPlain.ts
 function wrapNodeIfPlain(children, render) {
-	const childrenIsFragment = children && (Array.isArray(children) || isFragment(children));
+	const childrenIsFragment = Array.isArray(children) || isValidElement(children) && children.type === Fragment;
 	if (!children || !childrenIsFragment && isValidElement(children)) return children;
 	return render();
 }

package/dist/utils/react/wrapNodeIfPlain.js.map

@@ -1 +1 @@
-{"version":3,"file":"wrapNodeIfPlain.js","names":["isValidElement","ReactNode","isFragment","wrapNodeIfPlain","children","render","childrenIsFragment","Array","isArray"],"sources":["../../../src/utils/react/wrapNodeIfPlain.ts"],"sourcesContent":["import { isValidElement, ReactNode } from 'react';\nimport { isFragment } from 'react-is';\n\nexport function wrapNodeIfPlain(children: ReactNode, render: () => ReactNode) {\n  const childrenIsFragment =\n    children && (Array.isArray(children) || isFragment(children));\n\n  if (!children || (!childrenIsFragment && isValidElement(children))) {\n    return children;\n  }\n\n  return render();\n}\n"],"mappings":";;;;;AAGA,SAAgBG,gBAAgBC,UAAqBC,QAAyB;CAC5E,MAAMC,qBACJF,aAAaG,MAAMC,QAAQJ,SAAS,IAAIF,WAAWE,SAAS;AAE9D,KAAI,CAACA,YAAa,CAACE,sBAAsBN,eAAeI,SAAU,CAChE,QAAOA;AAGT,QAAOC,QAAQ"}
+{"version":3,"file":"wrapNodeIfPlain.js","names":["Fragment","isValidElement","ReactNode","wrapNodeIfPlain","children","render","childrenIsFragment","Array","isArray","type"],"sources":["../../../src/utils/react/wrapNodeIfPlain.ts"],"sourcesContent":["import { Fragment, isValidElement, ReactNode } from 'react';\n\nexport function wrapNodeIfPlain(children: ReactNode, render: () => ReactNode) {\n  // Compared by `type`, not with `react-is`: the pinned `react-is@18` does not\n  // recognise React 19 elements, so it called every fragment a single element.\n  const childrenIsFragment =\n    Array.isArray(children) ||\n    (isValidElement(children) && children.type === Fragment);\n\n  if (!children || (!childrenIsFragment && isValidElement(children))) {\n    return children;\n  }\n\n  return render();\n}\n"],"mappings":";;;;AAEA,SAAgBG,gBAAgBC,UAAqBC,QAAyB;CAG5E,MAAMC,qBACJC,MAAMC,QAAQJ,SAAS,IACtBH,eAAeG,SAAS,IAAIA,SAASK,SAAST;AAEjD,KAAI,CAACI,YAAa,CAACE,sBAAsBL,eAAeG,SAAU,CAChE,QAAOA;AAGT,QAAOC,QAAQ"}

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.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.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.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.183.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.185.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.183.0";
+const VERSION = "0.185.0";
 const TASTY_VERSION = "3.9.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/FieldProperties.md

@@ -23,7 +23,7 @@ For modern forms, follow the [use-case guide](./components/form/ModernForm.md).
 - **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Position of the label relative to the input.
 - **`description`** `ReactNode` — Description text placed below the label.
 - **`extra`** `ReactNode` — Additional content displayed next to the label.
-- **`tooltip`** `ReactNode` — Tooltip shown inside the label.
+- **`labelTooltip`** `ReactNode` — Content of an info badge shown next to the label. Only rendered when the field has a label. (Formerly `tooltip`. On most fields `tooltip` is gone; on `Select` and `Checkbox` it is the control's own tooltip, as on `Item` and `Button`.)
 - **`labelSuffix`** `ReactNode` — Content displayed after the label text.
 - **`labelProps`** `object` — Additional HTML props passed to the label element.
 - **`labelStyles`** `Styles` — Tasty styles for the label element.
@@ -132,7 +132,7 @@ function ExampleForm() {
       <Select
         name="role"
         label="Role"
-        tooltip="Your primary role in the organization"
+        labelTooltip="Your primary role in the organization"
         necessityIndicator="label"
         isRequired
       >

package/docs/Usage.md

@@ -281,15 +281,16 @@ Defined in `src/tokens/typography.ts`.
 
 ### Text
 
-| Preset | Size | Line Height | Weight | Notes                 |
-| ------ | ---- | ----------- | ------ | --------------------- |
-| `t1`   | 18px | 24px        | 400    |                       |
-| `t2`   | 16px | 22px        | 400    |                       |
-| `t2m`  | 16px | 22px        | 500    | Medium weight variant |
-| `t3`   | 14px | 20px        | 400    | Base text size        |
-| `t3m`  | 14px | 20px        | 500    | Medium weight variant |
-| `t4`   | 12px | 18px        | 500    | Small text            |
-| `t4m`  | 12px | 18px        | 600    | Small text, semi-bold |
+| Preset | Size | Line Height | Weight | Notes |
+| --- | --- | --- | --- | --- |
+| `t1` | 18px | 24px | 400 |  |
+| `t2` | 16px | 22px | 400 |  |
+| `t2m` | 16px | 22px | 500 | Medium weight variant |
+| `t3` | 14px | 20px | 400 | Base text size |
+| `t3m` | 14px | 20px | 500 | Medium weight variant |
+| `t4` | 12px | 18px | 500 | Small text |
+| `t4m` | 12px | 18px | 600 | Small text, semi-bold |
+| `t4n` | 12px | 18px | 400 | Small text, normal weight — for secondary metadata beside `t4` |
 
 ### Paragraph
 

package/docs/components/actions/ButtonSplit.md

@@ -60,6 +60,8 @@ Pass an `actions` array to automatically render an action button and a trigger b
 
 Each action object requires `key` and `label`, and inherits all other props from `Menu.Item` (`icon`, `rightIcon`, `description`, `descriptionPlacement`, `prefix`, `suffix`, `hotkeys`, `textValue`, `isDisabled`, `qa`, `styles`, etc.).
 
+The action button shows the current action's `icon`, `label` and `tooltip`, so an action's tooltip appears both on its menu item and on the action button while that action is selected. `actionProps.tooltip` overrides it.
+
 ```jsx
 import { Button } from '@cube-dev/ui-kit';
 

package/docs/components/actions/ItemButton.md

@@ -26,7 +26,7 @@ An interactive button component built on top of `Item` that provides all the lay
 - **`hotkeys`** `string` — Keyboard shortcut that triggers the button (e.g., `"cmd+s"`, `"ctrl+alt+d"`)
 - **`tooltip`** `boolean | string | object` — Tooltip configuration: string for simple text, `true` for auto overflow tooltips, or object for advanced config with optional `auto` property
 - **`isDisabled`** `boolean` — Whether the button is disabled
-- **`isSelected`** `boolean` — Whether the button shows as selected with a checkmark (pairs with `icon="checkmark"`)
+- **`isSelected`** `boolean` — Whether the button shows as selected with a checkmark (pairs with `icon="checkmark"`). Announced as `aria-pressed`, so a button with `isSelected` is a toggle; see [ARIA Properties](#aria-properties)
 - **`to`** `string` — URL for link behavior (makes button act as link)
 - **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type attribute
 - **`description`** `string` — Secondary text shown below the main content
@@ -192,7 +192,7 @@ Three consequences worth knowing:
 
 - `aria-label` - Provides accessible label when text content isn't descriptive enough
 - `aria-disabled` - Indicates disabled state
-- `aria-pressed` - Indicates toggle state for toggle buttons
+- `aria-pressed` - Set from `isSelected`, so `isSelected={false}` announces an unpressed toggle. Not set on a link (`to`), on a button with its own `role` (a tab or option gets `aria-selected` instead), or on a trigger that reports `aria-expanded`. An explicit `aria-pressed` wins
 - `role` - Automatically set to "button" or "link" based on props
 
 ## Behaviour Inside Popovers

package/docs/components/content/InfoBadge.md

@@ -10,7 +10,7 @@ The badge contains its own press events, which lets it sit inside a bigger click
 - Link a piece of UI to its documentation page
 - Any place that used to render a bare info icon wrapped in a tooltip by hand
 
-Every field's `tooltip` prop already renders an `InfoBadge` next to the label, so reach for this component only when you need an info icon outside of a field.
+Every field's `labelTooltip` prop already renders an `InfoBadge` next to the label, so reach for this component only when you need an info icon outside of a field.
 
 ## Properties
 

package/docs/components/content/Layout.md

@@ -108,7 +108,7 @@ A semantic page header with title, breadcrumbs, subtitle, and action areas.
 />
 ```
 
-- **`title`** `ReactNode` — Page/section title
+- **`title`** `ReactNode` — Page/section title. A string title that runs out of room is truncated and shown in full in a tooltip; when the title and `extra` both overflow, they share the shortfall
 - **`level`** `1-6` (default: `3`) — Heading level for accessibility
 - **`breadcrumbs`** `[label, href][]` — Navigation breadcrumbs
 - **`subtitle`** `ReactNode` — Text below the title

package/docs/components/content/Tag.md

@@ -23,7 +23,7 @@ Tags are compact, inline elements used to label, categorize, or organize items.
 
 ### Properties
 
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Visual theme of the tag
+- **`theme`** `'default' | 'primary' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Visual theme of the tag
 - **`size`** `string` (default: `inline`) — Size of the tag
 - **`isClosable`** `boolean` (default: `false`) — Whether the tag can be closed
 - **`onClose`** `() => void` — Handler called when close button is pressed
@@ -64,9 +64,17 @@ Available themes:
 - **Note**: Violet, informational content
 - **Success**: Green, positive states or completed actions
 - **Danger**: Red, errors or destructive actions
-- **Special**: Purple, highlighted or premium features
+- **Primary**: Soft brand purple, for chips that reference a primary-colored entity
+- **Special**: Solid brand purple, for highlighted or premium features
 - **Disabled**: Gray, inactive or unavailable items
 
+`primary` and `special` are the same brand hue at two weights. `primary` is the soft card — pale fill, tinted border, colored text — matching `note`, `success`, `danger` and `warning` in everything but hue, so reach for it when a chip should sit quietly beside its content. `special` is a solid fill with white text, which carries far more weight on the page.
+
+```jsx
+<Tag theme="primary">Claimed by Group A</Tag>
+<Tag theme="special">Premium</Tag>
+```
+
 ### With Icons
 
 Icons can be added to provide additional visual context:

package/docs/components/fields/Checkbox.md

@@ -24,6 +24,7 @@ Checkboxes allow users to select multiple items from a list of individual items,
 - **`onChange`** `function` — Callback fired when the checkbox value changes
 - **`onFocus`** `function` — Callback fired when the checkbox receives focus
 - **`onBlur`** `function` — Callback fired when the checkbox loses focus
+- **`tooltip`** `string | TooltipProviderProps` — Tooltip shown on hover over the box and its inline label, in or out of a group, including while disabled. A string, or `TooltipProvider` props such as `title` and `placement`. It also opens when the checkbox takes keyboard focus, and describes its input to screen readers. The info badge next to a field label is `labelTooltip`
 
 ### Base Properties
 
@@ -100,6 +101,16 @@ The `mods` property accepts the following modifiers you can override:
 </Checkbox>
 ```
 
+### With a Tooltip
+
+A disabled checkbox still shows its tooltip, which makes it a good place to say why the option is unavailable.
+
+```jsx
+<Checkbox isDisabled tooltip="Available on the Team plan">
+  Single sign-on
+</Checkbox>
+```
+
 ### With Validation
 
 ```jsx

package/docs/components/fields/ColorInput.md

@@ -30,6 +30,8 @@ Reach for a `RadioGroup` or `Picker` of swatches instead when the choice is limi
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the popover is open initially
 - **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover may flip to the other side of the input
+- **`placement`** `Placement` (default: `bottom right`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the field wrapper; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`onFocus`** `(event: FocusEvent) => void` — Fired when the text input receives focus
 - **`onBlur`** `(event: FocusEvent) => void` — Fired when the text input loses focus
 

package/docs/components/fields/ColorPicker.md

@@ -28,13 +28,15 @@ Use [ColorInput](./ColorInput.md) instead when the color has to be readable and
 - **`type`** `CubeItemProps['type']` (default: `outline`) — Visual type of the trigger
 - **`theme`** `CubeItemProps['theme']` (default: `default`) — Theme of the trigger
 - **`size`** `CubeItemProps['size']` — Size of the trigger
-- **`triggerTooltip`** `CubeItemProps['tooltip']` — Tooltip for the trigger, separate from the field tooltip
+- **`triggerTooltip`** `CubeItemProps['tooltip']` — Tooltip for the trigger, separate from `labelTooltip`
 - **`swatches`** `Array<string | { color: string; label?: string }>` — Colors to offer under the editor, as a [ColorSwatchGroup](./ColorSwatchGroup.md)
 - **`swatchColumns`** `number` — How many swatches per row. Defaults to a single row
 - **`isOpen`** `boolean` — Whether the popover is open (controlled)
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the popover is open initially
 - **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover may flip to the other side of the trigger
+- **`placement`** `Placement` (default: `bottom start`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 
 There is no `formatMode`: with no text to reconcile, `format` alone decides how the value is written. Everything else about the color model — the notations it reads, the gamut handling, the three spaces — is identical to `ColorInput` and documented there.
 

package/docs/components/fields/DatePicker.md

@@ -26,6 +26,8 @@ A date picker combines a text input with a calendar interface, allowing users to
 - **`useLocale`** `boolean` (default: `undefined`) — Date segment formatting. Leave unset for the kit's own segment order; `true` uses the active locale's order; `false` forces `en-US`. Note that unset and `false` are **not** the same — unset applies extra segment formatting that `false` skips
 - **`maxVisibleMonths`** `number` (default: `1`) — Maximum number of months to display in calendar
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the calendar popover should flip to fit in the viewport
+- **`placement`** `Placement` (default: `bottom right`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the field wrapper; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`isOpen`** `boolean` — Whether the calendar popover is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the calendar popover is open by default (uncontrolled)
 - **`isDateUnavailable`** `(date: DateValue) => boolean` — Callback to mark specific dates as unavailable

package/docs/components/fields/FilterPicker.md

@@ -56,7 +56,7 @@ Choose a different component when the interaction has another shape:
 - **`listBoxStyles`** `Styles` — Custom styles for the dropdown list container within the popover
 - **`popoverStyles`** `Styles` — Custom styles for the popover dialog that contains the FilterListBox
 - **`triggerStyles`** `Styles` — Custom styles for the trigger button element
-- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from field tooltip)
+- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
 - **`triggerDescription`** `string` — Description for the trigger button (separate from field description)
 - **`prefix`** `ReactNode` — Content to show before the trigger button text
 - **`suffix`** `ReactNode` — Content to show after the trigger button text
@@ -65,6 +65,8 @@ Choose a different component when the interaction has another shape:
 - **`headerStyles`** `Styles` — Custom styles for the header area when header prop is provided
 - **`footerStyles`** `Styles` — Custom styles for the footer area when footer prop is provided
 - **`shouldFlip`** `boolean` (default: `true`) — Whether to flip the popover placement when it overflows
+- **`placement`** `Placement` (default: `bottom start`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`containerPadding`** `number` (default: `8`) — Minimum padding in pixels between the popover and viewport edges
 - **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens (only works with `items` prop, defaults to `true` when items are provided)
 - **`searchValue`** `string` — Controlled search input value

package/docs/components/fields/PeriodPicker.md

@@ -35,6 +35,8 @@ In the month and quarter panels the year in the header is a button that opens a
 - **`formatValue`** `(date: DateValue, picker: PickerType, locale: string) => string` — Overrides the displayed label
 - **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — Field size
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the popover flips to fit the viewport
+- **`placement`** `Placement` (default: `bottom right`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the field wrapper; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`isOpen`** `boolean` — Whether the popover is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the popover is open by default (uncontrolled)
 - **`onChange`** `(value: DateValue | null) => void` — Fired when the selected period changes

package/docs/components/fields/Picker.md

@@ -58,9 +58,11 @@ Choose a different component when the interaction has another shape:
 - **`listBoxStyles`** `Styles` — Custom styles for the ListBox within the popover
 - **`popoverStyles`** `Styles` — Custom styles for the popover container
 - **`triggerStyles`** `Styles` — Custom styles for the trigger button
-- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from field tooltip)
+- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
 - **`triggerDescription`** `string` — Description for the trigger button (separate from field description)
 - **`shouldFlip`** `boolean` — Whether to flip the popover placement when it overflows
+- **`placement`** `Placement` (default: `bottom start`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`containerPadding`** `number` — Minimum padding between the popover and viewport edges
 - **`onSelectionChange`** `(keys: Key | Key[] | 'all' | null) => void` — Callback when selection changes
 - **`onClear`** `() => void` — Callback called when the clear button is pressed

package/docs/components/fields/RadioGroup.md

@@ -49,12 +49,12 @@ Each option is a `Radio` (also exported as `Radio.Button`).
 - **`type`** `'radio' | 'button'` — Overrides the group's visual type for this option
 - **`size`**, **`buttonType`** — Override the group's `size` / `buttonType` for this option
 
-A `button`- or `tabs`-type radio renders an [Item](../content/Item.md), so it takes the same content props an [ItemButton](../actions/ItemButton.md) does. These are ignored by a classic radio:
+A `button`- or `tabs`-type radio renders an [Item](../content/Item.md), so it takes the same content props an [ItemButton](../actions/ItemButton.md) does. A classic radio ignores all of these except `tooltip` and `labelRef`:
 
 - **`icon`**, **`rightIcon`** — Icons before / after the label
 - **`prefix`**, **`suffix`** — Content before / after the label
 - **`description`**, **`descriptionPlacement`**, **`descriptionProps`** — Secondary line, placed `inline` (default) or `block`
-- **`tooltip`** — Tooltip content, or `true` to show one only when the label is truncated
+- **`tooltip`** — Tooltip content, or `true` to show one only when the label is truncated. A button radio defaults to `true`; its label truncates only when the radio gets less room than it (an explicit `width`, say), and never with a `block` description, which keeps the label at full width. A classic radio's label wraps instead of truncating, so it shows a tooltip only when given content. Either way a disabled option still shows its tooltip — a good place to say why it is unavailable. Tooltips open on hover and when the option takes keyboard focus, and describe its input to screen readers. The info badge next to the group's label is the group's `labelTooltip`
 - **`hotkeys`**, **`keyboardShortcutProps`** — Keyboard shortcut that selects the option, rendered as a hint
 - **`isLoading`**, **`loadingSlot`** — Replaces a slot with a spinner and disables the option
 - **`highlight`**, **`highlightCaseSensitive`**, **`highlightStyles`** — Highlights a substring of the label

package/docs/components/fields/Select.md

@@ -41,6 +41,8 @@ Choose a different component when the interaction has another shape:
 - **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`shouldFlip`** `boolean` (default: `true`) — Whether dropdown should flip to fit in viewport
+- **`placement`** `Placement` (default: `${direction} end`) — Placement of the popover relative to the anchor, as a React Aria placement string (e.g. `'bottom start'`, `'top end'`)
+- **`targetRef`** `RefObject<HTMLElement | null>` — The element the popover visually attaches to. Defaults to the trigger; use it to anchor the popover to an outer container so sibling controls' popovers line up
 - **`overlayOffset`** `number` (default: `8`) — Distance between select and dropdown in pixels
 - **`items`** `Iterable<T>` — Item objects used when rendering dynamic collections
 - **`disabledKeys`** `Iterable<Key>` — Keys of items that are disabled
@@ -60,6 +62,7 @@ Choose a different component when the interaction has another shape:
 - **`triggerDescription`** `ReactNode` — Description text displayed within the trigger button (different from field-level description)
 - **`descriptionPlacement`** `'inline' | 'block'` — Controls how the trigger description is positioned
 - **`hotkeys`** `string` — Keyboard shortcut that triggers the select when pressed
+- **`tooltip`** `string | boolean | object` — Tooltip on the trigger (see [Notable Properties](#notable-properties)). The info badge next to the label is the field-level `labelTooltip`
 - **`containerPadding`** `number` (default: `8`) — Minimum padding in pixels between the popover and viewport edges
 - **`isOpen`** `boolean` — Whether the dropdown is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the dropdown is open by default (uncontrolled)
@@ -87,6 +90,8 @@ Choose a different component when the interaction has another shape:
 - `true` - Auto tooltip on overflow (shows selected value when truncated)
 - `object` - Advanced configuration with optional `auto` property
 
+It belongs to the trigger alone. The info badge next to the field's label is `labelTooltip` — before that prop existed, a `tooltip` on a labelled Select rendered in both places.
+
 **triggerDescription** - Text description displayed within the trigger button. Different from field-level description provided by FieldWrapper.
 
 **descriptionPlacement** - Controls how description is positioned: `inline` or `block`.