@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/music-library.mdx

@@ -0,0 +1,159 @@
+---
+title: Music Library
+description: The Your Library side panel and its rows, plus the search page parts — the search pill, result tabs, top result card, recent searches and the browse grid.
+order: 66
+---
+
+# Music Library
+
+Two screens of a music app: the library panel on the left, and the search page.
+
+```tsx
+import {
+  BrowseGrid,
+  LibraryItem,
+  LibraryPanel,
+  RecentSearches,
+  SearchField,
+  SearchResultTabs,
+  TopResultCard,
+  filterLibraryItems,
+  sortLibraryItems,
+} from '@oxy.so/bloom/music-library';
+```
+
+Colours come from the theme in light and dark: surfaces are the page background stepped toward the text colour (so a panel reads as a panel on any page), the accent is the theme's `primary`. Hover and press change colour only — nothing scales.
+
+## `LibraryPanel`
+
+```tsx
+<LibraryPanel
+  items={entries}
+  selectedId={openPageId}
+  nowPlayingId={context?.id}
+  paused={!playing}
+  onItemPress={(item) => router.push(`/library/${item.id}`)}
+  onCreatePress={openCreateMenu}
+  collapsed={railOpen}
+  onCollapsedChange={setRailOpen}
+  expanded={wide}
+  onExpandedChange={setWide}
+  renderContextMenu={(item) => (
+    <>
+      <ContextMenuItem onPress={() => pin(item)}>{item.pinned ? 'Unpin' : 'Pin'}</ContextMenuItem>
+      <ContextMenuItem variant="destructive" onPress={() => remove(item)}>Remove from Your Library</ContextMenuItem>
+    </>
+  )}
+  style={{ width: wide ? 560 : 360, height: '100%' }}
+/>
+```
+
+| prop | decides |
+| --- | --- |
+| `items` | `LibraryEntry[]` — `id`, `title`, `kind` (`playlist` · `artist` · `album` · `podcast` · `audiobook` · `folder`), `subtitle` ("Maya"), `meta` (replaces "Playlist · Maya"), `cover` (URL or ImageResolver id), `pinned`, `downloaded`, `addedAt`, `lastPlayedAt`, `creator` |
+| `filter` / `onFilterChange` | the kind chip, or `null`. Pressing the active chip turns it off; the × chip clears the kind and Downloaded |
+| `downloadedOnly` / `onDownloadedOnlyChange` | the Downloaded chip — combines with the kind filter (AND) |
+| `sort` / `onSortChange` | `recents` (default) · `recently-added` · `alphabetical` · `creator` |
+| `view` / `onViewChange` | `compact` · `list` (default) · `grid` |
+| `query` / `onQueryChange` | the in-library search, opened from the search glyph |
+| `filters`, `hideDownloadedFilter` | which chips to draw |
+| `collapsed`, `onCollapsedChange` | the rail: 72 wide, covers only, tooltips on web. The title becomes the rail toggle when `onCollapsedChange` is set |
+| `expanded`, `onExpandedChange` | draws the expand toggle; the panel's width is yours to change |
+| `onCreatePress` | draws the + button |
+| `selectedId`, `nowPlayingId`, `paused` | the open page's fill, the playing entry's accent title and bars |
+| `renderContextMenu` | `ContextMenuItem` rows per entry — right-click on web, long press on native |
+| `labels` | every string, merged over English defaults (nested `filter`, `sort`, `view`, `kind`) |
+| `emptyState` | replaces "Nothing here yet" |
+
+**Controlled or not, per value.** Filter, Downloaded, sort, view and query each follow their prop when it is set and keep their own state when it is not; the change callback fires in both cases. So `sort="alphabetical"` alone pins the sort while the chips stay interactive.
+
+**Order.** Pinned entries always lead, in the current sort among themselves. `recents` and `recently-added` put entries without the timestamp last; `alphabetical` ignores case and accents; `creator` sorts by `creator`, else `subtitle`, then title. The sort is stable.
+
+The logic is exported so a server-backed library can apply the same rules:
+
+```ts
+const shown = sortLibraryItems(filterLibraryItems(items, { filter, downloadedOnly, query }), sort);
+```
+
+The sort and view menu is one `DropdownMenu` with two radio groups; its trigger is named "Sort and view: Recents, List".
+
+## `LibraryItem`
+
+One row, used by the panel and usable on its own (a "Your playlists" list elsewhere).
+
+| `variant` | draws |
+| --- | --- |
+| `list` (default) | 48 cover (a circle for artists) · title over "Playlist · Maya", led by the pinned and downloaded glyphs · the now-playing bars |
+| `compact` | title · meta on one line, no cover |
+| `grid` | a square cover filling the tile, title, meta |
+| `rail` | the cover alone, the bars on its corner while playing; a tooltip on web hover |
+
+The row is a `button` named by everything it shows — "Night Drive, Playlist · Maya, Pinned, Downloaded, Now playing" — because the glyphs carry state no text does. `selected` sets `aria-current="page"` on web and `accessibilityState.selected` on native. `pinnedLabel`, `downloadedLabel`, `nowPlayingLabel` and `kindLabels` translate it.
+
+## `SearchField`
+
+```tsx
+<SearchField
+  value={query}
+  onChangeText={setQuery}
+  onClear={() => setQuery('')}
+  onSubmit={runSearch}
+  onBrowsePress={() => router.push('/search')}
+  browseActive={onBrowsePage}
+/>
+```
+
+A 48-tall full pill: search glyph, input, a clear × once there is text, then a divider and the browse button. The field is controlled — `onClear` reports, it does not clear. The browse button is a toggle (`aria-pressed` on web, `accessibilityState.selected` on native). A press anywhere on the pill focuses the input; focus draws a text-coloured border without changing the size.
+
+## `SearchResultTabs`
+
+```tsx
+<SearchResultTabs
+  tabs={[{ value: 'all', label: 'All' }, { value: 'songs', label: 'Songs' }, { value: 'artists', label: 'Artists' }]}
+  value={tab}
+  onValueChange={setTab}
+/>
+```
+
+`Chip`s on the `xl` rung (32 tall, 12px sides): neutral at rest, the brand subtle tint when selected. The row is a `ChipRow`, so it scrolls sideways with a fade at whichever edge has more behind it. A `tablist` of `tab`s with `aria-selected` — `Chip`'s `role="tab"`, which picks `aria-selected` over `aria-pressed`; on web the row is one tab stop and the arrow keys, Home and End move focus.
+
+## `TopResultCard`
+
+```tsx
+<TopResultCard
+  title="Lumen Vale"
+  kind="artist"
+  subtitle="4.2M monthly listeners"
+  cover={artist.image}
+  onPress={openArtist}
+  onPlayPress={playArtist}
+  playing={isPlaying}
+/>
+```
+
+A 16-radius card: a 92 cover (round for `artist` and `profile`), the title in `title-1-bold`, a kind pill and the subtitle. The `PlayButton` sits in the bottom-right corner — on web it fades in on hover or keyboard focus (and stays while playing), on touch and native it is always shown. It is a sibling of the card's button, not nested in it, so both are reachable. `kindLabel` translates the pill.
+
+## `RecentSearches`
+
+```tsx
+<RecentSearches
+  items={recent}
+  onItemPress={(item) => setQuery(item.title)}
+  onRemove={(item) => forget(item.id)}
+  onClearAll={forgetAll}
+/>
+```
+
+Rows of cover, title and meta with a × button beside each (a separate control named "Remove Paper Moons"), and a "Clear recent searches" button while there is anything to clear. `round` draws an artist's cover as a circle.
+
+## `BrowseGrid`
+
+```tsx
+<BrowseGrid title="Browse all" items={genres} onItemPress={openGenre} />
+
+<BrowseGrid minTileWidth={200}>
+  {moods.map((mood) => <MoodCard key={mood.id} {...mood} />)}
+</BrowseGrid>
+```
+
+Columns are as many as fit at `minTileWidth` (default 128, which is two on a phone), measured from the grid's width. With `items` each tile is a 12-radius colour block with its title and a tilted image in the corner. **The title always clears 4.5:1**: white when white does, near-black when that does, and for a mid-grey that neither clears the tile's fill is darkened until white does — so any colour the backend sends stays readable. An unparseable colour falls back to a neutral tile. With `children`, each child is one cell and draws itself.

