@oxy.so/bloom 2.11.0 → 2.12.1

package/docs/app-shell.mdx

@@ -1,6 +1,6 @@
 ---
 title: AppShell
-description: Page frame with four layout variants, the sidebar and a responsive drawer, pinned top/bottom/floating slots, a breadcrumb + title header, a notification bell and a floating Pro offer card.
+description: Page frame with five layout variants, the sidebar and a responsive drawer, pinned top/bottom/floating slots, a breadcrumb + title header, a notification bell and a floating Pro offer card.
 order: 83
 ---
 
@@ -27,9 +27,9 @@ import { AppShell, NotificationBell, ProOfferCard } from '@oxy.so/bloom/app-shel
 
 ## Variants
 
-One engine, four shapes. `variant` picks the shape; everything else — the nav,
+One engine, five shapes. `variant` picks the shape; everything else — the nav,
 the drawer, the pinned regions, the slots, the sizes — works the same in all
-four.
+five.
 
 | `variant` | The page | Scroll |
 | --- | --- | --- |
@@ -37,6 +37,7 @@ four.
 | `feed` | nav + a `contentWidth` reading column CENTRED in what the nav leaves, optional `aside` beside it, optionally in a `ContentPanel` | `document` / `container` / `fixed` |
 | `split` | a list pane, a detail pane and an optional info pane, each scrolling on its own, with a draggable divider | always one screen |
 | `focus` | one centred `contentWidth` column and NO nav | `document` / `container` / `fixed` |
+| `canvas` | ONE edge-to-edge area — no column, no cap, no padding — with the chrome floating over it | always one screen |
 
 `dashboard` is what this component always was, unchanged to the pixel — the
 existing stories render byte-identically against the version before variants
@@ -62,12 +63,59 @@ aside at `y = 16` while the content moved from `16` to `-390`.
 
 `panel` wraps the centre column in a [`ContentPanel`](/docs/bloom/main/content-panel),
 so the page background reads as a gutter around a framed surface; `framedFrom`
-is forwarded. The panel's content is inset by `gutter` — without it the page sits
+is forwarded.
+
+**The panel occupies the screen either way — what differs is what scrolls.**
+
+- `scroll="document"` (the default): the page scrolls, and the panel's frame is
+  a screen-tall sticky rectangle pinned at the shell's own `gutter`, so the
+  panel reads as a surface filling the window while the content moves inside
+  it. Measured in Chrome at 1280 × 900: the frame reports `top: 16, height: 868`
+  at scrollY 0, 1, 200, 600 and 846 — the same rectangle every time — while the
+  content behind it travels from 16 to −830. (The inset is what makes that
+  true: at the 8px default the frame would sit above the panel's real top edge
+  and snap down on the first scroll.)
+- `scroll="fixed"` / `"container"`: the shell bounds the panel, so the panel IS
+  the box — it closes at the bottom like the rail beside it, the header is
+  pinned inside it, and only the routed content scrolls, under the frame. The
+  document never moves at all.
+
+Both are right; they are different apps. A feed with the address bar collapsing
+on a phone and real anchor links wants `document`; a workspace whose regions
+each keep their own position wants `fixed`. The panel's content is inset by `gutter` — without it the page sits
 ON the frame, and a radius-28 corner clips whatever is in it (the heading loses
 its first letter). So `contentWidth` is the COLUMN's width, and the reading
 measure inside a panel is that minus two gutters. Do not render your own
 `ContentPanel` inside this one; it trips the nesting guard.
 
