@oxy.so/bloom 2.10.0 → 2.12.0

package/src/stay-search/types.ts

@@ -97,6 +97,18 @@ export interface DestinationSuggestion {
   description?: string;
   /** A Remix icon component (`RiMapPinLine`, `RiTimeLine`…). Default `RiMapPinLine`. */
   icon?: ButtonIconComponent;
+  /**
+   * The row is offered but cannot be chosen — "Use my location" while location
+   * is off. It dims, answers no press, and the arrow keys step over it.
+   */
+  disabled?: boolean;
+  /**
+   * Why it cannot be chosen ("Location is off"). Drawn in place of
+   * `description` while `disabled`, and read after the title, so the row says
+   * what is wrong rather than only looking wrong. Ignored when the row is not
+   * disabled.
+   */
+  disabledReason?: string;
 }
 
 export interface DestinationSuggestionsProps {
@@ -135,6 +147,14 @@ export interface GuestPickerProps {
   labels?: Partial<Record<GuestKind, string>>;
   /** Override descriptions (`null` hides one). */
   descriptions?: Partial<Record<GuestKind, string | null>>;
+  /**
+   * The name of every row's `−` button, which is English by default
+   * (`"Decrease"`). Same spelling as `Stepper`'s, and passed to every row — the
+   * row's own title is what says WHICH counter it belongs to.
+   */
+  decrementLabel?: string;
+  /** The name of every row's `+` button. Default `"Increase"`. */
+  incrementLabel?: string;
   /**
    * The most guests the place takes, counting adults and children (infants and
    * pets do not count). Their `+` buttons disable once the sum reaches it.

package/src/stepper/Stepper.tsx

@@ -1,13 +1,14 @@
-import React, { memo, useCallback, useEffect, useMemo } from 'react';
+import React, { memo, useCallback, useMemo } from 'react';
 import { Platform, View, type AccessibilityActionEvent } from 'react-native';
 
 import { Button } from '../button';
 import { resolveButtonRamps } from '../button/shared';
-import { FOCUS_RING_OFFSET_COLOR, webDataSet } from '../checkbox/shared';
+import { webDataSet } from '../styles/web-data';
 import { useAccessibleNameWarning } from '../hooks/use-accessible-name-warning';
 import { RiAddLine } from '../icons/remix/RiAddLine';
 import { RiSubtractLine } from '../icons/remix/RiSubtractLine';
-import { adoptStyleSheet } from '../styles/adopt-style-sheet';
+import { useRingOffsetStyle } from '../styles/surface-levels';
+import { interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
@@ -58,14 +59,17 @@ function stepperClamp(raw: number, min: number, max: number | undefined, step: n
 
 const STYLE_ID = 'bloom-stepper-web-css';
 const VALUE = '[data-bloom-stepper-value]';
-const BLOOM_STEPPER_CSS = `
-${VALUE} {
-  outline: none;
-}
-${VALUE}:focus-visible {
-  box-shadow: 0 0 0 2px ${FOCUS_RING_OFFSET_COLOR}, 0 0 0 4px var(--bloom-stepper-ring, currentColor);
-}
-`;
+const BLOOM_STEPPER_CSS = interactiveWebCss({
+  selector: VALUE,
+  varPrefix: 'bloom-stepper',
+  // The VALUE is a focusable readout, not a button: no `<button>` reset, no
+  // hover rule, no press scale — only focus.
+  reset: 'none',
+  base: 'cursor: default;',
+  transition: 'box-shadow 120ms ease',
+  focus: { mode: 'ring' },
+  disabled: { opacity: null },
+});
 
 function StepperComponent({
   value,
@@ -83,10 +87,9 @@ function StepperComponent({
   testID,
 }: StepperProps) {
   const theme = useTheme();
+  const ringOffset = useRingOffsetStyle();
   useAccessibleNameWarning('Stepper', accessibilityLabel);
-  useEffect(() => {
-    adoptStyleSheet(STYLE_ID, BLOOM_STEPPER_CSS);
-  }, []);
+  useInteractiveWebCss(STYLE_ID, BLOOM_STEPPER_CSS);
   const { accent } = useMemo(() => resolveButtonRamps(theme), [theme]);
   const config = SIZE_CONFIG[size];
 
@@ -156,6 +159,7 @@ function StepperComponent({
     alignItems: 'center',
     justifyContent: 'center',
     '--bloom-stepper-ring': accent[500],
+    ...ringOffset,
   };
 
   return (

package/src/styles/clamp.ts

@@ -0,0 +1,34 @@
+/**
+ * The two clamps every family writes for itself. Pure, no dependencies.
+ *
+ * Five copies of `clamp` and three of `clamp01` existed under four names
+ * (`clamp01`, `clampFraction`, and the 0–100 `clampProgress`, which is a
+ * different function and stays where it is).
+ */
+
+/**
+ * `value` held inside `[min, max]`.
+ *
+ * An INVERTED range (`min > max`) resolves to `min`, and that is load-bearing
+ * rather than incidental: `overlay/dropdown-placement.ts` inverts the range
+ * exactly when a surface is larger than the viewport minus its gutters, and
+ * preferring `min` pins the surface to the top/left gutter so its FIRST rows
+ * stay reachable. Preferring `max` would push its start off-screen and strand
+ * every row. Three of the five copies agreed with `min`; the ordering here is
+ * the one that keeps that true.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+/**
+ * `value` held inside `[0, 1]` — a fraction, a progress share, a scroll ratio.
+ *
+ * `undefined`, `NaN` and the infinities all answer `0`, so an unmeasured or
+ * not-yet-loaded value reads as "none of it" rather than propagating a
+ * non-finite number into a width or an opacity.
+ */
+export function clamp01(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}

package/src/styles/color-contrast.ts

@@ -17,6 +17,77 @@ export function relativeLuminance(color: string): number | null {
   return 0.2126 * channel(c.r) + 0.7152 * channel(c.g) + 0.0722 * channel(c.b);
 }
 
+/** Composite `top` at `alpha` over opaque `base` — CSS `color-mix(in srgb)`. */
+export function mixColors(base: string, top: string, alpha: number): string {
+  const b = parseRgba(base);
+  const t = parseRgba(top);
+  if (!b || !t) return base;
+  const ch = (x: number, y: number) => Math.round(y * alpha + x * (1 - alpha));
+  return `rgb(${ch(b.r, t.r)} ${ch(b.g, t.g)} ${ch(b.b, t.b)})`;
+}
+
+/**
+ * The quietest blend of `text` over `surface` that still clears `minRatio`.
+ *
+ * Contrast rises monotonically with the blend, so a bisection finds the rung —
+ * and then the QUANTIZED colour is re-checked and nudged upward, because an
+ * 8-bit round turns a nominal 4.50 into a measured 4.49. What a caller gets back
+ * therefore clears the floor as RENDERED, not as computed.
+ *
+ * This is the one way Bloom builds a quiet text colour. A ramp STOP cannot do
+ * the job: `neutral-400` clears AA on the page and measures 2.42:1 on a chart
+ * card, because the card is not the page. Reading the rung off the fill it
+ * actually lands on is the whole difference — and it needs no new colours, since
+ * every rung is the theme's own `text` over the theme's own surface.
+ */
+export function quietText(surface: string, text: string, minRatio: number): string {
+  if (contrastRatio(surface, text) <= minRatio) return text;
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < 16; i += 1) {
+    const midpoint = (lo + hi) / 2;
+    if (contrastRatio(mixColors(surface, text, midpoint), surface) >= minRatio) hi = midpoint;
+    else lo = midpoint;
+  }
+  for (let t = hi; t <= 1; t += 1 / 255) {
+    const candidate = mixColors(surface, text, t);
+    if (contrastRatio(candidate, surface) >= minRatio) return candidate;
+  }
+  return text;
+}
+
+/**
+ * One quiet colour for SEVERAL surfaces — the rung that clears `minRatio` on the
+ * hardest of them.
+ *
+ * A family's caption grey usually lands on more than one fill: a chart card's
+ * ticks sit on the card AND on the stat tiles inset into it, and those two are
+ * on opposite sides of the text in dark mode. Flooring against one of them is
+ * how `2.42:1` happened in the first place, one level up.
+ *
+ * Each surface proposes its own rung and the one with the best WORST case wins,
+ * rather than assuming which surface is hardest — that assumption flips between
+ * light and dark for exactly these pairs. Falls back to `text` if no rung clears
+ * every surface, which is the honest answer: there is no quiet colour there.
+ */
+export function quietTextOver(
+  surfaces: readonly string[],
+  text: string,
+  minRatio: number,
+): string {
+  let best = text;
+  let bestWorstCase = -1;
+  for (const surface of surfaces) {
+    const candidate = quietText(surface, text, minRatio);
+    const worstCase = Math.min(...surfaces.map((s) => contrastRatio(candidate, s)));
+    if (worstCase > bestWorstCase) {
+      bestWorstCase = worstCase;
+      best = candidate;
+    }
+  }
+  return bestWorstCase >= minRatio ? best : text;
+}
+
 /** WCAG contrast ratio between two opaque colours (1..21); `1` if either does not parse. */
 export function contrastRatio(a: string, b: string): number {
   const la = relativeLuminance(a);
@@ -25,3 +96,93 @@ export function contrastRatio(a: string, b: string): number {
   const [hi, lo] = la > lb ? [la, lb] : [lb, la];
   return (hi + 0.05) / (lo + 0.05);
 }
+
+// ---------------------------------------------------------------------------
+//  The bars
+//
+//  Four families had each named 4.5 for themselves (`COVER_TEXT_CONTRAST`,
+//  `IMMERSIVE_TEXT_TARGET`, `LYRICS_UPCOMING_CONTRAST`, `MIN_TEXT_CONTRAST`),
+//  which made "do these two surfaces hold text to the same bar?" a question you
+//  had to answer by reading five files.
+// ---------------------------------------------------------------------------
+
+/** WCAG AA for body text. The bar every label on a computed surface is held to. */
+export const AA_TEXT_CONTRAST = 4.5;
+
+/** WCAG AA for LARGE text — 24px and up, or 19px bold. */
+export const AA_LARGE_TEXT_CONTRAST = 3;
+
+/** WCAG AAA for body text. What a surface holds its most important line to. */
+export const AAA_TEXT_CONTRAST = 7;
+
+/**
+ * Of `candidates`, the colour whose WORST contrast over every surface in `over`
+ * is highest — text laid over a gradient has to read at both ends, and text on
+ * a computed tint has to read on whatever the tint turned out to be.
+ *
+ * Returns the first candidate when none is better than another, so the caller's
+ * order is its preference order.
+ */
+export function readableOn(over: string | readonly string[], candidates: readonly string[]): string {
+  const surfaces = typeof over === 'string' ? [over] : over;
+  let best = candidates[0]!;
+  let bestScore = -1;
+  for (const candidate of candidates) {
+    const score = Math.min(...surfaces.map((surface) => contrastRatio(candidate, surface)));
+    if (score > bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/**
+ * `color` pulled toward black by `amount` (0..1), as `#rrggbb`; `null` if it
+ * does not parse.
+ *
+ * Scaling every channel by the same factor keeps their RATIO, so the hue and
+ * the saturation survive — this is why a darkened teal is still teal. It is
+ * exactly `mixColor(color, '#000000', amount)`, which is how two of the copies
+ * spelled it.
+ */
+export function darken(color: string, amount: number): string | null {
+  const c = parseRgba(color);
+  if (!c) return null;
+  const k = 1 - amount;
+  const hex = (v: number) =>
+    Math.round(Math.max(0, Math.min(255, v * k)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${hex(c.r)}${hex(c.g)}${hex(c.b)}`;
+}
+
+/**
+ * The lightest shade of `color` on which EVERY colour in `foreground` clears
+ * `ratio`: the colour itself when it already does, else pulled toward black in
+ * `1 / steps` increments until it does.
+ *
+ * `null` when `color` does not parse — the caller falls back to its own
+ * neutral surface rather than being handed a colour it did not ask for. Black
+ * clears any light foreground, so the walk always ends somewhere.
+ *
+ * **Darken the COLOUR, never walk its ramp.** A generated ramp re-derives every
+ * stop's lightness and chroma from the hue, so a near-black input comes back
+ * ten times lighter than it went in and a vivid one has a channel zeroed. This
+ * keeps what it was handed and only removes light from it.
+ */
+export function darkenUntilContrast(
+  color: string,
+  foreground: string | readonly string[],
+  ratio: number = AA_TEXT_CONTRAST,
+  steps = 20,
+): { color: string; amount: number } | null {
+  if (!parseRgba(color)) return null;
+  const fgs = typeof foreground === 'string' ? [foreground] : foreground;
+  for (let step = 0; step <= steps; step++) {
+    const amount = step / steps;
+    const shade = darken(color, amount) as string;
+    if (fgs.every((fg) => contrastRatio(shade, fg) >= ratio)) return { color: shade, amount };
+  }
+  return { color: '#000000', amount: 1 };
+}

package/src/styles/index.ts

@@ -6,4 +6,39 @@ export type { Breakpoint } from './breakpoints';
 export { Z_INDEX } from './z-index';
 export { web, native, ios, android, platform, select } from './platform';
 export { SUPPORTS_NATIVE_DRIVER } from './native-driver';
-export { contrastRatio, relativeLuminance } from './color-contrast';
+export {
+  contrastRatio,
+  relativeLuminance,
+  readableOn,
+  darken,
+  darkenUntilContrast,
+  AA_TEXT_CONTRAST,
+  AA_LARGE_TEXT_CONTRAST,
+  AAA_TEXT_CONTRAST,
+} from './color-contrast';
+export { webDataSet } from './web-data';
+export { clamp, clamp01 } from './clamp';
+export { mixColors, quietText, quietTextOver } from './color-contrast';
+export {
+  AA_GRAPHICAL,
+  AA_TEXT,
+  AA_TEXT_STRONG,
+  hairlineOn,
+  resolveSurfaceLevel,
+  SURFACE_FILL_CSS,
+  SURFACE_FILL_VAR,
+  SURFACE_LEVELS,
+  SurfaceLevelProvider,
+  surfaceFillOn,
+  surfaceFillVars,
+  surfaceTextOn,
+  useSurfaceFill,
+  useSurfaceLevel,
+  useSurfaceLevelValue,
+} from './surface-levels';
+export type {
+  SurfaceLevel,
+  SurfaceLevelPaint,
+  SurfaceLevelProviderProps,
+  SurfaceTextPaint,
+} from './surface-levels';

package/src/styles/interactive-web-css.ts

@@ -15,6 +15,17 @@
  * base declarations (layout, border, font), the transition list, WHICH property
  * hover changes, and the focus ring's offset.
  *
+ * It grew because it was not being used. Thirty-odd families called only
+ * `useInteractiveWebCss()` — the two-line adopter — and hand-wrote the sheet it
+ * was supposed to build, which is exactly why rings, hovers and disabled states
+ * drifted: three focus-ring mechanisms in one package, a `#FFFFFF` ring gap
+ * baked into a dark-mode component, and disabled opacity at 0.4, 0.5 and 0.6.
+ * The options below therefore cover what those callers actually needed — a
+ * hover fill, a pressed fill, a disabled block and a focus ring whose GAP comes
+ * from the surface — so that hand-writing one is a decision rather than the
+ * default. **This is THE way to build a raw-DOM or `dataSet`-hooked control's
+ * stylesheet in Bloom.**
+ *
  * TWO RULES THAT MUST SURVIVE ANY EDIT HERE:
  *
  * - **The keyboard focus ring is `:focus-visible`, never `:focus`.** An
@@ -34,6 +45,60 @@
 import { useEffect } from 'react';
 
 import { adoptStyleSheet } from './adopt-style-sheet';
+import { DISABLED_OPACITY } from './tokens';
+
+/**
+ * The custom property every Bloom focus ring reads its GAP colour from.
+ *
+ * Three ring mechanisms existed: the canonical `outline` + `outline-offset`, a
+ * two-step `box-shadow` whose gap was the literal `#FFFFFF`, and an inset
+ * shadow. The literal is the one that broke — `ring-offset-color` defaults to
+ * white in Tailwind and was never overridden, so in DARK mode a focused filter
+ * chip, filter text button, stepper value or slider thumb drew a 2px white halo
+ * against a near-black page. A gap is meant to be a hole in the ring, and a hole
+ * is the colour of whatever is behind it.
+ *
+ * So the gap is a variable, set inline from the surface the control sits on
+ * (`useRingOffsetStyle()` in `styles/surface-levels.ts`). The fallback below is
+ * only for a control that sets nothing.
+ */
+export const RING_OFFSET_VAR = '--bloom-ring-offset';
+
+/** What the gap falls back to when nothing sets {@link RING_OFFSET_VAR}. */
+export const RING_OFFSET_FALLBACK = '#FFFFFF';
+
+/** The two-step ring: a `gap`px hole in the surface colour, then a `width`px ring. */
+export interface FocusRingSpec {
+  /**
+   * `outline` is the canonical recipe — a real `outline` with `outline-offset`,
+   * which follows a rounded corner and never joins the paint. `ring` is the
+   * `box-shadow` form, for a control whose ring must sit on a CHILD element (a
+   * slider thumb, a checkbox glyph) where an outline on the focusable ancestor
+   * would draw round the wrong box.
+   */
+  mode?: 'outline' | 'ring';
+  /** The gap, in px, between the control's edge and the ring. */
+  offset?: number;
+  /** The ring's own thickness, in px. */
+  width?: number;
+}
+
+/**
+ * The `box-shadow` value of a `ring`-mode focus ring.
+ *
+ * `ringVar` is the full custom-property name the family already sets inline for
+ * its accent, e.g. `--bloom-stepper-ring`. Anything in `extra` is appended, for
+ * a control that also carries a resting shadow the ring must not erase.
+ */
+export function focusRingShadow(
+  ringVar: string,
+  { offset = 2, width = 2 }: FocusRingSpec = {},
+  extra?: string,
+): string {
+  const gap = `0 0 0 ${offset}px var(${RING_OFFSET_VAR}, ${RING_OFFSET_FALLBACK})`;
+  const ring = `0 0 0 ${offset + width}px var(${ringVar}, currentColor)`;
+  return extra ? `${gap}, ${ring}, ${extra}` : `${gap}, ${ring}`;
+}
 
 /**
  * The filter every interactive rule carries: a control that is disabled by
@@ -61,16 +126,32 @@ export interface InteractiveWebCssOptions {
    * `bloom-btn` yields `--bloom-btn-ring` and `--bloom-btn-press-scale`.
    */
   varPrefix: string;
+  /**
+   * `button` (the default) emits the `<button>` reset — `appearance`,
+   * `display: inline-flex`, `cursor`, `user-select`. It is right for a raw-DOM
+   * fork and WRONG for a react-native-web control: RNW lays a `View` out with
+   * `display: flex`, so `inline-flex` from a stylesheet silently changes how the
+   * control participates in its parent's layout. A `dataSet`-hooked caller
+   * passes `none` and keeps its geometry in the inline style, where RNW can see
+   * it on native too.
+   */
+  reset?: 'button' | 'none';
   /**
    * The family's own base declarations, appended after the shared reset — its
    * layout (`flex-direction`, `gap`, `padding`), border, font and anything else
    * that is not common to all three. A declaration here overrides the reset.
+   * Optional: a control whose geometry lives entirely in its inline style (every
+   * react-native-web one does, so native gets it too) has nothing to put here.
    */
-  base: string;
+  base?: string;
   /** Value of the base rule's `transition` shorthand. */
   transition: string;
-  /** The hover rule. */
-  hover: {
+  /**
+   * The hover rule. Optional: a react-native-web control gets `onHoverIn` in JS
+   * and paints hover through its inline style, so it has no hover rule to emit —
+   * and a CSS one would then be a second source of truth for the same state.
+   */
+  hover?: {
     /** Extra selector filter appended after {@link NOT_DISABLED}, e.g. `:not([data-active="true"])`. */
     filter?: string;
     /** Declarations the hover state sets. */
@@ -85,8 +166,33 @@ export interface InteractiveWebCssOptions {
    * depending on which selector happens to win.
    */
   pressDeclarations?: string;
-  /** `outline-offset` for the focus ring, in px. */
-  outlineOffset: number;
+  /**
+   * Whether to emit the `:active` press-scale rule. Defaults to true for the
+   * `button` reset and false for `none` — Bloom's controls change COLOUR on
+   * press, and the scale exists only for the three raw-DOM forks that shipped
+   * with it.
+   */
+  pressScale?: boolean;
+  /**
+   * `outline-offset` for the focus ring, in px — shorthand for `focus.offset`.
+   * Defaults to 2, the canonical gap.
+   */
+  outlineOffset?: number;
+  /**
+   * The focus ring, when the family needs the `ring` form or a thicker ring.
+   * Omitted, it is `{ mode: 'outline', offset: outlineOffset }` — the canonical
+   * recipe, unchanged.
+   */
+  focus?: FocusRingSpec;
+  /**
+   * The disabled block. Omitted, the control takes `cursor: default` and
+   * {@link DISABLED_OPACITY}.
+   *
+   * `opacity: null` opts a family OUT of the opacity convention — for a control
+   * that RECOLOURS when disabled (`Button` does, by token) and must not also
+   * fade, which would apply the dimming twice.
+   */
+  disabled?: { opacity?: number | null; declarations?: string };
   /** Rules appended verbatim, for a family-specific modifier class. */
   extraRules?: string;
 }
@@ -110,19 +216,22 @@ function block(declarations: string): string {
 export function interactiveWebCss({
   selector,
   varPrefix,
-  base,
+  reset = 'button',
+  base = '',
   transition,
   hover,
   pressDeclarations,
+  pressScale = reset === 'button',
   outlineOffset,
+  focus,
+  disabled,
   extraRules,
 }: InteractiveWebCssOptions): string {
   const c = selector;
   const interactive = `${c}${NOT_DISABLED}`;
-
-  return `
-${c} {
-  appearance: none;
+  const resetDeclarations =
+    reset === 'button'
+      ? `  appearance: none;
   -webkit-appearance: none;
   box-sizing: border-box;
   display: inline-flex;
@@ -132,23 +241,41 @@ ${c} {
   cursor: pointer;
   user-select: none;
   outline: none;
-${block(base)}
-  transition: ${transition};
+`
+      : `  cursor: pointer;
+  outline: none;
+`;
+  const ring: FocusRingSpec = { mode: 'outline', offset: outlineOffset ?? 2, width: 2, ...focus };
+  const focusDeclarations =
+    ring.mode === 'ring'
+      ? `box-shadow: ${focusRingShadow(`--${varPrefix}-ring`, ring)};`
+      : `outline: 2px solid var(--${varPrefix}-ring, currentColor);\n  outline-offset: ${ring.offset ?? 0}px;`;
+  const disabledOpacity = disabled?.opacity === undefined ? DISABLED_OPACITY : disabled.opacity;
+
+  const pressRule =
+    pressScale || pressDeclarations
+      ? `${interactive}:active {
+${pressScale ? `  transform: scale(var(--${varPrefix}-press-scale, 1));\n` : ''}${pressDeclarations ? `${block(pressDeclarations)}\n` : ''}}
+`
+      : '';
+
+  return `
+${c} {
+${resetDeclarations}${base.trim() ? `${block(base)}\n` : ''}  transition: ${transition};
 }
 ${c}:disabled,
 ${c}[aria-disabled="true"] {
   cursor: default;
-  opacity: 0.5;
-}
-${interactive}${hover.filter ?? ''}:hover {
+${disabledOpacity === null ? '' : `  opacity: ${disabledOpacity};\n`}${disabled?.declarations ? `${block(disabled.declarations)}\n` : ''}}
+${
+  hover
+    ? `${interactive}${hover.filter ?? ''}:hover {
 ${block(hover.declarations)}
 }
-${interactive}:active {
-  transform: scale(var(--${varPrefix}-press-scale, 1));
-${pressDeclarations ? `${block(pressDeclarations)}\n` : ''}}
-${c}:focus-visible {
-  outline: 2px solid var(--${varPrefix}-ring, currentColor);
-  outline-offset: ${outlineOffset}px;
+`
+    : ''
+}${pressRule}${c}:focus-visible {
+  ${focusDeclarations}
 }
 ${extraRules ? `${extraRules.trim()}\n` : ''}`;
 }

package/src/styles/panel-chrome.ts

@@ -0,0 +1,56 @@
+/**
+ * The FLOATING PANEL chrome — the edge Bloom's big surfaces wear: a hairline
+ * plus the soft three-part shadow that lifts a panel off the page background.
+ *
+ * It lives here because two surfaces wear the same thing and had it written
+ * twice: the `Sidebar`'s panel and the framed `ContentPanel`. A panel that only
+ * draws a border reads as a box; the shadow is what makes it a panel.
+ *
+ *   shadow   0 1px 0 (the seat), 0 1px 12px (the soft body), 0 0 1px (the edge
+ *            definition that keeps the hairline from disappearing on a
+ *            same-coloured background)
+ *   border   the CARD colour in light mode — a panel on a tinted page reads as
+ *            a lighter edge, not a grey line — and neutral-800 in dark
+ */
+import { useContext } from 'react';
+
+import { resolveButtonRamps } from '../button/shared';
+import { BloomThemeContext } from '../theme/BloomThemeProvider';
+import type { Theme } from '../theme/types';
+
+export const PANEL_SHADOW = {
+  light: '0 1px 0 0 rgba(0, 0, 0, 0.0196), 0 1px 12px 0 rgba(0, 0, 0, 0.0588), 0 0 1px 0 rgba(0, 0, 0, 0.3216)',
+  dark: '0 1px 0 0 rgba(0, 0, 0, 0.1), 0 1px 12px 0 rgba(0, 0, 0, 0.16), 0 0 1px 0 rgba(0, 0, 0, 0.42)',
+} as const;
+
+export interface PanelChrome {
+  /** The panel's own fill. */
+  surface: string;
+  /** Its 1px edge. */
+  border: string;
+  /** The `box-shadow` string (web and RN ≥ 0.76 both take it). */
+  shadow: string;
+}
+
+export function resolvePanelChrome(theme: Theme): PanelChrome {
+  const { neutral: n } = resolveButtonRamps(theme);
+  const dark = theme.isDark;
+  return {
+    surface: dark ? n[900] : n[100],
+    border: dark ? n[800] : theme.colors.card,
+    shadow: dark ? PANEL_SHADOW.dark : PANEL_SHADOW.light,
+  };
+}
+
+/**
+ * The chrome for the current theme, or `null` outside a `BloomThemeProvider`.
+ *
+ * Optional on purpose: `ContentPanel` draws its own surface and had never
+ * touched the theme, so a consumer (or a test) rendering one without the
+ * provider used to work. Making the shadow mandatory would have turned that
+ * into a thrown error at the moment the panel merely got prettier.
+ */
+export function useOptionalPanelChrome(): PanelChrome | null {
+  const ctx = useContext(BloomThemeContext);
+  return ctx ? resolvePanelChrome(ctx.theme) : null;
+}