@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/image-resolver.mdx

@@ -34,6 +34,35 @@ That is also why there is no `avatarUrl` field on any DTO and no per-app URL
 helper: **one chokepoint**, `getFileDownloadUrl(id, variant)`, plus this
 resolver.
 
+## `isImageUrl` — the one answer to "URL or id"
+
+Every component that takes a `source` has to decide the same thing: render the
+string, or hand it to the resolver. That decision is one exported function.
+
+```tsx
+import { isImageUrl } from '@oxy.so/bloom/image-resolver';
+
+const uri = isImageUrl(source) ? source : resolver?.(source, 'thumb');
+```
+
+It is true for `http://`, `https://`, `data:`, `blob:`, `file:` and **a leading
+slash** — `/img/cover.jpg` is a root-relative path to an asset the app already
+serves. It is deliberately not a URL parser: it routes, and anything that is
+not one of those shapes is an id.
+
+**This used to differ per family.** Twelve copies of this predicate had grown across the
+package under three spellings (`isUrl`, `isImageUrl`, and an inline check in
+`Avatar`), and they disagreed. Only `listing-card`'s accepted a leading slash;
+`Avatar`'s accepted neither `blob:` nor `file:`. All of them now behave like the
+one above, which is strictly more permissive — a path or a `blob:` URL used to
+be sent to the resolver, and a resolver has nothing to answer for one, so the
+image rendered as its placeholder. If an app really does mint ids that start
+with `/`, `blob:` or `file:`, they are no longer routed to the resolver.
+
+It also tightened in one place: `media-player` and `music-library` matched on
+the bare scheme (`http:a.jpg` with no `//`), which `<Image>` cannot load anyway.
+Those strings are now treated as ids.
+
 ## `source` versus `uri` — the failure that is total and silent
 
 `Avatar` invokes the resolver only for a **non-URL string** passed as `source`.

package/docs/listing-actions.mdx

