@oxy.so/bloom 4.0.0 → 4.2.0

package/src/payment-method/PaymentMethodRow.tsx

@@ -0,0 +1,210 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { Badge } from '../badge';
+import { Item } from '../item';
+import { RadioIndicator } from '../radio-indicator';
+import { useSurfaceFill } from '../styles/surface-levels';
+import { space } from '../styles/tokens';
+import { resolveAccentColors } from '../theme/accent-colors';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { PaymentMethodMark } from './PaymentMethodMark';
+import { PAYMENT_METHOD_GEOMETRY, PAYMENT_METHOD_STATE_TONE } from './constants';
+import { composePaymentMethodName, paymentMethodStateMessage, resolvePaymentMethodPaint } from './shared';
+import type { PaymentMethodRowProps } from './types';
+
+/**
+ * A way to pay, as a row: the mark, the scheme, the masked identifier, when it
+ * runs out, whether it is the default one, and either a trailing action or a
+ * selection control.
+ *
+ * It is `Item` with a payment method's slots filled in, for the same reason
+ * `AddressRow` is: the row, the press target, the selected wash, the density
+ * rungs, the disabled opacity and the ARIA role translation are `Item`'s job,
+ * and this family owns no second copy of any of them. What it adds is the card
+ * plate, the scheme/masked pairing on the title line, the default badge, the
+ * state line and the radio dot.
+ *
+ *   mark     `PaymentMethodMark`, plate only — the row draws the name itself,
+ *            so the title line can hold the masked tail and the badge too
+ *   title    scheme in `Item`'s own title rung; the masked identifier beside it
+ *            in body-2 TABULAR figures, so four rows of digits line up
+ *   line 2   the expiry, secondary
+ *   line 3   the state's words in the state's own colour, drawn only when the
+ *            method cannot be used
+ *   trailing the radio dot (`selectable`) or the action
+ *
+ * NOTHING HERE IS SENSITIVE. `masked` is a string the app already masked; this
+ * row never unmasks, parses, stores, logs or transmits anything, and there is no
+ * prop that takes a full number.
+ */
+function PaymentMethodRowComponent({
+  scheme,
+  masked,
+  expiry,
+  kind = 'card',
+  icon,
+  image,
+  leading,
+  isDefault = false,
+  defaultLabel = 'Default',
+  state = 'ok',
+  stateMessage,
+  selectable = false,
+  selected,
+  action,
+  onPress,
+  disabled = false,
+  density = 'comfortable',
+  role,
+  accessibilityLabel,
+  style,
+  testID,
+}: PaymentMethodRowProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolvePaymentMethodPaint(theme, surface), [theme, surface]);
+  const g = PAYMENT_METHOD_GEOMETRY[density];
+  const tone = PAYMENT_METHOD_STATE_TONE[state];
+  const stateWords = paymentMethodStateMessage(state, stateMessage);
+  // The state's words are read as TEXT on the row's own surface, so they take
+  // the tone's `accent` member (`outlined` foreground) rather than the fill.
+  const stateColor = tone ? resolveAccentColors(theme.colors, tone, 'outlined').foreground : undefined;
+
+  const media =
+    leading !== undefined ? (
+      leading
+    ) : (
+      <PaymentMethodMark
+        kind={kind}
+        icon={icon}
+        image={image}
+        state={state}
+        density={density}
+        testID={testID ? `${testID}-mark` : undefined}
+      />
+    );
+
+  const titleNode = (
+    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8, minWidth: 0 }}>
+      {scheme ? (
+        <Text
+          variant="headline-medium"
+          numberOfLines={1}
+          testID={testID ? `${testID}-scheme` : undefined}
+          style={{ flexShrink: 1, minWidth: 0, color: paint.text }}
+        >
+          {scheme}
+        </Text>
+      ) : null}
+      {masked ? (
+        <Text
+          variant="body-2-regular"
+          numberOfLines={1}
+          testID={testID ? `${testID}-masked` : undefined}
+          style={{ flexShrink: 1, minWidth: 0, color: paint.textSecondary, fontVariant: ['tabular-nums'] }}
+        >
+          {masked}
+        </Text>
+      ) : null}
+      {isDefault ? (
+        // The badge does not SHRINK: it is two or three words that mean
+        // "this is the one", and a truncated "D…" says nothing. The masked
+        // identifier beside it gives way instead, which is the part a reader
+        // can still recognise from its first characters.
+        <View style={{ flexShrink: 0 }}>
+          <Badge
+            content={defaultLabel}
+            variant="subtle"
+            color="primary"
+            size="label-small"
+            testID={testID ? `${testID}-default` : undefined}
+          />
+        </View>
+      ) : null}
+    </View>
+  );
+
+  const subtitleNode =
+    expiry || stateWords ? (
+      <View style={{ gap: 2, minWidth: 0 }}>
+        {expiry ? (
+          <Text
+            variant="body-2-regular"
+            numberOfLines={1}
+            testID={testID ? `${testID}-expiry` : undefined}
+            style={{ color: paint.textSecondary, fontVariant: ['tabular-nums'] }}
+          >
+            {expiry}
+          </Text>
+        ) : null}
+        {stateWords ? (
+          <Text
+            variant="body-2-medium"
+            numberOfLines={2}
+            testID={testID ? `${testID}-state` : undefined}
+            style={{ color: stateColor ?? paint.textSecondary }}
+          >
+            {stateWords}
+          </Text>
+        ) : null}
+      </View>
+    ) : null;
+
+  // A PRESSABLE row is a real `<button>` on web, so a control cannot live
+  // inside it: a button in a button is invalid HTML and, unlike native, a web
+  // click on the inner control ALSO fires the row. The selection DOT is not a
+  // control — it draws no press target of its own — so it stays inside; an
+  // `action` does not. The mechanism is measured in `address/AddressRow.tsx`.
+  const splitAction = action != null && onPress != null;
+
+  const trailing = selectable ? (
+    <RadioIndicator
+      selected={selected === true}
+      size={g.dot}
+      testID={testID ? `${testID}-dot` : undefined}
+    />
+  ) : splitAction ? null : (
+    (action ?? null)
+  );
+
+  const row = (
+    <Item
+      title={titleNode}
+      subtitle={subtitleNode}
+      leading={media}
+      trailing={trailing}
+      onPress={onPress}
+      disabled={disabled}
+      selected={selected}
+      density={density}
+      role={role}
+      accessibilityLabel={
+        accessibilityLabel ??
+        composePaymentMethodName([scheme, masked, expiry, isDefault && defaultLabel, stateWords])
+      }
+      // `paddingRight`, never `paddingHorizontal`: `Item` writes the longhand,
+      // and on web a shorthand here would outrank it while native honoured it.
+      style={splitAction ? { paddingRight: space.sm } : style}
+      testID={testID}
+    />
+  );
+
+  if (!splitAction) return row;
+
+  return (
+    <View style={[{ flexDirection: 'row', alignItems: 'center', paddingRight: space.lg }, style]}>
+      {/*
+        `Item`'s `style` lands on its CONTENT view, one node below the flex
+        child the parent actually lays out, so the flex goes on a wrapper the
+        parent can see. Same shape as `AddressRow`.
+      */}
+      <View style={{ flex: 1, minWidth: 0 }}>{row}</View>
+      {action}
+    </View>
+  );
+}
+
+export const PaymentMethodRow = memo(PaymentMethodRowComponent);
+PaymentMethodRow.displayName = 'PaymentMethodRow';