+### `canvas`
+
+```tsx
+<AppShell
+  variant="canvas"
+  sidebar={{ ...sidebar, surface: 'docked' }}
+  aside={<PlacesInView />}
+  floatingAction={<Button variant="primary" leadingIcon={RiAddFill}>Add a pin</Button>}
+>
+  <Map />
+</AppShell>
+```
+
+The content **is** the screen: one area, edge to edge, no reading column, no max
+width, no padding, exactly one viewport tall. A map, a board, an editor, a photo
+viewer. The header (if you pass one) sits above it in flow, because a toolbar
+over a map belongs to the map; `topBar`, `bottomBar`, `floatingAction` and
+`overlay` float over it as everywhere else.
+
+The shell's padding moves OUT of the row and onto the regions, so the nav is
+still a card with a gutter around it and the aside keeps its inset while the
+canvas alone runs to the window's edge — no negative margins anywhere: each
+region states its own inset.
+
+**`canvas` never scrolls the document**, for the same reason `split` doesn't: a
+canvas that grew the page would pan the page instead of the canvas.
+`scroll="document"` resolves to `fixed`, `scroll="container"` is honoured.
+
 ### `split`
 
 ```tsx
@@ -267,6 +315,44 @@ overlapping another, and no console error.
 A second column on the right of the page (`dashboard` and `feed`; `split` has
 its `info` pane instead and `focus` has no second column at all). From `asideFrom` (`xl`, 1280; or `md` / `lg`) it sits beside the content at `asideWidth` (320), pinned like the sidebar — with document scroll it is sticky and scrolls its own overflow, so give it `flex: 1` content if it should fill the height. Below the breakpoint it is stacked after the content (`asideCollapse="stack"`, the default) or dropped (`"hidden"`). Under `drawer="reveal"` it slides with the page.
 
+## Eight shells, one component
+
+The shape (`variant`), what scrolls (`scroll`), whether the column is a panel
+(`panel`) and the nav's own look (`sidebar.surface` / `sidebar.size`) are
+independent. That is the point: an app picks a row from this table and does not
+look like the app that picked the row above it.
+
+| The app | variant | scroll | nav |
+| --- | --- | --- | --- |
+| Product dashboard | `dashboard` | `document` | `card`, `medium` |
+| Social reader | `feed` + `panel` | `fixed` | `plain`, `large` |
+| Long-form feed | `feed` | `document` | `card`, `medium` |
+| Workspace (channels, files) | `dashboard` | `fixed` | `docked`, `small` |
+| Messenger | `split` | one screen | `docked`, `small` |
+| Map / board / editor | `canvas` | one screen | `docked`, `medium` |
+| Marketplace | `dashboard`, no `sidebar`, `topBar` `always` | `document` | — |
+| Sign-in, onboarding, reader | `focus` | `document` | none |
+
+```tsx
+// Social reader: a framed column that fills the screen, a nav with no edge.
+<AppShell variant="feed" panel scroll="fixed" sidebar={{ items, surface: 'plain', size: 'large' }} title="Home">
+  {feed}
+</AppShell>
+
+// Workspace: a column flush to the window, the page bounded, its own scrollers.
+<AppShell scroll="fixed" sidebar={{ items, surface: 'docked', size: 'small' }} title="Reports">
+  {report}
+</AppShell>
+
+// Marketplace: no rail at all — the navigation is the bar across the top.
+<AppShell topBar={<MarketHeader />} topBarVisibility="always" contentMaxWidth={1280}>
+  {results}
+</AppShell>
+```
+
+The stories **Three identities**, **Feed in a full-height panel** and **Canvas**
+render three of these side by side with nothing positioned by hand.
+
 ## The nav's identity is not the shell's layout
 
 `variant` picks the LAYOUT; `sidebar.surface` and `sidebar.size` pick what the navigation looks like. They are separate axes on purpose — the same shell carries a social reader, a workspace and a product dashboard without any of them re-implementing it:

package/docs/content-panel.mdx

@@ -51,28 +51,48 @@ the shadow is what makes it a panel lifted off it.
 | `surfaceColor`     | what the panel tells its content it is painted in — only when `surfaceClassName`/`surfaceStyle` repainted it |
 | `contentStyle` / `contentClassName` | the column inside it                      |
 | `maskColor`        | the colour the gutter mask fades to                        |
-| `overlaySizing`     | (web) how the mask/border overlays size themselves — see below |
+| `overlaySizing`     | (web) the screen's frame (default) or the panel's own box — see below |
+| `overlayInset`      | (web) where that sticky frame pins — match your layout's gutter |
+| `fill`              | the panel is the height it is given; its content scrolls inside |
 
-## `overlaySizing`: the panel's own box, or a constant frame
+## `overlaySizing`: the screen's frame, or the panel's own box
 
 The web overlays (the border frame and the gutter bleed-mask) default to
-**`overlaySizing="panel"`**: sized to the panel's own real box through CSS Grid
-layer-stacking. The edge behaves like any other border — it scrolls with the
-content, you see the two side edges while reading and the rounded corners at the
-ends of the page.
-
-`overlaySizing="viewport"` is the other mode: the overlays are `100dvh` and
-`position: sticky`-pinned, so a rounded top and bottom edge follow the viewport
-down the page. It was the default until it was measured against a long feed: the
-frame holds still while the content moves inside it and it jumps 8px on the
-first scroll, which reads as the panel breathing. It remains for a consumer that
-wants that constant frame — and it is also the mode `overlayTopOffset` exists
-for.
-
-Panel mode is additionally the right answer whenever the consumer's OWN shell
-bounds the panel (a fixed app shell with internal scroll containers): a
-viewport-sized overlay there paints over anything placed outside the panel, such
-as a header above it.
+**`overlaySizing="viewport"`**: a screen-tall sticky rectangle, `100dvh` minus
+the insets. The panel's own box grows with its content and the document scrolls
+it, while the edge stays where the screen is — so the panel occupies the window
+from top to bottom and the content moves inside it. That is what makes a
+document-scrolled column read as a surface rather than as an open-ended strip
+whose bottom edge is somewhere past the fold.
+
+**`overlayInset` has to match where the panel really starts.** Sticky
+positioning leaves an element at its static position until scrolling would push
+it past the inset, so a panel that begins 16px down the page with the default
+8px inset draws its frame at 16 and then SNAPS it to 8 on the first scroll. That
+8px jump is what "the panel moves when I scroll" is. Pass the gutter your
+layout uses:
+
+```tsx
+<View style={{ padding: 16 }}>
+  <ContentPanel framed overlayInset={16}>{page}</ContentPanel>
+</View>
+```
+
+`AppShell` passes its own `gutter` for you. Measured in Chrome at 1280 × 900,
+`variant="feed" panel`: the frame reports `top: 16, height: 868` at scrollY 0,
+1, 200, 600 and 846 — the same rectangle at every one — while the surface
+behind it moves from 16 to −830.
+
+An inset PAIR (`{ top, bottom }`) is for persistent chrome the consumer keeps
+outside the panel: a sticky header above it shifts where the panel visually
+starts without moving its DOM position, so the frame starts lower without also
+ending higher.
+
+`overlaySizing="panel"` is the other mode: the overlays are the panel's own box,
+through CSS Grid layer-stacking. Use it when the panel's box already IS the
+visible area (`fill`, below) or when something placed outside the panel must
+never be painted over by an overlay sized to the whole viewport — a bounded app
+shell with its own internal scrollers.
 
 ```tsx
 <View style={{ flex: 1 }}>
