@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/address/autofill.ts

@@ -0,0 +1,78 @@
+// Address autofill — type the first line, fill the other five.
+//
+// ★ THIS IS A FORM CAPABILITY, NOT A MAP ONE, which is why it lives outside src/map. Nothing here
+// needs a map, renders to a canvas, or knows what a vehicle is; a signup screen with no map on it is
+// the main caller. It shares a package with the geocoders because it shares their endpoint family and
+// their session-billing rule, not because it shares their surface.
+//
+// ★ SUGGEST IS FREE-ISH, RETRIEVE IS THE BILLED CALL — one session token spans the keystrokes leading
+// to a single retrieve, exactly as the places source does. Rolling the token per keystroke would bill
+// every letter as its own search.
+import { AddressAutofillCore, SessionToken } from '@mapbox/search-js-core';
+import { fromAutofill, type ForestAddress } from './address';
+
+type AutofillClient = Pick<AddressAutofillCore, 'suggest' | 'retrieve'>;
+
+export interface AddressSuggestion {
+  id: string;
+  /** the address line, e.g. "12 Morning Lane" */
+  label: string;
+  /** the rest of it, e.g. "London, E9 6NU, United Kingdom" */
+  description?: string;
+  /** Mapbox's own object, handed back to `retrieve` — opaque to callers */
+  raw: unknown;
+}
+
+export interface AddressAutofillOptions {
+  accessToken: string;
+  country?: string;
+  language?: string;
+  limit?: number;
+  client?: AutofillClient;
+}
+
+export interface AddressAutofill {
+  suggest(query: string, signal?: AbortSignal): Promise<AddressSuggestion[]>;
+  /** The chosen suggestion, resolved into every part a form binds. Ends the billing session. */
+  retrieve(suggestion: AddressSuggestion, signal?: AbortSignal): Promise<ForestAddress | null>;
+}
+
+export function addressAutofill(options: AddressAutofillOptions): AddressAutofill {
+  const client: AutofillClient =
+    options.client ??
+    new AddressAutofillCore({
+      accessToken: options.accessToken,
+      country: options.country,
+      language: options.language,
+    });
+
+  let session = new SessionToken();
+
+  return {
+    async suggest(query, signal) {
+      const { suggestions } = await client.suggest(query, {
+        sessionToken: session,
+        limit: options.limit ?? 5,
+        signal,
+      });
+
+      return suggestions.map((s) => ({
+        id: s.mapbox_id,
+        label: s.feature_name,
+        // `description` is Mapbox's own "the rest of the address" string; full_address repeats the
+        // line the reader is already looking at, so it is the fallback rather than the first choice.
+        description: s.description ?? s.full_address,
+        raw: s,
+      }));
+    },
+
+    async retrieve(suggestion, signal) {
+      const { features } = await client.retrieve(suggestion.raw as never, {
+        sessionToken: session,
+        signal,
+      });
+      session = new SessionToken();
+      return features.length ? fromAutofill(features[0]) : null;
+    },
+  };
+}

package/packages/ui/src/address/geocode.ts