package/src/payment-method/constants.ts

@@ -0,0 +1,61 @@
+import { RiBankCardLine } from '../icons/remix/RiBankCardLine';
+import { RiBankLine } from '../icons/remix/RiBankLine';
+import { RiCoinsLine } from '../icons/remix/RiCoinsLine';
+import { RiWallet3Line } from '../icons/remix/RiWallet3Line';
+import type { BloomIconComponent } from '../icons/icon-component';
+import type { AccentTone } from '../theme/accent-colors';
+import type { PaymentMethodDensity, PaymentMethodKind, PaymentMethodState } from './types';
+
+/** The glyph each kind draws when the caller names none. */
+export const PAYMENT_METHOD_KIND_ICON: Record<PaymentMethodKind, BloomIconComponent> = {
+  card: RiBankCardLine,
+  account: RiBankLine,
+  wallet: RiWallet3Line,
+  cash: RiCoinsLine,
+};
+
+/** What the row says under itself when a state has no message of its own. */
+export const PAYMENT_METHOD_STATE_LABELS: Record<PaymentMethodState, string> = {
+  ok: '',
+  expired: 'Expired',
+  declined: 'Declined',
+};
+
+/**
+ * The tone each state paints. `ok` paints nothing — an ordinary row is not a
+ * status.
+ */
+export const PAYMENT_METHOD_STATE_TONE: Record<PaymentMethodState, AccentTone | undefined> = {
+  ok: undefined,
+  expired: 'warning',
+  declined: 'error',
+};
+
+export interface PaymentMethodGeometry {
+  /** The plate the glyph sits on: wider than tall, which is what says "card". */
+  plateWidth: number;
+  plateHeight: number;
+  plateRadius: number;
+  /** The glyph inside it. */
+  glyph: number;
+  /** The radio dot in the trailing slot. */
+  dot: number;
+}
+
+/**
+ * 40 wide is the leading column `Item` rows across the library already use
+ * (`address`'s tile is 40 round), so a checkout screen stacking an address row
+ * and a payment row does not step sideways between them. 28 tall against 40
+ * wide is the ratio that reads as a card rather than a square tile, and it is
+ * the one measurement in this family that is about SHAPE rather than size.
+ */
+export const PAYMENT_METHOD_GEOMETRY: Record<PaymentMethodDensity, PaymentMethodGeometry> = {
+  comfortable: { plateWidth: 40, plateHeight: 28, plateRadius: 6, glyph: 18, dot: 16 },
+  compact: { plateWidth: 32, plateHeight: 22, plateRadius: 5, glyph: 14, dot: 14 },
+};
+
+/** Space between the plate and the name, inside a `PaymentMethodMark`. */
+export const PAYMENT_METHOD_MARK_GAP = 8;
+
+/** Space between the rows of a list, and between the list and its add row. */
+export const PAYMENT_METHOD_LIST_GAP = 4;

