@oxy.so/bloom 4.17.0 → 4.18.0

package/src/cart-panel/CartLine.tsx

@@ -21,12 +21,17 @@ import type { CartLineProps } from './types';
  *   leading   the square photo (56; 44 compact), washed while it is sold out
  *   body      the name; the chosen options on one quiet line; the note; then
  *             the quantity control and remove, side by side
- *   trailing  the price, right-aligned, with an optional struck original
+ *   trailing  the price, right-aligned, with an optional struck original, and
+ *             an optional `secondaryPrice` (a second currency) under it in the
+ *             secondary colour
  *
- * THE STEPPER DOES NOT REMOVE. Its floor is 1, and removing is its own control
- * with its own name — a stepper that deletes the line when you press `−` once
- * too often is a destructive action behind an arithmetic one, and it has no
- * label saying so.
+ * BY DEFAULT THE STEPPER DOES NOT REMOVE. Its floor is 1, and removing is its
+ * own control with its own name — a stepper that deletes the line when you
+ * press `−` once too often is a destructive action behind an arithmetic one.
+ * `removeInStepper` opts into the storefront pattern instead: at 1 the `−`
+ * becomes a trash button NAMED as removal (`Stepper`'s `onRemove`), and the
+ * separate remove control is not drawn. A sold-out line keeps the separate
+ * control, because its stepper is disabled and could not remove anything.
  *
  * The row is never pressable, which is what lets the controls live in it: a
  * pressable `Item` is a real `<button>` on web and a control inside one is
@@ -48,6 +53,7 @@ function CartLineComponent(props: CartLineProps) {
     note,
     price,
     originalPrice,
+    secondaryPrice,
     quantity,
     photo,
     photoVariant,
@@ -56,6 +62,7 @@ function CartLineComponent(props: CartLineProps) {
     onQuantityChange,
     onRemove,
     removeLabel,
+    removeInStepper = false,
     density = 'comfortable',
     accessibilityLabel,
     style,
@@ -68,6 +75,10 @@ function CartLineComponent(props: CartLineProps) {
   const g = CART_GEOMETRY[density];
   const compact = density === 'compact';
   const chosen = optionsLine(options);
+  const removeName = removeLabel ?? `Remove ${name}`;
+  // The stepper carries removal only when it is live; a disabled stepper
+  // (sold out) cannot, and the line still needs its remove control.
+  const stepperRemoves = removeInStepper && onRemove !== undefined && onQuantityChange !== undefined && !unavailable;
 
   return (
     <Item
@@ -95,6 +106,16 @@ function CartLineComponent(props: CartLineProps) {
             secondaryColor={paint.textSecondary}
             testID={testID ? `${testID}-price` : undefined}
           />
+          {secondaryPrice ? (
+            <Text
+              variant={compact ? 'caption-1-regular' : 'body-2-regular'}
+              numberOfLines={1}
+              testID={testID ? `${testID}-secondary-price` : undefined}
+              style={{ color: paint.textSecondary, fontVariant: ['tabular-nums'] }}
+            >
+              {secondaryPrice}
+            </Text>
+          ) : null}
         </View>
       }
       style={style}
@@ -146,6 +167,8 @@ function CartLineComponent(props: CartLineProps) {
               min={1}
               disabled={unavailable}
               onValueChange={onQuantityChange}
+              onRemove={stepperRemoves ? onRemove : undefined}
+              removeLabel={stepperRemoves ? removeName : undefined}
               accessibilityLabel={name}
               testID={testID ? `${testID}-stepper` : undefined}
             />
@@ -158,11 +181,11 @@ function CartLineComponent(props: CartLineProps) {
               {`×${quantity}`}
             </Text>
           )}
-          {onRemove ? (
+          {onRemove && !stepperRemoves ? (
             <GlyphButton
               size={32}
               icon={RiDeleteBinLine}
-              accessibilityLabel={removeLabel ?? `Remove ${name}`}
+              accessibilityLabel={removeName}
               onPress={onRemove}
               testID={testID ? `${testID}-remove` : undefined}
             />

package/src/cart-panel/CartPanel.tsx

@@ -187,6 +187,7 @@ function CartPanelComponent({
   lines,
   onLineQuantityChange,
   onLineRemove,
+  removeInStepper = false,
   minimumOrder,
   tip,
   promo,
@@ -239,6 +240,7 @@ function CartPanelComponent({
                 note={line.note}
                 price={line.price}
                 originalPrice={line.originalPrice}
+                secondaryPrice={line.secondaryPrice}
                 quantity={line.quantity}
                 photo={line.photo}
                 photoVariant={line.photoVariant}
@@ -251,6 +253,7 @@ function CartPanelComponent({
                     : undefined
                 }
                 onRemove={onLineRemove ? () => onLineRemove(line.id) : undefined}
+                removeInStepper={removeInStepper}
                 testID={testID ? `${testID}-line-${line.id}` : undefined}
               />
             ))}

package/src/cart-panel/shared.ts

@@ -45,7 +45,15 @@ export function optionsLine(options: ReadonlyArray<string> | undefined): string
 export function composeCartLineName(
   line: Pick<
     CartLineEntry,
-    'name' | 'options' | 'note' | 'quantity' | 'price' | 'originalPrice' | 'unavailable' | 'unavailableLabel'
+    | 'name'
+    | 'options'
+    | 'note'
+    | 'quantity'
+    | 'price'
+    | 'originalPrice'
+    | 'secondaryPrice'
+    | 'unavailable'
+    | 'unavailableLabel'
   >,
 ): string {
   const parts: string[] = [line.name];
@@ -55,6 +63,8 @@ export function composeCartLineName(
   parts.push(String(line.quantity));
   if (line.originalPrice) parts.push(`${line.price}, originally ${line.originalPrice}`);
   else parts.push(line.price);
+  // The second currency travels with the price it restates.
+  if (line.secondaryPrice) parts.push(line.secondaryPrice);
   if (line.unavailable) parts.push(line.unavailableLabel ?? 'Sold out');
   return parts.join(', ');
 }

package/src/cart-panel/types.ts

@@ -26,6 +26,12 @@ export interface CartLineEntry {
   price: string;
   /** PRE-FORMATTED price before a discount, struck through BEFORE `price`. */
   originalPrice?: string;
+  /**
+   * A second, PRE-FORMATTED rendering of `price` — the buyer's currency beside
+   * the shop's, `"≈ 12,00 €"` — drawn de-emphasised under it. The cart's
+   * spelling of `ListingPriceLine.secondary`; drawn as given, nothing converts.
+   */
+  secondaryPrice?: string;
   /** How many. Always at least 1 — a line with none of it is a line that was removed. */
   quantity: number;
   /** An absolute URL, or an id the app's `ImageResolver` turns into one. */
@@ -45,6 +51,13 @@ export interface CartLineProps extends Omit<CartLineEntry, 'id'> {
   onRemove?: () => void;
   /** Names the remove control, which draws no text. Default `"Remove <name>"`. */
   removeLabel?: string;
+  /**
+   * Moves removal INTO the stepper: at quantity 1 its `−` becomes a trash button
+   * named `removeLabel` that calls `onRemove`, and no separate remove control is
+   * drawn. Needs both `onQuantityChange` and `onRemove`; a sold-out line keeps
+   * the separate control. Default `false` — the stepper floors at 1.
+   */
+  removeInStepper?: boolean;
   /** Default `comfortable`. */
   density?: CartDensity;
   /** Replaces the composed name ("Ember flatbread, Large, Extra cheese, 2, €24.00"). */
@@ -151,6 +164,11 @@ export interface CartPanelProps {
   onLineQuantityChange?: (id: string, quantity: number) => void;
   /** With it every line draws a remove control. */
   onLineRemove?: (id: string) => void;
+  /**
+   * Every line removes from its stepper at quantity 1 instead of drawing a
+   * separate remove control (`CartLine`'s `removeInStepper`). Default `false`.
+   */
+  removeInStepper?: boolean;
 
   /** The shortfall warning. Drawn above the totals, where the number it is about is. */
   minimumOrder?: CartMinimumOrder;

package/src/checkout-summary/CheckoutConfirm.tsx

@@ -15,6 +15,9 @@ import type { CheckoutConfirmProps } from './types';
  * terms under it, and the state where it must not fire twice.
  *
  *   button   `Button` primary large, full width, "Place order · €24.80"
+ *   second   `secondaryAmount` ("≈ 12,00 €"), 8 under the button, the same
+ *            centred secondary line as the terms — the button carries ONE
+ *            amount, the one the charge is made in
  *   terms    12 under it; the centred secondary line every Bloom action card
  *            draws under its primary (`ActionCardNote`)
  *   footer   16 under the terms
@@ -44,6 +47,7 @@ import type { CheckoutConfirmProps } from './types';
 function CheckoutConfirmComponent({
   label = CHECKOUT_CONFIRM_LABEL,
   amount,
+  secondaryAmount,
   terms,
   onConfirm,
   disabled = false,
@@ -90,6 +94,11 @@ function CheckoutConfirmComponent({
       >
         {words}
       </Button>
+      {secondaryAmount ? (
+        <ActionCardNote style={{ marginTop: 8 }} testID={id('secondary-amount')}>
+          {secondaryAmount}
+        </ActionCardNote>
+      ) : null}
       {terms != null ? (
         <ActionCardNote style={{ marginTop: 12 }} testID={id('terms')}>
           {terms}

package/src/checkout-summary/types.ts

@@ -89,6 +89,12 @@ export interface CheckoutConfirmProps {
    * press commits to and the press are one decision.
    */
   amount?: string;
+  /**
+   * A second, PRE-FORMATTED rendering of `amount` — the buyer's currency beside
+   * the shop's, `"≈ 12,00 €"` — drawn de-emphasised, centred under the button.
+   * Named like `PriceLine.secondaryAmount`; drawn as given, nothing converts.
+   */
+  secondaryAmount?: string;
   /**
    * The terms line under the button — a string, or a node with links in it.
    * `null` draws none.

package/src/chip/Chip.tsx

@@ -242,8 +242,10 @@ const ChipComponent = forwardRef<View, ChipProps>(function ChipComponent(
     // 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.
+    // A `checkbox` (a multi-select filter chip) reads `aria-checked` like a
+    // `radio`; what differs is that its group allows several at once.
     const stateProps =
-      role === 'radio'
+      role === 'radio' || role === 'checkbox'
         ? { accessibilityState: { checked: selected, disabled }, 'aria-checked': selected }
         : role === 'tab'
           ? { accessibilityState: { selected, disabled }, 'aria-selected': selected }

package/src/chip/types.ts

@@ -26,10 +26,11 @@ export type ChipHue = 'lime' | 'rose' | 'yellow' | 'cyan' | 'blue' | 'purple' |
 
 /**
  * What a pressable chip IS, which decides the state ARIA reads it by:
- * a toggle `button` (`aria-pressed`), a `radio` in a radiogroup
- * (`aria-checked`), or a `tab` in a tablist (`aria-selected`).
+ * a toggle `button` (`aria-pressed`), a `checkbox` in a multi-select filter
+ * group (`aria-checked`), a `radio` in a radiogroup (`aria-checked`), or a
+ * `tab` in a tablist (`aria-selected`).
  */
-export type ChipRole = 'button' | 'radio' | 'tab';
+export type ChipRole = 'button' | 'checkbox' | 'radio' | 'tab';
 
 export interface ChipProps {
   appearance?: BloomAppearance;
@@ -84,9 +85,10 @@ export interface ChipProps {
   selected?: boolean;
   /**
    * What a pressable chip is to assistive technology. Default `button`
-   * (`aria-pressed`). Use `radio` inside a `radiogroup` and `tab` inside a
-   * `tablist` — the state attribute follows the role, and a `radio` announcing
-   * `aria-pressed` is invalid.
+   * (`aria-pressed`). Use `checkbox` for a multi-select filter chip (in a
+   * `group`), `radio` inside a `radiogroup` and `tab` inside a `tablist` — the
+   * state attribute follows the role, and a `radio` announcing `aria-pressed`
+   * is invalid.
    */
   role?: ChipRole;
   /** Whether the chip is disabled. */

package/src/dialog/Dialog.tsx

@@ -28,6 +28,7 @@ import Animated, {
 import { BottomSheet, type BottomSheetRef } from '../bottom-sheet';
 import { Backdrop, OverlayRoot } from '../overlay';
 import { useTheme } from '../theme/use-theme';
+import { useIsRtl } from '../hooks/use-is-rtl';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { StyledView } from '../styles/styled-primitives';
 import { SurfaceLevelProvider } from '../styles/surface-levels';
@@ -51,6 +52,8 @@ import {
   PANEL_RADIUS,
   SIDE_SHEET_MIN_GUTTER,
   useResolvedPlacement,
+  physicalDialogSide,
+  type DialogSidePlacement,
 } from './placement';
 import type {
   DialogAction,
@@ -137,9 +140,9 @@ function CenteredOrSideDialog({
   containerClassName,
   label,
   children,
-}: Omit<DialogProps, 'placement'> & { placement: 'center' | 'left' | 'right' }) {
+}: Omit<DialogProps, 'placement'> & { placement: 'center' | DialogSidePlacement }) {
   const isControlled = controlledOpen !== undefined;
-  const isSide = placement === 'left' || placement === 'right';
+  const isSide = placement !== 'center';
   const headerController = useDialogHeaderController();
   const scrollableResolved = scrollable ?? true;
   const { height: viewportHeight } = useWindowDimensions();
@@ -422,7 +425,7 @@ function SideSheet({
 }: {
   open: boolean;
   onDismiss: () => void;
-  side: 'left' | 'right';
+  side: DialogSidePlacement;
   width: number;
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
@@ -453,8 +456,16 @@ function SideSheet({
   const insetBottom = inset?.bottom ?? 0;
   const insetLeft = inset?.left ?? 0;
   const insetRight = inset?.right ?? 0;
-  const anchorInset = side === 'left' ? insetLeft : insetRight;
-  const oppositeInset = side === 'left' ? insetRight : insetLeft;
+  // `start`/`end` resolve to the physical edge they land on for everything a
+  // layout engine does not mirror: the slide sign, and which `inset` applies.
+  const rtl = useIsRtl();
+  const edge = physicalDialogSide(side, rtl);
+  // The POSITION of a logical placement is a logical key, resolved by Yoga
+  // against `I18nManager` — a physical `left`/`right` here would be swapped by
+  // React Native's default `swapLeftAndRightInRTL` and land on the wrong edge.
+  const anchorKey = side === 'start' ? 'insetInlineStart' : side === 'end' ? 'insetInlineEnd' : side;
+  const anchorInset = edge === 'left' ? insetLeft : insetRight;
+  const oppositeInset = edge === 'left' ? insetRight : insetLeft;
 
   const sideWidth = useMemo(() => {
     const available = viewportWidth - anchorInset - oppositeInset - SIDE_SHEET_MIN_GUTTER;
@@ -491,7 +502,7 @@ function SideSheet({
     if (dismissOnBackdrop) onDismiss();
   }, [dismissOnBackdrop, onDismiss]);
 
-  const hiddenSign = side === 'left' ? -1 : 1;
+  const hiddenSign = edge === 'left' ? -1 : 1;
   const panelAnimatedStyle = useAnimatedStyle(() => {
     const hidden = 1 - progress.value;
     return {
@@ -513,11 +524,11 @@ function SideSheet({
       ({
         top: insetTop,
         bottom: insetBottom,
-        [side]: anchorInset,
+        [anchorKey]: anchorInset,
         width: sideWidth,
         borderRadius: PANEL_RADIUS,
       }),
-    [insetTop, insetBottom, side, anchorInset, sideWidth],
+    [insetTop, insetBottom, anchorKey, anchorInset, sideWidth],
   );
 
   if (!mounted) return null;

package/src/dialog/Dialog.web.tsx

@@ -45,6 +45,7 @@ import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { useTheme } from '../theme/use-theme';
+import { useIsRtl } from '../hooks/use-is-rtl';
 import { Context, useDialogContext, useDialogControl } from './context';
 import { DialogBody } from './DialogContent';
 import { DialogBottomSheet } from './DialogBottomSheet';
@@ -69,6 +70,8 @@ import {
   PANEL_RADIUS,
   SIDE_SHEET_MIN_GUTTER,
   useResolvedPlacement,
+  physicalDialogSide,
+  type DialogSidePlacement,
 } from './placement';
 import type {
   DialogAction,
@@ -196,7 +199,7 @@ function CenterOrSideDialog({
   containerClassName,
   label,
   children,
-}: Omit<DialogProps, 'placement'> & { placement: 'center' | 'left' | 'right' }) {
+}: Omit<DialogProps, 'placement'> & { placement: 'center' | DialogSidePlacement }) {
   // Inject the required @keyframes on mount (before the panel ever appears —
   // this component renders once with `isOpen=false` prior to opening, so the
   // stylesheet is present by the time the animated surface mounts).
@@ -647,7 +650,7 @@ function SheetSurface({
   actions?: DialogAction[];
   header?: DialogProps['header'];
   scrollable?: boolean;
-  placement: 'left' | 'right';
+  placement: DialogSidePlacement;
   shown: boolean;
   width: number;
   inset?: DialogInset;
@@ -666,6 +669,7 @@ function SheetSurface({
   const descriptionId = useId();
   const headerController = useDialogHeaderController();
   const { width: viewportWidth } = useWindowDimensions();
+  const rtl = useIsRtl();
 
   // Defer the entry transition by a frame so the start state paints before the
   // browser animates to `shown`. `entered` is false on the first committed
@@ -707,22 +711,26 @@ function SheetSurface({
     const insetBottom = inset?.bottom ?? 0;
     const insetLeft = inset?.left ?? 0;
     const insetRight = inset?.right ?? 0;
-    const anchorInset = placement === 'left' ? insetLeft : insetRight;
-    const oppositeInset = placement === 'left' ? insetRight : insetLeft;
+    // `start`/`end` land on a physical edge read from `useIsRtl()`. The drawer
+    // is portaled outside any `dir` context, so react-native-web would resolve
+    // a logical key left-to-right; the physical edge is the one that is right.
+    const edge = physicalDialogSide(placement, rtl);
+    const anchorInset = edge === 'left' ? insetLeft : insetRight;
+    const oppositeInset = edge === 'left' ? insetRight : insetLeft;
     const available = viewportWidth - anchorInset - oppositeInset - SIDE_SHEET_MIN_GUTTER;
     const cappedWidth = Math.max(0, Math.min(width, available));
-    const hiddenSign = placement === 'left' ? '-100%' : '100%';
+    const hiddenSign = edge === 'left' ? '-100%' : '100%';
 
     return {
       top: insetTop,
       bottom: insetBottom,
-      [placement]: anchorInset,
+      [edge]: anchorInset,
       width: cappedWidth,
       borderRadius: PANEL_RADIUS,
       transform: [{ translateX: visible ? 0 : hiddenSign }],
       opacity: visible ? 1 : 0,
     };
-  }, [visible, placement, width, inset, viewportWidth]);
+  }, [visible, placement, rtl, width, inset, viewportWidth]);
 
   const handleBackdropPress = useCallback(() => {
     if (dismissOnBackdrop) onDismiss();

package/src/dialog/placement.ts

@@ -7,10 +7,27 @@ import { BREAKPOINTS } from '../styles/breakpoints';
  * Anchor a `<Dialog>` can render against.
  *
  * - `'center'` — the default centered modal card (current behavior).
- * - `'left'` / `'right'` — an anchored side-sheet / drawer.
+ * - `'left'` / `'right'` — an anchored side-sheet / drawer on that PHYSICAL edge.
+ * - `'start'` / `'end'` — the same drawer on the LOGICAL edge: `start` is the
+ *   left in a left-to-right layout and the right in a right-to-left one, and it
+ *   slides in from that edge. Resolved with `useIsRtl()`.
  * - `'bottom'` — a bottom-sheet (drag handle, slide-up).
  */
-export type DialogPlacement = 'center' | 'left' | 'right' | 'bottom';
+export type DialogPlacement = 'center' | 'left' | 'right' | 'start' | 'end' | 'bottom';
+
+/** The four side-sheet placements, physical and logical. */
+export type DialogSidePlacement = 'left' | 'right' | 'start' | 'end';
+
+/**
+ * The PHYSICAL edge a side placement lands on. `left`/`right` are themselves;
+ * `start` is `left` left-to-right and `right` right-to-left, `end` the reverse.
+ * The panel's `translateX` sign, which no layout engine mirrors, follows this.
+ */
+export function physicalDialogSide(side: DialogSidePlacement, rtl: boolean): 'left' | 'right' {
+  if (side === 'start') return rtl ? 'right' : 'left';
+  if (side === 'end') return rtl ? 'left' : 'right';
+  return side;
+}
 
 /**
  * A `<Dialog>` placement that may vary by viewport width.

package/src/dialog/types.ts

@@ -256,8 +256,9 @@ export type DialogProps = React.PropsWithChildren<{
   actions?: DialogAction[];
   /**
    * Surface anchor. Defaults to `'center'` (the centered modal — current
-   * behavior). `'left'`/`'right'` render an anchored side-sheet, `'bottom'` a
-   * bottom-sheet. A responsive map resolves by viewport width, e.g.
+   * behavior). `'left'`/`'right'` render an anchored side-sheet on that
+   * physical edge; `'start'`/`'end'` on the logical edge (mirrored, with its
+   * slide-in, in a right-to-left layout); `'bottom'` a bottom-sheet. A responsive map resolves by viewport width, e.g.
    * `{ base: 'bottom', md: 'left' }` (drawer on wide, sheet on narrow).
    */
   placement?: ResponsiveDialogPlacement;

package/src/loading/Loading.tsx

@@ -18,7 +18,7 @@ import { resolveBloomColors } from '../appearance/colors';
 import { useBloomAppearance } from '../appearance';
 import { animation } from '../styles/tokens';
 import { useTheme } from '../theme/use-theme';
-import { bindLoading, SIZE_CONFIG, styles } from './LoadingBase';
+import { bindLoading, LoadingRoot, SIZE_CONFIG, styles } from './LoadingBase';
 import { SpinnerIcon } from './SpinnerIcon';
 import type { TopLoadingProps } from './types';
 
@@ -31,6 +31,7 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   iconSize,
   heightOffset = 0,
   spinnerIcon,
+  accessibilityLabel,
   testID,
 }) => {
   const theme = useTheme();
@@ -69,7 +70,10 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   return (
     <Animated.View style={[styles.topContainer, containerAnimated]} testID={testID}>
       <Animated.View style={[styles.topLoadingView, { height: targetHeight }, innerAnimated, style]}>
-        {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        {/* Named only while it is showing: a collapsed bar is not a wait. */}
+        <LoadingRoot accessibilityLabel={showLoading ? accessibilityLabel : undefined}>
+          {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        </LoadingRoot>
       </Animated.View>
     </Animated.View>
   );

package/src/loading/Loading.web.tsx

@@ -16,7 +16,7 @@ import { useBloomAppearance } from '../appearance';
 import { animation } from '../styles/tokens';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
-import { bindLoading, SIZE_CONFIG, styles } from './LoadingBase';
+import { bindLoading, LoadingRoot, SIZE_CONFIG, styles } from './LoadingBase';
 import { SpinnerIcon } from './SpinnerIcon.web';
 import type { TopLoadingProps } from './types';
 
@@ -41,6 +41,7 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   iconSize,
   heightOffset = 0,
   spinnerIcon,
+  accessibilityLabel,
   testID,
 }) => {
   const theme = useTheme();
@@ -84,7 +85,10 @@ const TopLoading: React.FC<TopLoadingProps> = ({
           style,
         ]}
       >
-        {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        {/* Named only while it is showing: a collapsed bar is not a wait. */}
+        <LoadingRoot accessibilityLabel={showLoading ? accessibilityLabel : undefined}>
+          {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        </LoadingRoot>
       </View>
     </View>
   );

package/src/loading/LoadingBase.tsx

@@ -23,7 +23,7 @@ import { normalizeBloomSize } from '../appearance/legacy';
 import { resolveBloomColors } from '../appearance/colors';
 import { useBloomAppearance } from '../appearance';
 import React, { memo } from 'react';
-import { View, Text, StyleSheet } from 'react-native';
+import { View, Text, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
 import type {
@@ -41,6 +41,54 @@ export const SIZE_CONFIG = {
   lg: { spinner: 44, text: 16 },
 } as const;
 
+/**
+ * The indicator's root: an indeterminate, NAMED `progressbar` when the caller
+ * gave `accessibilityLabel`, a plain view (today's behaviour) when not.
+ *
+ * Flat `aria-*` because react-native-web drops `accessibilityState` /
+ * `accessibilityValue`; React Native folds them back. `aria-valuenow` is
+ * deliberately absent (`undefined`): that is what makes a progressbar
+ * INDETERMINATE in ARIA, and a spinner has no amount done to report. The role
+ * is a literal on its own branch so `aria-state-source-census.test.ts` can read
+ * it; a computed role would be invisible to it.
+ */
+export function LoadingRoot({
+  accessibilityLabel,
+  style,
+  testID,
+  children,
+}: {
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  children: React.ReactNode;
+}) {
+  if (accessibilityLabel) {
+    return (
+      <View
+        role="progressbar"
+        accessible
+        accessibilityLabel={accessibilityLabel}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={undefined}
+        aria-busy
+        style={style}
+        testID={testID}
+      >
+        {children}
+      </View>
+    );
+  }
+  // Nothing to carry (the `top` variant's inner slot): no extra node at all.
+  if (style === undefined && testID === undefined) return <>{children}</>;
+  return (
+    <View style={style} testID={testID}>
+      {children}
+    </View>
+  );
+}
+
 /** The two platform pieces a fork supplies. */
 export interface LoadingPlatform {
   /** Forked: react-native-svg on native, a DOM `<svg>` on web. */
@@ -61,6 +109,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     showText = true,
     iconSize,
     spinnerIcon,
+    accessibilityLabel,
     testID,
   }) => {
     const theme = useTheme();
@@ -71,7 +120,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     const textColor = color ?? theme.colors.textSecondary;
 
     return (
-      <View style={[styles.container, style]} testID={testID}>
+      <LoadingRoot accessibilityLabel={accessibilityLabel} style={[styles.container, style]} testID={testID}>
         {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} className={className} />}
         {showText && text && (
           <Text
@@ -84,7 +133,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
             {text}
           </Text>
         )}
-      </View>
+      </LoadingRoot>
     );
   };
 
@@ -96,6 +145,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     style,
     textStyle,
     spinnerIcon,
+    accessibilityLabel,
     testID,
   }) => {
     const theme = useTheme();
@@ -105,7 +155,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     const textColor = theme.colors.textSecondary;
 
     return (
-      <View style={[styles.inlineContainer, style]} testID={testID}>
+      <LoadingRoot accessibilityLabel={accessibilityLabel} style={[styles.inlineContainer, style]} testID={testID}>
         {spinnerIcon ?? <SpinnerIcon size={sizeConfig.spinner} color={spinnerColor} />}
         {text && (
           <Text
@@ -117,7 +167,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
             {text}
           </Text>
         )}
-      </View>
+      </LoadingRoot>
     );
   };
 

package/src/loading/types.ts

@@ -20,6 +20,17 @@ interface BaseLoadingProps {
   style?: ViewStyle;
   /** Whether loading is active (for animated variants) */
   showLoading?: boolean;
+  /**
+   * Names the indicator and makes it an indeterminate `progressbar` to
+   * assistive technology (`role="progressbar"` with `aria-label` and
+   * `aria-busy` on web; the same role, label and busy state natively). A
+   * spinner draws no words, so nothing else can say what is loading.
+   *
+   * Opt-in: without it the indicator carries no role, as before — which is
+   * right when it sits INSIDE a named progressbar already (an upload overlay),
+   * where a second one would announce the same wait twice.
+   */
+  accessibilityLabel?: string;
   testID?: string;
 }