@@ -0,0 +1,55 @@
+// Coordinates → address, and address → coordinates.
+//
+// ★ NOT THE SAME ENDPOINT AS <FMapSearch>'s places source. Search Box is built for a person typing
+// into a field and ranks by relevance; Geocoding answers a precise question about a point or a string
+// and returns postal parts. Reverse in particular has no Search Box equivalent at all — it is the only
+// way to turn a map position into words, which is what a surface needs the moment a reader drops a pin
+// or finishes a ride somewhere.
+import { GeocodingCore } from '@mapbox/search-js-core';
+import { fromGeocodingFeature, type ForestAddress } from './address';
+
+/** The two calls this makes, so a test can stand in for the client. */
+type GeocodingClient = Pick<GeocodingCore, 'forward' | 'reverse'>;
+
+export interface GeocoderOptions {
+  accessToken: string;
+  /** ISO country codes to restrict to, e.g. `'gb'` */
+  country?: string;
+  language?: string;
+  /** forward results returned; reverse always takes the closest single answer */
+  limit?: number;
+  /** stands in for the real client in tests */
+  client?: GeocodingClient;
+}
+
+export interface Geocoder {
+  /** What is at this point. Null when Mapbox has nothing there — mid-ocean, or a blank tile. */
+  reverse(at: [number, number], signal?: AbortSignal): Promise<ForestAddress | null>;
+  /** Where is this address. Ordered by relevance, empty when nothing matched. */
+  forward(query: string, signal?: AbortSignal): Promise<ForestAddress[]>;
+}
+
+export function geocoder(options: GeocoderOptions): Geocoder {
+  const client: GeocodingClient =
+    options.client ??
+    new GeocodingCore({
+      accessToken: options.accessToken,
+      country: options.country,
+      language: options.language,
+    });
+
+  return {
+    async reverse(at, signal) {
+      // limit 1: reverse geocoding returns a stack of ever-coarser features for the same point —
+      // the building, then the street, then the postcode, then the city. The first is the answer;
+      // the rest are its context, and `fromGeocodingFeature` already reads that off `context`.
+      const { features } = await client.reverse(at, { limit: 1, signal });
+      return features.length ? fromGeocodingFeature(features[0]) : null;
+    },
+
+    async forward(query, signal) {
+      const { features } = await client.forward(query, { limit: options.limit ?? 5, signal });
+      return features.map(fromGeocodingFeature);
+    },
+  };
+}

package/packages/ui/src/address/index.ts

@@ -0,0 +1,31 @@
+// Forest's address subsystem — the Mapbox address family, normalised onto one shape.
+//
+// Three endpoints answer three different questions and name the answer's parts three different ways.
+// Everything here lands on `ForestAddress`, so a form binding six inputs never learns which one
+// replied:
+//
+//   addressAutofill()   type the first line, fill the other five      — a signup or billing form
+//   geocoder()          reverse: a point → words. forward: words → a point
+//   addressValidator()  is it real, and which part is wrong
+//
+// ★ SEPARATE ENTRY POINT (`@humanforest/ui/address`), like the places source. None of this is map
+// chrome — a billing form has no map on it — and an app that only draws maps should not carry the
+// address clients, nor the reverse.
+export type { ForestAddress } from './address';
+export { areaLabel, formatAddress, fromAutofill, fromGeocodingFeature } from './address';
+
+export { addressAutofill } from './autofill';
+export type { AddressAutofill, AddressAutofillOptions, AddressSuggestion } from './autofill';
+
+export { geocoder } from './geocode';
+export type { Geocoder, GeocoderOptions } from './geocode';
+
+export { addressValidator } from './validate';
+export type {
+  AddressCheck,
+  AddressConfidence,
+  AddressPart,
+  AddressPartMatch,
+  AddressValidator,
+  AddressValidatorOptions,
+} from './validate';

package/packages/ui/src/address/validate.ts

