@oxy.so/bloom 2.9.0 → 2.11.0

package/src/queue-panel/types.ts

@@ -0,0 +1,129 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** One track in the queue. Every string arrives pre-formatted by the app. */
+export interface QueueTrack {
+  /** Stable identity: rows are keyed by it, so a reorder keeps keyboard focus. */
+  id: string;
+  title: string;
+  /** "Ilse Marn, The Quiet Coast" — already joined. */
+  artists?: string;
+  /** Cover art: a URL, or an id the app's `ImageResolver` turns into one. */
+  cover?: string;
+  /** Draws the explicit badge before the artists. */
+  explicit?: boolean;
+  /** A trailing meta string: a duration ("3:45") or, in history, when it played ("2 hours ago"). */
+  meta?: string;
+}
+
+/** The two reorderable lists: what the listener added, and what follows from the playing context. */
+export type QueueSection = 'queue' | 'context';
+
+/** The two tabs of the panel. */
+export type QueuePanelTab = 'queue' | 'recent';
+
+/** `panel` — a rounded, bordered surface of `width` (web). `sheet` — flat, full width, for a bottom sheet (native). */
+export type QueuePanelVariant = 'panel' | 'sheet';
+
+/** Every string the panel draws or announces. Pass any subset to translate. */
+export interface QueuePanelLabels {
+  queueTab: string;
+  recentTab: string;
+  close: string;
+  nowPlaying: string;
+  nextInQueue: string;
+  /** Heading of the context list: `nextFrom("Night Drive")` → "Next from: Night Drive". */
+  nextFrom: (context: string) => string;
+  /** Heading of the context list when no context name is given. */
+  nextUp: string;
+  clearQueue: string;
+  /** Row name prefix: "Play Night Drive". */
+  play: string;
+  /** The row menu button: "More options for Night Drive". */
+  moreOptions: (title: string) => string;
+  /** The drag handle: "Reorder Night Drive". */
+  reorder: (title: string) => string;
+  /** The drag handle's hint. */
+  reorderHint: string;
+  moveUp: string;
+  moveDown: string;
+  remove: string;
+  /** Announced after a move. `position` is 1-based. */
+  moved: (title: string, position: number, total: number) => string;
+  emptyQueue: string;
+  emptyQueueHint: string;
+  emptyRecent: string;
+}
+
+export interface QueuePanelProps {
+  /** The track that is loaded. Omit to hide the section. */
+  nowPlaying?: QueueTrack | null;
+  /** Animates the now-playing bars. Default `true`. */
+  playing?: boolean;
+  /** "Next in queue": tracks the listener added. */
+  queue?: QueueTrack[];
+  /** "Next from": what follows from the playing album, playlist or radio. */
+  context?: QueueTrack[];
+  /** Name of the playing context, for the heading: "Night Drive". */
+  contextName?: string;
+  /** The "Recently played" tab's rows, newest first. */
+  recentlyPlayed?: QueueTrack[];
+
+  /** Controlled tab. */
+  tab?: QueuePanelTab;
+  /** Initial tab when uncontrolled. Default `queue`. */
+  defaultTab?: QueuePanelTab;
+  onTabChange?: (tab: QueuePanelTab) => void;
+
+  /**
+   * A row was dragged, moved by keyboard or moved from its menu. Indices are
+   * within `section`. The panel draws what it is given — apply the move with
+   * `moveQueueItem` and pass the new list back.
+   */
+  onReorder?: (section: QueueSection, from: number, to: number) => void;
+  /** A row's remove action. Omit to hide it. */
+  onRemove?: (section: QueueSection, index: number, track: QueueTrack) => void;
+  /** A row was pressed. `index` is within `section`; `now` is the now-playing row. */
+  onPlay?: (section: QueueSection | 'recent' | 'now', index: number, track: QueueTrack) => void;
+  /** "Clear queue" beside "Next in queue". Omit to hide it. */
+  onClearQueue?: () => void;
+  /** The header's close button. Omit to hide it. */
+  onClose?: () => void;
+
+  /** Default: `panel` on web, `sheet` on native. */
+  variant?: QueuePanelVariant;
+  /** Width of the `panel` variant. Default `360`. */
+  width?: number;
+  labels?: Partial<QueuePanelLabels>;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface RecentlyPlayedListProps {
+  items: QueueTrack[];
+  onPlay?: (index: number, track: QueueTrack) => void;
+  /** Id of the loaded track: its title turns accent and the now-playing bars show. */
+  currentId?: string;
+  /** Animates the bars on the current row. Default `true`. */
+  playing?: boolean;
+  labels?: Partial<Pick<QueuePanelLabels, 'play' | 'emptyRecent'>>;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface QueuePanelRowProps {
+  track: QueueTrack;
+  /** Called by pressing the row's main area. */
+  onPress?: () => void;
+  /** Accent title and now-playing bars. */
+  current?: boolean;
+  /** Animates the bars while `current`. Default `true`. */
+  playing?: boolean;
+  /** The name of the row's main area. Default "Play <title>". */
+  accessibilityLabel?: string;
+  /** Drawn at the trailing edge, after `meta`. */
+  trailing?: React.ReactNode;
+  /** Keeps the highlight and the revealed trailing controls, e.g. while the row's menu is open. */
+  highlighted?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/radio/Radio.tsx

@@ -5,10 +5,11 @@ import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
 import type { TypeScaleVariant } from '../typography';
 import { TYPE_SCALE } from '../typography/scale';
-import { FOCUS_RING_OFFSET_COLOR } from '../checkbox/shared';
-import { space } from '../styles/tokens';
+
+import { space, DISABLED_OPACITY } from '../styles/tokens';
+import { useRingOffsetStyle } from '../styles/surface-levels';
 import { resolveButtonRamps } from '../button/shared';
-import { interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
+import { focusRingShadow, interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { RadioIndicator } from '../radio-indicator';
 import { RadioCard } from './RadioCard';
@@ -77,7 +78,7 @@ ${ROW}:focus-visible {
   outline: none;
 }
 ${ROW}:focus-visible ${DOT} {
-  box-shadow: 0 0 0 2px ${FOCUS_RING_OFFSET_COLOR}, 0 0 0 4px var(--bloom-radio-ring, currentColor);
+  box-shadow: ${focusRingShadow('--bloom-radio-ring')};
 }`,
 });
 
@@ -98,6 +99,7 @@ const RadioComponent = function Radio<Value extends string = string>({
   testID,
 }: RadioProps<Value>) {
   const theme = useTheme();
+  const ringOffset = useRingOffsetStyle();
   useInteractiveWebCss(STYLE_ID, BLOOM_RADIO_CSS);
   const sizeConfig = SIZE_CONFIG[size];
   const { accent, neutral } = useMemo(() => resolveButtonRamps(theme), [theme]);
@@ -116,9 +118,10 @@ const RadioComponent = function Radio<Value extends string = string>({
     alignItems: 'flex-start',
     gap: LABEL_GAP,
     // `opacity-50` on the whole row.
-    opacity: disabled ? 0.5 : 1,
+    opacity: disabled ? DISABLED_OPACITY : 1,
     // The `:focus-visible` ring colour, read by the adopted sheet.
     '--bloom-radio-ring': color ?? accent[500],
+    ...ringOffset,
   };
 
   return (

package/src/radio/RadioCard.tsx

@@ -5,11 +5,13 @@ import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { mixColor, resolveButtonRamps } from '../button/shared';
-import { useInteractiveWebCss } from '../styles/interactive-web-css';
+import { focusRingShadow, useInteractiveWebCss } from '../styles/interactive-web-css';
+import { useRingOffsetStyle } from '../styles/surface-levels';
 import type { WebCssStyle } from '../styles/web-view-style';
-import { FOCUS_RING_OFFSET_COLOR, webDataSet } from '../checkbox/shared';
+import { webDataSet } from '../styles/web-data';
 import { RadioIndicator } from '../radio-indicator';
 import type { RadioCardProps } from './types';
+import { DISABLED_OPACITY } from '../styles/tokens';
 
 /**
  * `RadioCard` — the radio flavour of `CheckboxCard`: title and an optional
@@ -48,7 +50,7 @@ ${CARD}:focus-visible {
   outline: none;
 }
 ${CARD}:focus-visible ${DOT} {
-  box-shadow: 0 0 0 2px ${FOCUS_RING_OFFSET_COLOR}, 0 0 0 4px var(--bloom-radio-ring, currentColor);
+  box-shadow: ${focusRingShadow('--bloom-radio-ring')};
 }
 @media (prefers-reduced-motion: reduce) {
 ${CARD} {
@@ -69,6 +71,7 @@ const RadioCardComponent = function RadioCard<Value extends string = string>({
   testID,
 }: RadioCardProps<Value>) {
   const theme = useTheme();
+  const ringOffset = useRingOffsetStyle();
   useInteractiveWebCss(STYLE_ID, CARD_CSS);
   const { state: hovered, onIn: onHoverIn, onOut: onHoverOut } = useInteractionState();
   const { state: pressed, onIn: onPressIn, onOut: onPressOut } = useInteractionState();
@@ -108,8 +111,9 @@ const RadioCardComponent = function RadioCard<Value extends string = string>({
     paddingTop: 12,
     paddingBottom: 12,
     backgroundColor: highlighted ? paint.backgroundHover : paint.background,
-    opacity: disabled ? 0.5 : 1,
+    opacity: disabled ? DISABLED_OPACITY : 1,
     '--bloom-radio-ring': paint.ring,
+    ...ringOffset,
     ...(IS_WEB
       ? {
           transitionProperty: 'background-color, border-color, color',

package/src/rating/RatingBar.tsx

@@ -1,19 +1,25 @@
-import React, { memo, useMemo } from 'react';
+import React, { memo } from 'react';
 import { View } from 'react-native';
 
-import { resolveButtonRamps } from '../button/shared';
+import { Meter } from '../stat-bar';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
 import type { RatingBarProps } from './types';
 
 /**
- * One row of a rating breakdown: label, a 4px bar, and an optional value.
+ * One row of a rating breakdown: label, a 4px `Meter`, and an optional value.
  *
  *   label     body-regular, text-primary
- *   track     4 tall, radius 2, neutral-200 (dark neutral-800)
- *   fill      text-primary, `value / max` of the track
+ *   track     4 tall, radius 2, neutral-200 (dark neutral-700)
+ *   fill      the accent, `value / max` of the track
  *   display   body-semibold, text-primary, tabular, min width 28, right-aligned
  *
+ * The fill was text-primary — a near-black bar — until the meters were folded
+ * onto one primitive. A rating breakdown is NOT a chart: the rows do not encode
+ * different categories by colour (they are all "how good is this, out of 5"),
+ * so a chart hue would claim a distinction that is not there. It is a
+ * measurement, and the accent is the theme's colour for one.
+ *
  * Without `labelWidth` the label flexes and the bar is 96 wide, so a column of
  * categories lines up on the right; with it the bar flexes, for a 5→1
  * distribution. The bar is a `progressbar` with flat `aria-value*` (and
@@ -24,10 +30,7 @@ const BAR_WIDTH = 96;
 
 function RatingBarComponent({ label, value, max = 5, display, labelWidth, style, testID }: RatingBarProps) {
   const theme = useTheme();
-  const { neutral } = useMemo(() => resolveButtonRamps(theme), [theme]);
   const safeMax = max > 0 ? max : 1;
-  const clamped = Math.min(safeMax, Math.max(0, value));
-  const fraction = clamped / safeMax;
 
   return (
     <View
@@ -46,29 +49,16 @@ function RatingBarComponent({ label, value, max = 5, display, labelWidth, style,
       >
         {label}
       </Text>
-      <View
-        accessibilityRole="progressbar"
+      <Meter
+        value={value}
+        max={safeMax}
+        height={4}
         accessibilityLabel={label}
-        aria-valuemin={0}
-        aria-valuemax={safeMax}
-        aria-valuenow={clamped}
-        aria-valuetext={display}
+        valueText={display}
         testID={testID ? `${testID}-bar` : undefined}
-        style={[
-          {
-            height: 4,
-            borderRadius: 2,
-            overflow: 'hidden',
-            backgroundColor: theme.isDark ? neutral[800] : neutral[200],
-          },
-          labelWidth === undefined ? { width: BAR_WIDTH } : { flex: 1, minWidth: 0 },
-        ]}
-      >
-        <View
-          testID={testID ? `${testID}-fill` : undefined}
-          style={{ width: `${fraction * 100}%`, height: '100%', backgroundColor: theme.colors.text }}
-        />
-      </View>
+        fillTestID={testID ? `${testID}-fill` : undefined}
+        style={labelWidth === undefined ? { width: BAR_WIDTH } : { flex: 1, minWidth: 0 }}
+      />
       {display != null && (
         <Text
           variant="body-semibold"

package/src/search/Search.tsx

@@ -4,7 +4,7 @@ import { Platform, type TextInput, View } from 'react-native';
 import { useTheme } from '../theme/use-theme';
 import { atoms as a } from '../styles';
 import { borderRadius } from '../styles/tokens';
-import { Button } from '../button';
+import { GlyphButton } from '../button';
 import { TextField, TextFieldIcon, TextFieldInput, type TextFieldInputProps } from '../text-field';
 import { RiSearchLine as MagnifyingGlassIcon } from '../icons/remix/RiSearchLine';
 import { RiCloseLine as X } from '../icons/remix/RiCloseLine';
@@ -55,15 +55,16 @@ export const Search = forwardRef<TextInput, SearchProps>(
               a.pr_sm,
               { left: 'auto' },
             ]}>
-            <Button
+            {/* Neutral and transparent. `variant="ghost"` painted an accent
+                wash inside the field, which read as a state the field was not
+                in. */}
+            <GlyphButton
               testID="searchTextInputClearBtn"
               onPress={onClearText}
               accessibilityLabel="Clear search query"
-              hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
-              variant="ghost"
-              size="small"
-              icon={<X fill={theme.colors.textSecondary} size="xs" />}
-              style={{ padding: 4, minHeight: 0 }}
+              size={28}
+              icon={X}
+              glyphSize={16}
             />
           </View>
         )}

package/src/segmented-control/SegmentedControl.tsx

@@ -23,7 +23,7 @@ import { Text } from '../typography';
 import type { TypeScaleFamily } from '../typography';
 import type { Theme } from '../theme/types';
 import { useInteractionState } from '../hooks/use-interaction-state';
-import { borderRadius } from '../styles/tokens';
+import { borderRadius, DISABLED_OPACITY } from '../styles/tokens';
 import { NOT_DISABLED, interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { mixColor, resolveButtonRamps } from '../button/shared';
@@ -346,7 +346,7 @@ export function SegmentedControlItem({
     height: geometry.height,
     paddingHorizontal: geometry.paddingHorizontal,
     borderRadius: borderRadius.full,
-    opacity: disabled ? 0.5 : 1,
+    opacity: disabled ? DISABLED_OPACITY : 1,
     '--bloom-segmented-ring': ctx.palette.ring,
   };
 

package/src/settings-list/SettingsList.tsx

@@ -2,10 +2,12 @@ import React, { memo } from 'react';
 import { View, Text, Pressable, StyleSheet } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
+import { useSurfaceFill } from '../styles/surface-levels';
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { Card } from '../card';
 import { Divider } from '../divider';
 import { RiArrowRightSLine as ChevronRightIcon } from '../icons/remix/RiArrowRightSLine';
+import { SETTINGS_LIST_GROUP_TEST_ID, settingsGroupSurface } from './surface';
 import type {
   SettingsListItemProps,
   SettingsListGroupProps,
@@ -132,9 +134,21 @@ export const SettingsListGroup = memo<SettingsListGroupProps>(function SettingsL
   footer,
   children,
   style,
-  variant = 'plain',
+  variant,
 }) {
   const theme = useTheme();
+  // Which surface the group paints is a question about its PARENT, and a group
+  // cannot see its parent — so it asks the surrounding surface what colour it
+  // actually painted (`styles/surface-levels.ts`) and resolves off THAT. On the
+  // page that is `colors.card`, exactly what these groups have always painted;
+  // on anything else it is one ladder step off the real fill, which is the only
+  // answer that cannot land on its own parent. `./surface.ts` carries the rule,
+  // the measurements behind it, and why the fill rather than the rung.
+  //
+  // It is a DEFAULT, not a rule: an explicit `variant` wins, for a container
+  // Bloom does not paint and therefore cannot publish a fill for.
+  const ambientFill = useSurfaceFill();
+  const backgroundColor = settingsGroupSurface(theme, ambientFill, variant);
   const filteredChildren = React.Children.toArray(children).filter(Boolean);
 
   return (
@@ -152,7 +166,20 @@ export const SettingsListGroup = memo<SettingsListGroupProps>(function SettingsL
         the title/search). A self-margin here double-inset grouped rows on every
         screen that also applies that padding.
       */}
-      <Card variant={variant} radius="radius-16">
+      {/*
+        The surface is passed as the resolved COLOUR, not as a variant: above
+        the page it is a step off the container's own fill, which is not one of
+        `Card`'s two named surfaces. `variant` still rides along so the card's
+        other axes keep meaning what the caller asked for, and the two can never
+        disagree — `settingsGroupSurface` resolves an explicit variant to that
+        variant's own colour.
+      */}
+      <Card
+        variant={variant ?? 'plain'}
+        radius="radius-16"
+        style={{ backgroundColor }}
+        testID={SETTINGS_LIST_GROUP_TEST_ID}
+      >
         {filteredChildren.map((child, index) => (
           <React.Fragment key={index}>
             {child}

package/src/settings-list/surface.ts

@@ -0,0 +1,112 @@
+/**
+ * Which surface a `SettingsListGroup` paints, given the colour actually behind
+ * it. Pure, so the rule can be walked over every preset x mode without rendering
+ * anything: `__tests__/surface-level-adoption.test.ts` does that (it is where
+ * the families that resolve their own surface are measured against the ladder),
+ * and `__tests__/SettingsListGroupSurface.test.tsx` ties the rendered component
+ * to it in both modes.
+ *
+ * The question a group has to answer is about its PARENT, and a group cannot
+ * see its parent. It used to be told, per call site, by a `variant` prop: one
+ * app repeated it at ~75 of them, and a screen that forgot rendered a `card`
+ * group on a `card` panel — present, correct, invisible.
+ *
+ * ## The rule
+ *
+ * The group is a surface ON another surface, so it takes the surface ladder's
+ * own step off the fill the container published (`styles/surface-levels.ts`),
+ * with ONE named exception:
+ *
+ *   on the page   `theme.colors.background` behind it -> `theme.colors.card`
+ *   anywhere else                                     -> `surfaceFillOn(fill)`
+ *
+ * ### Why the page is a special case rather than another step
+ *
+ * Because the palette already has a token for this exact pair, and it is a
+ * stronger answer than the ladder's in dark mode. Measured over all 64 presets:
+ *
+ *   light   `card` on the page  1.101-1.110   the ladder's step  1.101-1.110  (identical:
+ *                                                                 rung 1 IS `card` in light)
+ *   dark    `card` on the page  1.552-1.576   the ladder's step  1.226-1.241
+ *
+ * So in light the two answers coincide and the branch is invisible; in dark,
+ * taking the step would flatten every settings screen in the fleet against its
+ * page for no gain. `theme.colors.card` means "the colour a card paints on the
+ * page", and on the page that is what a group has always painted. This is the
+ * one surface pair the palette has an opinion about — off the page there is no
+ * "card on a panel" token, and the step is the only honest answer.
+ *
+ * ### Why the FILL and not the rung
+ *
+ * The first version of this read `useSurfaceLevelValue() === 0`, which is the
+ * same answer for every container Bloom currently ships — and wrong the moment
+ * one publishes a rung that is not its colour. `ContentPanel` does: repainted
+ * with `surfaceColor={colors.background}` it still publishes level 1, so the
+ * rung says "you are on a card" while the panel is painting the page. Asking
+ * the fill gets `colors.card` there, which is right; asking the rung got
+ * `backgroundSecondary`, which measures 1.121-1.132 against that page in dark.
+ *
+ * ### Why a step and not `backgroundSecondary`
+ *
+ * `backgroundSecondary` is calibrated against `card`, so it works on a
+ * `ContentPanel` (dark 1.378-1.404) and nowhere else. On the menu/popover
+ * surface `FloatingPanel` and `QueuePanel` publish, in DARK, it measures
+ * **1.086-1.106 — failing the ladder's 1.1 just-noticeable floor on 52 of the
+ * 64 presets** and scraping over it on the other 12: the disappearance this
+ * whole design exists to prevent, reappearing one container over. The ladder's
+ * step measures 1.296-1.312 there, on all 64. In LIGHT both clear it
+ * comfortably (1.221-1.230 vs 1.148-1.152), which is why a suite pinned to one
+ * mode cannot see any of this. `surface-level-adoption.test.ts` pins the failing
+ * presets as a named set.
+ *
+ * ### Why `surfaceFillOn` and not `useSurfaceLevel(1)`
+ *
+ * `useSurfaceLevel(1)` CLAMPS at rung 3, so a group inside a rung-3 container
+ * would be handed rung 3 — its parent's own colour, 1.000:1. A step that always
+ * steps cannot do that, and "never lands on my parent" is the one property this
+ * component must not lose.
+ */
+import { surfaceFillOn } from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+import type { SettingsListGroupVariant } from './types';
+
+/**
+ * The `testID` on the group's card.
+ *
+ * The group's fill is the whole point of this component and it is invisible to a
+ * structural assertion, so a test has to read the style off the exact node that
+ * carries it. Without a handle, a suite identifies it by elimination — "the one
+ * background that is not the container's" — which degenerates silently the day a
+ * container paints through a `className` instead of an inline style, and then
+ * measures the wrong node while staying green.
+ */
+export const SETTINGS_LIST_GROUP_TEST_ID = 'settings-list-group';
+
+/**
+ * The colour the group's card paints.
+ *
+ * `variant` is the explicit override and wins in both directions — it names one
+ * of `Card`'s two surfaces, for a container Bloom does not paint and therefore
+ * cannot publish a fill for.
+ *
+ * @param ambientFill what `useSurfaceFill()` reports: the colour the surrounding
+ *   surface actually painted.
+ */
+export function settingsGroupSurface(
+  theme: Theme,
+  ambientFill: string,
+  variant?: SettingsListGroupVariant,
+): string {
+  if (variant === 'filled') return theme.colors.backgroundSecondary;
+  if (variant === 'plain') return theme.colors.card;
+  // A string equality, and deliberately: every Bloom surface publishes a colour
+  // read off the SAME theme object — level 0 resolves to `colors.background`,
+  // `Dialog` and the sheet shell publish it verbatim, a panel repainted as the
+  // page publishes it through `surfaceColor` — so the two are identical by
+  // construction, not by luck. A consumer publishing an equal-but-differently-
+  // spelled colour falls through to the step, which is a legible surface on the
+  // page too — just not the one the palette names. Wrong-but-legible, never
+  // invisible, which is the direction this failure has to fall.
+  if (ambientFill === theme.colors.background) return theme.colors.card;
+  return surfaceFillOn(theme, ambientFill);
+}

package/src/settings-list/types.ts

@@ -40,10 +40,27 @@ export interface SettingsListGroupProps {
   style?: StyleProp<ViewStyle>;
   /**
    * The surface the group's card paints, named after `Card`'s own variants.
-   * `plain` (default) is the `card` colour, which reads on a page painted in
-   * `background`. `filled` is `backgroundSecondary`, for a group that sits on a
-   * surface already painted in `card` — a `ContentPanel`, a Dialog body — where a
-   * `plain` group would vanish into its parent.
+   * `plain` is the `card` colour, which reads as a raised card on a page painted
+   * in `background`; `filled` is `backgroundSecondary`.
+   *
+   * UNSET IS THE NORMAL CASE, and it is not one of these two. The group asks the
+   * surrounding surface what colour it actually painted
+   * (`styles/surface-levels.ts` `useSurfaceFill()`) and resolves off that: on the
+   * page, `card`; on anything else, one ladder step off the real fill — a step
+   * that cannot land on its own parent, whether that parent is a `ContentPanel`,
+   * a menu or a container Bloom has never heard of. `./surface.ts` carries the
+   * rule and the measurements behind it.
+   *
+   * Passing it per call site is what a whole app ends up repeating — and
+   * forgetting once renders a group invisible, which is exactly the kind of
+   * mistake a default can make impossible.
+   *
+   * Pass it only for a surface Bloom does not paint and so cannot publish a fill
+   * for — your own coloured section — where it always wins over the ambient one.
+   * If that container is yours and holds more than a settings list, publishing
+   * the surface once is better than annotating everything inside it:
+   * `<SurfaceLevelProvider level={1} fill={myColour}>` from
+   * `@oxy.so/bloom/styles`.
    */
   variant?: SettingsListGroupVariant;
 }

package/src/settings-modal/SettingsFields.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useRef, useState } from 'react';
 import { Platform, Pressable, StyleSheet, View, type ViewStyle } from 'react-native';
 
 import { borderRadius } from '../styles/tokens';
+import { webDataSet } from '../styles/web-data';
 import { Calendar } from '../date-picker';
 import { RiCalendarLine } from '../icons/remix';
 import { Popover, PopoverContent, PopoverTrigger } from '../popover';
@@ -9,7 +10,7 @@ import { TextField, TextFieldIcon, TextFieldInput } from '../text-field';
 import { Text } from '../typography';
 import { useSettingsPalette, useSettingsSavedToast } from './context';
 import type { SettingsDateFieldProps, SettingsTextFieldProps } from './types';
-import { useSettingsWebCss, webData } from './web-css';
+import { useSettingsWebCss } from './web-css';
 
 /**
  * The Profile page's editable controls.
@@ -121,7 +122,7 @@ export function SettingsDateField({
         <Pressable
           role="button"
           accessibilityLabel={`${label}, ${text}`}
-          {...webData({ bloomSettingsPress: '' })}
+          {...webDataSet({ bloomSettingsPress: '' })}
           onHoverIn={() => setHovered(true)}
           onHoverOut={() => setHovered(false)}
           testID={testID}

package/src/settings-modal/SettingsModal.tsx

@@ -30,6 +30,7 @@ import { RiArrowLeftSLine, RiArrowRightSLine, RiCheckboxCircleFill, RiCloseLine
 import { VerticalFade } from './SettingsArt';
 import { Backdrop, OverlayRoot } from '../overlay';
 import type { WebCssStyle } from '../styles/web-view-style';
+import { webDataSet } from '../styles/web-data';
 import { Text } from '../typography';
 import {
   SettingsModalContext,
@@ -40,7 +41,7 @@ import {
 import { ModalPortal } from './modal-portal';
 import type { SettingsPalette } from './palette';
 import type { SettingsModalProps, SettingsNavGroup, SettingsNavItem } from './types';
-import { IS_WEB, useSettingsWebCss, webData } from './web-css';
+import { IS_WEB, useSettingsWebCss } from './web-css';
 
 /**
  * A settings modal.
@@ -366,7 +367,7 @@ export function SettingsModal({
                   aria-modal
                   aria-label={labels?.dialog ?? 'Settings'}
                   testID={testID}
-                  {...webData({ bloomSettingsDialog: '' })}
+                  {...webDataSet({ bloomSettingsDialog: '' })}
                   style={[
                     styles.panel,
                     layout === 'compact'
@@ -593,7 +594,7 @@ function RailRow({
       accessibilityState={{ selected, disabled: item.disabled }}
       aria-disabled={item.disabled}
       {...(IS_WEB ? { 'aria-current': selected ? 'page' : undefined } : null)}
-      {...webData({ bloomSettingsPress: '' })}
+      {...webDataSet({ bloomSettingsPress: '' })}
       disabled={item.disabled}
       onPress={onPress}
       onHoverIn={() => setHovered(true)}
@@ -650,7 +651,7 @@ function SettingsCloseButton({
     <Pressable
       role="button"
       accessibilityLabel={label}
-      {...webData({ bloomSettingsPress: '' })}
+      {...webDataSet({ bloomSettingsPress: '' })}
       onPress={onPress}
       onHoverIn={() => setHovered(true)}
       onHoverOut={() => setHovered(false)}
@@ -695,7 +696,7 @@ function CompactHeader({
         <Pressable
           role="button"
           accessibilityLabel={backLabel}
-          {...webData({ bloomSettingsPress: '' })}
+          {...webDataSet({ bloomSettingsPress: '' })}
           onPress={onBack}
           hitSlop={8}
           testID={testID ? `${testID}-back` : undefined}

package/src/settings-modal/SettingsStorage.tsx

@@ -30,6 +30,7 @@ import {
 import { Pagination } from '../pagination';
 import { Select, SelectContent, SelectIcon, SelectItem, SelectItemIndicator, SelectItemText, SelectTrigger, SelectValue } from '../select';
 import { borderRadius } from '../styles/tokens';
+import { webDataSet } from '../styles/web-data';
 import { TextField, TextFieldIcon, TextFieldInput } from '../text-field';
 import { Tooltip, TooltipTextBubble, TooltipTrigger } from '../tooltip';
 import { Text } from '../typography';
@@ -42,7 +43,7 @@ import type {
   SettingsStoragePageProps,
   SettingsStoredFile,
 } from './types';
-import { useSettingsWebCss, webData } from './web-css';
+import { useSettingsWebCss } from './web-css';
 
 /**
  * The Storage page.
@@ -110,7 +111,7 @@ function SortableHeader({
     <Pressable
       role="button"
       accessibilityLabel={`Sort by ${label}`}
-      {...webData({ bloomSettingsPress: '', ringOffset: '' })}
+      {...webDataSet({ bloomSettingsPress: '', ringOffset: '' })}
       onPress={() => onSort(sortKey)}
       style={styles.sortable}
     >
@@ -180,7 +181,7 @@ function RowMoreMenu({
             accessibilityLabel={label}
             aria-expanded={open}
             accessibilityState={{ expanded: open }}
-            {...webData({ bloomSettingsPress: '', ringOffset: '' })}
+            {...webDataSet({ bloomSettingsPress: '', ringOffset: '' })}
             onHoverIn={() => setHovered(true)}
             onHoverOut={() => setHovered(false)}
             style={[