@cube-dev/ui-kit 0.161.0 → 0.162.0

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.161.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.162.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.161.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.162.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.161.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.162.0 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.161.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.162.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.161.0";
+const VERSION = "0.162.0";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

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/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.162.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {