@oxy.so/bloom 4.0.0 → 4.1.0

package/docs/empty-state.mdx

@@ -0,0 +1,89 @@
+---
+title: Empty state
+description: Nothing to show, said once — a glyph or an illustration, a title, a line of explanation and up to two actions, at a screen rung and a panel rung.
+order: 48
+---
+
+# Empty state
+
+A list with nothing in it still has to say something, and until this family existed every
+list in Bloom said it differently. Twelve components had each drawn their own block: five
+of them the same glyph-over-headline-over-line, at five paddings and four maximum widths,
+under six spellings of the same two strings — `emptyTitle`/`emptyDescription`,
+`emptyMessage`, `emptyQueueHint`, `emptyLabel`, `emptyText`, `noResultsLabel`.
+
+```tsx
+import { EmptyState } from '@oxy.so/bloom/empty-state';
+import { RiInbox2Line } from '@oxy.so/bloom/icons/RiInbox2Line';
+
+<EmptyState
+  icon={RiInbox2Line}
+  title="Nothing in this folder"
+  description="Mail you file here will show up in this list."
+  action={{ label: 'Write a message', onPress: compose }}
+/>;
+```
+
+## The two rungs are about WHERE, not about how much there is to say
+
+`comfortable` is the screen: a 32 glyph, a headline, 48 of air above and below, and the
+text capped at 360. `compact` is the panel — a side panel, a popover, a card that is
+already inside something: a 24 glyph, a body title, 24 of air, capped at 280. Nothing
+else changes, so a list that moves from a screen into a panel changes a prop and not a
+component.
+
+The 360 is the number worth defending. The five hand-rolled blocks this family replaces
+used 280, 260, 360, 340 and none, and the one with none is the reason: a centred line of
+explanation that runs the full width of a 1440 page needs a second fixation per line, and
+every author who noticed picked a different cap. 360 is roughly sixty characters at
+`body-regular`.
+
+## The mark: three ways, and when each is right
+
+- **`icon` + `media="glyph"`** (the default) is the bare mark in the GRAPHICAL rung —
+  `textGraphical`, the ladder stop sized for a line rather than for text, so it clears
+  3:1 on whatever surface the block was dropped on. It is the quiet answer, right when
+  the empty state is REPORTING (a filter matched nothing, a folder is empty).
+- **`icon` + `media="circle"`** is `IconCircle`, the tinted disc. Louder; right when the
+  block is the whole screen, or when it is INVITING rather than reporting.
+- **`illustration`** is an arbitrary node and wins over `icon`, drawn exactly as it comes
+  with no tile of its own. It is read for PRESENCE, so `illustration={null}` draws no
+  mark at all even when an `icon` arrived from a default two levels up.
+
+There is no fourth. A neutral "well" and a tinted disc side by side were two answers to
+one question, and both shipped in this repo.
+
+## The actions are DATA, and there are at most two
+
+A node would have worked — the six blocks this replaces each passed one, which is how
+three of them ended up with three different button sizes for the same button. As
+`EmptyStateAction` the family owns the size (medium, or small at the panel rung), the
+order and the wrap; the caller owns the words and the handler. Anything that is not a
+button — a row of suggestion pills, a link, a note — goes in `footer`, under them.
+
+`children` is the third slot, between the explanation and the actions. It is stretched to
+the block's full width and left to lay itself out, because what goes there is a strip, a
+fact box or a list rather than centred text. `order-confirmation` is built on exactly
+that: a "done" screen is the same object as a "nothing here" screen with a different
+reason for existing.
+
+## It is ONE named group
+
+The whole block carries `role="group"` named by the title and the description joined. A
+screen reader that reaches an empty list should be told the situation; a heading, a
+paragraph and a button with nothing joining them are three stops that each say a third of
+it. The glyph is hidden from assistive technology — it repeats what the title says, and
+an unnamed image between a heading and its paragraph is a stop that announces nothing.
+
+## `minHeight` is for holding a band open
+
+A table body, a panel that must not collapse. The content centres in it. Without it the
+block is exactly as tall as what it contains, which is what a list wants.
+
+## Migrating a hand-rolled one
+
+Not done yet, and deliberately: this family is designed to cover the existing call sites
+as they stand, and moving them is a separate change with its own screenshots. The ones it
+was measured against are `cart-panel`'s `EmptyBasket`, `carrier-quote`'s empty offers
+list, `mail-list`, `chat-list`, `address`'s `AddressList` and `data-table`'s empty band —
+six shapes between them, from a 32-glyph column to a text-only 160-tall band.