@@ -0,0 +1,91 @@
+// Is this address real, and did every part of it match.
+//
+// ★ THE PER-PART VERDICT IS THE USEFUL HALF, not the overall confidence. "That address looks wrong"
+// gives a reader nothing to act on; "the postcode did not match" points at the field to fix. Mapbox
+// returns both, and a form should surface the parts.
+//
+// ★ THE UNIONS ARE DECLARED HERE RATHER THAN IMPORTED. Mapbox ships MatchCodeType and
+// MatchCodeConfidence as `const enum` in a .d.ts — TypeScript inlines those at compile time and emits
+// no runtime object, so importing them as VALUES throws under a bundler. Types only, and our own
+// literals for anything that has to exist at runtime.
+import { ValidationCore, SessionToken } from '@mapbox/search-js-core';
+import { fromGeocodingFeature, formatAddress, type ForestAddress } from './address';
+
+type ValidationClient = Pick<ValidationCore, 'validate'>;
+
+/** How one component of the address fared. */
+export type AddressPartMatch =
+  | 'matched'
+  | 'unmatched'
+  /** interpolated rather than found — the street is real, the number was estimated */
+  | 'plausible'
+  /** not part of this address's postal form at all */
+  | 'not_applicable'
+  /** not submitted, but filled in confidently. Mapbox only does this for country. */
+  | 'inferred';
+
+export type AddressConfidence = 'exact' | 'high' | 'medium' | 'low';
+
+export type AddressPart = 'address_number' | 'street' | 'postcode' | 'place' | 'region' | 'country';
+
+export interface AddressCheck {
+  confidence: AddressConfidence;
+  /** per-component verdicts — the part a form points its error at */
+  parts: Partial<Record<AddressPart, AddressPartMatch>>;
+  /** what Mapbox believes the address actually is, normalised */
+  resolved: ForestAddress | null;
+  /** the components that came back `unmatched`, ready to mark in a form */
+  problems: AddressPart[];
+}
+
+export interface AddressValidatorOptions {
+  accessToken: string;
+  country?: string;
+  client?: ValidationClient;
+}
+
+export interface AddressValidator {
+  /** Null when Mapbox recognised nothing at all — a typo storm, or an address that does not exist. */
+  validate(address: string | ForestAddress, signal?: AbortSignal): Promise<AddressCheck | null>;
+}
+
+export function addressValidator(options: AddressValidatorOptions): AddressValidator {
+  const client: ValidationClient =
+    options.client ??
+    new ValidationCore({ accessToken: options.accessToken, country: options.country });
+
+  return {
+    async validate(address, signal) {
+      const query = typeof address === 'string' ? address : formatAddress(address);
+      if (!query) return null;
+
+      const { features } = await client.validate(query, { sessionToken: new SessionToken(), signal });
+      if (!features.length) return null;
+
+      const feature = features[0];
+      // MatchCode's fields are typed as const-enum members; read as plain strings, since the enum has
+      // no runtime object to compare against (see the note at the top of this file).
+      const code = (feature.properties?.match_code ?? {}) as unknown as Record<string, string>;
+      const parts: Partial<Record<AddressPart, AddressPartMatch>> = {};
+      for (const part of [
+        'address_number',
+        'street',
+        'postcode',
+        'place',
+        'region',
+        'country',
+      ] as const) {
+        if (code[part]) parts[part] = code[part] as AddressPartMatch;
+      }
+
+      return {
+        confidence: (code.confidence ?? 'low') as AddressConfidence,
+        parts,
+        resolved: fromGeocodingFeature(feature as never),
+        // `not_applicable` and `inferred` are not faults — a UK address has no region to match, and an
+        // inferred country is Mapbox being helpful. Only `unmatched` is worth pointing a reader at.
+        problems: (Object.keys(parts) as AddressPart[]).filter((p) => parts[p] === 'unmatched'),
+      };
+    },
+  };
+}

package/packages/ui/src/canvas/FCanvasCard.vue