package/docs/offering-badge.mdx

@@ -0,0 +1,79 @@
+---
+title: Offering Badge
+description: A small pill naming how a home is offered — for rent, for sale, vacation rental or swap — tinted on the page or light over a photo.
+order: 106
+---
+
+# Offering Badge
+
+```tsx
+import { OfferingBadge } from '@oxy.so/bloom/offering-badge';
+import type { Offering } from '@oxy.so/bloom/offering-badge';
+
+<OfferingBadge offering="long_term_rent" />
+<OfferingBadge offering="sale" size="small" />
+<OfferingBadge offering="short_term_rent" variant="onMedia" />
+<OfferingBadge offering="exchange" label="Intercambio" />
+```
+
+An **offering** is how a home is put on the market, and a listing may carry
+several at once (a flat for rent and for sale). A room, a studio or a house is
+the property's _type_, not an offering.
+
+```ts
+type Offering = 'long_term_rent' | 'short_term_rent' | 'sale' | 'exchange';
+```
+
+The type lives with the listing card (`@oxy.so/bloom/listing-card`) and is
+re-exported here.
+
+| prop       | decides                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| `offering` | the default label, icon and tint                                                             |
+| `label`    | replaces the English label — "For rent", "For sale", "Vacation rental", "Swap"               |
+| `icon`     | `true` (default) the offering's icon, `false` none, or an icon component to draw instead     |
+| `size`     | `'medium'` (default) or `'small'`                                                            |
+| `variant`  | `'tinted'` (default) on the page, `'onMedia'` over a photo                                   |
+| `style`, `testID` | the icon is `<testID>-icon`                                                           |
+
+## Anatomy
+
+|          | height | padding-x | icon | text                 |
+| -------- | ------ | --------- | ---- | -------------------- |
+| `small`  | 20     | 8         | 12   | `caption-1-semibold` |
+| `medium` | 24     | 10        | 14   | `body-2-semibold`    |
+
+A full pill, 4 between the icon and the label, the leading padding 2 tighter
+when there is an icon. One line, truncated.
+
+Those two rows ARE [`Badge`](/docs/bloom/main/badge)'s `label-small` and
+`label-medium` rungs, and this component is a preset over them — about forty
+lines that map an offering to a word, a glyph and a tone. It used to carry its
+own copy of the geometry, its own paint resolver and its own pill, and the
+listing card's status pill had grown a third copy of the same table.
+
+| offering          | icon                   | tone      |
+| ----------------- | ---------------------- | --------- |
+| `long_term_rent`  | `RiKey2Line`           | `info`    |
+| `sale`            | `RiPriceTag3Line`      | `success` |
+| `short_term_rent` | `RiSuitcaseLine`       | `warning` |
+| `exchange`        | `RiArrowLeftRightLine` | `default` (neutral) |
+
+## Colour
+
+`tinted` paints the tone's `subtle` pair from `resolveAccentColors` — the tint and
+its foreground, gated at AA by the colour policy, so nothing is derived here.
+The tones are **fixed**, never the preset's brand colour: `info`, `success` and
+`warning` do not move with the preset, so "blue is rent" holds in every app,
+whereas a brand tint would collide with one of them (a blue brand IS `info`, a
+green one `success`). Swap takes the one neutral, which no preset can collide
+with. The four stay distinct on every preset in both modes.
+
+`onMedia` is `Badge`'s own `onMedia` fill: a `neutral-50` pill with a
+`neutral-900` label and icon and `shadow-s`, the same in both modes because the
+photo under it does not change with the theme.
+
+## Accessibility
+
+It is text, not a control: no role, the icon hidden, so it reads as its label.
+Inside a pressable card, fold the label into the card's name — `ListingCard` does.

