@oxy.so/bloom 2.10.0 → 2.12.0

package/src/chip/Chip.tsx

@@ -1,4 +1,4 @@
-import React, { memo, useMemo } from 'react';
+import React, { forwardRef, memo, useMemo } from 'react';
 import {
   View,
   Platform,
@@ -9,36 +9,26 @@ import {
 
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography/Typography';
-import { TYPE_SCALE, type TypeScaleVariant } from '../typography/scale';
 import { borderRadius } from '../styles/tokens';
-import { resolveAccentColors } from '../theme/accent-colors';
-import { resolveChipHueColors } from './hue-colors';
-import { pressedSurface } from '../theme/press-colors';
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { RiCloseLine } from '../icons/remix/RiCloseLine';
-import { interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
+import { NOT_DISABLED, interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
+import { CHIP_GEOMETRY, resolveChipPaint, resolveChipRing } from './shared';
 import type { ChipProps } from './types';
 
 /**
- * The chip, one Bloom size per emphasis level:
+ * The chip, five rungs and four fills. The rung table and the paint recipe are
+ * in `shared.ts` — including why `inverted` is a different idea rather than a
+ * fourth loudness, and why the scale had to grow past 28 (five families had
+ * drawn their own pill because it did not).
  *
- *   small   caption  caption-1-medium (12/16, tracking .15), py 4  → 24 tall
- *   medium  bold     body-medium (14/20),                   py 2  → 24 tall
- *   large   subtle   body-medium (14/20),                   py 4  → 28 tall
- *
- * All px 6. Bloom keeps the full pill, like `Button`, rather than a 6px corner.
- * The icon and close slots are Bloom's own, sized to
- * the label, with Remix's `close-line` (16) as the close glyph.
+ * Bloom keeps the full pill, like `Button`, rather than a 6px corner. The icon
+ * and close slots are Bloom's own, sized to the rung, with Remix's
+ * `close-line` (16) as the close glyph.
  */
 const CLOSE_ICON = 16;
 
-const SIZE_CONFIG = {
-  small: { height: 24, type: 'caption-1-medium', paddingHorizontal: 6, iconGap: 4 },
-  medium: { height: 24, type: 'body-medium', paddingHorizontal: 6, iconGap: 4 },
-  large: { height: 28, type: 'body-medium', paddingHorizontal: 6, iconGap: 4 },
-} as const satisfies Record<string, { height: number; type: TypeScaleVariant; paddingHorizontal: number; iconGap: number }>;
-
 // ---------------------------------------------------------------------------
 //  Keyboard focus on web
 //
@@ -55,6 +45,15 @@ const SIZE_CONFIG = {
 //  attribute rather than a class because a class never reaches the DOM here:
 //  react-native-css consumes `className` into `style` before that could happen.
 //
+//  THE RING COLOUR IS THE ACCENT RAMP'S 500, not the chip's own label. It was
+//  the label, which is the one colour guaranteed to be invisible on the chip:
+//  a solid chip's ring was white on white (measured 1.09:1 in light mode, black
+//  on black in dark). Every other ring in the library — sidebar, menus, the map
+//  markers, the category bar, the filter pills — is `accent[500]`, and it is a
+//  ring on the PAGE, so it must contrast with what is behind the chip rather
+//  than with the chip. Nothing in jest can see this: the custom property is
+//  present, spelled correctly, and carries a real colour either way.
+//
 //  `adoptStyleSheet` no-ops without a `document`, so this file stays universal
 //  and native pays for a hook call and nothing else.
 // ---------------------------------------------------------------------------
@@ -81,87 +80,108 @@ const BLOOM_CHIP_CSS = interactiveWebCss({
   transition: 'background-color 120ms ease, border-color 120ms ease, opacity 120ms ease',
   hover: { declarations: 'opacity: 0.9;' },
   outlineOffset: 2,
+  extraRules: `
+/* The rung with a minWidth ("Any", "1", "8+" in a counts row) centres its
+   label. The style prop cannot say so: the reset above is an adopted sheet and
+   wins over react-native-web's atomic classes, so it has to be said here too. */
+[data-bloom-chip][data-bloom-chip-center] {
+  justify-content: center;
+}
+/* An inverted chip answers hover with its BORDER, in JS, because the colour is
+   a resolved token. The shared opacity hover would fire as well and fade the
+   label of a pill that has no fill to fade. The disabled filter is not optional:
+   without it this would undo the 0.5 a disabled chip is dimmed to, on hover. */
+[data-bloom-chip][data-bloom-chip-inverted]${NOT_DISABLED}:hover {
+  opacity: 1;
+}
+`,
 });
 
 const IS_WEB = Platform.OS === 'web';
 
-const ChipComponent: React.FC<ChipProps> = ({
-  children,
-  variant = 'subtle',
-  color = 'default',
-  hue,
-  surface,
-  size = 'medium',
-  startIcon,
-  endIcon,
-  onPress,
-  onClose,
-  selected = false,
-  disabled = false,
-  style,
-  textStyle,
-  accessibilityLabel,
-  testID,
-}) => {
+const ChipComponent = forwardRef<View, ChipProps>(function ChipComponent(
+  {
+    children,
+    variant = 'subtle',
+    color = 'default',
+    hue,
+    surface,
+    size = 'medium',
+    startIcon,
+    endIcon,
+    onPress,
+    onClose,
+    selected = false,
+    role = 'button',
+    disabled = false,
+    tabIndex,
+    onKeyDown,
+    style,
+    textStyle,
+    accessibilityLabel,
+    testID,
+  },
+  ref,
+) {
   const theme = useTheme();
   useInteractiveWebCss(STYLE_ID, BLOOM_CHIP_CSS);
   // No press scale, like `Button`: a press is the background change alone,
   // which is also the one press affordance that reads under a mouse.
   const { state: pressed, onIn: onPressIn, onOut: onPressOut } = useInteractionState();
-  // Selection promotes the chip to the brand tone \u2014 the filter-pill behaviour \u2014
-  // rather than to a second colour system of its own.
-  const colors = useMemo(() => {
-    if (!hue || selected) return resolveAccentColors(theme.colors, selected ? 'primary' : color, variant);
-    const pair = resolveChipHueColors(theme, hue, surface);
-    return { ...pair, border: 'transparent' };
-  }, [theme, hue, surface, selected, color, variant]);
-  const sizeConfig = SIZE_CONFIG[size];
-  // All three fills go through the one resolver and land somewhere different
-  // because their REST surfaces do: `solid` keeps its tone and gains a state
-  // layer of its own label colour, `subtle` deepens the tint AND its alpha
-  // rather than flattening it, `outlined` has no fill so the press IS the fill.
-  const pressedBackground = useMemo(
-    () => pressedSurface(theme.colors, colors.background, colors.foreground),
-    [theme.colors, colors.background, colors.foreground],
+  // Hover is JS only for the fill that answers it with a border colour; every
+  // other fill answers in CSS, and wiring the handlers unconditionally would
+  // re-render every chip in a tag list on pointer move for nothing.
+  const { state: hovered, onIn: onHoverIn, onOut: onHoverOut } = useInteractionState();
+  const paint = useMemo(
+    () => resolveChipPaint(theme, { tone: color, variant, selected, hue, surface }),
+    [theme, color, variant, selected, hue, surface],
   );
+  const ring = useMemo(() => resolveChipRing(theme), [theme]);
+  const geometry = CHIP_GEOMETRY[size];
 
   const containerStyle = useMemo((): WebCssStyle => ({
-    height: sizeConfig.height,
+    height: geometry.height,
     borderRadius: borderRadius.full,
-    paddingHorizontal: sizeConfig.paddingHorizontal,
-    backgroundColor: colors.background,
-    borderWidth: variant === 'outlined' && !(hue && !selected) ? 1 : 0,
-    borderColor: colors.border,
+    paddingHorizontal: geometry.paddingHorizontal,
+    backgroundColor: paint.background,
+    borderWidth: paint.borderWidth,
+    borderColor: paint.border,
     flexDirection: 'row',
     alignItems: 'center',
-    gap: sizeConfig.iconGap,
+    gap: geometry.iconGap,
     alignSelf: 'flex-start',
+    ...(geometry.minWidth ? { minWidth: geometry.minWidth, justifyContent: 'center' } : null),
     // A pill is a fixed-size token. In a flex row of chips (a filter bar, a tag
     // list) the default `flexShrink: 1` lets a long label squeeze its
-    // neighbours into ellipsis; shadcn's badge says the same thing as
-    // `shrink-0`. `overflow: hidden` keeps the content inside the radius.
+    // neighbours into ellipsis. `overflow: hidden` keeps the content inside the
+    // radius.
     flexShrink: 0,
     overflow: 'hidden',
     // The `:focus-visible` ring colour, read by the adopted sheet. A custom
     // property because the value is a resolved theme token the static sheet
     // cannot know; native has no such style key and ignores it.
-    '--bloom-chip-ring': colors.foreground,
-  }), [sizeConfig, colors, variant, hue, selected]);
+    '--bloom-chip-ring': ring,
+  }), [geometry, paint, ring]);
 
   const labelStyle = useMemo((): TextStyle => ({
-    color: colors.foreground,
+    color: paint.foreground,
     // The label yields before the pill does: a chip narrower than its text
     // ellipsises rather than overflowing its own radius.
     flexShrink: 1,
-  }), [sizeConfig, colors]);
+  }), [paint]);
 
-  // Icons inside the pill are sized to the pill, not to whatever the caller
-  // happened to pass \u2014 shadcn's badge pins them with `[&>svg]:size-3`. A slot
-  // with a fixed box does the same thing without reaching into the child.
-  const iconSlotStyle = useMemo((): ViewStyle => {
-    const box = Math.round(TYPE_SCALE[sizeConfig.type].fontSize * 1.15);
-    return { width: box, height: box, alignItems: 'center', justifyContent: 'center' };
-  }, [sizeConfig]);
+  // Icons inside the pill are sized to the RUNG, not to whatever the caller
+  // happened to pass. A slot with a fixed box does that without reaching into
+  // the child.
+  const iconSlotStyle = useMemo(
+    (): ViewStyle => ({
+      width: geometry.icon,
+      height: geometry.icon,
+      alignItems: 'center',
+      justifyContent: 'center',
+    }),
+    [geometry],
+  );
 
   const closeButton = onClose ? (
     <Pressable
@@ -171,7 +191,7 @@ const ChipComponent: React.FC<ChipProps> = ({
       accessibilityRole="button"
       style={iconSlotStyle}
     >
-      <RiCloseLine width={CLOSE_ICON} height={CLOSE_ICON} fill={colors.foreground} />
+      <RiCloseLine width={CLOSE_ICON} height={CLOSE_ICON} fill={paint.foreground} />
     </Pressable>
   ) : null;
 
@@ -179,7 +199,7 @@ const ChipComponent: React.FC<ChipProps> = ({
     <>
       {startIcon != null ? <View style={iconSlotStyle}>{startIcon}</View> : null}
       {typeof children === 'string' ? (
-        <Text variant={sizeConfig.type} numberOfLines={1} style={[labelStyle, textStyle]}>
+        <Text variant={geometry.type} numberOfLines={1} style={[labelStyle, textStyle]}>
           {children}
         </Text>
       ) : (
@@ -191,8 +211,23 @@ const ChipComponent: React.FC<ChipProps> = ({
   );
 
   if (onPress) {
+    // Both spellings of the state, because neither platform reads the other's
+    // and there is no single prop that serves both: react-native-web ignores
+    // `accessibilityState`, while React Native has no `aria-pressed` at all
+    // (its `AccessibilityState` is disabled/selected/checked/busy/expanded).
+    // WHICH attribute is a property of the ROLE, not a preference — a `radio`
+    // carries `aria-checked` and a `tab` `aria-selected`; `aria-pressed` on
+    // either is invalid, and `aria-selected` on a `button` is too.
+    const stateProps =
+      role === 'radio'
+        ? { accessibilityState: { checked: selected, disabled }, 'aria-checked': selected }
+        : role === 'tab'
+          ? { accessibilityState: { selected, disabled }, 'aria-selected': selected }
+          : { accessibilityState: { disabled, selected }, 'aria-pressed': selected };
+
     return (
       <Pressable
+        ref={ref}
         // The DOM hook the adopted sheet above hangs off.
         //
         // It MUST go through `dataSet`. react-native-web filters props against
@@ -208,29 +243,34 @@ const ChipComponent: React.FC<ChipProps> = ({
         // as `TextField`'s DOM mouse handlers, registered in
         // `classname-interop.test.ts`'s exemption list. It is NOT a `className`
         // smuggled past `styled()`, which is what that gate forbids.
-        {...(IS_WEB ? ({ dataSet: { bloomChip: '' } } as Record<string, unknown>) : {})}
+        {...(IS_WEB
+          ? ({
+              dataSet: {
+                bloomChip: '',
+                ...(geometry.minWidth ? { bloomChipCenter: '' } : null),
+                ...(variant === 'inverted' ? { bloomChipInverted: '' } : null),
+              },
+              ...(tabIndex !== undefined ? { tabIndex } : null),
+              ...(onKeyDown ? { onKeyDown } : null),
+            } as Record<string, unknown>)
+          : {})}
         style={[
           containerStyle,
           disabled && { opacity: 0.5 },
+          hovered && !disabled && paint.hoveredBorder ? { borderColor: paint.hoveredBorder } : null,
           // Before the caller's `style`, so `style` still wins the array.
-          pressed && !disabled && { backgroundColor: pressedBackground },
+          pressed && !disabled && { backgroundColor: paint.pressedBackground },
           style,
         ]}
         onPress={onPress}
         onPressIn={onPressIn}
         onPressOut={onPressOut}
+        {...(paint.hoveredBorder ? { onHoverIn, onHoverOut } : null)}
         disabled={disabled}
         accessibilityLabel={accessibilityLabel}
-        accessibilityRole="button"
-        // Both spellings, because neither platform reads the other's and
-        // there is no single prop that serves both here: react-native-web
-        // ignores `accessibilityState`, while React Native has no
-        // `aria-pressed` at all (its `AccessibilityState` is
-        // disabled/selected/checked/busy/expanded). `aria-pressed` is also
-        // the state ARIA defines for a toggle with `role="button"` —
-        // `aria-selected` would be invalid on that role.
-        accessibilityState={{ disabled, selected }}
-        aria-pressed={selected}
+        role={role}
+        {...stateProps}
+        aria-disabled={disabled || undefined}
         testID={testID}
       >
         {content}
@@ -240,6 +280,7 @@ const ChipComponent: React.FC<ChipProps> = ({
 
   return (
     <View
+      ref={ref}
       style={[containerStyle, disabled && { opacity: 0.5 }, style]}
       accessibilityLabel={accessibilityLabel}
       testID={testID}
@@ -247,7 +288,7 @@ const ChipComponent: React.FC<ChipProps> = ({
       {content}
     </View>
   );
-};
+});
 
 export const Chip = memo(ChipComponent);
 Chip.displayName = 'Chip';

package/src/chip/ChipRow.tsx

@@ -0,0 +1,164 @@
+import React, { memo, useCallback, useMemo, useState } from 'react';
+import {
+  Platform,
+  ScrollView,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from 'react-native';
+
+import { adoptStyleSheet } from '../styles/adopt-style-sheet';
+import type { WebCssStyle } from '../styles/web-view-style';
+import { useTheme } from '../theme/use-theme';
+import { chipRowOverflow, type ChipRowScroll } from './shared';
+import type { ChipRowProps } from './types';
+
+/**
+ * A row of pills that scrolls sideways, with a fade at whichever edge has more
+ * behind it.
+ *
+ * The fade is the thing worth sharing. Without it a clipped pill just stops
+ * mid-glyph and reads as a rendering fault rather than as "there is more"; the
+ * row `category-bar` draws is the only place in the library that had one, and
+ * five filter rows were scrolling without it. The gradient resolves into
+ * `fadeColor` — the surface BEHIND the row, which the row cannot know — so a
+ * caller on a card must say so or the fade will blend into the page instead.
+ *
+ * Web only, and deliberately: the fade is painted with a CSS gradient, and on
+ * native a scroll row already shows its own bounce. The row scrolls on both.
+ *
+ * `ringInset` keeps room on every side for a pill's focus ring and takes it
+ * back out with negative margins, so the row still lines up with the heading
+ * above it — a ring clipped by its own scroller is the usual way a focus
+ * outline half-disappears.
+ *
+ * Semantics belong to the CALLER: pass `role` and `accessibilityLabel` that
+ * match what the pills are (`group` of toggles, `radiogroup`, `tablist`). The
+ * row draws nothing of its own that assistive technology should see.
+ */
+
+const IS_WEB = Platform.OS === 'web';
+
+/** Width of each edge's fade. */
+export const CHIP_ROW_EDGE = 40;
+
+const STYLE_ID = 'bloom-chip-row-web-css';
+const TRACK = '[data-bloom-chip-row-track]';
+
+const BLOOM_CHIP_ROW_CSS = `
+${TRACK} {
+  scrollbar-width: none;
+  overscroll-behavior-x: contain;
+}
+${TRACK}::-webkit-scrollbar {
+  display: none;
+}
+`;
+
+function ChipRowComponent({
+  children,
+  gap = 8,
+  contentInset = 0,
+  fadeColor,
+  ringInset = 4,
+  role = 'group',
+  accessibilityLabel,
+  disabled,
+  style,
+  contentContainerStyle,
+  testID,
+}: ChipRowProps) {
+  const theme = useTheme();
+  React.useEffect(() => {
+    adoptStyleSheet(STYLE_ID, BLOOM_CHIP_ROW_CSS);
+  }, []);
+
+  const [scroll, setScroll] = useState<ChipRowScroll>({ x: 0, viewport: 0, content: 0 });
+  const overflow = useMemo(() => chipRowOverflow(scroll), [scroll]);
+  const fade = fadeColor ?? theme.colors.background;
+
+  const onScroll = useCallback((event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+    setScroll({ x: contentOffset.x, viewport: layoutMeasurement.width, content: contentSize.width });
+  }, []);
+
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const { width } = event.nativeEvent.layout;
+    setScroll((previous) => (previous.viewport === width ? previous : { ...previous, viewport: width }));
+  }, []);
+
+  const onContentSizeChange = useCallback((width: number) => {
+    setScroll((previous) => (previous.content === width ? previous : { ...previous, content: width }));
+  }, []);
+
+  // The fade has to cover the SCROLLER, which sits `ringInset` outside the
+  // wrapper on every side (the negative margins above). Pinned to the wrapper's
+  // own edge instead, it leaves exactly that much uncovered, and a chip clipped
+  // by those few pixels reads as a hard cut with a fade beside it — measured in
+  // Chrome at 4px, which is enough to see.
+  const edgeStyle = (side: 'left' | 'right'): WebCssStyle => ({
+    position: 'absolute',
+    top: -ringInset,
+    bottom: -ringInset,
+    ...(side === 'left' ? { left: -ringInset } : { right: -ringInset }),
+    width: CHIP_ROW_EDGE,
+    backgroundImage: `linear-gradient(to ${side === 'left' ? 'right' : 'left'}, ${fade} 0%, ${fade} 40%, transparent 100%)`,
+  });
+
+  return (
+    // The ROLE and the name go on the wrapper, not the scroller: the wrapper is
+    // the element a caller's `testID` lands on, and a group whose semantics
+    // hide one node deeper is a group every consumer's test misses.
+    <View
+      role={role}
+      accessibilityLabel={accessibilityLabel}
+      aria-disabled={disabled || undefined}
+      style={[{ position: 'relative' }, style]}
+      testID={testID}
+    >
+      <ScrollView
+        {...(IS_WEB ? ({ dataSet: { bloomChipRowTrack: '' } } as Record<string, unknown>) : {})}
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        scrollEventThrottle={16}
+        onScroll={onScroll}
+        onLayout={onLayout}
+        onContentSizeChange={onContentSizeChange}
+        // The ring room, and the same amount taken back out, so a focus outline
+        // is not clipped by the scroller and the row still lines up.
+        style={{
+          flexGrow: 0,
+          marginTop: -ringInset,
+          marginBottom: -ringInset,
+          marginLeft: -ringInset,
+          marginRight: -ringInset,
+        }}
+        contentContainerStyle={[
+          {
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap,
+            paddingTop: ringInset,
+            paddingBottom: ringInset,
+            paddingLeft: contentInset + ringInset,
+            paddingRight: contentInset + ringInset,
+          },
+          contentContainerStyle,
+        ]}
+        testID={testID ? `${testID}-track` : undefined}
+      >
+        {children}
+      </ScrollView>
+      {IS_WEB && overflow.previous ? (
+        <View pointerEvents="none" style={edgeStyle('left')} testID={testID ? `${testID}-fade-start` : undefined} />
+      ) : null}
+      {IS_WEB && overflow.next ? (
+        <View pointerEvents="none" style={edgeStyle('right')} testID={testID ? `${testID}-fade-end` : undefined} />
+      ) : null}
+    </View>
+  );
+}
+
+export const ChipRow = memo(ChipRowComponent);
+ChipRow.displayName = 'ChipRow';

package/src/chip/index.ts

@@ -1,3 +1,6 @@
 export { Chip } from './Chip';
+export { ChipRow, CHIP_ROW_EDGE } from './ChipRow';
 export { resolveChipHueColors } from './hue-colors';
-export type { ChipHue, ChipProps, ChipSize } from './types';
+export { CHIP_GEOMETRY, chipRowOverflow, resolveChipPaint, resolveChipRing } from './shared';
+export type { ChipGeometry, ChipPaint, ChipRowScroll } from './shared';
+export type { ChipHue, ChipProps, ChipRole, ChipRowProps, ChipSize, ChipVariant } from './types';

package/src/chip/shared.ts

@@ -0,0 +1,162 @@
+import { resolveButtonRamps } from '../button/shared';
+import { TYPE_SCALE, type TypeScaleVariant } from '../typography/scale';
+import { resolveAccentColors, type AccentTone } from '../theme/accent-colors';
+import { pressedSurface } from '../theme/press-colors';
+import type { Theme } from '../theme/types';
+import { resolveChipHueColors } from './hue-colors';
+import type { ChipHue, ChipSize, ChipVariant } from './types';
+
+/**
+ * `Chip`'s rungs and paint, pure so a gate can walk them without rendering.
+ *
+ *            height  padding-x  gap  icon  text
+ *   small    24      6          4    14    caption-1-medium
+ *   medium   24      6          4    16    body-medium         ← default
+ *   large    28      6          4    16    body-medium
+ *   xl       32      12         8    16    body-medium
+ *   2xl      40      16         8    18    body-medium
+ *
+ * The scale used to stop at `large`, which is why FIVE families grew their own
+ * pill rather than use this one: 28 tall with 6px sides is a TAG, and a filter
+ * you tap needs a target. `xl` is the filter/segment row (the pill
+ * `media-shelf`, `music-library` and `stay-search` each re-drew at 32); `2xl`
+ * is the filters-sheet pill, tall enough for touch, with the `minWidth` that
+ * keeps a one-character label ("1", "8+") from collapsing to a dot.
+ */
+export interface ChipGeometry {
+  height: number;
+  type: TypeScaleVariant;
+  paddingHorizontal: number;
+  iconGap: number;
+  /** The icon slot's box. Defaults to 1.15 of the label's font size. */
+  icon: number;
+  /** Floor on the pill's width, or 0. A rung with one CENTRES its contents. */
+  minWidth: number;
+}
+
+function rung(
+  height: number,
+  type: TypeScaleVariant,
+  paddingHorizontal: number,
+  iconGap: number,
+  minWidth = 0,
+  icon = Math.round(TYPE_SCALE[type].fontSize * 1.15),
+): ChipGeometry {
+  return { height, type, paddingHorizontal, iconGap, icon, minWidth };
+}
+
+export const CHIP_GEOMETRY: Readonly<Record<ChipSize, ChipGeometry>> = {
+  small: rung(24, 'caption-1-medium', 6, 4),
+  medium: rung(24, 'body-medium', 6, 4),
+  large: rung(28, 'body-medium', 6, 4),
+  xl: rung(32, 'body-medium', 12, 8),
+  '2xl': rung(40, 'body-medium', 16, 8, 48, 18),
+};
+
+export interface ChipPaint {
+  background: string;
+  foreground: string;
+  border: string;
+  /** Border width the variant draws. */
+  borderWidth: number;
+  /** What the surface becomes while the chip is held. */
+  pressedBackground: string;
+  /** What the BORDER becomes under a web pointer, or `null` for no hover border change. */
+  hoveredBorder: string | null;
+}
+
+/**
+ * Resolve every colour one chip paints, for one tone at one loudness in one
+ * selection state.
+ *
+ * `solid` / `subtle` / `outlined` go through the shared accent recipe, and
+ * selection promotes the chip to the BRAND tone — the filter-pill behaviour.
+ *
+ * `inverted` is the fourth, and it is a different idea rather than a fourth
+ * loudness: at rest it is a hairline on the page, and selected it turns the
+ * page's own reading pair OVER (fill `text`, label `background`). That pair is
+ * legible by construction in both modes and under every preset, which is what
+ * a filters sheet needs and what a brand-tone promotion cannot promise. It is
+ * the pill `stay-filters` used to draw itself.
+ */
+export function resolveChipPaint(
+  theme: Theme,
+  {
+    tone,
+    variant,
+    selected,
+    hue,
+    surface,
+  }: { tone: AccentTone; variant: ChipVariant; selected: boolean; hue?: ChipHue; surface?: string },
+): ChipPaint {
+  if (variant === 'inverted') {
+    const { neutral } = resolveButtonRamps(theme);
+    const text = theme.colors.text;
+    if (selected) {
+      const pressed = pressedSurface(theme.colors, text, theme.colors.background);
+      return {
+        background: text,
+        foreground: theme.colors.background,
+        border: text,
+        borderWidth: 1,
+        pressedBackground: pressed,
+        hoveredBorder: text,
+      };
+    }
+    return {
+      background: 'transparent',
+      foreground: text,
+      border: theme.isDark ? neutral[700] : neutral[200],
+      borderWidth: 1,
+      pressedBackground: theme.isDark ? neutral[800] : neutral[100],
+      hoveredBorder: text,
+    };
+  }
+
+  const colors =
+    !hue || selected
+      ? resolveAccentColors(theme.colors, selected ? 'primary' : tone, variant)
+      : { ...resolveChipHueColors(theme, hue, surface), border: 'transparent' };
+
+  return {
+    background: colors.background,
+    foreground: colors.foreground,
+    border: colors.border,
+    borderWidth: variant === 'outlined' && !(hue && !selected) ? 1 : 0,
+    // All three fills go through the one resolver and land somewhere different
+    // because their REST surfaces do: `solid` keeps its tone and gains a state
+    // layer of its own label colour, `subtle` deepens the tint AND its alpha
+    // rather than flattening it, `outlined` has no fill so the press IS the fill.
+    pressedBackground: pressedSurface(theme.colors, colors.background, colors.foreground),
+    hoveredBorder: null,
+  };
+}
+
+/** The keyboard focus ring every Bloom control draws: the accent ramp's 500. */
+export function resolveChipRing(theme: Theme): string {
+  return resolveButtonRamps(theme).accent[500];
+}
+
+export interface ChipRowScroll {
+  /** Scroll offset. */
+  x: number;
+  /** Visible width. */
+  viewport: number;
+  /** Scrollable content width. */
+  content: number;
+}
+
+/**
+ * Whether there is more of a scrolling pill row to each side. 1px slack for
+ * fractional offsets.
+ *
+ * `CategoryBar` re-exports this as `categoryBarOverflow`: one answer, so the
+ * strip and the pill row cannot disagree about when an edge fade is up.
+ */
+export function chipRowOverflow({ x, viewport, content }: ChipRowScroll): {
+  previous: boolean;
+  next: boolean;
+} {
+  if (viewport <= 0 || content <= viewport + 1) return { previous: false, next: false };
+  return { previous: x > 1, next: x < content - viewport - 1 };
+}