@cube-dev/ui-kit 0.0.0-canary-a9d94d7 → 0.0.0-canary-a1aba4f

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-a9d94d7 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-a1aba4f | 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.0.0-canary-a9d94d7 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-a1aba4f | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.0.0-canary-a9d94d7";
+const VERSION = "0.0.0-canary-a1aba4f";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Theming.md

@@ -5,10 +5,6 @@ handful of seeds: an accent hue, a base hue, a saturation, and a hue per status
 theme. Those seeds are tunable at runtime — change one and every token re-resolves, in light,
 dark, and high-contrast schemes at once.
 
-The accent and base zones can each be seeded by a **color** instead of a hue, which is
-usually what you have: `accentColor: '#2F5BFF'` rather than `hue: 266`. See
-[Two zones, two ways to seed them](#two-zones-two-ways-to-seed-them).
-
 ```ts
 import { setPaletteConfig } from '@cube-dev/ui-kit';
 
@@ -27,17 +23,13 @@ value so this stays true.
 
 | Option                       | Scope                                                                                                                                                                 | Default                             |
 | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `accentColor`                | **Accent** zone seeded by a color. Derives the hue, the saturation (with `pastel` off) and the accent **tone**, so the brand fill renders as the color you passed.    | unset                               |
-| `baseColor`                  | **Base** zone seeded by a color. **Hue only** — its tone and saturation are discarded.                                                                                | unset                               |
 | `hue`                        | **Accent** hue in degrees — the brand. Drives the `accent-*` family, `primary` / `purple` / `special`, and the brand-tinted `focus`, loading faces and disabled chip. | `280.3`                             |
 | `baseHue`                    | **Base** hue in degrees — the neutral chrome: `surface` and its ladder, the `surface-text*` ramp, `border`, `placeholder`.                                            | inherits `hue`                      |
-| `saturation`                 | Seed saturation (0–100) for the `default` theme, and the fallback for every theme that sets none. Setting it **turns `pastel` off**, which is the path it belongs to. | `100`                               |
-| `baseSaturation`             | Seed saturation (0–100) of the **base** zone — the same family `baseHue` governs. On the same scale as `saturation`; the shipped chrome is `12`.                      | `saturation × 0.12`                 |
-| `surfaceMode`                | Global. `'tinted'` moves the neutral surface ramp two tones off the end of the tone scale, which is what gives `baseSaturation` room to reach the page surface.        | `'default'`                         |
+| `saturation`                 | Seed saturation (0–100) for the `default` theme, and the fallback for every theme that sets none.                                                                     | `100`                               |
 | `themes.<status>.hue`        | Hue for `success` / `danger` / `warning` / `note`.                                                                                                                    | `156.9` / `23.1` / `84.3` / `302.3` |
 | `themes.<status>.saturation` | Saturation for that status theme.                                                                                                                                     | inherits `saturation`               |
 | `themes.code.saturation`     | Saturation for the `code-*` syntax family. Hues are fixed, and this does **not** inherit `saturation`, nor track its default.                                         | `80`                                |
-| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit, and **pins `saturation` to 100**. Wins wherever both are set. Every theme except `code`.                                  | `true`                              |
+| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit. Every theme except `code`.                                                                                                | `true`                              |
 | `contrastLevel`              | Global. `'auto'`, or a manual `0`–`100` level.                                                                                                                        | `'auto'`                            |
 
 ### The setter replaces
@@ -72,13 +64,13 @@ setPaletteConfig((config) => ({
 `resetPaletteConfig()` drops all tuning at once — the same as
 `setPaletteConfig({})`, just easier to read at a call site.
 
-### Two zones, two ways to seed them
+### Two hue zones
 
 Hue is split into an **accent** zone and a **base** zone:
 
-- **Accent** (`hue` / `accentColor`) — the `accent-*` family on every theme, `primary` /
-  `purple` / `special`, plus `focus`, the loading faces and the disabled chip.
-- **Base** (`baseHue` / `baseColor`) — the neutral chrome: `surface` and its ladder, the
+- **Accent** (`hue`) — the `accent-*` family on every theme, `primary` / `purple` /
+  `special`, plus `focus`, the loading faces and the disabled chip.
+- **Base** (`baseHue`) — the neutral chrome: `surface` and its ladder, the
   `surface-text*` ramp, `border`, `placeholder`.
 
 `baseHue` inherits `hue`, so out of the box the chrome carries a faint tint of the
@@ -91,67 +83,11 @@ setPaletteConfig({ hue: 235, baseHue: 60 });
 Only the `default` theme is affected. A colored theme's tinted `surface`
 deliberately follows _its own_ hue, because a danger banner should read as red.
 
-Either zone can take a **color** instead, which is usually the form a brand arrives in.
-Anything Glaze parses works — hex, `rgb()`, `hsl()`, `okhsl()`, `okhst()`, `oklch()`.
-CSS color keywords (`rebeccapurple`) are not supported; an unparseable value warns and
-falls back to the numeric seed.
-
-```ts
-setPaletteConfig({ accentColor: '#2F5BFF', baseColor: '#7A7269' });
-```
-
-The two are not symmetric, and the difference is the point:
-
-- `accentColor` contributes hue, saturation **and tone**. The tone is what makes the
-  brand fill actually _be_ your color. Without it the fill is authored as a fixed tone
-  step off white, so every accent hue lands at roughly the same lightness — a yellow
-  brand comes out olive.
-- `baseColor` contributes **hue only**. Its tone and saturation are discarded, because
-  the chrome's lightness ladder and its 0.10–0.20 saturation factors are the design. A
-  base color says which way the greys lean, not how dark or how vivid they are.
-
-The numeric fields still win where both are set, and the tone keeps coming from the
-color either way — so a preview can rotate the hue without losing the brand's lightness:
-
-```ts
-setPaletteConfig({ accentColor: '#2F5BFF', hue: 300 }); // hue 300, tone still #2F5BFF's
-```
-
-### A color seed is a request
-
-The palette renders the color you asked for, and moves it only as far as it has to. Two
-things can make it move.
-
-First, **exactness is scoped to the light, normal-contrast variant.** That is the one
-that reproduces your color. Dark and high contrast adapt, as every other color in the
-palette does — they are different pages, and a brand pinned across all four would be
-less faithful, not more. What holds everywhere is the floor below.
-
-**The fill has a 3:1 floor against the page.** That is WCAG's non-text floor: enough
-that a button reads as a shape on the surface. It is a floor and not a target — a brand
-already at 5:1, or 17:1, is emitted exactly as given, and one that misses moves only as
-far as the floor. `#FFD400` cannot clear 3:1 on a white page, so it darkens to
-`#b09200`; `#7A4DBF` measures 5.8:1 and is left alone.
-
-High contrast tightens it further, deliberately: there the floor goes back to AAA
-whatever you passed, because that tier is selected by `prefers-contrast: more` or an
-explicit `data-contrast="high"` — anyone reading it has asked for separation over brand.
-
-**`pastel` caps chroma.** The flat, hue-independent ceiling is what makes pastel even
-across hues, and it sits below where a saturated color would land, so under it a color
-seed can never resolve to itself: `#EF4444` renders `#c47069`. Under pastel the color
-contributes its hue and its tone; turn pastel off to get its chroma too.
-
-Read the result back from the tokens themselves — `#accent-surface` is the fill,
-`#accent-text-soft` the rest link color — or watch the requested/resolved chips in the
-[Theme builder](#theme-builder).
-
 ### One saturation scale per theme
 
-Saturation is _not_ split per token, deliberately: `saturation` is the theme's
-**seed**, and every color's own `saturation` is a 0–1 factor of it. `surface` sits
-at `0.12`, `border` at `0.175`, the text ramp at `0.2`, the accent family at
-~`1.0`.
+Saturation is _not_ split, deliberately: `saturation` is the theme's **seed**, and
+every color's own `saturation` is a 0–1 factor of it. `surface` sits at `0.12`,
+`border` at `0.175`, the text ramp at `0.2`, the accent family at ~`1.0`.
 
 So the palette has one saturation _scale_, and everything on it keeps its
 proportions: turning `saturation` down mutes the brand fills and the neutral tint
@@ -159,79 +95,6 @@ together, in the ratios the palette was designed around. That is the point — t
 relationship between a subtle surface tint and a saturated accent is part of the
 design, not something to tune per token.
 
-The one seam is the **base zone**, and it is the same seam `baseHue` opens: the
-chrome is the one family whose job is _not_ to look like the brand. `baseSaturation`
-gives it its own seed, on the same 0–100 scale, so a vivid accent over near-grey
-chrome — or a muted accent over visibly warm chrome — is one number rather than a
-choice between them:
-
-```ts
-setPaletteConfig({ pastel: false, saturation: 90, baseSaturation: 3 });
-```
-
-It defaults to `saturation × 0.12`, which is `surface`'s own factor, so leaving it
-alone reproduces the shipped palette exactly and a muted `saturation` still mutes
-the chrome along with everything else. **The shipped value is `12`** — a faint tint
-is what a neutral surface _is_ — so the interesting range is the low end. The base
-colors keep their proportions to one another until the highest of them (`0.475`,
-`surface-inverse`) hits the top of the scale, around `25`; past that they converge.
-
-Note the asymmetry with `saturation`: writing `baseSaturation` does **not** turn
-`pastel` off. How much hue the chrome carries says nothing about which chroma space
-the palette is in.
-
-### Tinted surfaces
-
-A neutral `surface` sits at the extreme of the tone scale — pure white in light,
-the darkest step the dark tone window allows in dark. Chroma needs distance from
-the extreme to exist at all, so on a light page `surface` is white whatever
-`baseSaturation` asks for. The base seed reaches `surface-2`…`surface-4`, `border`,
-`placeholder` and the text ramp, and stops at the page itself.
-
-`surfaceMode: 'tinted'` moves the whole ramp two tones inward:
-
-```ts
-setPaletteConfig({ surfaceMode: 'tinted', baseSaturation: 25 });
-```
-
-Two tones is not a lightness change you would name — it is _room_. Everything below
-`surface` is positioned relative to it, so the ladder, the borders and the text ramp
-all follow, and the text's `['AA','AAA']` floors re-solve against the new background
-rather than drifting. The `code-*` family follows too: its mirrored `surface` exists
-to be the page, so it tracks both the tone and the base seed.
-
-**The tinted surfaces move with it.** A status theme's `surface` — and a runtime
-tint's, from `getColorTheme()` — is authored as an offset from the page's rather
-than as an absolute tone, and that offset is exactly the two tones `tinted` shifts
-by. Anchored absolutely they would land on the page's own new tone and a `note`
-banner would stop reading as a banner at all; anchored to the page they keep the
-separation the offset was chosen for, in both schemes. They also pick up a little
-more chroma there, being further from the extreme — so `tinted` makes a status
-surface easier to see, not harder.
-
-The tint stays subtle by construction. Near white the sRGB gamut has very little
-chroma to give, so `tinted` buys a surface that reads as warm or cool rather than
-one that reads as colored — which is the whole ask. For a genuinely colored panel,
-reach for a status theme's `surface` instead.
-
-All of which describes the `pastel: false` path. Under `pastel` there is still one seed
-and it is pinned to `100`, because a flat chroma ceiling is the whole mechanism and a
-second scale on top of it would only undo the evenness. So there are two paths:
-
-```ts
-setPaletteConfig({ pastel: true }); // even across hues; saturation is 100, full stop
-setPaletteConfig({ saturation: 65 }); // your scale, per-hue ceiling — pastel goes off
-```
-
-Note the second line does not mention `pastel`. **Setting a `saturation` turns pastel
-off**, because tuning a saturation is the non-pastel path by definition — so you pick a
-path by asking for what you want from it, not by setting a flag first.
-
-State `pastel` only to override that. It is the coarser of the two choices — a color
-space rather than a value on one — so it wins wherever both are set, and a saturation it
-shadows is ignored with a dev-mode warning. The number is **kept** rather than dropped,
-though: it stays in the sparse config, so turning pastel back off restores it.
-
 ### The `code-*` family is the exception
 
 Syntax colors are their own theme with their own seed, so neither the brand hue nor
@@ -279,20 +142,6 @@ setPaletteConfig({ hue: 235 }); // baseHue dropped — inherits again → 235
 setPaletteConfig(({ baseHue, ...config }) => config);
 ```
 
-The color seeds are pinned fields too, which makes the base zone three-state: unset and
-it follows the accent, `baseHue` and it is pinned to a number, `baseColor` and it is
-derived from a color. A settings UI reads the sparse config to know which of its own
-controls is in charge:
-
-```ts
-const input = getPaletteConfigInput();
-const accentMode = input.accentColor !== undefined ? 'color' : 'hue';
-```
-
-Swapping one form for the other counts as a change even when the numbers agree — a
-`hue: 45` replaced by a color that derives hue 45 resolves identically, but the UI still
-has to re-render to move its mode control.
-
 An explicit `baseHue: undefined` is equivalent to omitting it; neither is a value.
 
 `getPaletteConfig()` resolves everything, which loses that distinction — it cannot
@@ -334,94 +183,29 @@ By default contrast is a two-tier switch: normal colors plus a separate
 high-contrast set, selected by `<html data-contrast="high">` or a
 `prefers-contrast: more` preference.
 
-A manual `contrastLevel` adds a 0–100 slider that positions the **normal** colors,
-for a product that wants to offer its own contrast control. Level `0` is the
-shipped palette and `100` is the high-contrast one, bit for bit, so the slider
-interpolates between exactly what the two tiers already ship.
-
-The two **compose**; the slider does not replace the switch. The high-contrast
-tier stays the true high-contrast resolution at every level — identical to what
-`'auto'` emits — so `data-contrast="high"` and `prefers-contrast: more` keep
-working and escalate on top of wherever the slider has put the baseline.
-
-The one exception is level `100`: there the normal colors already _are_ the
-high-contrast ones, so a second tier would only duplicate them and a single
-light/dark set is emitted.
+A manual `contrastLevel` replaces both tiers with a single 0–100 slider. Because
+the level already carries the contrast preference, **no separate high-contrast
+variant is emitted** — which means `data-contrast="high"` and
+`prefers-contrast: more` stop having any effect while a level is set. Levels `0`
+and `100` reproduce the normal and high-contrast palettes bit for bit, so the
+slider is a continuous interpolation between exactly what the two tiers ship
+today.
 
-Because level `0` reproduces `'auto'` exactly, tier included, shipping the slider
-and defaulting it off costs a consumer nothing.
+That is a real accessibility trade-off: leave `contrastLevel` at `'auto'` unless
+you are giving users their own contrast control.
 
 ## Theme builder
 
 The `Theme Builder` story puts the whole config behind controls and renders the
-result into a single region, with one line drawn through the middle of the page:
-**the left column is the theme, the two switches over the preview are the
-viewing conditions.** Everything on the left writes to the palette config and
-would ship with the product; **Light / Dark** and **Normal / High contrast**
-write nothing at all — the same theme renders in all four combinations, and
-moving between them is how you check a theme rather than how you change one.
-
-Those two switches start on whatever the surrounding page is already showing and
-keep following it until you press one, after which they are yours. There is no
-`Auto` option to press: `Auto` means "follow the OS" — a _preference_ — and the
-preview resolves to flat token values, which can only express one concrete
-variant. Following is the default behaviour rather than a third choice.
-
-On the theme side, the panel is grouped by **what a knob reaches** rather than by
-what it is named after: **Global** for the ones that govern both zones — `pastel`,
-`saturation`, `surfaceMode` and `contrastLevel` — then **Accent** and **Base** for
-the ones that do not. `surfaceMode` files under Global despite moving the *base*
-surfaces, because the status themes' tinted surfaces follow it too, and so does the
-mirrored surface the syntax palette solves against.
-
-Those headings are also why the field labels are bare. `Seeded by` and `Hue` appear
-in both zones, and the heading above them is what says which — repeating it in
-every label was two words of noise on every line of a narrow column.
-
-The **contrast level** needs no on/off switch: level `0` and `'auto'` are
-output-identical, tier included, so the slider at rest _is_ the shipped palette.
-
-Status themes are four chips on one line rather than eight sliders. Each chip is a
-`type="current"` `Button` colored by its own theme with a
-[ColorSwatch](./components/fields/ColorSwatch.md) of its accent, so the group answers
-the question you actually have — do these four still read as four different
-things — at a glance; press one to open its hue and saturation. The hue is not
-printed on the chip: it belongs to the slider that sets it, and carrying it there
-cost the whole row, since `success — 157°` is wide enough that four of them have
-to stack.
-
-**Reset**, **Export** and **JSON** sit at the top of the column, not the bottom.
-The one button you reach for when an experiment goes wrong should not be behind
-the controls that caused it. `Export` opens the config as a `setPaletteConfig()`
-call to copy; `JSON` downloads `palette.json` on the press, with no intermediate
-state worth a second click. Both carry the config _as written_ rather than the
-resolved one, so an inherited `baseHue` stays inherited instead of being frozen to
-whatever the accent happened to be.
-
-Every caveat on the panel is an **InfoBadge** beside the control it qualifies rather
-than a paragraph under it. A tuner is a dense column of controls, and prose between
-them pushes the next knob off the screen to explain something you need once.
-
-Each of the two zones has a **Seeded by** switch — Hue or Color, plus _Follow accent_
-for the base. The hue slider stays on screen in color mode, disabled, showing the hue the
-color derived; switching back therefore hands the slider a value it was already
-displaying. One rule covers every inert control on the panel: **a control is disabled
-exactly when the config field it writes is not the field in charge.** That is also why
-the saturation slider greys out under Pastel rather than disappearing — it keeps showing
-the pinned `100`, which _is_ the contract, and your own number comes back when you turn
-Pastel off.
-
-In color mode the panel shows where the color actually landed — **Accent Fill** and
-**Accent Text**, the two tokens the seed's tone reaches. The requested color is not
-repeated beside them: the field above holds it, with a swatch of its own. Under Pastel
-the pair visibly diverges from what you typed, which is the chroma cap made legible
-rather than mysterious — type a saturated hex with Pastel off, then turn Pastel on and
-watch the chips soften.
-
-The **preset** buttons show which one is active, and stop showing it the moment you
-touch a control. The setter replaces rather than merges, so a preset is either the
-whole config or it is not the config at all; anything else would claim a theme is
-still `Ocean` after you had re-seeded half of it.
+result into a single region: pick **Light / Dark**, then either a contrast **mode**
+(Normal / High) or a **custom** 0–100 level, and the preview shows exactly that
+variant while the page around it stays as it is.
+
+There is no `Auto` for scheme or contrast mode, on purpose. `Auto` means "follow
+the OS" — a _preference_, and a flat token value cannot express one. A preview
+renders one concrete variant, so it has to name which. The contrast _level_ keeps
+its `Auto`, because there the choice is between the two-tier model and a hand-set
+number rather than between following and not following the system.
 
 The preview deliberately shows all three surface levels with their own text ramps
 (`#surface-text`, `#surface-2-text`, `#surface-3-text`), because a theme that looks
@@ -483,10 +267,8 @@ Notes:
 - `contrastLevel` works per region, so the whole 0–100 ramp can be shown at once —
   something a document cannot do, since it is only ever at one level. Level `0`
   reproduces the normal tier and `100` the high-contrast tier exactly, in both
-  schemes. `highContrast: true` still returns the genuine high-contrast
-  resolution at any level below `100`, because the level moves the baseline and
-  the tier escalates from where `'auto'` would put it; at `100` the two coincide
-  and it returns the same colors as the normal variant.
+  schemes. Because a manual level leaves no separate high-contrast tier,
+  `highContrast: true` correctly returns the same colors as the normal variant.
   Note that tokens carrying a contrast _floor_ (most text) can sit still over part
   of the ramp — the floor is solved, not approximated, so the value only moves once
   the interpolated target does. Tokens positioned by a plain tone pair, like
@@ -568,18 +350,9 @@ therefore re-tunes nothing — a seed picked in one space lands somewhere else i
 other, and the warm statuses move most. Re-tune the seeds alongside it, in whichever
 direction you flip.
 
-It also owns `saturation` outright — pinned to `100`, so a number passed _explicitly
-alongside_ it is inert and warned about (a number passed on its own turns pastel off
-instead). And it caps an `accentColor` short of itself: the ceiling sits below where a
-saturated color lands, so `#EF4444` resolves to `#c47069`. Both are visible in the
-[Theme builder](#theme-builder), the first as a disabled slider and the second as the
-requested/resolved chips.
-
 **Re-seeding costs about 10 ms.** Rebuilding the eight themes and re-solving
 ~156 tokens across four scheme variants is not free, though it is inside a frame.
-A manual `contrastLevel` costs the same — it runs the same four passes — except
-at level `100`, which skips the two high-contrast ones because the normal pass
-already produced those values.
+A manual `contrastLevel` is cheaper, since it skips both high-contrast passes.
 Setting the config to a value it already holds is free — it does not even bump
 the version. If you are driving it from a slider, let the input coalesce to
 frames (a pointer-driven `onChange` already does) rather than writing on every

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,189 @@
+# 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.
+- `Escape` inside the day panel does not close the surrounding popover — that is
+  a `Dialog` behaviour, not a calendar one.
+
+## 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