package/docs/overlay.mdx

@@ -42,6 +42,43 @@ Toasts are the one deliberate exception: `ToastHost` mounts for the app's whole
 life, so taking a rank would wedge the counter, and it passes an explicit
 `zIndex` instead.
 
+## An overlay starts a new painting context
+
+`OverlayRoot` publishes surface level 0 for everything inside it (the ladder in
+[Styles](/docs/bloom/main/styles)). React context reaches through a portal even
+though the DOM does not, so without that reset a dialog opened from a control
+inside a `ContentPanel` would inherit "I am on a card" and paint itself
+differently from the same dialog opened on a bare screen — a surface taking its
+colours from where its TRIGGER lives.
+
+It publishes the **rung alone, with no `fill`**, and that is the shape of what an
+`OverlayRoot` knows. It paints nothing itself — it is a transparent, `box-none`
+full-screen layer — so it has no colour to report. What it can say truthfully is
+"you are not on the surface your trigger was on", and level 0 is the assumption
+that costs least when nothing better arrives: the page rung, which is what every
+unwrapped consumer already assumed.
+
+The surfaces that DO know their colour declare it INSIDE their own `OverlayRoot`,
+which is what makes each claim absolute rather than a step off an ancestor it
+cannot see:
+
+| Surface | Publishes |
+| --- | --- |
+| `dialog/Dialog` (both forks) | level 0, `fill` = `colors.background` |
+| `bottom-sheet/BottomSheetBase` | level 0, `fill` = `colors.background` |
+| `floating/FloatingPanel` | level 1 — the menu/popover surface |
+
+**Not every overlay body paints `colors.background`.** `SettingsModal` paints
+`resolveSettingsPalette(theme).full` and `Tooltip` paints the menu palette, and
+neither publishes a fill — so content inside either reads the page rung rather
+than the real colour behind it. That is an approximation inherited from before
+the ladder existed, not a claim this root makes; the fix is for each surface to
+publish its own `fill`, not for `OverlayRoot` to guess one on its behalf.
+
+Native bottom sheets never reach an `OverlayRoot` (they mount in an RN
+`<Modal>`), so `bottom-sheet/BottomSheetBase` does the same reset itself, once,
+for every sheet-presenting family.
+
 ## The `pointerEvents` rule
 
 `box-none` and `box-only` are React Native-only values and **must be passed as