package/src/payment-method/index.ts

@@ -0,0 +1,24 @@
+export { PaymentMethodList } from './PaymentMethodList';
+export { PaymentMethodMark } from './PaymentMethodMark';
+export { PaymentMethodRow } from './PaymentMethodRow';
+export {
+  PAYMENT_METHOD_GEOMETRY,
+  PAYMENT_METHOD_KIND_ICON,
+  PAYMENT_METHOD_LIST_GAP,
+  PAYMENT_METHOD_MARK_GAP,
+  PAYMENT_METHOD_STATE_LABELS,
+  PAYMENT_METHOD_STATE_TONE,
+} from './constants';
+export type { PaymentMethodGeometry } from './constants';
+export { composePaymentMethodName, paymentMethodStateMessage, resolvePaymentMethodPaint } from './shared';
+export type { PaymentMethodPaint } from './shared';
+export type {
+  PaymentMethodDensity,
+  PaymentMethodEntry,
+  PaymentMethodKind,
+  PaymentMethodListProps,
+  PaymentMethodListVariant,
+  PaymentMethodMarkProps,
+  PaymentMethodRowProps,
+  PaymentMethodState,
+} from './types';

package/src/payment-method/shared.ts

@@ -0,0 +1,50 @@
+/**
+ * What a payment-method row paints, read RELATIVE to the surface it was dropped
+ * on (`styles/surface-levels.ts`) — a saved-methods screen sits on the page, a
+ * checkout picker sits in a card and a sheet's picker sits two rungs up, and a
+ * plate colour picked by eye disappears on one of the three.
+ *
+ * Pure, so `PaymentMethod.test.tsx` can walk presets and modes without
+ * rendering.
+ */
+import { surfaceFillOn, surfaceTextOn, type SurfaceTextPaint } from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+import { PAYMENT_METHOD_STATE_LABELS } from './constants';
+import type { PaymentMethodState } from './types';
+
+export interface PaymentMethodPaint extends SurfaceTextPaint {
+  /** The plate the mark's glyph sits on — one step off whatever is behind the row. */
+  plate: string;
+}
+
+export function resolvePaymentMethodPaint(theme: Theme, surface: string): PaymentMethodPaint {
+  return {
+    ...surfaceTextOn(theme, surface),
+    plate: surfaceFillOn(theme, surface),
+  };
+}
+
+/** Joins the non-empty parts of an accessible name, in reading order. */
+export function composePaymentMethodName(
+  parts: ReadonlyArray<string | false | null | undefined>,
+  separator = ', ',
+): string {
+  return parts
+    .filter((part): part is string => typeof part === 'string' && part !== '')
+    .join(separator);
+}
+
+/**
+ * The words a state says when the caller gave no message.
+ *
+ * `ok` has none: an ordinary method is not a status, and a row that said "OK"
+ * under every card would be noise a reader has to read past four times.
+ */
+export function paymentMethodStateMessage(
+  state: PaymentMethodState,
+  message?: string,
+): string | undefined {
+  if (typeof message === 'string' && message !== '') return message;
+  const label = PAYMENT_METHOD_STATE_LABELS[state];
+  return label === '' ? undefined : label;
+}