@@ -0,0 +1,97 @@
+<script setup lang="ts">
+// A card floating ON a canvas — a readout, a legend, a stat panel, a filter row.
+//
+//   <FCanvasCard>5 bays in view</FCanvasCard>
+//   <FCanvasCard><template #header>Live fleet</template>…</FCanvasCard>
+//
+// ★ IT IS A UCard, and adds ONLY what the canvas changes. An earlier cut reimplemented the box — its own
+// radius, its own padding rungs, its own header — and every one of those was a worse copy of a decision
+// the card theme had already made: `soft` is a quiet fill with no ring, `divide-y-0` (so no rule under a
+// header) and a padding scale the rest of Forest shares. Reimplementing it drifted a canvas card away
+// from a page card for no reason anyone could name, and the hand-rolled header put a rule INSIDE the
+// card's own padding, floating in the middle of the tile.
+//
+// What is left here is the difference, and only the difference:
+//
+//   · the chrome surface — translucent, backdrop-blurred — so the map stays legible as context under
+//     its own chrome rather than being covered by an opaque tile;
+//   · the edge, `ring-default`: the same ring the side panel carries, so a card and a panel on one
+//     canvas read as the same material rather than as two kinds of glass;
+//   · the radius, 16px, matching the side panel rather than the card theme's own 24. A canvas puts a
+//     card, a panel and a control side by side, and at the theme's default that was three radii in one
+//     frame (24 / 16 / 12). It arrives through the `forest-canvas-card` marker rather than a utility,
+//     because the concentric nesting rule in forest.css is UNLAYERED and outranks any `rounded-*` a
+//     component can carry — measured: inside a UCard (a map panel on a dashboard, a specimen in these
+//     docs) the ramp stepped this card to 8px. The marker also says what is true: chrome on a canvas is
+//     not a surface nested in another surface, so the ramp does not describe it.
+//
+// Everything else — padding, the header and footer slots, the ink — belongs to the card theme and stays
+// there. A site that needs a tighter body passes UCard's own `:ui`, which is what it would
+// use for a page card too.
+//
+// ★ NO DROP SHADOW. Forest separates surfaces by ring and tint rather than by lift, and a canvas is
+// where that matters most: a shadow over a moving map reads as a second, softer copy of the card
+// sliding along with it. The edge does the work.
+//
+// ★ IT DOES NOT POSITION ITSELF. Placement on a canvas belongs to <FCanvasHud>'s areas, or to a page
+// with no HUD; a card that placed itself would be a second layout system competing with the rails for
+// the same corners.
+//
+// ★ `interactive` is for a pressable tile — a stat you can open. A pressable tile with ONE icon is an
+// <FCanvasControl> instead; this is for the case where the tile holds a layout a button would have to
+// rebuild inside itself. It adds the affordance once, on the shared motion tokens, where the site that
+// motivated it had hand-rolled its own hover and `active:scale-[.97]`.
+import { computed } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** Pressable: hover fill, press nudge, focus ring. Pair with `as="button"` so it is reachable. */
+    interactive?: boolean;
+    /** Forwarded to UCard, so a site can tighten the body exactly as it would on any card. */
+    ui?: Record<string, string>;
+  }>(),
+  { interactive: false, ui: undefined },
+);
+
+// `pointer-events-auto` because the HUD's areas are pointer-transparent and opt their children back in:
+// a card dropped into a rail would otherwise let clicks fall through to the map beneath it.
+//
+// The press treatment rides the shared motion tokens rather than a hand-picked duration. The nudge is a
+// scale rather than a lift, because a lift under a translucent surface changes what shows through it.
+const press = computed(() =>
+  props.interactive
+    ? [
+        'cursor-pointer text-left',
+        'transition-[transform,background-color] duration-(--motion-fast) ease-(--motion-ease-out)',
+        'hover:[--forest-canvas-chrome-fill:var(--ui-bg)] active:scale-[.98]',
+        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
+      ].join(' ')
+    : '',
+);
+
+// ★ The title takes the SIDE PANEL's treatment, not the page card's. On a page a card title is sans at
+// rest (the card theme leaves it to the --fx-* traits); on a canvas a card sits beside a panel whose
+// title is MohrAlt, and two headings in one frame reading differently is the drift a shared surface is
+// supposed to prevent. Same class the sidebar fragment carries: one heading voice per canvas.
+const TITLE = 'font-display';
+
+const cardUi = computed(() => ({
+  ...props.ui,
+  title: [TITLE, props.ui?.title].filter(Boolean).join(' '),
+  root: [
+    'forest-canvas-chrome forest-canvas-card pointer-events-auto ring ring-default',
+    press.value,
+    props.ui?.root,
+  ]
+    .filter(Boolean)
+    .join(' '),
+}));
+</script>
+
+<template>
+  <UCard :ui="cardUi">
+    <template v-if="$slots.header" #header><slot name="header" /></template>
+    <slot />
+    <template v-if="$slots.footer" #footer><slot name="footer" /></template>
+  </UCard>
+</template>

package/packages/ui/src/canvas/FCanvasControl.vue