package/docs/place-reviews.mdx

@@ -0,0 +1,80 @@
+---
+title: Place reviews
+description: Reviews of a building by its past tenants — an anonymised review card with housing categories, a summary with deposit and recommendation stats, and an invitation to review.
+order: 122
+---
+
+# Place reviews
+
+Reviews of a BUILDING, not a listing: they outlive any one listing and stay with the
+place.
+
+```tsx
+import { PlaceReviewCard, PlaceReviewSummary, WriteReviewPrompt } from '@oxy.so/bloom/place-reviews';
+
+<PlaceReviewSummary
+  rating={3.9}
+  title="Rated by past tenants"
+  reviewCount={46}
+  categories={[
+    { label: 'Landlord responsiveness', value: 3.4, icon: RiCustomerService2Line },
+    { label: 'Maintenance', value: 3.1, icon: RiToolsLine },
+    { label: 'Noise', value: 4.2, icon: RiVolumeDownLine },
+  ]}
+  depositReturnedRate={0.82}
+  recommendRate={0.71}
+/>
+
+<WriteReviewPrompt buildingTitle="Calle del Olmo 14" onStart={openReviewForm} onDismiss={hide} />
+
+<PlaceReviewCard
+  authorLabel="Tenant, 2021–2024"
+  authorInitial="T"
+  date="Reviewed March 2026"
+  rating={4}
+  wouldRecommend
+  depositReturned
+  categories={[{ label: 'Maintenance', value: 3.5 }, { label: 'Neighbours', value: 5 }]}
+  text={review.text}
+  helpfulCount={12}
+  helpful={helpful}
+  onHelpfulChange={setHelpful}
+  onReport={report}
+/>
+```
+
+## Anonymous by construction
+
+`PlaceReviewCard` has no name field: `authorLabel` is the anonymised line ("Tenant,
+2021–2023") and `authorInitial` an optional single letter in the avatar disc. A review
+of a building can reach the landlord, so the app decides what the line reveals.
+
+## `PlaceReviewSummary` reuses `ReviewSummary`
+
+It renders `ReviewSummary` from `@oxy.so/bloom/listing-details` — the big rating, the
+title, "46 reviews" and the category `RatingBar`s in two columns from 640 wide — and adds
+the tenancy stat lines under it. It does not copy that part, so the two stay one design.
+
+The rates are fractions (0..1) and are the one thing computed here: rounded to a whole
+percent and passed to `formatDepositReturned` ("Deposit returned in 82% of tenancies")
+and `formatRecommend` ("71% would recommend living here"). Each line is one accessible
+element. `formatReviewCount` defaults to "1 review" / "46 reviews".
+
+## `PlaceReviewCard`
+
+- **Chips:** would recommend (success) or not (neutral); deposit returned (success) or
+  not (error). `undefined` draws neither — unknown is not "no".
+- **Categories:** `RatingBar`s, two columns from 520 wide (`layout="auto"`), one below.
+- **Text:** clamped to `numberOfLines` (4); "Show more" appears only when the text IS
+  clamped (measured), with `aria-expanded` / `expanded`.
+- **Helpful:** a pill toggle with `aria-pressed` (web) and `accessibilityState.selected`
+  (native), named "Helpful, 12". The count is the caller's — add the viewer's vote
+  yourself.
+- **Report:** a secondary link button, drawn with `onReport`.
+
+## `WriteReviewPrompt`
+
+A card with a building tile, "Did you live here?" (a heading), a description that names
+`buildingTitle`, and a small primary "Write a review" button that drops under the text
+when narrow. `onDismiss` adds a close button named `dismissLabel`. `media` replaces the
+tile (a photo of the building).

package/docs/popover.mdx

@@ -110,6 +110,14 @@ A popover centres on its trigger by default, where a menu starts at its left edg
 
 A numeric `maxWidth` prop replaces the viewport cap.
 
+## Following the anchor (web)
+
+An open panel tracks its trigger. Bloom listens for `scroll` in the CAPTURE phase, which is the only listener that hears a scroll inside an ancestor — a panel opened from a row of a scrolling list stays on its row — plus `resize`, because the viewport is what the surface flips and clamps against.
+
+What it does NOT do is work per event. A scroll gesture dispatches a stream of events and nested scrollers dispatch one each, while the browser paints once; so the measurement is coalesced to at most one pass per animation frame, and the frame boundary is the last moment before the paint, which makes it the most recent position the panel can be given. A pass that resolves to the box the surface already holds is dropped rather than stored: the anchor and the placement keep their identity, nothing re-renders, and the listeners — registered once when the panel opens — are not detached and re-attached. Opening still measures synchronously in a layout effect, so the first painted frame is already in the right place.
+
+This is `FloatingPanel`'s behaviour, so it is every menu, popover and select's; `Tooltip` follows its trigger every frame instead, for the reason its own page gives. The cost model is pinned by `src/__tests__/floating-anchor-cost.test.tsx`, which counts measurements, commits and listener registrations in a real DOM.
+
 ## Native
 
 The popover is a bottom sheet on native: a phone has no room to float a panel beside a control, and every Bloom overlay resolving to the same sheet is what makes the native surfaces feel like one system. The sheet is the chrome (its surface, corner and drag handle), so the placement props are ignored and only the body takes the panel geometry — the same 10px inset on the sides and bottom, below the handle's clearance — so the panel parts line up exactly as they do on web. `className`, `style` and `testID` land on that body.
@@ -125,3 +133,10 @@ Press outside or hit Escape. `dismissible={false}` turns both off, for a popover
 Escape stops at the innermost open surface, so a popover opened from inside a dialog closes the popover and leaves the dialog up.
 
 The outside press is caught by a transparent backdrop (it closes the popover and goes no further). Popovers are non-modal — a press outside would otherwise also reach the page — but Bloom keeps the caught press so a popover opened inside a dialog cannot dismiss the dialog with the same click.
+
+## The panel publishes its surface
+
+`FloatingPanel` — the surface behind every menu, popover, select and tooltip —
+wraps its children in `SurfaceLevelProvider level={1}`
+([Styles → Ambient level](/docs/bloom/main/styles)). A `TextField` inside used to
+step off the PAGE and land on exactly the panel's own fill (1.000:1, no shell).

package/docs/property-insights.mdx

@@ -0,0 +1,192 @@
+---
+title: Property insights
+description: The data parts of a home for rent or sale — energy label and badge, price history chart, explainable price estimate, price per area comparison, neighbourhood scores, nearby places and rent history.
+order: 114
+---
+
+# Property insights
+
+```tsx
+import {
+  EnergyBadge,
+  EnergyLabel,
+  NearbyPlaces,
+  NeighbourhoodScores,
+  PriceEstimate,
+  PriceHistoryChart,
+  PricePerAreaComparison,
+  RentHistoryList,
+} from '@oxy.so/bloom/property-insights';
+
+<ListingSection title="Energy certificate">
+  <EnergyLabel
+    consumption={{ rating: 'C', value: '112 kWh/m²·year' }}
+    emissions={{ rating: 'D', value: '24 kg CO₂/m²·year' }}
+  />
+</ListingSection>
+
+<ListingSection title="Is the price right?">
+  <PriceEstimate
+    low={362000}
+    high={398000}
+    estimate={381000}
+    asking={385000}
+    confidence="high"
+    confidenceNote="Nine recent sales nearby"
+    reasons={reasons}
+    comparables={24}
+    method="Automated valuation"
+    version="Model 3.2"
+    updated="Updated 2 Sep 2026"
+    format={formatPrice}
+  />
+  <PriceHistoryChart periods={periods} format={formatPrice} formatAxisValue={formatPriceShort} />
+  <PricePerAreaComparison rows={[
+    { label: 'This home', value: 2790, display: '€2,790/m²', highlight: true },
+    { label: 'Cedofeita', value: 2940, display: '€2,940/m²' },
+  ]} />
+</ListingSection>
+
+<ListingSection title="The neighbourhood">
+  <NeighbourhoodScores items={scores} />
+  <NearbyPlaces items={places} />
+</ListingSection>
+
+<ListingSection title="Rent history">
+  <RentHistoryList items={history} />
+</ListingSection>
+```
+
+The page around them — facts, floor plans, the agent or landlord card — is in
+[`@oxy.so/bloom/listing-details`](./listing-details) (`PropertyFacts`, `FloorPlan`,
+`ContactCard`). Storybook: **Blocks/Housing/Property Insights** has a full sale page
+and a rental page at 1280 and 390, light and dark, and every part alone.
+
+## What arrives formatted, and what the parts compute
+
+Labels, dates, units, `display` values and deltas are pre-formatted strings. Three
+parts must do arithmetic, so they take NUMBERS plus a `format` function (the app owns
+currency and locale; the default is `€385,000`):
+
+| part | computes |
+| --- | --- |
+| `PriceHistoryChart` | the Y domain and ticks, the path, the headline and the chart summary |
+| `PriceEstimate` | the bar positions, the verdict and its percentage |
+| `PricePerAreaComparison` | bar lengths (`value / largest value`); the label is `display` |
+| `NeighbourhoodScores` | `value / max`; the label is `display`, default `value` to one decimal |
+
+## `EnergyLabel` and `EnergyBadge`
+
+Seven bars, A → G, 24 tall and 4 apart; A is 40% of the scale column and each class
+adds 10%. The colours are Bloom's own scale on the theme: a fixed lightness curve
+(dark green, up to a light yellow at D, down to a deep red) with the HUES taken from
+the theme's `success` (A), `warning` (E) and `error` (G), interpolated in OKLCH. The
+letter is white or neutral-950, whichever contrasts more — at least 4.5:1 in every
+preset and mode (gated).
+
+Each rating given (`consumption`, `emissions`) gets a column with an arrow tag on its
+class's row, in the class colour: "C · 112 kWh/m²·year". With both columns below 560
+wide the tags hold the letter only and the values move under the scale, so nothing
+truncates on a phone. `pending` draws the scale neutral, no tags, and "Certificate in
+progress" (`pendingLabel`).
+
+The label is one image with a composed name ("Energy rating. Consumption: C,
+112 kWh/m²·year. Emissions: D, 24 kg CO₂/m²·year.").
+
+`EnergyBadge` is the class inline — a neutral pill (20 / 24 tall, `size`) with a disc in
+the class colour and `label` ("Energy"; `""` for the class alone). Without `rating`, or
+with `pending`, it draws a clock and "Pending". Named "Energy rating C".
+
+## `PriceHistoryChart`
+
+Built on the chart-card primitives (`ChartCardSurface`, `PeriodChartHeader`,
+`CartesianPlot`): the headline is the current price and follows the hovered point;
+`periods` are the 1Y / 3Y / All segments, each with its own `data` and `events`.
+
+- `shape="step"` (default) holds each price until it changes — an asking price does not
+  glide between listings. `shape="line"` joins the points.
+- The Y axis is nice ticks AROUND the prices, not from zero, so a 5% drop is visible.
+- `events` are markers on their point, coloured by `kind`: `listed` primary,
+  `price-drop` success, `price-rise` warning, `rented` / `sold` text, `delisted`
+  tertiary — and repeated as text in a legend under the plot.
+- The last point carries a "Now · €385,000" callout (`currentLabel`), hidden while a
+  point is hovered.
+- Fewer than two points draw "No price history yet" (`emptyLabel`) instead of a plot.
+
+**Accessible summary.** The plot's `role="img"` is named by a composed summary: "Price
+history, 1Y: from €405,000 in September 2025 to €385,000 in March 2026. Listed,
+September 2025. Price drop −5%, March 2026." (`accessibilityLabel` overrides it). Give
+points a `title` so the summary reads in full months, not axis labels.
+
+## `PriceEstimate`
+
+An estimate that explains itself and never implies precision it does not have.
+
+- The range as a heading, then a bar: the band `low` → `high`, the point `estimate` as
+  a tick, the `asking` price as a taller marker with its label, and the ends labelled.
+- The verdict compares `asking` with the NEAREST edge of the range: inside is "Fair
+  price" (success); below is "Below estimate by 6%" (success); above is "Above estimate
+  by 8%" — warning up to `highAboveRatio` (10%), error beyond. `formatVerdict`
+  translates it.
+- `confidence` is a 3-segment meter (a `progressbar`, 1–3) with its label and
+  `confidenceNote`.
+- "Why this estimate" expands `reasons` and the `comparables` count; the footer joins
+  `method`, `version` and `updated`.
+
+### Confidence changes the drawing, not just the label
+
+| confidence | band drawn | core band | estimate tick | verdict |
+| --- | --- | --- | --- | --- |
+| `high` | `low` → `high` | accent | shown | shown |
+| `medium` | widened by 25% of the range each side, soft | accent | shown | shown |
+| `low` | widened by 50% of the range each side, soft | **soft, no firm edge** | **hidden** | **replaced by "Not enough data for a verdict"** |
+
+`confidence: 'low'` widens the visual band and hides the verdict. The numbers under
+the band stay the model's range — only the picture refuses to look precise.
+
+## `PricePerAreaComparison`
+
+Rows of label + `display` over an 8-tall bar from zero. This is the one family here
+that is a CHART rather than a meter — each bar is a different subject compared with
+the others — so its colours come from the chart palette, not the meter's: the
+`highlight` row takes the brand-anchored data hue (`chartHueTone(theme, 6)`) and the
+comparators `neutralSeries`. Painting them with the accent would have said each row was
+progress toward something. There is no rail: `neutralSeries` is neutral-800 in dark, so
+on any rail dark enough to read as one the comparators land on its colour — and a bar
+chart does not draw the remainder anyway. A named list; each row reads
+"This home: €2,790/m²".
+
+## `NeighbourhoodScores` and `NearbyPlaces`
+
+`NeighbourhoodScores` draws each score as a bar (`variant="bars"`, default) or a 56px
+ring (`rings`) — both [`Meter`](/docs/stat-bar) and `MeterRing`, so the shared
+neutral track and accent fill — with an optional icon and a short `description`. The labels are yours
+("Transport", "Schools", "Quiet"…); `max` defaults to 10. Columns: 1 below 560 wide,
+2 from 560 (`columns`). Every bar or ring is a `progressbar` named by its label with
+flat `aria-valuemin/max/now` and `aria-valuetext` ("9.2 out of 10").
+
+`NearbyPlaces` rows: a 40 icon disc, name and category, and the walking time on the
+right (`modeIcon` for another mode). Each row reads "Lapa station, Metro, 4 min walk"
+(`formatTime`).
+
+## `RentHistoryList`
+
+The rents (or prices) a place has had, for a place page that outlives its listings:
+amount, period, note, and a small `Chip` for the delta. A leading "+" is warning, "−"
+success (`deltaTone` overrides). An empty list draws "No history for this home yet".
+
+## Accessibility
+
+- Charts and scales are images with composed names; the history legend repeats the
+  events as text.
+- Every meter is a `progressbar` with flat `aria-value*`.
+- "Why this estimate" carries `aria-expanded` (web) and `expanded` (native).
+- Nothing relies on colour alone: verdicts are words, events are labelled, the energy
+  class is a letter.
+
+## Quiet labels
+
+`muted` is floored with `quietTextOver` against BOTH fills the family paints on
+(the page and the card), rather than taken from `theme.colors.textTertiary` —
+which is the page's rung and was 4.04:1 in light before it was fixed. See
+[Styles → Quiet text](/docs/bloom/main/styles).