@@ -83,6 +103,32 @@ as a header above it.
 </View>
 ```
 
+## `fill`: a panel that reaches the bottom
+
+```tsx
+<AppShell scroll="fixed">        {/* something has to bound it */}
+  <ContentPanel framed fill>
+    <FlatList … />                {/* scrolls INSIDE the panel */}
+  </ContentPanel>
+</AppShell>
+```
+
+By default the panel grows with its content and the page scrolls: on a feed
+taller than the window you see the panel's top edge and its bottom edge is
+somewhere past the fold — an open-ended column, not a surface.
+
+`fill` makes the panel the height of the space it is given, with its content
+scrolling inside it. It closes at the bottom of the screen, the way the
+[`Sidebar`](/docs/bloom/main/sidebar) beside it does, and the frame never moves
+because the frame IS that box.
+
+It needs a parent that bounds it — an `AppShell` with `scroll="fixed"` or
+`scroll="container"` (which passes `fill` for you when you ask for `panel`), or
+any screen that is `flex: 1`. In a document-scrolled page there is no height to
+fill and the panel keeps growing; that page wants `scroll="document"`, not this
+prop. On web the content wrapper becomes the scroller; on native the panel is
+already `flex: 1`, so a `FlatList` inside fills it and scrolls within it.
+
 ## `framedFrom` is why the branch is not in your screen
 
 A phone wants a plain column: a frame a few pixels from the screen edge reads

package/docs/date-picker.mdx

@@ -6,16 +6,19 @@ order: 13
 
 # DatePicker
 
-`DatePicker`, `DateRangePicker` and `MeetingScheduler`. Bloom takes no dependency on react-aria or `@internationalized/date`, so the month layout, selection, constraints and keyboard navigation are plain TypeScript over local-midnight `Date`s. Colours come from the Bloom-derived ramps in `src/button/shared.ts`.
+`DatePicker`, `DateRangePicker`, `MeetingScheduler` and `TimeField`. Bloom takes no dependency on react-aria or `@internationalized/date`, so the month layout, selection, constraints and keyboard navigation are plain TypeScript over local-midnight `Date`s. Colours come from the Bloom-derived ramps in `src/button/shared.ts`.
 
 ```tsx