package/docs/fab.mdx

@@ -11,7 +11,7 @@ import * as Icons from '@oxy.so/bloom/icons';
 <Fab icon={Icons.RiAddLine} label="Compose" tone="action" appearance="solid" />
 ```
 
-`size` is `xs | sm | md | lg` (40, 48, 56, 64 points; default `md`).
+`size` is `xs | sm | md | lg` (40, 48, 50, 64 points; default `md`). The corresponding glyphs are20,24,26,32points. The default50/26 geometry is shared by standalone, sidebar, Screen and BottomBar actions. `iconSize` optionally sets the glyph dimensions independently; for example, `size={50} iconSize={26}`. The collapsed circle keeps its requested diameter and adjusts its padding around the glyph.
 `size` and `tone` inherit from `BloomScope`. `tone` defaults to `action`;
 `appearance` defaults to `solid` and also accepts `subtle`, `outline`, `plain`.
 Icon props take a component, which receives its size and foreground color.
@@ -23,6 +23,23 @@ Use `AppShell.primaryAction` to coordinate a screen action with navigation, or
 `BottomBar.action` for a custom bottom composition. A standalone Fab stays in
 normal flow and accepts the usual `style` and `className` layout overrides.
 
+## Controlled collapse
+
+```tsx
+<Fab icon={Icons.RiAddLine} label="New post" collapsed={compact} onPress={createPost} />
+```
+
+`collapsed` defaults to `false`. It contracts the measured label width and opacity
+with Bloom's 300ms motion timing, reverses from the current position, and respects
+reduced motion. The same Button stays mounted: focus, accessible name, loading
+and disabled behavior remain available when only the icon is visible. Parent
+`style` widths remain authoritative, so an extended full-width action can follow
+a collapsing sidebar without another animated button or duplicated label.
+
+The existing `minimizeBehavior="collapse"` compatibility prop uses the same label
+transition when its minimization context requests it. Explicit `collapsed` also
+works independently, without a navigation or Sidebar provider.
+
 ## Migration
 
 Remove `placement`, `offset`, `zIndex`, and `minimizeBehavior`. Position the action

package/docs/job-board.mdx

@@ -0,0 +1,82 @@
+---
+title: Job board
+description: Work a courier can take — what a job pays, where it starts and ends, how long the offer stands, and the board it sits on with the four filters that matter, a sort, a refresh and an empty state.
+order: 137
+---
+
+# Job board
+
+```tsx
+import { JobBoard, JobCard } from '@oxy.so/bloom/job-board';
+
+<JobBoard
+  jobs={jobs}
+  payBands={payBands}
+  onTake={take}
+  onPass={hide}
+  onRefresh={pull}
+/>
+```
+
+`JobCard` is one piece of work. `JobBoard` is the work on offer, filtered, ordered and counted.
+
+## It is the offer card seen from the other side
+
+`carrier-quote`'s `CarrierQuoteCard` is a carrier saying what they would charge to move something. This is the same object read by the person who would move it: the same blocks in the same order, the same tile row, the same 420 threshold at which the actions drop their labels, the same footer over a hairline. Both were built from the same measurements on purpose — a courier app shows one of these on the board and the other in the customer's app, and two different geometries would make them look like two products.
+
+What differs is only whose number the headline is, and what stands where the person does:
+
+| | `CarrierQuoteCard` | `JobCard` |
+| --- | --- | --- |
+| the mark | the carrier's 48 avatar | the 48 vehicle tile |
+| the identity | the carrier's name and rating | what is being moved |
+| the headline | the price asked | the pay offered |
+| the middle | three tiles | the route, then three tiles |
+| the footer | decline · message · accept | pass · take |
+
+## The geometry
+
+- **Card.** Outlined, radius 20, 16 inset, 16 between blocks. Chosen, it takes a 2px border and gives the pixel back out of its own inset, so nothing inside moves.
+- **Mark.** 48 comfortable, 36 compact, radius 12, at the surface's next fill up. It carries the glyph for `vehicleKind`, or `vehicleIcon` when the app names one. With neither it is the route glyph — a marketplace that routes five bodies has five glyphs, and guessing between them is worse than not drawing one.
+- **Tiles.** Distance, time, window. One row over 420, two columns under it, an odd tile keeping its half.
+- **Compact.** 64 tall, the mark, the load, one meta line, the pay. No route, no tiles, no breakdown: that density is a LIST ROW, and a list row that drew a route would be a card with the padding taken out.
+
+## The route is `RouteStops`, not a second pin column
+
+`pickup`, `via` and `dropoff` become that family's stops, at its `compact` density. It already owns the marker shapes, the connector that fills behind a journey, the position words and the announced name; a second column drawn here would be a fourth marker vocabulary in one library.
+
+## What a job is CLOSED does not remove it
+
+`state` is `open`, `taken` or `expired`. A closed job keeps its place, dims to the disabled opacity, and says which of the two happened — as a `Badge` beside the load and again where the take action was. The take action is GONE rather than greyed out: a dimmed primary button invites a press that can never succeed.
+
+This is the one behaviour the board exists to get right. A row that vanishes under a thumb is indistinguishable from a mis-tap, and the reader is left unsure whether they took the job or lost it. `filterJobOffers` answers the reader's four questions and nothing else, so nothing about a job's state can make it disappear.
+
+## The filters
+
+Four independent questions, combined with AND, each a sideways-scrolling `ChipRow`:
+
+| | reads | default bands |
+| --- | --- | --- |
+| distance | `distanceKm` | `JOB_DISTANCE_BANDS` — any, 3, 10, 25 km |
+| pay | `payValue` | **none** |
+| when | `startsInMinutes` | `JOB_WHEN_BANDS` — any, hour, 4 hours, today |
+| vehicle | `vehicleKind` | the five `vehicle-picker` knows |
+
+**`payBands` has no default and will not get one.** A band is words plus an amount, and the amount is a currency. A kilometre and a minute are nobody's; twenty euros is somebody's.
+
+**A filter cannot exclude what it cannot measure.** A job with no `distanceKm` survives every distance band; one with no `payValue` survives every pay floor. Treating a missing value as zero is how a filter hides work from a courier because the app omitted a field.
+
+**Vehicle is a set of toggles, not a radiogroup.** A courier with a van can take a bike job, and "van or box truck" is a sentence the board has to be able to say. Pressing the only selected vehicle clears the dimension.
+
+## The order
+
+`sortJobOffers` is stable, and PAY sorts high first while distance, start and expiry sort low first — a courier scanning for money wants the biggest number and scanning for distance wants the smallest, so one direction would be wrong three times. A job with no number for the current key goes LAST, keeping the caller's order inside that group: there is nothing left to sort it on, and re-shuffling a group of equals makes a board jump for no visible reason.
+
+## Traps
+
+- **Money is never parsed.** `pay`, `payNote` and every `payLines` amount are drawn exactly as given. `payValue` is a separate number for ordering and the pay filter, and it is never drawn. Nothing here adds, converts or rounds.
+- **The card is not one big button.** `onPressJob` is bound to the load block; the actions sit outside it. A control inside a control is invalid on web and renders fine either way.
+- **The actions lose their labels, never their names.** Under 420 each drops to a glyph and keeps `"<action> <load>"`.
+- **`disabled` is a constraint, not a default.** It combines with the job's own state, so a caller cannot re-enable a job the marketplace has already given away.
+- **The refresh control does not spin.** Bloom draws no press animations; while `refreshing` it is inert, because a second pull would race the first.
+- **The empty state offers the undo it caused.** With a filter narrowed and no `emptyAction`, the clear control is drawn there.

package/docs/location-puck.mdx

@@ -0,0 +1,160 @@
+---
+title: LocationPuck
+description: Where you are, on a map Bloom does not own — the dot, the accuracy halo, the heading cone and the navigating chevron.
+order: 137
+---
+
+# LocationPuck
+
+`@oxy.so/bloom/location-puck`
+
+Everything else in Bloom's maps set is chrome AROUND a map: a place card, a
+route summary, the controls that float on top. This is the one thing drawn ON
+it, and it answers one question — where are you, how sure are we, and which way
+are you facing.
+
+```tsx
+import { LocationPuck } from '@oxy.so/bloom/location-puck';
+
+<LocationPuck
+  state="located"
+  heading={heading}
+  headingAccuracy={headingAccuracy}
+  accuracyRadius={metresToPixels(accuracy)}
+/>
+```
+
+## It positions nothing
+
+The same contract `map-marker` publishes, and for the same reason: Bloom has no
+projection, no tile source and no opinion about which map library you use. The
+puck draws ONE square box with every layer centred in it, and the app centres
+that box on the coordinate — the dot lands on the coordinate because it is at
+the centre of the box, not because of an offset.
+
+The box's size is whichever layer reaches furthest: `2 × accuracyRadius`,
+`2 × coneLength`, or the puck itself. It takes no presses
+(`pointerEvents="none"`), so a halo that happens to cover a third of the screen
+never eats a pan the map was meant to receive.
+
+`accuracyRadius` is in PIXELS, computed by the app from metres at this latitude
+and zoom, and re-passed on every zoom. Without it no halo is drawn at all: a
+halo of an invented size is a claim about precision nobody measured.
+
+## The layers
+
+| layer | what it is |
+| --- | --- |
+| halo | `MapAreaCircle` — literally the approximate-area circle `map-marker` publishes, at the radius the app gave |
+| cone | a wedge from the dot, fading along its length, as wide as the device is unsure |
+| puck | an 18 dot in the accent inside a 3 ring, `shadow-m`; a chevron while navigating |
+
+The halo is not a second implementation of a translucent accent circle. It IS
+the one `map-marker` already draws — the accent at 15% with a 1.5 edge — so a
+preset change moves the halo with every other circle on the map.
+
+## The cone is the uncertainty, drawn
+
+`headingAccuracy` is the platform's own ± reading in DEGREES and it is the
+cone's half-width, clamped into `[14°, 55°]`. Narrow means "this way"; wide
+means "roughly this way"; there is no third vocabulary and no separate
+confidence prop, because the device already reports the number.
+
+`headingUnknown` draws **no cone** and speaks no bearing. A cone at a default
+angle would be a confident claim about the one thing the device could not
+measure, and a reader who cannot see the screen would be told a heading that
+does not exist.
+
+### The gradient is the trap
+
+`react-native-svg` reads `stopColor` for its RGB and **discards any alpha inside
+it**. A stop written as `rgba(…, 0.45)` renders correctly in a browser and
+FULLY OPAQUE on a device — a hard-edged accent wedge lying over half the map —
+and a gate that pinned both platforms to the same colour token would stay green,
+because the two agree about every value and only the renderer's reading differs.
+That exact defect shipped once in `theme/glass-colors.ts`.
+
+So `LOCATION_PUCK_CONE_STOPS` holds an OFFSET and an OPACITY in separate fields,
+and the cone hands `color` to `stopColor` and `opacity` to `stopOpacity`, which
+are the two props SVG actually defines. `LocationPuck.test.tsx` asserts every
+rendered `<stop>` carries a `stop-opacity` and that no `stop-color` contains an
+alpha channel.
+
+The gradient is also `gradientUnits="userSpaceOnUse"`. The default,
+`objectBoundingBox`, resolves against the bounding box of the element that
+REFERENCES the gradient — the wedge, not the square — so `cx/cy = 0.5` lands
+somewhere out along the cone and moves as the angle widens. Measured in a
+browser before it was fixed: the fade started partway down the cone and was
+brightest off to one side of it.
+
+## `following`, `compass`, `navigating`
+
+The mode decides how much the puck turns, and the component owns that decision
+rather than making every caller repeat it:
+
+- **`following`** — the map is north-up, so the cone turns by `heading`.
+- **`compass`** — the app has already rotated the MAP so the heading is up, so
+  the cone turns by **nothing**. Passing the heading here as well would apply
+  the rotation twice; it is the mirror of the correction `MapCompass` makes for
+  its needle.
+- **`navigating`** — the dot becomes a chevron pointing along the route, and the
+  cone disappears with it. The chevron IS the direction; a cone beside it is a
+  second arrow saying the same thing.
+
+The chevron has no drop shadow, on purpose. A drop shadow is the shadow of a
+node's BOX, and the chevron's box is a square containing a wedge — so a shadow
+on it draws a rectangle floating under a triangle. It is separated from the map
+by its ring-coloured stroke, which traces the shape it actually has.
+
+## The ring is the dot's own on-colour
+
+A ring has one job: make the dot read as a deliberate object over tiles Bloom
+cannot see. Bloom cannot measure anything against those tiles, but every fill in
+the library already ships with the colour that reads ON it — so the live ring is
+the accent's solid `foreground` (white for most seeds, black for a light one
+like yellow or peach; the pair adapts, a hardcoded white ring does not), and the
+stale ring is the map-chrome surface, because the stale dot is a text rung
+floored against exactly that surface.
+
+Measured over a dark tile: the chrome surface as the LIVE ring disappeared
+entirely in dark mode — a dark ring on a dark map.
+
+## States, and what they say out loud
+
+| state | drawn | announced |
+| --- | --- | --- |
+| `locating` | the dot swells 18%, the halo breathes | "Finding your location" |
+| `located` | still | "Your location" |
+| `stale` | the accent gone, the halo at half | "Your last known location" |
+
+`stale` is the one that must be a sentence rather than a shade. A dimmer dot
+tells a sighted reader something is different and tells everybody else nothing,
+and "the map is showing where you were" is not recoverable by looking harder.
+
+Every state adds the bearing when there is one — "Your location, facing 41
+degrees" — and none of them adds it when there is not.
+
+## Motion
+
+Only `locating` moves, out of one shared driver: the dot swells and the halo
+breathes over 1600ms. A pulse that never stops is a battery cost and a
+distraction, so it stops the moment there is a fix, and `useReducedMotion()` —
+or the `reducedMotion` prop — stops it outright.
+
+The driver is written IMPERATIVELY from an effect and only READ in
+`useAnimatedStyle`, with every shared value in the deps array. Both halves are
+load-bearing on web: an animation returned from a mapper never ticks, and
+without the worklets Babel plugin a mapper re-runs on its deps array rather than
+on auto-tracked reads. See `docs/motion.mdx`.
+
+Jest cannot see the pulse at all — the reanimated mock resolves a sequence to
+its last value, so the driver reads 0 whether or not it was started. The suite
+pins what IS asymmetric (an animating halo sits at the trough of its breath, a
+still one at its resting opacity), and the motion itself is measured in a real
+browser by sampling the dot's box over ten frames.
+
+## What is not here
+
+No engine, no tiles, no projection, no geolocation. `LocationPuck` is given a
+state, a heading and a radius in pixels; it reads no sensor and subscribes to
+nothing.

package/docs/map-attribution.mdx

@@ -0,0 +1,88 @@
+---
+title: MapAttribution
+description: The small print a map's licence requires — the data credit, a scale bar, and when the tiles were last refreshed.
+order: 139
+---
+
+# MapAttribution
+
+`@oxy.so/bloom/map-attribution`
+
+The quietest thing on the map, and the one part of it that is not optional. Tile
+providers require a credit; a map without a scale cannot be read as a
+measurement; and a reader deciding whether to trust what they are looking at
+wants to know when it was last refreshed.
+
+```tsx
+import { MapAttribution } from '@oxy.so/bloom/map-attribution';
+
+<MapAttribution
+  credit="Map data © Open Map Project contributors"
+  scales={[{ width: 88, label: '500 m' }, { width: 108, label: '2000 ft' }]}
+  updated="Updated 12 March"
+  onPressCredit={openLicence}
+/>
+```
+
+## The credit is required and never defaulted
+
+Every other string in this family has a sensible English default. This one does
+not, and that is the point: a component that invented a credit would put a
+WRONG attribution on a map, which is a licence problem rather than a visual one.
+The app passes what its provider's licence says, verbatim.
+
+It also never truncates. The row wraps instead — a credit that silently lost its
+second half on a narrow phone is the same failure as not drawing it.
+
+With `onPressCredit` the credit becomes `Button`'s `link` variant at the same
+type step: running text with the library's own focus ring and hover underline,
+rather than a second pressable with a ring of its own. Give it a `creditLabel`
+when the drawn words are not a sentence ("© OMP").
+
+## Legibility over content Bloom cannot see
+
+The map can be a night satellite tile, a white street map or a photograph, so no
+text rung can be floored against it. The strip sits on a `GlassIsland` instead —
+a translucent pane whose fill is rung 1 of the surface ladder, a surface Bloom
+DOES own — and every rung here is measured against THAT.
+
+`variant="inline"` drops the pane and draws the words and nothing else, with no
+padding at all, for a strip already inside a surface the app painted. That is
+also how `MapScaleBar` is mounted inside `MapAttribution`: one pane for the whole
+strip, never a pane inside a pane.
+
+The rungs:
+
+| part | rung | why |
+| --- | --- | --- |
+| credit | `textSecondary` (7:1) | 11px, and a licence requirement |
+| updated | `textTertiary` (4.5:1) | quieter, still AA |
+| scale rule | `textGraphical` (3:1) | a LINE, not text |
+
+Flooring the rule at text contrast would make the quietest thing on the map the
+loudest thing on the strip.
+
+## MapScaleBar
+
+A measured span with a tick at each END, and what that span is worth. The ticks
+are what make it read as a measurement between two marks rather than as an
+underline.
+
+Two bars — metric over imperial — share a left edge and stack, so the eye
+compares them as one instrument rather than reading two.
+
+**It converts nothing.** Both the width in pixels and the formatted words come
+from the app, because only the app knows its projection: which round number of
+metres a given number of pixels is worth at this latitude and this zoom. A scale
+bar that guessed its own units would be a measuring instrument that measures the
+component rather than the map.
+
+The whole bar is one `img` named `"Scale, 500 m, 2000 ft"`. A bar and two ticks
+say nothing aloud, and "500 m" on its own is as likely to be a distance to
+somewhere as a scale.
+
+## What is not here
+
+No clock. `updated` is a string the app formatted — this component does not know
+what "3 days ago" means, and a component that computed it would be wrong for
+every locale it was not written in.

package/docs/map-controls.mdx

@@ -0,0 +1,103 @@
+---
+title: Map controls
+description: The chrome that floats over a map — locate, compass, zoom, tilt and the layer picker — as a column of glass islands, with no map engine anywhere in it.
+order: 136
+---
+
+# Map controls
+
+```tsx
+import { MapControls, MapLayerPicker } from '@oxy.so/bloom/map-controls';
+
+<MapControls
+  onLocate={toggleFollow}
+  following={following}
+  heading={heading}
+  onResetNorth={resetNorth}
+  onZoomIn={zoomIn}
+  onZoomOut={zoomOut}
+  tilted={tilted}
+  onTiltChange={setTilted}
+>
+  <MapLayerPicker layers={LAYERS} layerId={layer} onLayerChange={setLayer} overlays={OVERLAYS} … />
+</MapControls>
+```
+
+## One material, and it is the island's
+
+Every group in the stack is a [`GlassIsland`](/docs/glass) and every control inside it is a
+`ButtonGroupItem`. That is not a preference:
+
+- the island paints rung 1 of the surface ladder at the chrome alpha, with the material's
+  own hairline and shadow, so the stack moves with a preset change like everything else;
+- the island mounts a `ControlSurface` with `material: 'glass'`, so the items inside paint
+  FLUSH with no `variant` written on any of them — the contract in
+  [composition](/docs/composition);
+- `ButtonGroupItem` is Bloom's island-aware control. It carries a toggle's `aria-pressed`
+  AND the native selected state in one `selected` prop, and it declares the trigger props
+  an anchored family's `asChild` hands it, which is what makes the layer picker's trigger
+  announce its own expanded state.
+
+**Why not `FrostedIconButton`.** It is one of the three glass materials Bloom grew
+independently, and `glass/` exists so there is not a fourth. Two glass recipes side by side
+in one stack is exactly the drift the island was written to end, so the whole stack is one
+material. A single frosted button over a photograph — where there is no island — is still
+the right control.
+
+**One capsule per GROUP.** Locate, compass and tilt each get their own; zoom in and zoom
+out share one, laid out in a column through the island's own `style`. That is what makes
+the stack read as separate controls rather than as one bar.
+
+## 44, not 34
+
+The button group's rungs are 34 and 30, sized for a toolbar standing beside other chrome
+where the row as a whole is what a finger aims at. A map control is a LONE circle over a
+moving map with a finger already on the glass, so `MAP_CONTROL_BOX` sets the item to 44
+square through the `style` override `ButtonGroupItem` publishes. Nothing about its fill,
+hover, press or focus ring changes.
+
+## The compass
+
+The needle turns by MINUS the heading, so it keeps pointing at north while the map turns
+under it. It **hides itself at north** by default (`hideAtNorth`, within
+`MAP_CONTROLS_GEOMETRY.northTolerance`): a compass on a map already pointing north is a
+control whose press changes nothing, and a reader has to press it to find that out.
+
+The heading reaches the needle through `MapHeadingContext`, not through a prop. That is
+worth knowing because it looks like over-engineering and is not: `ButtonGroupItem` takes
+its glyph as a COMPONENT, and a component built from the heading would be a new component
+TYPE on every degree — React would unmount and remount the SVG on every frame of a
+rotation. A module-scope component reading the context keeps one identity for the life of
+the control.
+
+A needle announces nothing, so the compass is named by prop: "Facing 34 degrees. Reset to
+north" by default, `accessibilityLabel` for a translated sentence.
+
+## The layer picker is two vocabularies
+
+`MapLayerPicker` answers two questions a reader asks in the same breath, and they answer
+differently:
+
+| | what | how |
+| --- | --- | --- |
+| map types | exactly one — standard, satellite, transit | `DropdownMenuRadioGroup`, so the chosen one carries `aria-checked` |
+| overlays | any number — traffic, bike lanes | `DropdownMenuCheckboxItem`s, each its own checkbox |
+
+The rows, indicators, keyboard handling, dismissal and anchoring are
+[`dropdown-menu`](/docs/dropdown-menu)'s. The trigger is a `ButtonGroupItem` composed
+through `asChild`, inside the same `GlassIsland` as everything else, so the picker lands in
+the stack as one more island rather than as a different kind of thing.
+
+It is placed in `children` rather than configured through a prop, so an app can put it
+above the stack, below it, or somewhere else entirely without this component growing a
+placement vocabulary.
+
+## It never touches a map
+
+Every control is a callback and every state is a prop. `MapControls` has no engine, no
+projection, no tiles and no opinion about where on the screen it sits — the app positions
+it, the app owns the map, and this tells the chrome what the map is doing.
+
+The markers, the cluster bubble, the approximate-area circle and the "search this area"
+pill are [`map-marker`](/docs/map-marker); the place they open is
+[`place-card`](/docs/place-card).

package/docs/media-header.mdx

@@ -98,7 +98,7 @@ Each control draws only when its handler is given.
 | Play (56, accent) | `playing`, `onPlayPress`, `playSubject`, `playDisabled` | "Play Lanterns…" / "Pause Lanterns…" |
 | Shuffle | `shuffle`, `onShuffleChange` | toggle "Shuffle", `aria-pressed`; accent with a dot when on |
 | Heart | `liked`, `onLikedChange` | `LikeButton` |
-| Outline pill | `following`, `onFollowChange`, `followLabel`, `followingLabel` | toggle named by `followLabel` in both states, `aria-pressed` |
+| Follow surface | `following`, `onFollowChange`, `followLabel`, `followingLabel` | toggle named by `followLabel` in both states, `aria-pressed` |
 | Download | `download` (`'idle' \| 'downloading' \| 'downloaded'`), `downloadProgress`, `onDownloadPress` | "Download", `aria-pressed` once downloaded, `aria-busy` plus a named `progressbar` while downloading |
 | More | `onMorePress`, or `more` to replace it | "More options" |
 | Search (right) | `onSearchPress`, `searchLabel` | "Search in playlist" |
@@ -181,3 +181,5 @@ Hover states (the edit overlay, underlined links, row washes) are web affordance
 `textMuted` is floored with `quietTextOver` against both the page and the card it
 paints on. As `neutral-500` it measured 4.38:1 on the light card. See
 [Styles → Quiet text](/docs/bloom/main/styles).
+
+`FollowButton` composes Bloom `Button` with a subtle surface. `tone="support"` (the default) uses the secondary palette; `tone="action"` uses the tertiary palette shared with FAB. `iconOnly` shows follow/following icons while retaining the accessible name and pressed state. Its two labels (or icons) slide and fade over 180 ms without changing width; reduced motion switches immediately. `loading` uses the shared Button spinner and blocks interaction while keeping both labels measured. `size` accepts `small`, `medium`, or `large`; `textStyle` applies to the labels and their measurement copies.