package/src/payment-method/types.ts

@@ -0,0 +1,190 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { BloomIconComponent } from '../icons/icon-component';
+
+/**
+ * WHAT KIND OF THING PAYS — data, not four components.
+ *
+ * It chooses the default glyph on the mark and nothing else: a card, a bank
+ * account the charge is drawn from, a stored balance, or money handed over at
+ * the door. An app whose kinds are not these four passes `icon`.
+ */
+export type PaymentMethodKind = 'card' | 'account' | 'wallet' | 'cash';
+
+/**
+ * Whether the method can still be used.
+ *
+ * `ok` is the ordinary case. `expired` and `declined` are the two an app has to
+ * be able to draw, and they are STATES rather than tones: the row picks the
+ * warning/error paint itself so two screens cannot disagree about which colour
+ * a declined card is.
+ */
+export type PaymentMethodState = 'ok' | 'expired' | 'declined';
+
+export type PaymentMethodDensity = 'comfortable' | 'compact';
+
+/**
+ * `list` is a set of saved methods a reader is managing; `picker` is a set they
+ * are choosing ONE of. The difference is the announced tree — a `radiogroup` of
+ * `radio`s against a `list` of `listitem`s — which is why it is a variant and
+ * not a styling prop.
+ */
+export type PaymentMethodListVariant = 'list' | 'picker';
+
+/**
+ * The brand mark.
+ *
+ * **Bloom never draws a brand's logo.** The mark is a neutral glyph on a plate
+ * the shape of a card, and the scheme's NAME as text beside it. An app that has
+ * the rights to a logo passes it as `image`, which replaces the glyph — the
+ * plate, the geometry and the name stay Bloom's.
+ */
+export interface PaymentMethodMarkProps {
+  /**
+   * The scheme's name, spelled by the APP — Bloom ships no list of schemes.
+   * Drawn as text beside the plate. Omit it for the plate alone, which is what
+   * `PaymentMethodRow` does: the row already draws the name in its title.
+   */
+  scheme?: string;
+  /** Chooses the default glyph. Default `card`. */
+  kind?: PaymentMethodKind;
+  /** The glyph, overriding whatever `kind` would have chosen. */
+  icon?: BloomIconComponent;
+  /**
+   * An image the app has the rights to, drawn inside the plate instead of the
+   * glyph. Read for PRESENCE, so `image={null}` is an empty plate rather than
+   * the glyph.
+   */
+  image?: ReactNode;
+  /** Paints the plate in the state's tone. Default `ok`. */
+  state?: PaymentMethodState;
+  /** Default `comfortable`. */
+  density?: PaymentMethodDensity;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface PaymentMethodRowProps {
+  /** The scheme's name, spelled by the app — "Aurora", "Meridian". */
+  scheme?: string;
+  /**
+   * The MASKED identifier — `"•••• 4417"`, `"ES•• •••• 8842"`, `"nil@example"`.
+   *
+   * The app masks it. Nothing in this family unmasks, parses, stores or
+   * transmits anything, and a full number should never reach this prop.
+   */
+  masked?: string;
+  /**
+   * Pre-formatted by the app: `"09/29"`, `"Expires 09/29"`. Bloom never reads a
+   * clock, so whether that date is in the past is the app's finding, reported
+   * through `state`.
+   */
+  expiry?: string;
+  /** Chooses the default glyph on the mark. Default `card`. */
+  kind?: PaymentMethodKind;
+  /** The glyph, overriding whatever `kind` would have chosen. */
+  icon?: BloomIconComponent;
+  /** An image the app has the rights to, drawn inside the plate. */
+  image?: ReactNode;
+  /**
+   * An arbitrary leading node instead of the mark. Read for PRESENCE:
+   * `leading={null}` draws no media at all.
+   */
+  leading?: ReactNode;
+  /** Marks this as the one that will be charged. Draws a `Badge`. */
+  isDefault?: boolean;
+  /** The default badge's word. Default `"Default"`. */
+  defaultLabel?: string;
+  /** Default `ok`. */
+  state?: PaymentMethodState;
+  /**
+   * The words under the row when `state` is not `ok` — "Declined by your bank",
+   * "This card expired in June". Without it the row draws the state's own
+   * label.
+   */
+  stateMessage?: string;
+  /**
+   * Draws the radio dot in the trailing slot and announces the row as a
+   * `radio`. `PaymentMethodList variant="picker"` sets it; set it yourself only
+   * for a row inside a `radiogroup` of your own.
+   */
+  selectable?: boolean;
+  /** Whether this is the chosen one. Announced as `aria-checked` on a `radio`. */
+  selected?: boolean;
+  /**
+   * A trailing control — a `GlyphButton` with the row's menu, a `Button`.
+   *
+   * A PRESSABLE row cannot nest one: on web the row is a real `<button>`, so
+   * the action is drawn beside the row instead of inside it. See `AddressRow`,
+   * where the same rule is measured.
+   */
+  action?: ReactNode;
+  onPress?: () => void;
+  disabled?: boolean;
+  /** Default `comfortable`. */
+  density?: PaymentMethodDensity;
+  /**
+   * What the row IS in the tree around it. `PaymentMethodList` passes this; a
+   * row on its own leaves it alone and gets a plain pressable row.
+   */
+  role?: 'radio' | 'option' | 'listitem';
+  /**
+   * The announced name. Defaults to the scheme, the masked identifier, the
+   * default mark and the state, joined — the row's own text in reading order.
+   */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** One saved method, as data. */
+export interface PaymentMethodEntry
+  extends Omit<PaymentMethodRowProps, 'onPress' | 'selected' | 'selectable' | 'role'> {
+  /** Identifies the entry to `onSelect` and `selectedId`. */
+  id: string;
+}
+
+export interface PaymentMethodListProps {
+  /** The saved methods, in the order they should be read. */
+  methods: readonly PaymentMethodEntry[];
+  /** The chosen entry's `id`. Only meaningful for `variant="picker"`. */
+  selectedId?: string;
+  onSelect?: (id: string) => void;
+  /** Default `list`. */
+  variant?: PaymentMethodListVariant;
+  /** Default `comfortable`. */
+  density?: PaymentMethodDensity;
+  /**
+   * Disables every row. Combined with an enclosing `Field`'s `disabled` with
+   * `||`, never replaced — a row inside a disabled field cannot re-enable
+   * itself.
+   */
+  disabled?: boolean;
+  /** Draws the "add a method" row under the list. Without it no row is drawn. */
+  onAdd?: () => void;
+  /** Default `"Add a payment method"`. */
+  addLabel?: string;
+  /** The glyph on the add row. Default a plus. */
+  addIcon?: BloomIconComponent;
+  /** Draws placeholder rows instead of the methods. */
+  loading?: boolean;
+  /** How many placeholder rows. Default 3. */
+  loadingRows?: number;
+  /** Replaces the whole empty block. The add row is still drawn under it. */
+  empty?: ReactNode;
+  /** Default `"No saved payment methods"`. */
+  emptyTitle?: string;
+  emptyDescription?: string;
+  /** The glyph above the empty text. Default a card. */
+  emptyIcon?: BloomIconComponent;
+  /**
+   * Names the list — and, for a picker, the `radiogroup`.
+   *
+   * Inside a `Field` the field's label supplies it; this wins when both are
+   * given. `"Payment methods"` is the last resort.
+   */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/payment-status/PaymentStatusBar.tsx

@@ -0,0 +1,67 @@
+import React, { memo } from 'react';
+
+import { OrderStatusBar } from '../order-status';
+import { resolvePaymentStatus } from './shared';
+import type { PaymentStatusBarProps } from './types';
+
+/**
+ * The compact live strip: what happened to the money, how much, and one action.
+ *
+ * ## It IS `OrderStatusBar`
+ *
+ * Not a second strip that looks like it. `order-status` already owns the
+ * library's answer to "where is this right now": the 40 tile in the tone's
+ * tint, the one-line status with a short trailing reading in tabular figures, a
+ * quiet second line, a `Meter` for progress, the surface-relative chrome and
+ * the `plain` variant for a strip already inside a card. A payment is the same
+ * question with different data, and shipping a second strip would mean two
+ * components drifting apart on every one of those decisions.
+ *
+ * What this adds is the mapping a payment needs and an order does not: five
+ * states to five sets of words, five tones and five glyphs, in one place
+ * (`constants.ts`) so a status row and a confirmation screen cannot disagree
+ * about what "pending" is called or what colour it is.
+ *
+ * ## The amount rides the trailing reading
+ *
+ * `OrderStatusBar`'s trailing slot is a short reading in tabular figures,
+ * capped so it cannot crush the status beside it — which is exactly what an
+ * amount is. Its PROP is spelled `eta`, because an order was the first thing
+ * that needed it; the slot is general and this is the second. That naming is
+ * worth fixing in `order-status`, and it is that family's to fix.
+ *
+ * Nothing here formats money: `amount` is a string the app already formatted.
+ */
+function PaymentStatusBarComponent({
+  state,
+  status,
+  amount,
+  detail,
+  progress,
+  icon,
+  action,
+  variant = 'surface',
+  labels,
+  style,
+  testID,
+}: PaymentStatusBarProps) {
+  const presentation = resolvePaymentStatus(state, { status, labels, icon });
+
+  return (
+    <OrderStatusBar
+      status={presentation.words}
+      eta={amount}
+      detail={detail}
+      progress={progress}
+      tone={presentation.tone}
+      icon={presentation.icon}
+      action={action}
+      variant={variant}
+      style={style}
+      testID={testID}
+    />
+  );
+}
+
+export const PaymentStatusBar = memo(PaymentStatusBarComponent);
+PaymentStatusBar.displayName = 'PaymentStatusBar';