-import { DatePicker, DateRangePicker, MeetingScheduler, Calendar, RangeCalendar } from '@oxy.so/bloom/date-picker';
+import { DatePicker, DateRangePicker, MeetingScheduler, TimeField, Calendar, RangeCalendar } from '@oxy.so/bloom/date-picker';
 
 const [day, setDay] = useState<Date | null>(null);
 <DatePicker value={day} onChange={setDay} minDate={new Date()} />
 
 const [range, setRange] = useState<DateRange | null>(null);
 <DateRangePicker value={range} onChange={setRange} />
+
+const [time, setTime] = useState<string | null>('18:30');
+<TimeField value={time} onChange={setTime} step={15} accessibilityLabel="Viewing time" />
 ```
 
 ## Pickers
@@ -81,3 +84,78 @@ A range takes two presses in either order; between them the band follows the poi
 | `disabled?` | `boolean` | `false` | Blocks opening (pickers). |
 | `RangeCalendar.visibleMonths?` | `1 \| 2` | `1` | Months side by side. |
 | `defaultMonth?` | `Date` | value's month, else today's | First month shown (calendars). |
+
+## TimeField
+
+`DatePicker` is the day; `TimeField` is the hour and minute. It is a **field,
+not a fourth popover** — a viewing at 18:30 is four keystrokes, and a popover is
+the wrong instrument for four keystrokes. (`MeetingScheduler` still has the
+other shape: a fixed list of bookable slots, which is a different question —
+"which of these?" rather than "when?".)
+
+```tsx
+const [time, setTime] = useState<string | null>(null);
+<TimeField
+  value={time}
+  onChange={setTime}
+  min="09:00"
+  max="20:00"
+  step={15}
+  accessibilityLabel="Viewing time"
+/>
+```
+
+| prop | |
+| --- | --- |
+| `value` | 24h `"HH:mm"`, or `null` while empty — fully controlled |
+| `onChange` | the committed time, or `null` once emptied; never fires while typing |
+| `min`, `max` | 24h `"HH:mm"` bounds; a time outside is pulled to the bound |
+| `step` | minutes per arrow press, and the grid a typed time snaps to. Default `1` |
+| `hourFormat` | `'24h'` (default) or `'12h'` — how it is DRAWN; the value stays 24h |
+| `size` | `'small'` (96 × 32) or `'medium'` (default, 104 × 38) |
+| `disabled` | not editable, `aria-disabled`, `DISABLED_OPACITY` |
+| `accessibilityLabel` | **required** — the field draws no label, and `"--:--"` names nothing |
+| `placeholder` | default `"--:--"`, or `"--:-- --"` in 12h |
+| `width`, `style`, `testID` | |
+
+**The value is always 24h.** `hourFormat` decides what the reader sees, never
+what the caller receives, so a `TimeField` value drops straight into one of
+`MeetingScheduler`'s `timeSlots` and the app needs no locale to read it back.
+
+**It looks like the date chip because it is the same control.** Geometry,
+palette and focus behaviour are `DateChipInput`'s — the `DD/MM/YYYY` chip inside
+the pickers — so a date and a time typed beside each other line up: 1px
+`chipBorder` darkening to `chipBorderFocused` on focus (the border IS the focus
+indicator, `outline-none`), radius 10, shadow-xs, the panel fill.
+
+### Typing
+
+The field keeps its own **draft** while you type, so the text is not reformatted
+under the cursor, and commits on blur or submit. Escape reverts to the committed
+value, and so does a draft that does not parse — rather than an error the field
+has no room to draw.
+
+Parsing is deliberately forgiving, because a field that only accepts what it
+printed is a field people fight. All of these commit to `09:30`:
+
+`9:30` · `930` · `9.30` · `9 30` · `0930` · `9:3` · `9:30 am` · `9:30 a.m.`
+
+and `9` alone is `09:00`, `21:30` is `21:30`, `9pm` is `21:00`. An `am`/`pm`
+marker decides the half of the day whatever `hourFormat` says — somebody who
+typed `pm` means pm.
+
+`step` snaps a committed time to a grid counted **from midnight**, so `step={15}`
+always means :00 :15 :30 :45. Counting from `min` instead would knock the round
+times off the grid the moment a shop opened at 09:10.
+
+### Keyboard
+
+ArrowUp and ArrowDown move by `step` and commit immediately, clamped at `min`
+and `max` rather than wrapping — a wrap from `max` back to `min` reads as the
+field refusing the key. With no value yet, ArrowUp starts at `min` (or 00:00)
+and ArrowDown at `max` (or 23:59).
+
+They are a convenience **on a text box**, not a `spinbutton`: the control
+announces itself as the text field it is, named by `accessibilityLabel`, and
+every value the arrows can reach can also be typed. A `spinbutton` role would
+promise `aria-valuenow` over a value that is a string and may be empty.

package/docs/listing-card.mdx

@@ -84,6 +84,8 @@ and plural rules. Nothing here computes a price.
 | `badge`                                | top-left over the photo — a string draws the white pill, any node is placed as given                      |
 | `favorite`, `onFavoriteChange`         | the heart, top-right; drawn only when `onFavoriteChange` is given                                          |
 | `onPress`, `href`                      | see below                                                                                                  |
+| `onLongPress`, `onContextMenu`         | the press shortcut — see below                                                                             |
+| `hoverZoom`                            | web only, off by default: the photo scales 1.06 under the pointer                                          |
 | `loading`                              | a skeleton in the same geometry (`aria-busy`)                                                              |
 | `layout`                               | `'vertical'` (default, photo 20:19) or `'horizontal'` (square photo 40% wide, for lists and map sheets)   |
 | `density`                              | `'comfortable'` (default) or `'compact'`, a dense list row — see below                                    |
@@ -106,6 +108,32 @@ anchor's default navigation is prevented and `onPress` runs — a router takes i
 On native, `href` alone opens with `Linking`. With neither the card is not a
 control.
 
+**The press shortcut.** `onLongPress` fires on a long press — native, and a
+touch-and-hold on web. `onContextMenu` is its pointer spelling: a right-click on
+web, with the event defaulted for you, which is the same contract
+[`MessageBubble`](/docs/message-bubble) carries. Two props rather than one
+bridged prop, because they are two different events and an app may well want
+only one of them.
+
+Two things follow from defaulting the event. The browser's own menu — "open in
+a new tab", "copy link address" — no longer appears **on the card** while
+`onContextMenu` is set, so set it only where the shortcut is worth that. And
+neither event has a keyboard spelling or a name to announce, so whatever they
+open must be reachable another way: the heart, a row in a menu, a button on the
+detail screen. A long press is a shortcut, never the only door.
+
+**Hover zoom.** `hoverZoom` scales the photo to 1.06 while the pointer is over
+the card, 400ms, inside the tile that already clips — the photo comes forward,
+the card does not move and the grid does not reflow. It is WEB ONLY and guarded
+by `@media (any-hover: hover)`, so a touch screen reporting a hover it cannot
+deliver is left out, and it does nothing at all under
+`prefers-reduced-motion: reduce`. The compact density ignores it: a 112px
+thumbnail has nothing to come forward from.
+
+It is **off by default.** A card that grows under the pointer is a decision an
+app makes for its own grid, not one to turn on under every app already shipping
+this card.
+
 **The controls are siblings of the link, not children.** The heart and arrows are
 laid over the photo from outside the link: a button inside an anchor is invalid
 HTML, and would make pressing the heart open the stay. Each is its own tab stop.
@@ -190,6 +218,32 @@ it, two sit side by side, three put one tall photo beside two, four (or more) ma
 a 2×2 of the first four. The name and `description` sit under it. `onPress` and
 `href` behave as on `ListingCard`; the name is "Coast weekends, 12 saved".
 
+| prop              | decides                                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `name`            | the collection's name, one line                                                          |
+| `description`     | the pre-formatted line under it ("12 saved")                                              |
+| `photos`          | up to four covers, URLs or `ImageResolver` ids                                           |
+| `icon`            | a 16px glyph left of the name — decorative                                               |
+| `color`           | the `icon`'s colour, and the empty cover's tint                                          |
+| `empty`           | what the cover holds while `photos` is empty                                             |
+| `onPress`, `href` | as on `ListingCard`                                                                      |
+| `accessibilityLabel`, `style`, `testID` | `testID` derives `-cover`, `-icon`, `-empty`                           |
+
+**The icon goes beside the name, never inside it.** A folder emoji typed into
+`name` is read out by a screen reader as its character, cannot be coloured or
+sized, and counts against the one line the name gets. `icon` is a
+[`BloomIconComponent`](/docs/icons), `aria-hidden`, drawn at 16 in `color` (or
+text-secondary), and the name keeps its own line.
+
+`color` is the caller's colour rather than a token, because a collection's
+colour is the person's choice and Bloom has no ramp for it. It paints the glyph
+and tints the cover while the collection is empty.
+
+**Empty.** With no photos the cover is the placeholder square, and `empty` is
+centred in it — a glyph, a line, an "add your first save" affordance. Without
+`empty` it is the plain square it has always been, so nothing changes for a
+caller that has not asked for one.
+
 ## Colours
 
 All from the theme: the text is `text` / `textSecondary`; the badge pill and the

package/docs/rating.mdx

@@ -1,13 +1,13 @@
 ---
 title: Rating
-description: A compact star, value and review count, and the bar for a rating breakdown.
+description: A compact star, value and review count, the bar for a rating breakdown, and the star picker a review form is written with.
 order: 61
 ---
 
 # Rating
 
 ```tsx
