@oxy.so/bloom 4.0.0 → 4.2.0

package/src/payment-status/PaymentStatusBlock.tsx

@@ -0,0 +1,181 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { Admonition } from '../admonition';
+import {
+  SurfaceLevelProvider,
+  surfaceFillVars,
+  useSurfaceLevel,
+  useSurfaceLevelValue,
+  type SurfaceLevel,
+} from '../styles/surface-levels';
+import { resolveAccentColors } from '../theme/accent-colors';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { PAYMENT_STATUS_GEOMETRY } from './constants';
+import { resolvePaymentStatus, resolvePaymentStatusPaint } from './shared';
+import type { PaymentStatusBlockProps } from './types';
+
+/** The parts of the name, in reading order, with the empty ones dropped. */
+function composeName(parts: ReadonlyArray<string | undefined>): string {
+  return parts.filter((part): part is string => typeof part === 'string' && part !== '').join(', ');
+}
+
+/**
+ * The block form: a confirmation screen's answer, not a row's.
+ *
+ * `PaymentStatusBar` is the strip a list, a header or a sticky footer carries
+ * while something is in progress. This is the thing a reader ARRIVES at — so
+ * the glyph is the page's subject rather than a row's ornament, the amount is
+ * the largest thing on it, and the failure's words get an `Admonition` of their
+ * own rather than a second line.
+ *
+ *   tile     56 round in the state's tint, a 28 glyph in the tone's own accent
+ *   status   title-2-semibold, centred
+ *   amount   title-1-semibold in TABULAR figures — the number a reader checks
+ *   detail   body-regular, secondary
+ *   ref      caption-1-medium label over a body-medium tabular value, so a
+ *            reference can be read out one character at a time
+ *   reason   `Admonition`, error for a failure and warning for a pending one.
+ *            The three states with nothing to explain draw none, whatever
+ *            `reason` says — a reason under a success is a reader hunting for a
+ *            problem that is not there.
+ *   surface  one rung above whatever it was dropped on, 16 radius, a hairline;
+ *            `plain` draws the content and no chrome
+ *
+ * Nothing here formats money, reads a clock or decides what a processor's
+ * status means.
+ */
+function PaymentStatusBlockComponent({
+  state,
+  status,
+  amount,
+  detail,
+  reference,
+  referenceLabel = 'Reference',
+  reason,
+  actions,
+  icon,
+  variant = 'surface',
+  labels,
+  accessibilityLabel,
+  style,
+  testID,
+}: PaymentStatusBlockProps) {
+  const theme = useTheme();
+  const level = useSurfaceLevelValue();
+  const own = useSurfaceLevel(variant === 'surface' ? 1 : 0);
+  const paint = useMemo(
+    () => resolvePaymentStatusPaint(theme, own.background),
+    [theme, own.background],
+  );
+  const presentation = resolvePaymentStatus(state, { status, labels, icon });
+  const accent = resolveAccentColors(theme.colors, presentation.tone, 'subtle');
+  const Glyph = presentation.icon;
+  const g = PAYMENT_STATUS_GEOMETRY;
+  const showReason = presentation.admonition !== undefined && reason !== undefined && reason !== '';
+
+  const body = (
+    <View style={{ gap: g.gap, alignItems: 'stretch' }}>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <View
+          testID={testID ? `${testID}-tile` : undefined}
+          style={{
+            width: g.tile,
+            height: g.tile,
+            borderRadius: g.tile / 2,
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: accent.background,
+          }}
+        >
+          <Glyph width={g.glyph} height={g.glyph} fill={accent.foreground} />
+        </View>
+        <Text
+          variant="title-2-semibold"
+          testID={testID ? `${testID}-status` : undefined}
+          style={{ color: paint.text, textAlign: 'center' }}
+        >
+          {presentation.words}
+        </Text>
+        {amount ? (
+          <Text
+            variant="title-1-semibold"
+            testID={testID ? `${testID}-amount` : undefined}
+            style={{ color: paint.text, textAlign: 'center', fontVariant: ['tabular-nums'] }}
+          >
+            {amount}
+          </Text>
+        ) : null}
+        {detail ? (
+          <Text
+            variant="body-regular"
+            testID={testID ? `${testID}-detail` : undefined}
+            style={{ color: paint.textSecondary, textAlign: 'center' }}
+          >
+            {detail}
+          </Text>
+        ) : null}
+      </View>
+
+      {reference ? (
+        <View style={{ alignItems: 'center', gap: 2 }}>
+          <Text variant="caption-1-medium" style={{ color: paint.textSecondary }}>
+            {referenceLabel}
+          </Text>
+          <Text
+            variant="body-medium"
+            testID={testID ? `${testID}-reference` : undefined}
+            style={{ color: paint.text, fontVariant: ['tabular-nums'] }}
+          >
+            {reference}
+          </Text>
+        </View>
+      ) : null}
+
+      {showReason ? (
+        <Admonition type={presentation.admonition} style={{ width: '100%' }}>
+          {reason}
+        </Admonition>
+      ) : null}
+
+      {actions ? <View style={{ gap: 8 }}>{actions}</View> : null}
+    </View>
+  );
+
+  const name = accessibilityLabel ?? composeName([presentation.words, amount, detail]);
+
+  if (variant === 'plain') {
+    return (
+      <View accessibilityLabel={name} testID={testID} style={style}>
+        {body}
+      </View>
+    );
+  }
+
+  const raised = Math.min(3, level + 1) as SurfaceLevel;
+  return (
+    <View
+      accessibilityLabel={name}
+      testID={testID}
+      style={[
+        {
+          padding: g.padding,
+          borderRadius: 16,
+          borderWidth: 1,
+          borderColor: own.border,
+          backgroundColor: own.background,
+        },
+        surfaceFillVars(own.background),
+        style,
+      ]}
+    >
+      <SurfaceLevelProvider level={raised} fill={own.background}>
+        {body}
+      </SurfaceLevelProvider>
+    </View>
+  );
+}
+
+export const PaymentStatusBlock = memo(PaymentStatusBlockComponent);
+PaymentStatusBlock.displayName = 'PaymentStatusBlock';