@@ -0,0 +1,121 @@
+<script setup lang="ts">
+// One control on a canvas — a zoom button, a layers toggle, the FAB that opens a panel.
+//
+//   <FCanvasControl icon="i-lucide-plus" label="Zoom in" />
+//   <FCanvasControl icon="i-lucide-sliders-horizontal" label="Filters" v-model:pressed="panel" />
+//
+// ★ WHY THIS EXISTS AND IS NOT JUST A UButton WITH A CLASS. The canvas-chrome surface replaces
+// `background-color`, which is right for neutral chrome and WRONG for a control carrying its own fill:
+// on a solid button it removes the very fill the label colour was chosen against and leaves that ink on
+// a translucent surface, unreadable in both modes. Every usage site therefore had to know a rule —
+// "apply the surface, except when pressed" — and one of them got it wrong the week the utility landed.
+// Here the two states are one component's business and the rule has nowhere to leak to.
+//
+// It also pins the two things a hand-rolled FAB forgets: the control size the HUD measures its rails in
+// (--forest-canvas-control, so a control and its rail cannot disagree), and the accessible name that an
+// icon-only button has no text to supply.
+import { computed } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** The glyph. Exactly one of `icon` or `text`. */
+    icon?: string;
+    /**
+     * A short string in place of the glyph — `2D`, `N`, a zoom level.
+     *
+     * ★ SOMETIMES A WORD IS THE ONLY LEGIBLE ICON. A cube does not say "three dimensions" to anyone
+     * who has not been told, and nothing says "2D" but "2D". The control keeps its square geometry,
+     * its size and both cuts; only the picture changes. Two or three characters — longer than that
+     * belongs on a button with a real label.
+     */
+    text?: string;
+    /** The accessible name. Required: a glyph-only control has no prose to fall back on. */
+    label: string;
+    disabled?: boolean;
+  }>(),
+  { icon: undefined, text: undefined, disabled: false },
+);
+
+/**
+ * Bind it and the control becomes a TOGGLE — aria-pressed, and the pressed cut. Left unbound it is a
+ * plain action, which is why the model has no default: `undefined` is how a control says it has no
+ * pressed state to report, and a default of `false` would make every zoom button claim to be an
+ * unpressed toggle.
+ */
+// ★ `default: undefined` is load-bearing. Vue casts an ABSENT Boolean prop to `false`, so without it a
+// plain action (no v-model) reported itself as an unpressed toggle — measured: `aria-pressed="false"` on
+// a zoom button, which tells a screen reader it is a toggle that happens to be off.
+const pressed = defineModel<boolean | undefined>('pressed', { default: undefined });
+
+const isToggle = computed(() => pressed.value !== undefined);
+
+// ★ The pressed cut is SOLID and takes no chrome surface; the resting cut is outline and takes it. That
+// pairing is the whole point of the component — see the note above.
+//
+// The class is applied here rather than in the theme because it is a surface for a PLACE (a canvas), not
+// a property of the button: the same outline button in a page's toolbar wants nothing to do with it.
+const surface = computed(() => (pressed.value ? '' : 'forest-canvas-chrome'));
+
+// ★ DISABLED HAS TO READ AS DISABLED, and the button recipe alone does not manage it here. Stock dims
+// with `opacity-75`, which is a fine signal on a page: the control fades against a known background.
+// On a canvas it fails twice — 75% of near-white ink is still near-white, and the opacity also thins
+// the chrome surface, so the map shows through MORE and the control looks lighter rather than quieter.
+// Measured: a disabled control and a live one differed by nothing but that 0.75.
+//
+// So the ink drops to `text-dimmed`: a colour change reads instantly at a glance, where a uniform fade
+// reads as "slightly further away". The icon is targeted directly because it takes its colour by
+// INHERITANCE from the button, and an inherited value loses to any declaration on the element itself.
+//
+// ★ THE EDGE DOES NOT CHANGE, deliberately. Softening the ring as well made a disabled control read as a
+// different KIND of control sitting in the rail rather than the same one switched off — the same reason
+// the merged group had to borrow the button's exact ring. One edge weight across every state; the state
+// lives in the fill and the glyph.
+//
+// ★ AND THE OPACITY IS TURNED OFF, not merely supplemented. Opacity fades the whole element — including
+// the chrome surface, which is already translucent — so a disabled control let MORE map through and read
+// as lighter and less solid, which is the opposite of quiet. Measured against the surface: the colour
+// change alone takes the ink from ~13:1 to ~3.4:1, which is the signal; the fade was adding nothing but
+// a thinner background. Both the `disabled:` and `aria-disabled:` paths are overridden, since the recipe
+// carries the fade on each.
+//
+// ★ THE SURFACE CARRIES THE STATE TOO, not just the glyph. A dimmed ink on an identical tile still reads
+// as pressable, so the disabled fill steps toward the middle — greyer in light, less black in dark, one
+// token doing both. The blur and the 85% stay, so it is the same material rather than a different object.
+//
+// ★ THE SURFACE HAS TO BE RESTATED UNDER THE SAME VARIANT. The recipe also sets a `disabled:bg-*`, and a
+// variant beats the chrome utility on source order even at equal specificity — measured, a disabled
+// control dropped to an OPAQUE tile while every live control beside it was 85% and blurred. It reads as
+// a different kind of object rather than the same object switched off. Referencing the named fill keeps
+// this a pointer to one value rather than a second copy of the colour-mix.
+const disabledLook = computed(() =>
+  props.disabled
+    ? [
+        'disabled:opacity-100 aria-disabled:opacity-100',
+        'disabled:bg-(--forest-canvas-chrome-fill-disabled) aria-disabled:bg-(--forest-canvas-chrome-fill-disabled)',
+        '[&_[data-slot=leadingIcon]]:text-dimmed',
+      ].join(' ')
+    : '',
+);
+</script>
+
+<template>
+  <UButton
+    :icon="text ? undefined : icon"
+    :color="pressed ? 'primary' : 'neutral'"
+    :variant="pressed ? 'solid' : 'outline'"
+    :disabled="disabled"
+    square
+    :aria-label="label"
+    :aria-pressed="isToggle ? String(!!pressed) : undefined"
+    :class="[surface, disabledLook]"
+    :ui="{ base: 'size-(--forest-canvas-control) shrink-0' }"
+    @click="isToggle && (pressed = !pressed)"
+  >
+    <!-- The scale bar's treatment, so the lettered chrome on a canvas reads as one voice: bold
+         because Forest authors two weights, tabular so a changing readout does not shuffle, and
+         `aria-hidden` because the accessible name is the label rather than these two characters. -->
+    <span v-if="text" class="text-[0.6875rem] leading-none font-bold tracking-wide tabular-nums" aria-hidden="true">
+      {{ text }}
+    </span>
+  </UButton>
+</template>