-import { Rating, RatingBar } from '@oxy.so/bloom/rating';
+import { Rating, RatingBar, RatingInput } from '@oxy.so/bloom/rating';
 
 <Rating value={4.92} count={128} />                        // ★ 4.92 (128)
 <Rating value={4.81} count={214} countStyle="reviews" />   // ★ 4.81 · 214 reviews
@@ -15,8 +15,13 @@ import { Rating, RatingBar } from '@oxy.so/bloom/rating';
 
 <RatingBar label="Cleanliness" value={4.9} display="4.9" />
 <RatingBar label="5" labelWidth={12} value={0.86} max={1} display="86%" />
+
+const [stars, setStars] = useState<number | null>(null);
+<RatingInput value={stars} onChange={setStars} accessibilityLabel="Overall rating" />
 ```
 
+`Rating` shows a rating that exists; `RatingInput` is how one comes to exist.
+
 ## `Rating`
 
 | prop                 | decides                                                                                 |
@@ -53,3 +58,48 @@ measurement — and a rating breakdown is not a chart: the rows do not encode
 different categories by colour, they all say "how good is this, out of 5". It is
 a `progressbar` carrying `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and
 `aria-valuetext` (from `display`).
+
+## `RatingInput`
+
+The picker for a review form. Fully controlled: `value` is `1..max` or `null`
+while nothing is chosen, and `onChange` fires with the star that was chosen.
+
+| prop                 | decides                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| `value`              | the chosen rating, or `null` for nothing chosen yet                                          |
+| `onChange`           | called with the chosen rating; never called with the value already chosen                    |
+| `max`                | how many stars, default `5`                                                                  |
+| `size`               | `'small'` (24px star), `'medium'` (default, 32) or `'large'` (40)                            |
+| `disabled`           | no press, no keyboard, the group at `DISABLED_OPACITY`                                       |
+| `accessibilityLabel` | **required** — the name of what is being rated ("Overall rating")                            |
+| `formatStarLabel`    | each star's own name, default `"1 star"` / `"4 stars"` — translate it                        |
+| `style`, `testID`    | `testID` derives `-star-<n>`                                                                  |
+
+Chosen stars fill with the ACCENT, the rest are `RiStarLine` outlines in the
+neutral ramp — the same reasoning as [`RatingBar`](#ratingbar)'s fill: a chosen
+star is an answer somebody gave, and text-primary reads as ink rather than as
+one. Under a pointer the stars up to the hovered one fill as a preview, which
+never touches `value`.
+
+### Operating it without a mouse
+
+The group is a `radiogroup` named by `accessibilityLabel`, holding one `radio`
+per star named by `formatStarLabel`. Exactly one of N is what a rating IS, so
+`radio` is the role rather than a `slider` — and it is the only one that gives
+each star its own touch target and its own name to announce.
+
+The tab stop roves: the chosen star is the one in the tab order, or the first
+star while nothing is chosen, so one Tab reaches the group either way. Inside
+it, ArrowRight/ArrowUp, ArrowLeft/ArrowDown, Home and End move **and** choose,
+which is how an ARIA radio group behaves. The focus ring is drawn on the star.
+
+### No half stars, and no clearing
+
+Half a star doubles the keyboard stops and halves the target — 16px of a 32px
+star, under any touch floor — and the icon set has no half-star glyph, so the
+state could not be drawn honestly either. `Rating` still DISPLAYS fractional
+values (`4.92`): a display has no target and no keyboard.
+
+Clearing is left out for the reason re-choosing a [`Radio`](/docs/radio) is a
+no-op — a radio has no "off". A form that has no rating yet holds `null`; it
+does not need the group to express a state it cannot draw.

package/docs/stay-search.mdx

@@ -118,6 +118,38 @@ It is a `listbox` of `option`s with `aria-selected` on the highlighted row. The
 list takes focus on web and answers ArrowDown/ArrowUp (wrapping) and Enter;
 hover moves the same highlight. The rows stay out of the tab order.
 
+**A row that cannot be chosen.** `disabled` on an item dims it to
+`tokens.DISABLED_OPACITY`, gives it `aria-disabled`, refuses press and Enter,
+keeps hover from highlighting it, and makes the arrow keys step OVER it —
+ArrowDown from the row above lands past it, and a list where every row is
+disabled leaves the highlight alone rather than parking it on a row that answers
+nothing.
+
+`disabledReason` is the line that says WHY ("Location is off"). It replaces
+`description` while the row is disabled and is read after the title, so the row
+announces "Use my location, Location is off".
+
+```tsx
+<DestinationSuggestions
+  items={[
+    {
+      id: 'here',
+      title: 'Use my location',
+      icon: RiFocus3Line,
+      disabled: !locationOn,
+      disabledReason: 'Location is off',
+    },
+    { id: 'lisbon', title: 'Lisbon', description: 'Portugal' },
+  ]}
+  onSelect={choose}
+/>
+```
+
+The row stays in the list rather than disappearing, and it is drawn by the list
+rather than beside it: a row that vanishes teaches nothing, and one hand-drawn
+outside the `listbox` is not an `option` — it breaks the arrow keys and the
+"2 of 5" a screen reader counts.
+
 ### GuestPicker
 
 `StepperRow`s for adults, children, infants and pets, with hairlines between
@@ -125,6 +157,12 @@ rows. `value: { adults, children, infants, pets }`, `onChange`, `max` (one
 number or per kind), `kinds` (which rows, in order), `labels`, `descriptions`
 (`null` hides one).
 
+`decrementLabel` and `incrementLabel` name every row's `−` and `+` buttons —
+`Stepper`'s own prop names, forwarded to all of them. They default to the
+English `"Decrease"` / `"Increase"`, and they are the last two words in this
+family that a translated app could not reach. The row's title is what says
+which counter a button belongs to, so one pair covers every row.
+
 It is the ONE guests picker: the search bar's "Who" panel and `BookingCard`'s
 guests popover both use it. For the booking side: