@oxy.so/bloom 2.10.0 → 2.11.0

package/src/queue-panel/QueueIconButton.tsx

@@ -1,76 +1,60 @@
 import React, { forwardRef, useMemo } from 'react';
-import { Pressable, View, type PressableProps } from 'react-native';
+import type { GestureResponderEvent, View } from 'react-native';
 
-import { webDataSet } from '../checkbox/shared';
-import { useInteractionState } from '../hooks/use-interaction-state';
+import { GlyphButton } from '../button';
+import type { ButtonIconComponent } from '../button';
+import type { WebAriaProps } from '../styles/styled-primitives';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
 import { resolveQueuePanelPaint } from './shared';
 
-type Glyph = React.ComponentType<{ width?: number; height?: number; fill?: string }>;
-
-export interface QueueIconButtonProps extends Omit<PressableProps, 'children' | 'style'> {
-  icon: Glyph;
+export interface QueueIconButtonProps {
+  icon: ButtonIconComponent;
   accessibilityLabel: string;
   /** Diameter. Default `32`; the glyph is half of it. */
   size?: number;
+  onPress?: (event: GestureResponderEvent) => void;
+  disabled?: boolean;
   style?: WebCssStyle;
+  testID?: string;
+  /** Set by a menu/popover trigger composing onto this with `asChild`. */
+  'aria-expanded'?: boolean;
+  'aria-haspopup'?: WebAriaProps['aria-haspopup'];
 }
 
 /**
  * A quiet round glyph button: no fill at rest, a neutral wash one step above
  * the row highlight under the pointer or finger, glyph in the secondary text
- * colour turning primary. Colour change only. Props beyond its own pass
- * through to the `Pressable`, which is what lets a menu trigger compose onto
- * it with `asChild`.
+ * colour turning primary. Colour change only.
+ *
+ * `button/GlyphButton` with this family's palette and its 0.5 glyph ratio (the
+ * lowest of the five that shared its shape, hence the explicit `glyphSize`).
+ * The trigger props a menu composes onto it with `asChild` — `onPress`,
+ * `aria-expanded`, `aria-haspopup`, the name — are NAMED here, because a
+ * component that destructures a known prop list drops whatever it does not.
  */
 export const QueueIconButton = forwardRef<View, QueueIconButtonProps>(function QueueIconButton(
-  { icon: Icon, accessibilityLabel, size = 32, style, onHoverIn, onHoverOut, onPressIn, onPressOut, ...rest },
+  { icon, accessibilityLabel, size = 32, style, testID, ...rest },
   ref,
 ) {
   const theme = useTheme();
   const paint = useMemo(() => resolveQueuePanelPaint(theme), [theme]);
-  const hover = useInteractionState();
-  const press = useInteractionState();
-  const active = !rest.disabled && (hover.state || press.state);
-  const glyph = Math.round(size / 2);
-  const buttonStyle: WebCssStyle = {
-    width: size,
-    height: size,
-    borderRadius: size / 2,
-    alignItems: 'center',
-    justifyContent: 'center',
-    backgroundColor: active ? paint.buttonHover : 'transparent',
-    '--bloom-queue-ring': paint.ring,
-    ...style,
-  };
 
   return (
-    <Pressable
+    <GlyphButton
       ref={ref}
-      {...webDataSet({ bloomQueueFocusable: '' })}
-      role="button"
-      accessibilityLabel={accessibilityLabel}
       {...rest}
-      onHoverIn={(e) => {
-        hover.onIn();
-        onHoverIn?.(e);
-      }}
-      onHoverOut={(e) => {
-        hover.onOut();
-        onHoverOut?.(e);
-      }}
-      onPressIn={(e) => {
-        press.onIn();
-        onPressIn?.(e);
-      }}
-      onPressOut={(e) => {
-        press.onOut();
-        onPressOut?.(e);
-      }}
-      style={buttonStyle}
-    >
-      <Icon width={glyph} height={glyph} fill={active ? paint.text : paint.textSecondary} />
-    </Pressable>
+      icon={icon}
+      accessibilityLabel={accessibilityLabel}
+      size={size}
+      glyphSize={Math.round(size / 2)}
+      color={paint.textSecondary}
+      hoverColor={paint.text}
+      fill="transparent"
+      hoverFill={paint.buttonHover}
+      ring={paint.ring}
+      style={style}
+      testID={testID}
+    />
   );
 });

package/src/queue-panel/QueuePanel.tsx

@@ -1,6 +1,7 @@
 import React, { memo, useCallback, useMemo, useState } from 'react';
 import { AccessibilityInfo, ScrollView, View } from 'react-native';
 
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import { Button } from '../button';
 import { RiCloseLine } from '../icons/remix/RiCloseLine';
 import { RiPlayListAddLine } from '../icons/remix/RiPlayListAddLine';
@@ -116,6 +117,10 @@ function QueuePanelComponent({
   const empty = !nowPlaying && queue.length === 0 && context.length === 0;
 
   return (
+    // The panel is a surface: children step off IT, not off the page. A tab
+    // strip inside used to paint its rail `neutral-800` — the panel's own fill
+    // (`styles/surface-levels.ts`).
+    <SurfaceLevelProvider level={isPanel ? 1 : 0}>
     <View
       testID={testID}
       style={[
@@ -273,6 +278,7 @@ function QueuePanelComponent({
         </View>
       ) : null}
     </View>
+    </SurfaceLevelProvider>
   );
 }
 

package/src/queue-panel/QueuePanelRow.tsx

@@ -1,14 +1,15 @@
 import React, { memo, useEffect, useMemo } from 'react';
 import { Image, Pressable, View } from 'react-native';
 
-import { webDataSet } from '../checkbox/shared';
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { RiMusic2Line } from '../icons/remix/RiMusic2Line';
 import { useImageResolver } from '../image-resolver/context';
+import { isImageUrl } from '../image-resolver/is-image-url';
 import { ExplicitBadge } from '../media-controls/ExplicitBadge';
 import { NowPlayingIndicator } from '../media-controls/NowPlayingIndicator';
 import { adoptStyleSheet } from '../styles/adopt-style-sheet';
 import type { WebCssStyle } from '../styles/web-view-style';
+import { webDataSet } from '../styles/web-data';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
 import {
@@ -17,7 +18,6 @@ import {
   QUEUE_PANEL_CSS,
   QUEUE_PANEL_STYLE_ID,
   QUEUE_ROW_HEIGHT,
-  isImageUrl,
   resolveQueuePanelPaint,
 } from './shared';
 import type { QueuePanelRowProps } from './types';

package/src/queue-panel/QueueReorderList.tsx

@@ -1,4 +1,5 @@
 import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { dragShift, dragTarget } from '../hooks/list-reorder';
 import {
   PanResponder,
   View,
@@ -6,7 +7,6 @@ import {
   type PanResponderGestureState,
 } from 'react-native';
 
-import { webDataSet } from '../checkbox/shared';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -21,14 +21,13 @@ import { RiDeleteBinLine } from '../icons/remix/RiDeleteBinLine';
 import { RiDraggable } from '../icons/remix/RiDraggable';
 import { RiMoreFill } from '../icons/remix/RiMoreFill';
 import type { WebCssStyle } from '../styles/web-view-style';
+import { webDataSet } from '../styles/web-data';
 import { useTheme } from '../theme/use-theme';
 import { QueueIconButton } from './QueueIconButton';
 import { QueuePanelRow } from './QueuePanelRow';
 import {
   IS_WEB,
   QUEUE_ROW_HEIGHT,
-  queueDragShift,
-  queueDragTarget,
   resolveQueuePanelPaint,
   type QueuePanelPaint,
 } from './shared';
@@ -155,7 +154,7 @@ function QueueReorderRow({
     [move, index, canUp, canDown],
   );
 
-  const offset = drag ? (dragging ? drag.dy : queueDragShift(index, drag.from, target, QUEUE_ROW_HEIGHT)) : 0;
+  const offset = drag ? (dragging ? drag.dy : dragShift(index, drag.from, target, QUEUE_ROW_HEIGHT)) : 0;
 
   const liftStyle: WebCssStyle = {
     transform: [{ translateY: offset }],
@@ -282,7 +281,7 @@ function QueueReorderListComponent({
   const paint = useMemo(() => resolveQueuePanelPaint(theme), [theme]);
   const [drag, setDrag] = useState<DragState | null>(null);
   const count = tracks.length;
-  const target = drag ? queueDragTarget(drag.from, drag.dy, QUEUE_ROW_HEIGHT, count) : -1;
+  const target = drag ? dragTarget(drag.from, drag.dy, QUEUE_ROW_HEIGHT, count) : -1;
 
   const handles = useRef(new Map<string, View>());
   const pendingFocus = useRef<string | null>(null);
@@ -340,7 +339,7 @@ function QueueReorderListComponent({
       setDrag(null);
       onDragActiveChange?.(false);
       if (!commit || !current) return;
-      const to = queueDragTarget(current.from, current.dy, QUEUE_ROW_HEIGHT, tracksRef.current.length);
+      const to = dragTarget(current.from, current.dy, QUEUE_ROW_HEIGHT, tracksRef.current.length);
       if (to !== current.from) {
         pendingFocus.current = null;
         const track = tracksRef.current[current.from];

package/src/queue-panel/shared.ts

@@ -2,6 +2,7 @@ import { Platform } from 'react-native';
 
 import { resolveButtonRamps } from '../button/shared';
 import { resolveMenuPalette } from '../floating/menu-palette';
+import { dragShift, dragTarget, moveItem } from '../hooks/list-reorder';
 import type { Theme } from '../theme/types';
 import type { QueuePanelLabels } from './types';
 
@@ -33,51 +34,15 @@ export const DEFAULT_QUEUE_PANEL_LABELS: QueuePanelLabels = {
   emptyRecent: 'Nothing played yet',
 };
 
-function clampIndex(index: number, count: number): number {
-  if (count <= 0) return 0;
-  return Math.min(count - 1, Math.max(0, Math.round(index)));
-}
-
-/**
- * `list` with the item at `from` moved to `to` (both clamped into range). Always
- * a new array; an out-of-range or no-op move returns an unchanged copy.
- */
-export function moveQueueItem<T>(list: readonly T[], from: number, to: number): T[] {
-  const next = list.slice();
-  if (list.length === 0 || from < 0 || from >= list.length) return next;
-  const target = clampIndex(to, list.length);
-  if (target === from) return next;
-  const [item] = next.splice(from, 1);
-  next.splice(target, 0, item as T);
-  return next;
-}
+/** @deprecated Use `moveItem` from `@oxy.so/bloom/hooks`; this is a re-export of it. */
+export const moveQueueItem = moveItem;
 
-/** The index a row dragged `dy` px from `from` lands on: nearest whole row, clamped. */
-export function queueDragTarget(from: number, dy: number, rowHeight: number, count: number): number {
-  if (count <= 0 || rowHeight <= 0) return 0;
-  return clampIndex(from + dy / rowHeight, count);
-}
+/** @deprecated Use `dragTarget` from `@oxy.so/bloom/hooks`; this is a re-export of it. */
+export const queueDragTarget = dragTarget;
 
-/**
- * How far a row that is NOT being dragged slides to make room, while the row at
- * `from` hovers over `target`: rows between the two move one row towards `from`.
- */
-export function queueDragShift(index: number, from: number, target: number, rowHeight: number): number {
-  if (index === from) return 0;
-  if (from < target && index > from && index <= target) return -rowHeight;
-  if (target < from && index >= target && index < from) return rowHeight;
-  return 0;
-}
+/** @deprecated Use `dragShift` from `@oxy.so/bloom/hooks`; this is a re-export of it. */
+export const queueDragShift = dragShift;
 
-export function isImageUrl(value: string): boolean {
-  return (
-    value.startsWith('http://') ||
-    value.startsWith('https://') ||
-    value.startsWith('data:') ||
-    value.startsWith('blob:') ||
-    value.startsWith('file:')
-  );
-}
 
 export interface QueuePanelPaint {
   surface: 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}