@humanforest/ui 0.1.0

package/src/address/address.ts

@@ -0,0 +1,125 @@
+// One address shape, and the normalisers that get Mapbox's several into it.
+//
+// ★ THE NORMALISING IS THE POINT, not the requests. Mapbox answers address questions from three
+// different endpoints and each names the parts differently: Autofill flattens them onto W3C-ish keys
+// (`address_line1`, `address_level2`), Geocoding nests them under `context` with its own slot names
+// (`context.place`, `context.region`), and Validation echoes a third variation back. A form binding
+// six inputs does not want to know which endpoint answered — so everything here lands on one shape and
+// the endpoint wrappers stay thin.
+
+/** An address, in the shape a form binds to. Every part optional: Mapbox omits what it cannot find. */
+export interface ForestAddress {
+  line1?: string;
+  line2?: string;
+  /**
+   * The named area below the city — Islington, Hackney, Shoreditch.
+   *
+   * ★ THIS IS NOT `city`, and conflating them is the trap. For any London address Mapbox answers
+   * `place: "London"`, and the borough a rider would actually name lands in `locality`. A surface
+   * writing "Islington to Hackney" that read `city` would print "London to London" and lose the only
+   * distinction it was making.
+   */
+  locality?: string;
+  /** finer still — a named neighbourhood inside a locality, where Mapbox has one */
+  neighborhood?: string;
+  /** the town or city — `address_level2` in W3C terms, `context.place` in Geocoding's */
+  city?: string;
+  /** county, state or province — `address_level1` / `context.region` */
+  region?: string;
+  postcode?: string;
+  country?: string;
+  /** ISO 3166-1 alpha-2, uppercase */
+  countryCode?: string;
+  /** what Mapbox itself would print for this address, when it offered one */
+  formatted?: string;
+  /** [lng, lat] — present when the answer came with a position */
+  at?: [number, number];
+}
+
+/**
+ * ★ Absent parts stay `undefined`, never ''. A form binds these straight to inputs, and the two are
+ * not interchangeable there: '' blanks a field the reader may have typed into, `undefined` leaves it
+ * alone. Autofill routinely omits line2 and region, so this is the common path rather than an edge.
+ */
+const text = (v: unknown): string | undefined => (typeof v === 'string' && v.length ? v : undefined);
+
+function position(geometry: unknown): [number, number] | undefined {
+  const coords = (geometry as { coordinates?: unknown } | undefined)?.coordinates;
+  return Array.isArray(coords) && typeof coords[0] === 'number' && typeof coords[1] === 'number'
+    ? [coords[0], coords[1]]
+    : undefined;
+}
+
+/**
+ * A retrieved Address Autofill feature → ForestAddress.
+ *
+ * ★ `properties` is typed loosely on purpose. Mapbox declares a different concrete interface for each
+ * endpoint's feature, and naming one here would reject the others at the call site for no gain — this
+ * reads a handful of optional string fields and checks each one anyway.
+ */
+export function fromAutofill(feature: { properties?: unknown; geometry?: unknown }): ForestAddress {
+  const p = (feature.properties ?? {}) as Record<string, unknown>;
+  return {
+    line1: text(p.address_line1),
+    line2: text(p.address_line2),
+    // Autofill's level3 is the same rung as Geocoding's `locality`; it has no neighbourhood at all.
+    locality: text(p.address_level3),
+    neighborhood: undefined,
+    city: text(p.address_level2),
+    region: text(p.address_level1),
+    postcode: text(p.postcode),
+    country: text(p.country),
+    countryCode: text(p.country_code)?.toUpperCase(),
+    formatted: text(p.full_address),
+    at: position(feature.geometry),
+  };
+}
+
+/** A Geocoding feature — forward or reverse — → ForestAddress. */
+export function fromGeocodingFeature(feature: {
+  properties?: unknown;
+  geometry?: unknown;
+}): ForestAddress {
+  const p = (feature.properties ?? {}) as Record<string, unknown>;
+  const ctx = (p.context ?? {}) as Record<string, { name?: unknown; country_code?: unknown }>;
+  const slot = (key: string) => text(ctx[key]?.name);
+
+  return {
+    // `context.address` is the street line when Mapbox resolved to a building; `properties.name` is
+    // what it resolved to at any other precision, which for a reverse lookup is often the street.
+    line1: slot('address') ?? text(p.name),
+    line2: undefined,
+    locality: slot('locality'),
+    neighborhood: slot('neighborhood'),
+    city: slot('place'),
+    region: slot('region'),
+    postcode: slot('postcode'),
+    country: slot('country'),
+    countryCode: text(ctx.country?.country_code)?.toUpperCase(),
+    formatted: text(p.full_address),
+    at: position(feature.geometry),
+  };
+}
+
+/**
+ * The address as one line, in postal order, skipping whatever is missing.
+ *
+ * For when Mapbox gave no `formatted` of its own, or the reader has edited the parts since — a
+ * surface that printed a stale `formatted` beside edited fields would be showing two addresses.
+ */
+/**
+ * The most specific name a person would use for where this is — "Shoreditch", "Islington", "London".
+ *
+ * For naming a place in a sentence rather than addressing an envelope: a ride's start and end, a bay's
+ * area, "reported near…". Falls down the rungs because Mapbox does not have every one everywhere —
+ * a village has a `place` and nothing below it.
+ */
+export function areaLabel(address: ForestAddress): string | undefined {
+  return address.neighborhood ?? address.locality ?? address.city;
+}
+
+export function formatAddress(address: ForestAddress): string {
+  return [address.line1, address.line2, address.city, address.postcode, address.country]
+    .filter((part): part is string => !!part)
+    .join(', ');
+}

package/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/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/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/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/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/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>