@cube-dev/ui-kit 0.153.0 → 0.154.1

package/docs/Theming.md

@@ -21,16 +21,16 @@ value so this stays true.
 
 ## What is tunable
 
-| Option | Scope | Default |
-| --- | --- | --- |
-| `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. | `80` |
-| `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`. | `80` |
-| `pastel` | Global. Relaxes the sRGB-safe chroma limit. | `false` |
-| `contrastLevel` | Global. `'auto'`, or a manual `0`–`100` level. | `'auto'` |
+| Option                       | Scope                                                                                                                                                                 | Default                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `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.                                                                     | `80`                                |
+| `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`.                                                                | `80`                                |
+| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit. Every theme except `code`.                                                                                                | `false`                             |
+| `contrastLevel`              | Global. `'auto'`, or a manual `0`–`100` level.                                                                                                                        | `'auto'`                            |
 
 ### The setter replaces
 
@@ -81,15 +81,15 @@ 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.
+deliberately follows _its own_ hue, because a danger banner should read as red.
 
 ### One saturation scale per theme
 
-Saturation is *not* split, deliberately: `saturation` is the theme's **seed**, and
+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
+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
 together, in the ratios the palette was designed around. That is the point — the
 relationship between a subtle surface tint and a saturated accent is part of the
@@ -101,13 +101,17 @@ Syntax colors are their own theme with their own seed, so neither the brand hue
 the palette saturation reaches them. Hues are absolute literals — a brand re-seeded
 toward green would otherwise collide `code-string` with `code-number` (156°) — and
 the saturation is fixed at `80` rather than inheriting, so muting the app cannot
-wash out a code block. Tune it on its own:
+wash out a code block. `pastel` skips them for the same reason: it lowers the chroma
+ceiling far enough to take `code-keyword` from ~0.19 to ~0.07, collapsing the spread
+that keeps the syntax hues apart.
+
+So `themes.code.saturation` is the only thing that moves them. Tune it on its own:
 
 ```ts
 setPaletteConfig({ themes: { code: { saturation: 60 } } });
 ```
 
-They are still *adaptive*: each one is anchored to the real `surface` with an
+They are still _adaptive_: each one is anchored to the real `surface` with an
 `['AA','AAA']` floor, so they re-solve for light, dark and high contrast. Only hue
 and saturation are pinned.
 
@@ -147,7 +151,7 @@ const pinned = getPaletteConfigInput().baseHue !== undefined;
 
 Pinning a field to the value it already inherited resolves to the same colors but
 still counts as a change, so a UI reading the sparse config re-renders. Re-applying
-an *already pinned* value is a true no-op and costs nothing.
+an _already pinned_ value is a true no-op and costs nothing.
 
 ## Palette playground
 
@@ -194,8 +198,8 @@ result into a single region: pick **Light / Dark**, then either a contrast **mod
 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
+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.
 
@@ -229,11 +233,11 @@ The reason this needs its own API: the document palette emits **state maps**
 time — that is what `@dark` means. Collapsing the palette to a chosen scheme
 removes the conditionality, so several themes can coexist.
 
-| Option | Meaning |
-| --- | --- |
+| Option                      | Meaning                                                                                       |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
 | every `PaletteConfig` field | merged over the **current** config, so `{ scheme: 'dark' }` previews the active theme in dark |
-| `scheme` | `'light'` (default) or `'dark'` |
-| `highContrast` | resolve that scheme's high-contrast variant. Default `false` |
+| `scheme`                    | `'light'` (default) or `'dark'`                                                               |
+| `highContrast`              | resolve that scheme's high-contrast variant. Default `false`                                  |
 
 Nothing is applied globally — the live palette and the stored config are
 untouched, so previews are safe to render anywhere.
@@ -261,7 +265,7 @@ Notes:
   reproduces the normal tier and `100` the high-contrast tier exactly, in both
   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
+  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
   `#border`, step at every level.
@@ -315,7 +319,7 @@ Because the setter replaces, the prop describes the **whole** palette: drop a
 field from the object and that customization goes away on the next render, which
 is what you want from a declarative prop.
 
-Removing the prop entirely is the one thing that does *not* reset the palette —
+Removing the prop entirely is the one thing that does _not_ reset the palette —
 `<Root>` with no `palette` leaves whatever is configured alone, so that the common
 case cannot clobber a host's imperative `setPaletteConfig()` call. Pass
 `palette={{}}` if you do want the default.
@@ -333,11 +337,11 @@ and not per request:
 
 ## Caveats
 
-**`pastel: true` is a redesign, not a filter.** It changes every resolved color.
-The per-color saturation factors in this palette were tuned for the non-pastel
-space — pastel equalizes chroma across hues, so a pastel palette on the shipped
-seeds resolves more saturated than you may expect. Re-tune the seeds alongside
-it.
+**`pastel: true` is a redesign, not a filter.** It changes every resolved color
+outside the `code-*` family. The per-color saturation factors in this palette were
+tuned for the non-pastel space — pastel equalizes chroma across hues, so a pastel
+palette on the shipped seeds resolves more saturated than you may expect. Re-tune
+the seeds alongside it.
 
 **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.
@@ -366,7 +370,7 @@ it.
 **Some things are not tunable at all.** Tasty locks its configuration on the
 first style injection, so the `@dark` / `@hc` state definitions and the
 `colorSpace` (both set in `Root`) are fixed for the lifetime of the page. Only
-token *values* stay mutable — which is all re-seeding needs.
+token _values_ stay mutable — which is all re-seeding needs.
 
 ## See also
 

package/docs/components/fields/PeriodPicker.md

@@ -0,0 +1,75 @@
+# Period Pickers
+
+`WeekPicker`, `MonthPicker`, `QuarterPicker`, and `YearPicker` let users select a
+whole calendar period instead of a specific day. They mirror Ant Design's
+`DatePicker picker="week|month|quarter|year"` feature, but are exposed as four
+dedicated components that share a single implementation.
+
+The value is always a single `CalendarDate` (from `@internationalized/date`)
+**snapped to the start of the chosen period**:
+
+- **Week** → the first day of the week (locale-aware)
+- **Month** → the 1st of the month
+- **Quarter** → the 1st of the first month of the quarter
+- **Year** → January 1st
+
+The field renders a compact label for the selected period (`2026-W33`, `2026-08`,
+`2026-Q3`, `2026`). Use `formatValue` to override it.
+
+## When to Use
+
+- Filtering or reporting by week, month, quarter, or fiscal year
+- Any input where the natural unit is a period rather than an exact day
+- As a lighter alternative to a full `DatePicker` when day precision is unwanted
+
+## Component
+
+---
+
+### Properties
+
+- **`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
+- **`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)
+- **`defaultOpen`** `boolean` — Whether the popover is open by default (uncontrolled)
+- **`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.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+- **`styles`** — root field styles
+- **`wrapperStyles`** — the input wrapper
+- **`inputStyles`** — the value/label area
+- **`triggerStyles`** — the calendar trigger button
+
+## Examples
+
+### Month
+
+### Quarter
+
+### Year
+
+### Week
+
+### Limited range
+

package/package.json

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