package/src/payment-status/constants.ts

@@ -0,0 +1,85 @@
+import { RiArrowGoBackLine } from '../icons/remix/RiArrowGoBackLine';
+import { RiCheckboxCircleLine } from '../icons/remix/RiCheckboxCircleLine';
+import { RiCloseCircleLine } from '../icons/remix/RiCloseCircleLine';
+import { RiErrorWarningLine } from '../icons/remix/RiErrorWarningLine';
+import { RiTimeLine } from '../icons/remix/RiTimeLine';
+import type { BloomIconComponent } from '../icons/icon-component';
+import type { AccentTone } from '../theme/accent-colors';
+import type { PaymentStatusState } from './types';
+
+/**
+ * The words each state says.
+ *
+ * `"Payment failed"` rather than `"Failed"` because the strip is read on its
+ * own, in a row of other rows, where "Failed" is a word with no subject.
+ */
+export const PAYMENT_STATUS_LABELS: Record<PaymentStatusState, string> = {
+  authorising: 'Authorising',
+  paid: 'Paid',
+  failed: 'Payment failed',
+  refunded: 'Refunded',
+  pending: 'Payment pending',
+};
+
+/**
+ * The tone each state paints.
+ *
+ * `refunded` is `default` — the NEUTRAL tone — and that is the one decision
+ * here worth arguing about: money coming back is neither good news nor bad,
+ * and painting it green would congratulate a reader on a cancelled order while
+ * painting it red would alarm one who asked for it.
+ */
+export const PAYMENT_STATUS_TONE: Record<PaymentStatusState, AccentTone> = {
+  authorising: 'info',
+  paid: 'success',
+  failed: 'error',
+  refunded: 'default',
+  pending: 'warning',
+};
+
+/** The glyph each state draws when the caller names none. */
+export const PAYMENT_STATUS_ICON: Record<PaymentStatusState, BloomIconComponent> = {
+  authorising: RiTimeLine,
+  failed: RiCloseCircleLine,
+  paid: RiCheckboxCircleLine,
+  pending: RiErrorWarningLine,
+  refunded: RiArrowGoBackLine,
+};
+
+/**
+ * Which `Admonition` a state's reason is drawn in, and `undefined` for the
+ * three states that have no reason to give.
+ */
+export const PAYMENT_STATUS_ADMONITION: Record<
+  PaymentStatusState,
+  'error' | 'warning' | undefined
+> = {
+  authorising: undefined,
+  failed: 'error',
+  paid: undefined,
+  pending: 'warning',
+  refunded: undefined,
+};
+
+export interface PaymentStatusGeometry {
+  /** The round tile the block's glyph sits in. */
+  tile: number;
+  /** The glyph inside it. */
+  glyph: number;
+  /** Between the tile, the heading block, the reference and the actions. */
+  gap: number;
+  /** The block's own padding when it paints a surface. */
+  padding: number;
+}
+
+/**
+ * The block is a CONFIRMATION, so its tile is bigger than the strip's 40: 56 is
+ * the size at which a glyph reads as the page's subject rather than as a row's
+ * ornament, and it is the same tile an empty state uses two families over.
+ */
+export const PAYMENT_STATUS_GEOMETRY: PaymentStatusGeometry = {
+  tile: 56,
+  glyph: 28,
+  gap: 16,
+  padding: 20,
+};

package/src/payment-status/index.ts

@@ -0,0 +1,18 @@
+export { PaymentStatusBar } from './PaymentStatusBar';
+export { PaymentStatusBlock } from './PaymentStatusBlock';
+export {
+  PAYMENT_STATUS_ADMONITION,
+  PAYMENT_STATUS_GEOMETRY,
+  PAYMENT_STATUS_ICON,
+  PAYMENT_STATUS_LABELS,
+  PAYMENT_STATUS_TONE,
+} from './constants';
+export type { PaymentStatusGeometry } from './constants';
+export { resolvePaymentStatus, resolvePaymentStatusPaint } from './shared';
+export type { PaymentStatusPaint, PaymentStatusPresentation } from './shared';
+export type {
+  PaymentStatusBarProps,
+  PaymentStatusBlockProps,
+  PaymentStatusLabels,
+  PaymentStatusState,
+} from './types';

package/src/payment-status/shared.ts

@@ -0,0 +1,56 @@
+/**
+ * What both `payment-status` components resolve before they draw anything: the
+ * words, the tone and the glyph for a state, with the caller's overrides
+ * already applied.
+ *
+ * Pure, so `PaymentStatus.test.tsx` can walk all five states without
+ * rendering.
+ */
+import type { BloomIconComponent } from '../icons/icon-component';
+import { surfaceTextOn, type SurfaceTextPaint } from '../styles/surface-levels';
+import type { AccentTone } from '../theme/accent-colors';
+import type { Theme } from '../theme/types';
+import {
+  PAYMENT_STATUS_ADMONITION,
+  PAYMENT_STATUS_ICON,
+  PAYMENT_STATUS_LABELS,
+  PAYMENT_STATUS_TONE,
+} from './constants';
+import type { PaymentStatusLabels, PaymentStatusState } from './types';
+
+export interface PaymentStatusPresentation {
+  /** The words on the line. */
+  words: string;
+  /** The tone the tile, the glyph and any bar are painted in. */
+  tone: AccentTone;
+  /** The glyph. */
+  icon: BloomIconComponent;
+  /** Which admonition a reason belongs in, or `undefined` for no reason at all. */
+  admonition: 'error' | 'warning' | undefined;
+}
+
+/**
+ * The state's presentation, with the caller's words and glyph applied.
+ *
+ * `status` is the caller's whole sentence and wins outright; `labels` replaces
+ * one state's default and is what an app translates once rather than at every
+ * call site.
+ */
+export function resolvePaymentStatus(
+  state: PaymentStatusState,
+  options: { status?: string; labels?: PaymentStatusLabels; icon?: BloomIconComponent } = {},
+): PaymentStatusPresentation {
+  return {
+    words: options.status ?? options.labels?.[state] ?? PAYMENT_STATUS_LABELS[state],
+    tone: PAYMENT_STATUS_TONE[state],
+    icon: options.icon ?? PAYMENT_STATUS_ICON[state],
+    admonition: PAYMENT_STATUS_ADMONITION[state],
+  };
+}
+
+export interface PaymentStatusPaint extends SurfaceTextPaint {}
+
+/** What the block draws its text in, read relative to the surface behind it. */
+export function resolvePaymentStatusPaint(theme: Theme, surface: string): PaymentStatusPaint {
+  return surfaceTextOn(theme, surface);
+}

package/src/payment-status/types.ts

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { BloomIconComponent } from '../icons/icon-component';
+import type { OrderStatusProgress } from '../order-status';
+
+/**
+ * WHAT HAPPENED TO THE MONEY.
+ *
+ * Five states, and they are the five an app has to be able to DRAW rather than
+ * the five a processor reports: `authorising` is in flight, `paid` is done,
+ * `failed` stopped and says why, `refunded` went back, and `pending` is waiting
+ * on something outside the app — a bank window, a queued retry, a device with
+ * no connection.
+ *
+ * A processor with twenty statuses maps them onto these five. This family does
+ * no mapping of its own, because which of a processor's statuses counts as
+ * "done" is a decision about that processor's contract, not about a strip.
+ */
+export type PaymentStatusState = 'authorising' | 'paid' | 'failed' | 'refunded' | 'pending';
+
+/** The words each state says, when the caller wants its own. */
+export type PaymentStatusLabels = Partial<Record<PaymentStatusState, string>>;
+
+export interface PaymentStatusBarProps {
+  /** Which of the five. */
+  state: PaymentStatusState;
+  /** Overrides the state's own words — "Held for review", "Retrying". */
+  status?: string;
+  /**
+   * PRE-FORMATTED, sign and currency included: `"€48.00"`, `"−€12.50"`.
+   * Nothing here parses, adds or formats a number.
+   */
+  amount?: string;
+  /** A quieter second line — the method, the reference, the reason in short. */
+  detail?: string;
+  /** How far along an authorisation is. Without it no bar is drawn. */
+  progress?: OrderStatusProgress;
+  /** The glyph, overriding the state's own. */
+  icon?: BloomIconComponent;
+  /** A trailing control — the retry `Button`, a "View receipt" link. */
+  action?: ReactNode;
+  /** `surface` paints a strip of its own; `plain` draws only the content. */
+  variant?: 'surface' | 'plain';
+  /** Replaces the default words for any of the five states. */
+  labels?: PaymentStatusLabels;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface PaymentStatusBlockProps {
+  /** Which of the five. */
+  state: PaymentStatusState;
+  /** Overrides the state's own words. */
+  status?: string;
+  /** PRE-FORMATTED, like every other amount in this library. */
+  amount?: string;
+  /** A line under the amount — "Aurora •••• 4417", "Charged on 4 June". */
+  detail?: string;
+  /**
+   * The reference a reader quotes when something goes wrong. Drawn in tabular
+   * figures so it can be read out a character at a time.
+   */
+  reference?: string;
+  /** The word before it. Default `"Reference"`. */
+  referenceLabel?: string;
+  /**
+   * WHY it failed, in the processor's own words, drawn in an `Admonition`.
+   *
+   * Only for `failed` and `pending`: a reason under a success is a reader
+   * looking for a problem that is not there.
+   */
+  reason?: string;
+  /** The retry, the receipt, the "try another method" — as `Button`s. */
+  actions?: ReactNode;
+  /** The glyph, overriding the state's own. */
+  icon?: BloomIconComponent;
+  /** `surface` paints a card of its own; `plain` draws only the content. */
+  variant?: 'surface' | 'plain';
+  /** Replaces the default words for any of the five states. */
+  labels?: PaymentStatusLabels;
+  /**
+   * Names the block. Defaults to the state's words and the amount joined — the
+   * block's own heading, which is what a reader lands on.
+   */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/place-card/PlaceActions.tsx

@@ -0,0 +1,72 @@
+import React, { memo } from 'react';
+import { View } from 'react-native';
+
+import { Button } from '../button';
+import { PLACE_CARD_GEOMETRY } from './constants';
+import type { PlaceActionsProps } from './types';
+
+/**
+ * What you can do with a place: `Directions`, `Call`, `Save`, `Share`.
+ *
+ * Each action is a Bloom `Button` in the `secondary` variant at the `small`
+ * rung — the same labelled action `ai-profile-card` pins under its cover — and
+ * the row is a `group` named as one. Nothing here draws a control: the fill,
+ * the hover, the press, the focus ring, the disabled opacity and the anchor an
+ * `href` turns the button into are all `Button`'s.
+ *
+ * The row WRAPS rather than scrolling. Four labelled actions do not fit across
+ * a 390 phone, and a horizontal scroller hides the fourth one behind an edge
+ * with nothing to say it is there; two rows of two are entirely legible and
+ * every action stays a tab stop in reading order.
+ *
+ * THERE IS NO PRESSED STATE, deliberately. "Save" is a toggle in every maps
+ * app, and `Button` carries no `aria-pressed` — so a saved place is expressed
+ * by the action's own WORDS and glyph ("Save" / "Saved", outline / filled),
+ * which is the one spelling that reaches both platforms today. `docs/place-card.mdx`
+ * records the gap.
+ */
+function PlaceActionsComponent({
+  actions,
+  size = 'small',
+  accessibilityLabel = 'Actions',
+  style,
+  testID,
+}: PlaceActionsProps) {
+  if (actions.length === 0) return null;
+  return (
+    <View
+      role="group"
+      accessibilityLabel={accessibilityLabel}
+      testID={testID}
+      style={[
+        {
+          flexDirection: 'row',
+          flexWrap: 'wrap',
+          alignItems: 'center',
+          columnGap: PLACE_CARD_GEOMETRY.actionGap,
+          rowGap: PLACE_CARD_GEOMETRY.actionGap,
+        },
+        style,
+      ]}
+    >
+      {actions.map((action) => (
+        <Button
+          key={action.id}
+          variant="secondary"
+          size={size}
+          leadingIcon={action.icon}
+          href={action.href}
+          onPress={action.onPress}
+          disabled={action.disabled}
+          accessibilityLabel={action.accessibilityLabel ?? action.label}
+          testID={testID ? `${testID}-${action.id}` : undefined}
+        >
+          {action.label}
+        </Button>
+      ))}
+    </View>
+  );
+}
+
+export const PlaceActions = memo(PlaceActionsComponent);
+PlaceActions.displayName = 'PlaceActions';