@cube-dev/ui-kit 0.161.0 → 0.163.0

package/docs/components/fields/PeriodPicker.md

@@ -16,6 +16,10 @@ The value is always a single `CalendarDate` (from `@internationalized/date`)
 The field renders a compact label for the selected period (`2026-W33`, `2026-08`,
 `2026-Q3`, `2026`). Use `formatValue` to override it.
 
+In the month and quarter panels the year in the header is a button that opens a
+year list, so picking a period several years away takes two clicks instead of
+paging through the arrows.
+
 ## When to Use
 
 - Filtering or reporting by week, month, quarter, or fiscal year
@@ -28,13 +32,14 @@ The field renders a compact label for the selected period (`2026-W33`, `2026-08`
 
 ### Properties
 
+- **`picker`** `'week' | 'month' | 'quarter' | 'year'` (default: `month`) — Which period is selected. The four named components set it for you; only the base `PeriodPicker` takes it directly
 - **`value`** `DateValue` — The current value (controlled), snapped to the period start
 - **`defaultValue`** `DateValue` — The default value (uncontrolled)
 - **`minValue`** `DateValue` — The earliest selectable period
 - **`maxValue`** `DateValue` — The latest selectable period
 - **`isDateUnavailable`** `(date: DateValue) => boolean` — Marks a period (by its start date) as unavailable
 - **`placeholder`** `string` — Text shown when no value is selected
-- **`formatValue`** `(date: DateValue, picker: PickerType) => string` — Overrides the displayed label
+- **`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
 - **`isOpen`** `boolean` — Whether the popover is open (controlled)
@@ -42,9 +47,8 @@ The field renders a compact label for the selected period (`2026-W33`, `2026-08`
 - **`onChange`** `(value: DateValue | null) => void` — Fired when the selected period changes
 - **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
 
-The advanced `PeriodPicker` base component accepts the same props plus a
-**`picker`** `'week' | 'month' | 'quarter' | 'year'` prop; the four named
-components are thin wrappers that set it for you.
+`WeekPicker`, `MonthPicker`, `QuarterPicker` and `YearPicker` are thin wrappers
+that pin `picker`; everything else is identical.
 
 ### Base Properties
 
@@ -61,6 +65,17 @@ Supports all [Field properties](../../FieldProperties.md)
 - **`inputStyles`** — the value/label area
 - **`triggerStyles`** — the calendar trigger button
 
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+- **Color:** `color`, `fill`, `fade`, `image`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
 ## Examples
 
 ### Month
@@ -73,3 +88,28 @@ Supports all [Field properties](../../FieldProperties.md)
 
 ### Limited range
 
+Periods that fall entirely outside `minValue` / `maxValue` are disabled, and the
+navigation arrows stop at the edge of the range.
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — Moves focus to the calendar trigger
+- `Enter` / `Space` — Opens the panel; focus lands on the selected period
+- `Arrow keys` — Move between periods, rolling over into the neighbouring year or decade
+- `PageUp` / `PageDown` — Previous / next year (or decade in the year list)
+- `Home` / `End` — First / last selectable period on the page
+- `Escape` — Steps back from the year list to the period list
+
+### Screen Reader Support
+
+- The panel is a `grid` labelled `Months`, `Quarters` or `Years`
+- The trigger is described by the field's current value, so the selection is
+  announced along with the button
+
+## Related Components
+
+- [DatePicker](./DatePicker.md) — pick an exact day
+- DateRangePicker — pick a start and end date
+- [Calendar](../other/Calendar.md) — the panels these fields render

package/docs/components/fields/RadioGroup.md

@@ -21,12 +21,38 @@ A radio group allows users to select exactly one option from a set of mutually e
 - **`defaultValue`** `string` — The default selected value (uncontrolled)
 - **`type`** `'radio' | 'button' | 'tabs'` (default: `radio`) — Visual type for all radios in the group (button/tabs default to horizontal)
 - **`orientation`** `undefined | 'vertical' | 'horizontal'` (default: `undefined`) — Orientation of the radio group. When unset it is derived from `type`: `horizontal` for `button` and `tabs`, `vertical` otherwise
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `xsmall`) — Size for all radio buttons in the group
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Size for all radio buttons in the group
 - **`buttonType`** `'outline' | 'outline-2' | 'clear' | 'primary'` — Button type for button-style radios (ignored in tabs mode). When set to "primary", selected buttons use primary style and non-selected use outline with brand tint. `outline-2` is identical to `outline` but uses `#surface-3` as its base fill, so it stands out when the radio group sits on a `#surface-2` container
 - **`onChange`** `function` — Callback fired when the selected value changes
 - **`onBlur`** `function` — Callback fired when the radio group loses focus
 - **`onFocus`** `function` — Callback fired when the radio group receives focus
 
+### Radio Properties
+
+Each option is a `Radio` (also exported as `Radio.Button`).
+
+- **`value`** `string` — The value this option contributes to the group
+- **`children`** — The option label
+- **`isDisabled`** `boolean` — Whether this option is disabled. Falls back to the group's `isDisabled`
+- **`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:
+
+- **`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
+- **`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
+- **`level`** — Heading level for the label when `buttonType` is `card` or `header`
+- **`labelRef`** — Ref to the label element
+
+Container [style properties](#style-properties) also apply to button-type radios (they style the `Item`). A classic radio only reads the outer subset — `margin`, `width`, `height`, `flex*`, `grid*`, `place*`, `position`, `inset`, `zIndex`, `border`, `radius`, `shadow`, `outline`.
+
+`shape` and `actions` are not forwarded: the corner radius is owned by the group layout, which keeps only the outer-side radius on the first and last option so the group reads as one continuous control, and a button radio renders as a `<label>`, where a click on a nested action button would select the option.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md)
@@ -101,12 +127,10 @@ Controls the size of all radio buttons in the group:
 
 **Size Mapping in Tabs Mode:**
 When `type="tabs"`, sizes are automatically mapped to maintain visual consistency:
-- `small` and `medium` → `xsmall`
 - `large` → `medium`
-- `xlarge` → `large`
-- `xsmall` remains `xsmall`
+- every other size → `xsmall`
 
-This ensures tab groups remain compact and cohesive.
+Only `large` is carried through; `xsmall`, `small`, `medium` and `xlarge` all collapse to `xsmall`. This ensures tab groups remain compact and cohesive.
 
 ### Button Type
 
@@ -160,6 +184,16 @@ When using `type="button"`, you can customize the button appearance:
 </Radio.Tabs>
 ```
 
+### Rich Button Content
+
+```jsx
+<Radio.ButtonGroup label="Region" defaultValue="eu">
+  <Radio value="eu" icon={<GlobeIcon />} description="Frankfurt">EU</Radio>
+  <Radio value="us" icon={<GlobeIcon />} description="Oregon" hotkeys="alt+2">US</Radio>
+  <Radio value="ap" icon={<GlobeIcon />} isLoading>AP</Radio>
+</Radio.ButtonGroup>
+```
+
 ### Custom Button Type
 
 ```jsx

package/docs/components/other/Calendar.md

@@ -0,0 +1,187 @@
+# Calendar
+
+`Calendar` renders a month grid for picking a single date. `RangeCalendar` picks
+a contiguous range, and `PeriodCalendar` picks a whole month, quarter or year.
+All three are the panels behind the date fields — [DatePicker](../fields/DatePicker.md),
+DateRangePicker and the
+[period pickers](../fields/PeriodPicker.md) — and they are built on
+React Aria's `useCalendar` / `useRangeCalendar`.
+
+The header title is the navigation: the month and the year are buttons that open
+a month list and a year list, so reaching a date two years out takes two clicks
+instead of twenty-four.
+
+## When to Use
+
+- Embedding a calendar directly in a page or panel rather than behind a field
+- Building a custom date input that needs the same grid and states
+- Otherwise, prefer the date fields — they add the text input, label, validation
+  and popover for you
+
+## Component
+
+---
+
+### Properties
+
+#### Calendar
+
+- **`value`** `DateValue` — The selected date (controlled)
+- **`defaultValue`** `DateValue` — The initially selected date (uncontrolled)
+- **`minValue`** `DateValue` — The earliest selectable date
+- **`maxValue`** `DateValue` — The latest selectable date
+- **`isDateUnavailable`** `(date: DateValue) => boolean` — Marks individual dates as unavailable
+- **`pickerMode`** `'day' | 'week'` (default: `day`) — `week` shows a week-number column and highlights the whole week of the selected day
+- **`hasMonthYearNavigation`** `boolean` (default: `true`) — Whether the header month and year are buttons that open the month and year lists
+- **`selectedRange`** `{ start: DateValue; end: DateValue }` — Highlights a range that lives outside the calendar's own state (used by `DateRangeSeparatedPicker`)
+- **`isDisabled`** `boolean` — Disables the whole calendar
+- **`isReadOnly`** `boolean` — Allows navigation but not selection
+- **`onChange`** `(value: DateValue) => void` — Fired when a date is selected
+
+#### RangeCalendar
+
+Accepts React Aria's `AriaRangeCalendarProps` (a `{ start, end }` value) plus
+**`hasMonthYearNavigation`**.
+
+#### PeriodCalendar
+
+- **`picker`** `'month' | 'quarter' | 'year'` — Which period the panel selects
+- **`value`** `DateValue | null` — The selected period, represented by its start date
+- **`minValue`** / **`maxValue`** `DateValue | null` — Range limits; a period is disabled only when *all* of it falls outside
+- **`isDateUnavailable`** `(date: DateValue) => boolean` — Called with the period's start date
+- **`isDisabled`** `boolean`
+- **`autoFocus`** `boolean` — Moves focus into the grid on mount
+- **`onChange`** `(date: CalendarDate) => void` — Fired with the period's start date
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Modifiers
+
+Day cells and period cells share one set of modifiers:
+
+| Modifier      | Type      | Description                                          |
+| ------------- | --------- | ---------------------------------------------------- |
+| `selected`    | `boolean` | The cell is part of the current selection            |
+| `current`     | `boolean` | The cell contains today                              |
+| `outside`     | `boolean` | The cell belongs to an adjacent month or decade      |
+| `rangeHover`  | `boolean` | The whole row is highlighted (week mode)             |
+| `pressed`     | `boolean` | The cell is being pressed                            |
+| `focused`     | `boolean` | The cell holds keyboard focus                        |
+| `disabled`    | `boolean` | The cell is outside `minValue` / `maxValue`          |
+| `unavailable` | `boolean` | `isDateUnavailable` returned `true` for the cell     |
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import { parseDate } from '@internationalized/date';
+
+<Calendar
+  defaultValue={parseDate('2026-08-12')}
+  onChange={(date) => console.log(date.toString())}
+/>;
+```
+
+### Week Selection
+
+```jsx
+<Calendar pickerMode="week" defaultValue={parseDate('2026-08-12')} />
+```
+
+### Limited Range
+
+Months and years that fall entirely outside `minValue` / `maxValue` are disabled
+in the month and year lists too, and the navigation arrows stop at the edge.
+
+```jsx
+<Calendar
+  defaultValue={parseDate('2026-08-12')}
+  minValue={parseDate('2026-08-05')}
+  maxValue={parseDate('2026-09-20')}
+/>
+```
+
+### Without Month/Year Navigation
+
+```jsx
+<Calendar hasMonthYearNavigation={false} defaultValue={parseDate('2026-08-12')} />
+```
+
+### Range
+
+```jsx
+<RangeCalendar
+  defaultValue={{
+    start: parseDate('2026-08-10'),
+    end: parseDate('2026-08-19'),
+  }}
+/>
+```
+
+### Period Panels
+
+```jsx
+<PeriodCalendar
+  picker="month"
+  value={new CalendarDate(2026, 8, 1)}
+  onChange={(date) => console.log(date.toString())}
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+Day grid (provided by React Aria):
+
+- `Arrow keys` — Move between days
+- `PageUp` / `PageDown` — Previous / next month
+- `Home` / `End` — First / last day of the week
+- `Enter` / `Space` — Select the focused day
+
+Month and year lists:
+
+- `Arrow keys` — Move between periods, rolling over into the neighbouring year or decade
+- `PageUp` / `PageDown` — Previous / next year (month list) or decade (year list)
+- `Home` / `End` — First / last selectable period on the page
+- `Enter` / `Space` — Choose the period
+- `Escape` — Step back to the previous panel without closing a surrounding popover
+
+### Screen Reader Support
+
+- Each panel is a `grid`, labelled `Months` / `Quarters` / `Years`
+- The visible month and year are the calendar's `heading`, and their buttons are
+  the controls that open the lists
+- Cells expose `aria-selected`; out-of-range periods are `disabled`
+
+## Best Practices
+
+1. **Do**: bound the calendar when the domain is bounded — the month and year
+   lists disable everything out of range, which is far clearer than letting the
+   user land somewhere unselectable.
+
+   ```jsx
+   <Calendar minValue={today(getLocalTimeZone())} />
+   ```
+
+2. **Don't**: reach for `PeriodCalendar` to pick a day. Its value is always the
+   *start* of a period, never an exact date.
+
+3. **Accessibility**: always give a standalone calendar an `aria-label` — inside
+   a field the label comes from the field.
+
+## Suggested Improvements
+
+- Range calendars paint every day in the range the same way; distinct start/end
+  caps would read better for long ranges.
+- Multi-month (`visibleDuration`) layouts are not implemented; the header falls
+  back to a plain title when a range spans more than one month.
+
+## Related Components
+
+- [DatePicker](../fields/DatePicker.md) — a date field with this calendar in a popover
+- DateRangePicker — a range field built on `RangeCalendar`
+- [PeriodPicker](../fields/PeriodPicker.md) — week / month / quarter / year fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.161.0",
+  "version": "0.163.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -120,6 +120,7 @@
     "dedent": "^0.7.0",
     "eslint": "^10.8.0",
     "husky": "^6.0.0",
+    "jiti": "^2.6.1",
     "jsdom": "^29.1.1",
     "lint-staged": "^17.0.8",
     "markdown-table": "^3.0.3",
@@ -158,6 +159,8 @@
     "watch": "tsdown --watch",
     "test": "vitest run",
     "test:browser": "vitest run --config vitest.browser.config.ts",
+    "probe": "node scripts/probe.mjs",
+    "probe:browser": "PROBE_TIER=browser node scripts/probe.mjs",
     "test-cover": "vitest run --coverage",
     "test-watch": "vitest",
     "prettier": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",