@@ -0,0 +1,287 @@
+---
+title: Listing actions
+description: The "act on this listing" cards for every housing offering — rent, buy, swap — plus a viewing scheduler, a mortgage calculator, a rental application checklist and the phone action bar.
+order: 114
+---
+
+# Listing actions
+
+The card beside a listing is where someone acts on it. A stay books
+(`BookingCard`, in [Booking](/docs/bloom/main/booking)); the rest live here, and
+all of them draw the **same card chrome** as `BookingCard`:
+
+| component              | what it is                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `RentalActionCard`     | long-term rent: monthly price, bills note, key facts, Request a viewing + Apply, status     |
+| `SaleActionCard`       | a home for sale: price, price per m², mortgage teaser, Contact agent + Request a visit      |
+| `ExchangeProposalCard` | a home swap: your home and theirs, dates, guests, swap mode, Propose a swap                 |
+| `ViewingScheduler`     | a day, a time, in person or video, a note, Request viewing                                  |
+| `MortgageCalculator`   | price, down payment, term and rate in; monthly payment, a principal / interest donut out    |
+| `ApplicationChecklist` | the documents a rental application needs, each with its status and action                 |
+| `ActionBar`            | the phone bar pinned under any listing; `BookingBar` is its stay preset                    |
+
+```tsx
+import {
+  ActionBar,
+  ApplicationChecklist,
+  ExchangeProposalCard,
+  MortgageCalculator,
+  RentalActionCard,
+  SaleActionCard,
+  ViewingScheduler,
+  computeMortgage,
+} from '@oxy.so/bloom/listing-actions';
+```
+
+Prices, dates and facts arrive as **pre-formatted strings** — the app owns
+currency, locale and plurals. The one exception is `MortgageCalculator`, which
+computes; see below.
+
+## The shared card
+
+Every card is up to 372 wide (`width: 100%`), radius 16, a 1px hairline
+(neutral-200, dark neutral-700), `shadow-m`, padding 24 on the card surface —
+the recipe `BookingCard` draws, from one internal shell, so a rental page and a
+stay page put the same card beside the listing. The price header is
+`title-3-semibold` with a `body-regular` unit, spoken as ONE element
+(`role="img"`): "€1,250 per month", "€362,500, originally €385,000".
+
+Buttons are full width and large: primary first, secondary 8 under it. Hover
+and press change colour only. Placing the card sticky beside a listing, or the
+bar at the bottom of the screen, is the page's job — see
+[Booking](/docs/bloom/main/booking).
+
+## RentalActionCard
+
+```tsx
+<RentalActionCard
+  price="€1,250"                      // drawn "€1,250 / month"
+  billsNote="Bills included"
+  facts={[
+    { label: 'Deposit', value: '€2,500' },
+    { label: 'Available from', value: 'Sep 1, 2026' },
+    { label: 'Minimum stay', value: '12 months' },
+    { label: 'Contract type', value: 'Long-term lease' },
+  ]}
+  status="available"                  // 'available' | 'reserved' | 'rented'
+  onRequestViewing={openScheduler}
+  onApply={openApplication}           // omit: no Apply button
+  note="Usually responds within a day"
+/>
+```
+
+| prop                                            | decides                                                                                  |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `price`, `originalPrice`, `priceAccessibilityLabel` | the header, as on `BookingCard`                                                      |
+| `priceUnit`, `priceUnitPrefix`                  | default `"month"` and `"/"` — "/ month"; the prefix is not spoken                        |
+| `billsNote`                                     | `body-2-regular` text-secondary under the price                                          |
+| `facts`                                         | label / value rows in a radius-12 box (neutral-300 / 600 border, 1px dividers)          |
+| `status`, `statusLabel`, `statusMessage`        | `reserved` / `rented` add a subtle `Badge` beside the price, an information tile above the buttons, disable both buttons and hide `note`. Defaults in `RENTAL_STATUS` |
+| `requestViewingLabel`, `applyLabel`, `loading`  | the buttons; `loading` spins the primary one                                             |
+| `note`, `footer`                                | the centred line under the buttons; anything at the bottom                               |
+
+## SaleActionCard
+
+```tsx
+<SaleActionCard
+  price="€385,000"
+  pricePerArea="€3,438 / m²"
+  mortgageEstimate="Est. €1,540/month"
+  onPressMortgage={() => calculator.open()}
+  facts={[{ label: 'Living area', value: '112 m²' }]}
+  status="available"                  // 'available' | 'reserved' | 'sold'
+  onContact={contactAgent}
+  onRequestVisit={requestVisit}       // omit: no secondary button
+  onMakeOffer={makeOffer}             // omit: no "Make an offer" link
+/>
+```
+
+- The mortgage teaser is a calculator glyph and an underlined `body-2-medium`
+  button (with `onPressMortgage`) — open the `MortgageCalculator` in a
+  `Dialog` or `BottomSheet`. Build its text from `computeMortgage` so the teaser
+  and the calculator agree.
+- `reserved` / `sold` badge the price, explain above the buttons (`SALE_STATUS`),
+  disable both buttons and hide "Make an offer".
+
+## ExchangeProposalCard
+
+```tsx
+const [mode, setMode] = useState<ExchangeMode>('swap');
+
+<ExchangeProposalCard
+  yourHome={{ image: mine.photoId, title: 'Stone house by the harbour', location: 'Porto Lindo', details: '3 beds · 6 guests' }}
+  theirHome={{ image: theirs.photoId, title: 'Farmhouse with an olive grove', location: 'Valle Serra', details: '2 beds · 4 guests' }}
+  dates="Jul 4 – 18"
+  onPressDates={openDates}
+  guests="4 guests"
+  onPressGuests={openGuests}
+  mode={mode}                          // 'swap' | 'host' | 'both'; omit for no chips
+  onModeChange={setMode}
+  onPropose={propose}
+/>
+```
+
+- **Homes.** Each is a caption-2-bold uppercase label ("YOUR HOME", "THEIR
+  HOME"), a 4:3 photo at radius 12 (a home glyph on a neutral tile while absent),
+  the title `body-2-medium` and location / size `caption-1-regular`. `image` is a
+  URL or an id for `ImageResolverProvider`. A 36 round swap glyph sits between
+  them on the photos' centre line.
+- **Narrow.** `layout="auto"` (default) measures the card and, below 360 wide,
+  stacks the homes as 72-square rows with the glyph turned 90°. Force it with
+  `'horizontal'` or `'vertical'`.
+- **Box.** DATES | GUESTS are `BookingCard`'s cells; empty ones show
+  `datesPlaceholder` / `guestsPlaceholder`.
+- **Mode.** `Chip`s on the `xl` rung (32 tall — a target rather than a tag) — `swap` "Reciprocal swap", `host` "Guest points", `both`
+  "Either" (`EXCHANGE_MODE_LABELS`, override with `modeLabels`, restrict with
+  `modes`). The chosen one is `selected` (`aria-pressed`).
+
+## ViewingScheduler
+
+Fully controlled — the app owns which days and times exist, and reloads `slots`
+when the day changes.
+
+```tsx
+<ViewingScheduler
+  days={[
+    { value: '2026-09-14', weekday: 'Mon', day: '14' },
+    { value: '2026-09-16', weekday: 'Wed', day: '16', disabled: true },
+  ]}
+  day={day}
+  onDayChange={(value) => { setDay(value); setSlot(null); }}
+  slots={slotsFor(day)}                // [{ value: '10:00', label: '10:00', disabled? }]
+  slot={slot}
+  onSlotChange={setSlot}
+  mode={mode}                          // 'in-person' | 'video'; omit for no toggle
+  onModeChange={setMode}
+  note={note}
+  onNoteChange={setNote}               // omit for no note field
+  onSubmit={requestViewing}
+/>
+```
+
+- **Days** scroll horizontally: 56-wide tiles at radius 12, weekday
+  `caption-1-regular` over the date `headline-semibold`. Unavailable days are at
+  40%, struck through and not pressable.
+- **Times** are 36-tall pill chips at least 76 wide, as many columns as fit,
+  8 apart. An empty `slots` shows `emptySlotsLabel`.
+- **Selected** days and times are INVERTED: text-primary fill, surface ink.
+- **Mode** is a `SegmentedControl`; the **note** a two-row `Textarea`.
+- **Request viewing** is disabled until a day and an enabled time are chosen;
+  `submitDisabled` overrides. `maxWidth` (default 372, `null` fills the column).
+
+## MortgageCalculator
+
+```tsx
+<MortgageCalculator
+  defaultPrice={385000}
+  defaultDownPayment={77000}           // default 20% of the price
+  defaultYears={25}
+  defaultAnnualRate={3.4}              // percent
+  formatCurrency={(n) => formatEuro(n)}
+/>
+```
+
+Every input is controlled (`price` / `onPriceChange`, `downPayment`,
+`years`, `annualRate`) or uncontrolled (`default…`).
+
+- **Inputs.** Property price; down payment as an amount AND a percent, kept in
+  sync, with a `Slider` (0–100%) under them; the term as radio chips
+  (`termOptions`, default 10, 15, 20, 25, 30); the interest rate with a "%"
+  suffix. A field keeps what is typed ("3." mid-typing) and reformats on blur.
+- **Result.** The monthly payment in `title-1-semibold` (a polite live region),
+  a 136 donut of principal (chart-6) against interest (chart-2) on the chart
+  cards' polar geometry, a legend, and rows for loan amount, total interest and
+  total cost (down payment plus everything repaid).
+- **Layout.** `layout="auto"` stacks the result under the inputs and puts them
+  side by side from 640 wide; `'stacked'` / `'split'` force it. `maxWidth`
+  defaults to `null` (fills its column).
+- **Text.** `formatCurrency` formats every amount (default: rounded, grouped
+  digits, no currency); `labels` translates every label.
+
+**It is an estimate.** The default `disclaimer` says so ("An estimate, not an
+offer…"); pass your own, or `null` only where the page already says it. The
+math leaves out fees, taxes, insurance and rate changes.
+
+### computeMortgage
+
+The calculator's math, pure and exported — use it for a teaser line or a
+server-side check:
+
+```ts
+computeMortgage({ price: 250000, downPayment: 50000, years: 30, annualRate: 6 });
+// { loanAmount: 200000, payments: 360, monthlyPayment: 1199.10…,
+//   totalRepaid: 431676.38…, totalInterest: 231676.38…, totalCost: 481676.38… }
+```
+
+A fixed-rate annuity compounded monthly: `r = annualRate / 100 / 12`,
+`n = years × 12`, `monthly = loan × r / (1 − (1 + r)^−n)` (`loan / n` at 0%). The
+down payment is clamped to `0…price`; nothing is rounded.
+
+## ApplicationChecklist
+
+```tsx
+<ApplicationChecklist
+  items={[
+    { key: 'id', title: 'Proof of identity', description: 'Passport or national ID', status: 'verified' },
+    { key: 'payslips', title: 'Last three payslips', status: 'uploaded' },
+    { key: 'contract', title: 'Employment contract', status: 'missing' },
+    { key: 'bank', title: 'Bank statement', status: 'rejected', reason: 'The name is cut off.' },
+  ]}
+  onItemAction={(item) => (item.status === 'missing' || item.status === 'rejected' ? upload(item) : view(item))}
+/>
+```
+
+- **Progress.** "{done} of {total} ready" (`formatProgress`) and a 6-tall bar
+  (accent-500 on neutral-200 / 700) counting uploaded and verified items.
+- **Rows.** A 20 status glyph — missing neutral, in review accent, verified
+  success, rejected error — the title `body-medium` with a subtle status `Badge`,
+  the description `body-2-regular` text-secondary, or the rejection `reason` in
+  the error colour.
+- **Action.** A small button on the right: Upload / Replace (primary) while
+  missing or rejected, View (secondary) otherwise (`APPLICATION_ITEM_STATUS`).
+  `actionLabel` renames it, `null` removes it; `onAction` per item overrides
+  `onItemAction`. Default `maxWidth` 560.
+
+## ActionBar
+
+```tsx
+<ActionBar
+  price="€385,000"
+  subtitle="Est. €1,540/month"
+  onPressSubtitle={openCalculator}
+  primaryLabel="Contact agent"
+  onPrimary={contactAgent}
+  secondaryIcon={RiHeart3Line}
+  secondaryLabel="Save"                // the icon button's name — required with an icon
+  onSecondary={save}
+/>
+```
+
+The phone bar under any listing: a 1px top hairline, the page background,
+padding 12 above and 24 at the sides, 12 plus the bottom safe-area inset below
+(`bottomInset` overrides). The price is `headline-semibold`; `subtitle` is
+`body-2-medium`, underlined and a button with `onPressSubtitle`. An optional
+large icon-only secondary button sits before the primary one.
+`BookingBar` is this bar with `dates` → `subtitle` and "Reserve".
+
+## Accessibility
+
+- **Prices** read as one `role="img"` element with a spoken name — "per month",
+  "originally …" — because a strikethrough and a "/" are not announced.
+- **Disabled** actions carry the disabled state; the status tile says why.
+- **Homes** are one named group each ("Your home, Stone house by the harbour,
+  Porto Lindo, 3 beds · 6 guests"); the swap glyph is hidden.
+- **Scheduler** days, times and calculator terms are `radio`s in named
+  `radiogroup`s with `aria-checked` and `aria-disabled` (and
+  `accessibilityState` on native). Mode chips are toggle buttons (`aria-pressed`).
+- **Calculator** fields are named by their labels; the slider is named
+  "Down payment percent" with `aria-value*`; the donut is `role="img"` named by
+  its two amounts; the monthly payment is a polite live region.
+- **Checklist** progress is a [`Meter`](/docs/stat-bar) — a `progressbar` with
+  `aria-valuenow` / `-max` / `-text`; each action is named with its item
+  ("Upload Employment contract").
+- Every custom pressable shows a 2px accent ring under keyboard focus on web.
+
+**Dark mode note.** `TextField` and `Textarea` fill with neutral-800 in dark
+mode, the same tone as the card surface, so the calculator's and scheduler's
+fields read by their labels and focus ring there rather than by a filled shell.

package/docs/listing-card.mdx

@@ -1,6 +1,6 @@
 ---
 title: Listing Card
-description: A stay in a results grid — paged photos, a heart, rating and price — plus the responsive grid, the heart on its own, and a saved-collection card.
+description: A home in a results grid — a stay, a rental, a sale or a swap — with paged photos, a heart, offerings, facts, price lines and status, a compact list row, the responsive grid, the heart on its own, and a saved-collection card.
 order: 107
 ---
 
@@ -37,6 +37,32 @@ import {
 </ListingCardGrid>
 ```
 
+A home for rent and for sale, with its facts:
+
+```tsx
+import { RiBuilding2Line, RiDropLine, RiHotelBedLine, RiRulerLine } from '@oxy.so/bloom/icons';
+
+<ListingCard
+  photos={home.photos}
+  title="Loft above the Ondel market"
+  address="Plaça Ferran, Ondel"
+  approximateLocation
+  offerings={['long_term_rent', 'sale']}
+  priceLines={[
+    { price: '€1,250', unit: '/ month' },
+    { price: '€310,000', secondary: '€4,130/m²' },
+  ]}
+  facts={[
+    { icon: RiHotelBedLine, label: '2', accessibilityLabel: '2 bedrooms' },
+    { icon: RiDropLine, label: '2', accessibilityLabel: '2 bathrooms' },
+    { icon: RiRulerLine, label: '75 m²' },
+    { icon: RiBuilding2Line, label: 'Floor 6' },
+  ]}
+  status="reserved"
+  href={`/homes/${home.id}`}
+/>
+```
+
 Prices, dates and counts arrive **pre-formatted** — the app owns currency, locale
 and plural rules. Nothing here computes a price.
 
@@ -49,12 +75,18 @@ and plural rules. Nothing here computes a price.
 | `subtitle`, `dates`                    | two secondary lines, one line each                                                                         |
 | `rating`, `reviewCount`, `newLabel`    | Bloom's `Rating`, right of the title. `undefined` draws nothing; `null` or `''` draws "New"                |
 | `price`, `priceUnit`, `originalPrice`  | the price line: `originalPrice` struck through, `price` semibold, then the unit                           |
-| `total`                                | a line under the price; with no `price` it IS the price line, semibold                                     |
+| `priceLines`                           | stacked price lines (`{ price, unit?, secondary?, originalPrice? }`); replaces the three props above, which are its single-line case |
+| `total`                                | a line under the price lines; with none it IS the price line, semibold                                     |
+| `address`, `approximateLocation`, `approximateLocationLabel` | a pin and the address line; `approximateLocation` adds "Approximate location" (or is the line) |
+| `facts`                                | one row of `{ icon?, label, accessibilityLabel? }` — bed 3 · bath 2 · 110 m² · floor 4                    |
+| `offerings`, `offeringLabels`          | `OfferingBadge`s — see below                                                                               |
+| `status`, `statusLabel`                | `'available'` (default) or `'reserved'`, `'sold'`, `'rented'`, `'unavailable'` — see below                |
 | `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                                                                                                  |
 | `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                                    |
 | `onPhotoIndexChange`                   | the photo in view changed                                                                                  |
 | `accessibilityLabel`                   | replaces the composed name                                                                                 |
 | `previousPhotoLabel`, `nextPhotoLabel`, `saveLabel`, `removeLabel` | the controls' names — translate them                                          |
@@ -78,10 +110,45 @@ control.
 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.
 
+**Homes, not only stays.** The card draws every housing offering.
+
+- **Price lines** stack one per line: an optional struck original, the price
+  semibold, the unit, then `· secondary` in secondary text ("€240,000 ·
+  €3,200/m²"). A home for rent and for sale passes two lines.
+- **Facts** are body-2 in secondary text with 16px icons, 12 apart, on ONE row.
+  The row wraps inside a box one line tall and clips, so facts that do not fit
+  drop out whole from the end instead of each being cut to "11…". Give each a
+  spoken `accessibilityLabel` ("3 bedrooms") — a bare "3" read aloud means nothing.
+  Suggested icons: `RiHotelBedLine` (bedrooms), `RiDropLine` (bathrooms),
+  `RiRulerLine` (area), `RiBuilding2Line` (floor).
+- **Offerings go over the photo.** The top-left slot is one wrapping row, 6
+  apart: the status pill, then `badge`, then the offerings as `onMedia`
+  `OfferingBadge`s (duplicates drawn once). The photo is where a scanning eye
+  lands, and keeping them off the text block keeps every card's text the same
+  height, so a grid row stays aligned whatever each home is offered as. The slot
+  stops 56 short of the right edge, clear of the heart.
+- **Status.** Anything but `available` washes the photo 50% toward the page
+  (`background`) and draws a pill first in the slot — the page's reading pair
+  inverted (`text` fill, `background` label), legible in both modes. Labels:
+  "Reserved", "Sold", "Rented", "Unavailable" (`statusLabel` translates).
+- The **address line** (pin + body-regular secondary) sits under the subtitle;
+  with `approximateLocation` it reads "Talmar Hill · Approximate location".
+
+**Compact density.** `density="compact"` is a row for dense result lists: a
+112 square thumbnail (radius 12, the first photo only — no paging, dots or
+arrows) and, 12 to its right, the offerings and status as a row of small
+**tinted** badges above the title (a 112 thumbnail has no room for pills over
+it), the title with a small `Rating`, subtitle, address, dates, price lines and
+facts at the body-2 size. The heart (20, a 32 target) sits over the thumbnail's
+top-right corner, still a sibling of the link. `layout` is ignored; `loading`
+draws a matching row skeleton.
+
 **Accessible name.** The link is named for the stay — "Alvora, Coast of Merin,
 Guest favourite, Rated 4.92 out of 5, 128 reviews, Hosted by Ilse, 12 – 17 Oct,
 €124 night, originally €150". That sentence is English; apps in other languages
-pass `accessibilityLabel`.
+pass `accessibilityLabel`. A home adds, in order: the status after the title,
+the offerings after the badge, the address after the subtitle, each price line
+("€240,000, €3,200/m², originally €255,000") and the facts last.
 
 ## `FavoriteButton`
 
@@ -129,4 +196,11 @@ All from the theme: the text is `text` / `textSecondary`; the badge pill and the
 arrow buttons are the floating surface (the menu palette and Bloom's secondary
 `Button`); the heart's outline and the dots are `neutral-50`, its body
 `neutral-950` at 50%, saved `red-500` from the theme's `error` hue. The photo
-placeholder is `neutral-100` (dark: the raised neutral).
+placeholder is `neutral-100` (dark: the raised neutral). Offering badges take
+their colours from `OfferingBadge` (`docs/offering-badge.mdx`).
+
+## Disabled
+
+The favourite button fades to `tokens.DISABLED_OPACITY` (0.5), not the 0.6 it
+carried. See [Styles → Disabled](/docs/bloom/main/styles) for when a fade is
+allowed at all.

package/docs/listing-details.mdx

@@ -1,6 +1,6 @@
 ---
 title: Listing details
-description: The parts of a stay's listing page — photo grid, header, highlights, amenities, host card, review summary and review cards — and the section wrapper that stacks them.
+description: The parts of a listing page — photo grid, header, highlights, amenities, property facts, floor plans, the host / landlord / agent contact card, review summary and review cards — and the section wrapper that stacks them.
 order: 112
 ---
 
@@ -9,12 +9,15 @@ order: 112
 ```tsx
 import {
   AmenityList,
+  ContactCard,
+  FloorPlan,
   HostCard,
   ListingHeader,
   ListingHeaderAction,
   ListingHighlights,
   ListingPhotoGrid,
   ListingSection,
+  PropertyFacts,
   ReviewCard,
   ReviewSummary,
 } from '@oxy.so/bloom/listing-details';
@@ -68,6 +71,8 @@ content column and a booking column gets the right layout in each.
 | `ListingHeader` | 640: actions under the meta row | 640: actions beside the title |
 | `AmenityList` (`columns="auto"`) | 560: one column | 560: two columns |
 | `ReviewSummary` | 640: stacked, one category column | 640: distribution beside two category columns |
+| `PropertyFacts` (`columns="auto"`) | 480: two columns | 480: three; 720: four |
+| `FloorPlan` (`columns="auto"`) | 560: one column | 560: two columns |
 
 Before the first layout the photo grid holds its height with an empty frame, so the
 page does not jump. `layout="grid" | "carousel"` and `columns={1 | 2}` skip the
@@ -145,6 +150,77 @@ lines), `responseLines` (text-secondary) and a "Message host" secondary button w
 `onMessage` is set. `onPressProfile` makes the card one button named
 "Marta, Top host, Verified, 214 Reviews, …".
 
+## Homes for rent and sale
+
+A rental or sale page reuses the same header, photos and sections, and adds three
+parts here plus the data parts in [`@oxy.so/bloom/property-insights`](./property-insights).
+Storybook: **Blocks/Housing/Property Insights**.
+
+```tsx
+<ListingSection title="Features">
+  <PropertyFacts items={[
+    { icon: RiRulerLine, label: 'Built area', value: '138 m²' },
+    { icon: RiHotelBedLine, label: 'Bedrooms', value: '3' },
+    { icon: RiStairsLine, label: 'Floor', value: '3rd of 5' },
+  ]} limit={8} total={12} onShowAll={openFeatures} />
+</ListingSection>
+<ListingSection title="Floor plans">
+  <FloorPlan plans={plans} onPressPlan={(i) => gallery.current?.open(planImages, i)} />
+</ListingSection>
+<ContactCard
+  role="agent"
+  name="Leonor Brandão"
+  avatar={photo}
+  verified
+  agency="Casa Ribeirinha Imóveis"
+  logo={agencyLogo}
+  responseTime="Usually responds within an hour"
+  activeListings={12}
+  onPressListings={openListings}
+  phone="+351 912 480 316"
+  onPhoneRevealedChange={logLead}
+  onMessage={message}
+  onCall={call}
+/>
+```
+
+### `PropertyFacts`
+
+A grid of icon (24) + value (headline-semibold) + label (body-2, text-secondary). The
+columns are equal shares with a 16px gutter as each cell's right padding, so explicit
+`columns={2 | 3 | 4}` need no layout pass; `auto` measures (table above). `limit`,
+`total`, `onShowAll` and `showAllLabel` work like `AmenityList`'s ("Show all 12
+features"). A named list (`accessibilityLabel`, default "Property features"); each fact
+reads "Built area: 138 m²".
+
+### `FloorPlan`
+
+A tile per plan — radius 16, hairline border, the plan CONTAINED with a 16 inset on a
+light sheet in both modes (a plan is dark line work and would vanish on a dark tile) —
+with `label` and `description` under it. With `onPressPlan` a tile is a button named
+"Main floor · 96 m², floor plan 1 of 2" (`planLabel`) with an expand disc top-right;
+without it, a named image. One plan spans the width; `auto` columns are 1 below 560
+wide and 2 from 560. Open `ZoomableMediaGallery` from `onPressPlan`, exactly as for
+the photo grid.
+
+### `ContactCard`
+
+`HostCard` generalised to landlords, agents and agencies: the same profile card (avatar,
+verified badge, name, label, stats column), then:
+
+| prop | draws |
+| --- | --- |
+| `role` | `host` (default) · `landlord` · `agent` · `agency` — the label under the name when `label` is not set ("Landlord", "Agent", "Agency"; nothing for a host), `roleLabel` overrides it |
+| `agency`, `logo` | a row with the logo in a 40px rounded tile and the agency name; `role="agency"` without an `avatar` uses the logo as a square-cornered avatar instead |
+| `responseTime` | a clock row |
+| `activeListings`, `onPressListings` | "12 active listings" (`activeListingsLabel`), a link when pressable |
+| `onMessage`, `messageLabel` | "Message" — secondary for a host ("Message host"), primary for everyone else |
+| `onCall`, `callLabel` | a secondary "Call" button with a phone icon |
+| `phone` | "Show phone"; pressed, the number replaces the label (announced politely). It then calls `onCall` when pressed, or becomes plain selectable text when there is nothing to call. `phoneRevealed` / `onPhoneRevealedChange` control it — log the lead there. |
+
+`HostCard` is `ContactCard` with `role="host"` and `messageLabel="Message host"`; its
+props, geometry and testIDs are unchanged.
+
 ## `ReviewSummary`
 
 A 32px star and the rating in display-2-semibold, with `title` / `description` beside