package/packages/ui/src/canvas/FCanvasControlGroup.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+// A merged cluster of canvas controls — zoom in / zoom out, or a set of map modes. Reads as ONE control
+// with several positions, which is why the members share one surface rather than floating as separate
+// tiles.
+//
+//   <FCanvasControlGroup>
+//     <FCanvasControl icon="i-lucide-plus" label="Zoom in" />
+//     <FCanvasControl icon="i-lucide-minus" label="Zoom out" />
+//   </FCanvasControlGroup>
+//
+// ★ THE GROUP OWNS THE SURFACE, and its members go transparent. Not cosmetic: the canvas-chrome surface
+// is translucent AND blurred, so a per-member surface would stack alpha and blur at every seam and draw
+// the joins as darker bands — the opposite of merged. One surface, hairlines inside it, radius on the
+// outer corners only.
+//
+// ★ WHY NOT <UFieldGroup>, which already joins controls and supports a vertical orientation. Because it
+// merges BORDERS, not SURFACES: `-space-y-px` overlaps its children by a pixel so their rings collapse
+// into one, and every child keeps its own background. That is exactly right for opaque form controls and
+// wrong here — the canvas surface is translucent AND backdrop-blurred, so per-child surfaces stack their
+// alpha at every overlap and each runs its own blur pass, sampling the map separately. The cluster stops
+// being one pane of glass and shows its joins as darker, differently-blurred bands.
+//
+// So the geometry is the easy half (a flex column, a hairline between, one radius) and the surface is the
+// reason this component exists: ONE fill, ONE blur, members bare.
+//
+// ★ Styled through child selectors rather than provide/inject — not because injection cannot reach slot
+// content (it can: Vue resolves it through the mounted tree, which is how UFieldGroup talks to its own
+// children), but because these members are not ours to instruct. A member is an <FCanvasControl> whose
+// surface comes from a utility class, and a child selector switches that off through the utility's own
+// vars without the member needing to know it is in a group at all.
+//
+// ★ THE EDGE IS THE BUTTON'S EDGE, and it took two measurements to get right. A lone control draws
+// `ring-accented` INSET (the outline button's own recipe); this group first drew `ring-default` OUTSET,
+// which differs twice over — a lighter colour, and a ring outside the box, so the cluster sat a pixel
+// wider than the controls beside it. Merged and lone have to be the same object at different lengths.
+// The inner hairlines take the same token for the same reason: one edge colour per cluster.
+//
+// ★ AND THE EDGE IS PAINTED ON A LAYER ABOVE THE MEMBERS. An inset box-shadow paints above its own
+// element's background but BELOW its descendants, so the moment a member takes a hover fill — which
+// spans the member's full width — it covers the group's ring along that member's edges and the border
+// breaks exactly where the pointer is. An overlay pseudo-element cannot be covered by a sibling's
+// background, so the edge survives every state a member can be in.
+//
+// ★ A PRESSED member keeps its solid fill: it is the one part that must stay opaque, and inside a merged
+// cluster it fills its whole cell so the selection reads as a position rather than a floating tile.
+//
+// What belongs in one group: actions on the same subject. Zoom in and zoom out, yes; zoom and "open
+// filters", no — a merged cluster claims the two things are one control, and unrelated actions in one
+// stack make that claim falsely.
+import { computed } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * Rails stack, so `vertical` is the default. The hub is the one horizontal area — pass
+     * `orientation="horizontal"` there.
+     *
+     * Not inferred from the area it sits in, and injection could not do it even though it would reach
+     * here: a `provide` is one value per HUD instance, and the HUD's areas disagree — its rails are
+     * vertical and its hub is horizontal, so a single provided orientation would be wrong in one of them.
+     * The alternative (a stylesheet rule keyed on `[data-area]`) would bury HUD knowledge in this
+     * component's CSS. The author already chose the area; this says so out loud.
+     */
+    orientation?: 'vertical' | 'horizontal';
+  }>(),
+  { orientation: 'vertical' },
+);
+
+const vertical = computed(() => props.orientation === 'vertical');
+
+// The members: surface off, radius off, and the ring off — the group draws all three once. Only the
+// hairline between members is theirs, and it goes on the leading edge of every member but the first.
+// ★ The surface is switched off through the utility's own VARS, not by out-specifying it. The chrome
+// rule is deliberately doubled (`.forest-canvas-chrome.forest-canvas-chrome`) so component recipes cannot
+// beat it, which means a child selector here loses too — measured, the members kept their own fill and
+// blur and the cluster showed its seams. Declaring the var on the child sidesteps the contest entirely.
+const members = [
+  '[&>*]:[--forest-canvas-chrome-fill:transparent] [&>*]:[--forest-canvas-chrome-blur:none]',
+  // ★ NO RULE BETWEEN MEMBERS. Mapbox's own control group draws one, and an earlier cut of this did
+  // too, on the reasoning that two squares in one pill would otherwise read as a single tall button.
+  // Over a canvas they lose that argument: the surface is a small pane of glass on a busy, moving map,
+  // and every line inside it competes with the map's own. Hover and press do the separating instead —
+  // they land on ONE member and end at its edges, which is a stronger boundary than a hairline because
+  // it appears exactly when the pointer is asking where the boundary is.
+  '[&>*]:rounded-none [&>*]:ring-0 [&>*]:shadow-none',
+].join(' ');
+</script>
+
+<template>
+  <div
+    class="forest-canvas-chrome pointer-events-auto relative flex overflow-hidden rounded-md after:pointer-events-none after:absolute after:inset-0 after:rounded-md after:ring after:ring-inset after:ring-accented"
+    :class="[
+      vertical ? 'flex-col' : 'flex-row',
+      members,
+    ]"
+    role="group"
+  >
+    <slot />
+  </div>
+</template>