@oxy.so/bloom 4.0.0 → 4.1.0

package/src/earnings/EarningsPayoutRow.tsx

@@ -0,0 +1,138 @@
+import React, { memo, useMemo } from 'react';
+import { View, type TextStyle } from 'react-native';
+
+import { Badge } from '../badge';
+import { RiBankCardLine } from '../icons/remix/RiBankCardLine';
+import { Item } from '../item';
+import { useSurfaceFill } from '../styles/surface-levels';
+import { resolveAccentColors } from '../theme/accent-colors';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { EARNINGS_GEOMETRY, EARNINGS_LABELS, EARNINGS_PAYOUT_TONE } from './constants';
+import { joinEarningsName, resolveEarningsPaint } from './shared';
+import type { EarningsPayoutRowProps } from './types';
+
+const TABULAR: TextStyle = { fontVariant: ['tabular-nums'] };
+
+/**
+ * The money that is on its way, and what is holding it up.
+ *
+ * It is an `Item`, not a card: a payout is a ROW in a panel, and `item` already
+ * owns the press target, the density, the leading and trailing slots and the
+ * disabled wash. What this component decides is what goes in the three slots.
+ *
+ *   leading   a 40 glyph tile at the panel's next fill up
+ *   content   the title over the date and the destination
+ *   trailing  the amount at `headline-semibold` in tabular figures, with the
+ *             state `Badge` under it
+ *   note      under the row, and ONLY for `held` and `failed` — the two states
+ *             that ask the reader to do something. A note on a scheduled payout
+ *             is a sentence nobody has to read.
+ *
+ * **THE STATE IS SAID IN WORDS, NOT ONLY IN COLOUR.** The badge carries the
+ * word; the tone is a second channel on top of it, so the row survives a reader
+ * who cannot tell the warning tint from the neutral one.
+ */
+function EarningsPayoutRowComponent({
+  payout,
+  title,
+  onPress,
+  action,
+  labels: labelOverrides,
+  accessibilityLabel,
+  style,
+  testID,
+}: EarningsPayoutRowProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolveEarningsPaint(theme, surface), [theme, surface]);
+  const labels = useMemo(
+    () => ({
+      ...EARNINGS_LABELS,
+      ...labelOverrides,
+      payoutState: { ...EARNINGS_LABELS.payoutState, ...labelOverrides?.payoutState },
+    }),
+    [labelOverrides],
+  );
+
+  const state = payout.state ?? 'scheduled';
+  const stateWord = labels.payoutState[state];
+  const heading = title ?? labels.payout;
+  const needsAction = state === 'held' || state === 'failed';
+  const noteTone = resolveAccentColors(theme.colors, EARNINGS_PAYOUT_TONE[state], 'subtle');
+  const id = (part: string) => (testID ? `${testID}-${part}` : undefined);
+
+  const name =
+    accessibilityLabel ??
+    joinEarningsName([heading, payout.amount, payout.date, stateWord, payout.destination]);
+
+  return (
+    // A `group`, not a bare column: `Item`'s non-pressable branch is
+    // `role="none"`, on which an `aria-label` is not exposed at all — so the
+    // composed name has to hang off something ARIA will read it from.
+    <View role="group" accessibilityLabel={name} style={style} testID={testID}>
+      <Item
+        onPress={onPress}
+        accessibilityLabel={onPress ? name : undefined}
+        leading={
+          <View
+            aria-hidden
+            style={{
+              width: EARNINGS_GEOMETRY.glyph,
+              height: EARNINGS_GEOMETRY.glyph,
+              borderRadius: EARNINGS_GEOMETRY.glyphRadius,
+              alignItems: 'center',
+              justifyContent: 'center',
+              backgroundColor: paint.tile,
+            }}
+            testID={id('glyph')}
+          >
+            <RiBankCardLine width={20} height={20} fill={paint.tileText.textSecondary} />
+          </View>
+        }
+        title={heading}
+        subtitle={joinEarningsName([payout.date, payout.destination], ' · ')}
+        trailing={
+          <View style={{ alignItems: 'flex-end', gap: 4 }} testID={id('amount')}>
+            <Text
+              variant="headline-semibold"
+              numberOfLines={1}
+              style={[{ color: paint.text }, TABULAR]}
+              testID={id('amount-text')}
+            >
+              {payout.amount}
+            </Text>
+            <Badge
+              content={stateWord}
+              variant="subtle"
+              color={EARNINGS_PAYOUT_TONE[state]}
+              size="label-small"
+              testID={id('state')}
+            />
+          </View>
+        }
+        testID={id('row')}
+      />
+      {payout.note && needsAction ? (
+        <Text
+          variant="body-2-regular"
+          style={{ color: noteTone.foreground, paddingLeft: 12, paddingRight: 12 }}
+          testID={id('note')}
+        >
+          {payout.note}
+        </Text>
+      ) : null}
+      {action ? (
+        <View
+          style={{ flexDirection: 'row', paddingLeft: 12, paddingTop: 8 }}
+          testID={id('action')}
+        >
+          {action}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+export const EarningsPayoutRow = memo(EarningsPayoutRowComponent);
+EarningsPayoutRow.displayName = 'EarningsPayoutRow';

package/src/earnings/EarningsSummary.tsx

@@ -0,0 +1,296 @@
+import React, { memo, useCallback, useMemo, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { EarningsChartCard } from '../chart-cards';
+import { useContainerWidth } from '../hooks/use-container-width';
+import { useControllableState } from '../hooks/use-controllable-state';
+import { SurfaceLevelProvider, useSurfaceFill } from '../styles/surface-levels';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { EARNINGS_GEOMETRY, EARNINGS_LABELS } from './constants';
+import { EarningsBreakdown } from './EarningsBreakdown';
+import { EarningsPayoutRow } from './EarningsPayoutRow';
+import {
+  earningsHeadline,
+  earningsHeadlineLabel,
+  resolveEarningsPaint,
+  resolveEarningsPeriod,
+} from './shared';
+import type { EarningsSummaryProps } from './types';
+
+/**
+ * What the work paid, for one period.
+ *
+ *   chart      `chart-cards`' `EarningsChartCard`, which already OWNS the
+ *              figure, the delta chip, the period switch and the bars
+ *   tiles      the period's readings, in `ai-profile-card`'s tile: the value
+ *              over its label. One row from 640, two columns below
+ *   breakdown  `EarningsBreakdown` — `price-breakdown`'s itemisation, by kind
+ *   payout     `EarningsPayoutRow` — an `item` row with the amount, the date
+ *              and the state
+ *
+ * ## Why this is built AROUND the chart card rather than beside it
+ *
+ * `EarningsChartCard` is already four of the five things a courier's earnings
+ * screen needs: the period's figure, the change on the period before, the
+ * Day / Week / Month switch and the bars of the last weeks. Drawing a second
+ * figure and a second switch above it would have put two of everything on one
+ * panel. So this family draws NONE of that — it hands the chart card the
+ * period's data and adds the three things the chart card has no opinion about:
+ * where the money came from, what the period's other readings were, and when
+ * it reaches the bank.
+ *
+ * ## The money is never computed, and the headline is the proof
+ *
+ * `EarningsChartCard` formats its headline from a NUMBER, which is exactly what
+ * this family must not do. So the headline is CHOSEN, not produced: this
+ * component owns the chart's active index, and `format` returns the period's
+ * own `total` at rest and the hovered bar's own `amount` over a bar — both
+ * strings the app formatted. A bar's `value` is geometry and is never drawn.
+ *
+ * Two consequences, both deliberate:
+ *
+ *  - **The headline does not roll.** `ChartHeadline` counts a number up over
+ *    320ms; a pre-formatted amount has nothing to count. The 220ms fade still
+ *    plays, so the change is still visible.
+ *  - **The Y axis prints a number.** A tick is a position on a scale the chart
+ *    chose, not a sum the app made, so no string exists for it to have
+ *    formatted. The default prints the rounded number with no currency;
+ *    `formatAxisValue` is where an app puts its own.
+ *
+ * **A jest test cannot see the hover.** The plot surface that carries the
+ * pointer handlers only exists after `onLayout`, which jsdom never fires —
+ * gutting `setActiveIndex` to a no-op leaves `Earnings.test.tsx` green. The
+ * choice itself (`earningsHeadline`) is pure and pinned there; that the panel
+ * owns the active bar is pinned in `scripts/verify-earnings-headline.mjs`.
+ *
+ * ## The period is controlled here, and the chart is remounted to follow it
+ *
+ * `useChartRange` inside `chart-cards` is uncontrolled — it has a `defaultRange`
+ * and no `range` — so a period changed from OUTSIDE cannot reach the chart's own
+ * segmented control. The chart is therefore keyed on the period id: an external
+ * change remounts it with the new default rather than letting the switch and the
+ * panel disagree. The cost is that the bars grow in again instead of morphing.
+ */
+
+/** The axis's last resort: a number, rounded, with nobody's currency on it. */
+const roundedAxisValue = (value: number) => String(Math.round(value));
+
+function EarningsSummaryComponent({
+  periods,
+  period: periodProp,
+  defaultPeriod,
+  onPeriodChange,
+  payout,
+  onPressPayout,
+  payoutAction,
+  formatAxisValue = roundedAxisValue,
+  chartHeight,
+  breakdown,
+  stats,
+  labels: labelOverrides,
+  accessibilityLabel = 'Earnings',
+  style,
+  testID,
+}: EarningsSummaryProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolveEarningsPaint(theme, surface), [theme, surface]);
+  const labels = useMemo(
+    () => ({
+      ...EARNINGS_LABELS,
+      ...labelOverrides,
+      payoutState: { ...EARNINGS_LABELS.payoutState, ...labelOverrides?.payoutState },
+    }),
+    [labelOverrides],
+  );
+
+  const [periodId, setPeriodId] = useControllableState<string>({
+    value: periodProp,
+    defaultValue: defaultPeriod ?? periods[0]?.id ?? '',
+    onChange: onPeriodChange,
+  });
+  const current = resolveEarningsPeriod(periods, periodId);
+
+  // The chart's active bar is OWNED here: the headline has to be able to say
+  // which amount it is showing, and only this component knows the strings.
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const changePeriod = useCallback(
+    (id: string) => {
+      setActiveIndex(null);
+      setPeriodId(id);
+    },
+    [setPeriodId],
+  );
+
+  const { width, onLayout } = useContainerWidth();
+  const wide = width === null || width >= EARNINGS_GEOMETRY.narrowWidth;
+  const id = (part: string) => (testID ? `${testID}-${part}` : undefined);
+
+  const bars = current?.bars;
+  const total = current?.total ?? '';
+  const chartData = useMemo(
+    () => (bars ?? []).map((bar) => ({ label: bar.label, value: bar.value })),
+    [bars],
+  );
+  const ranges = useMemo(
+    () => periods.map((entry) => ({ id: entry.id, label: entry.label })),
+    [periods],
+  );
+
+  // Both are CHOSEN from strings the app formatted, never produced from a
+  // number: `format` ignores the value the count-up hands it on purpose.
+  const headlineText = earningsHeadline(total, bars, activeIndex);
+  const headlineLabel = earningsHeadlineLabel(labels.earned, bars, activeIndex);
+  const format = useCallback(() => headlineText, [headlineText]);
+
+  const periodStats = current?.stats ?? [];
+  const showStats = (stats ?? true) && periodStats.length > 0;
+  const periodLines = current?.lines ?? [];
+  const showBreakdown = (breakdown ?? true) && periodLines.length > 0;
+  const shownPayout = current?.payout ?? payout;
+
+  const tileRows: number[][] = [];
+  if (wide) {
+    if (periodStats.length > 0) tileRows.push(periodStats.map((_unused, index) => index));
+  } else {
+    for (let i = 0; i < periodStats.length; i += 2)
+      tileRows.push(i + 1 < periodStats.length ? [i, i + 1] : [i]);
+  }
+
+  return (
+    <SurfaceLevelProvider level={0} fill={paint.surface}>
+      <View
+        onLayout={onLayout}
+        role="group"
+        accessibilityLabel={accessibilityLabel}
+        style={[{ gap: EARNINGS_GEOMETRY.gap }, style]}
+        testID={testID}
+      >
+        {/* Keyed on the period: see the note above about `useChartRange`. */}
+        <EarningsChartCard
+          key={periodId}
+          title={headlineLabel}
+          data={chartData}
+          // The figure is a string, so the number behind it only has to be
+          // STABLE — the fade replays on the period and the bar, not on it.
+          headline={0}
+          delta={current?.deltaRatio}
+          ranges={ranges.length > 1 ? ranges : undefined}
+          defaultRange={periodId}
+          onRangeChange={changePeriod}
+          rangesLabel={labels.period}
+          format={format}
+          formatAxisValue={formatAxisValue}
+          activeIndex={activeIndex}
+          onActiveIndexChange={setActiveIndex}
+          accessibilityLabel={labels.chart(current?.label ?? '')}
+          style={chartHeight === undefined ? undefined : { height: chartHeight }}
+          testID={id('chart')}
+        />
+
+        {current?.caption ? (
+          <Text
+            variant="body-2-regular"
+            style={{ color: paint.textSecondary }}
+            testID={id('caption')}
+          >
+            {current.caption}
+          </Text>
+        ) : null}
+
+        {showStats ? (
+          <View style={{ gap: EARNINGS_GEOMETRY.tileGap }} testID={id('stats')}>
+            {tileRows.map((row) => (
+              <View
+                key={`stat-row-${row[0]}`}
+                style={{
+                  flexDirection: 'row',
+                  alignItems: 'stretch',
+                  gap: EARNINGS_GEOMETRY.tileGap,
+                }}
+              >
+                {row.map((index) => {
+                  const stat = periodStats[index]!;
+                  return (
+                    <View
+                      key={`${index}-${stat.label}`}
+                      style={[styles.tile, { backgroundColor: paint.tile }]}
+                      testID={id(`stat-${index}`)}
+                    >
+                      <Text
+                        variant="body-medium"
+                        numberOfLines={1}
+                        style={{ width: '100%', color: paint.tileText.text }}
+                      >
+                        {stat.value}
+                      </Text>
+                      <Text
+                        variant="body-2-medium"
+                        numberOfLines={1}
+                        style={{ width: '100%', color: paint.tileText.textSecondary }}
+                      >
+                        {stat.label}
+                      </Text>
+                    </View>
+                  );
+                })}
+                {/* An odd tile keeps its half of the two-column grid. */}
+                {!wide && row.length === 1 ? <View style={styles.tileSpacer} /> : null}
+              </View>
+            ))}
+          </View>
+        ) : null}
+
+        {showBreakdown ? (
+          <EarningsBreakdown
+            lines={periodLines}
+            title={labels.breakdown}
+            labels={labelOverrides}
+            testID={id('breakdown')}
+          />
+        ) : null}
+
+        {shownPayout ? (
+          <EarningsPayoutRow
+            payout={shownPayout}
+            title={labels.payout}
+            onPress={onPressPayout}
+            action={payoutAction}
+            labels={labelOverrides}
+            testID={id('payout')}
+          />
+        ) : null}
+
+        {!showStats && !showBreakdown && shownPayout === undefined ? (
+          <Text
+            variant="body-regular"
+            style={{ color: paint.textSecondary }}
+            testID={id('empty')}
+          >
+            {labels.empty}
+          </Text>
+        ) : null}
+      </View>
+    </SurfaceLevelProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  tile: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
+    alignItems: 'flex-start',
+    borderRadius: EARNINGS_GEOMETRY.tileRadius,
+    paddingTop: EARNINGS_GEOMETRY.tilePadding,
+    paddingBottom: EARNINGS_GEOMETRY.tilePadding,
+    paddingLeft: EARNINGS_GEOMETRY.tilePadding,
+    paddingRight: EARNINGS_GEOMETRY.tilePadding,
+  },
+  tileSpacer: { flexGrow: 1, flexShrink: 1, flexBasis: 0, minWidth: 0 },
+});
+
+export const EarningsSummary = memo(EarningsSummaryComponent);
+EarningsSummary.displayName = 'EarningsSummary';

package/src/earnings/constants.ts

@@ -0,0 +1,62 @@
+import { RADIUS } from '../design-tokens/scales';
+import type { AccentTone } from '../theme/accent-colors';
+import type { EarningsLabels, EarningsPayoutState } from './types';
+
+/** Every default word the family draws. */
+export const EARNINGS_LABELS: Required<Omit<EarningsLabels, 'payoutState'>> & {
+  payoutState: Record<EarningsPayoutState, string>;
+} = {
+  earned: 'Earned',
+  period: 'Earnings period',
+  breakdown: 'What it came from',
+  payout: 'Next payout',
+  payoutState: {
+    scheduled: 'Scheduled',
+    processing: 'On its way',
+    paid: 'Paid',
+    held: 'On hold',
+    failed: 'Failed',
+  },
+  chart: (label: string) => `${label} earnings, by period`,
+  empty: 'Nothing earned yet',
+};
+
+/**
+ * The tone each payout state is painted in.
+ *
+ * `scheduled` is `default` because waiting is not news. `processing` is `info`:
+ * something is happening and there is nothing to do about it. `paid` is
+ * `success`. `held` is `warning` and `failed` is `error` — the two that need
+ * the reader to act, told apart by whether the money is still coming.
+ */
+export const EARNINGS_PAYOUT_TONE: Record<EarningsPayoutState, AccentTone> = {
+  scheduled: 'default',
+  processing: 'info',
+  paid: 'success',
+  held: 'warning',
+  failed: 'error',
+};
+
+/**
+ * The panel's geometry.
+ *
+ * `tile` is `ai-profile-card`'s stat tile exactly — radius 10, padding 10, the
+ * reading over its label — because a courier's "18 jobs" and a profile's
+ * "9B lifetime tokens" are the same object, and two tile geometries in one
+ * library is two answers to one question.
+ */
+export const EARNINGS_GEOMETRY = {
+  /** Between the chart, the tiles, the breakdown and the payout. */
+  gap: 16,
+  /** Between tiles, and between tile rows. */
+  tileGap: 8,
+  tilePadding: 10,
+  tileRadius: 10,
+  /** The payout row's leading glyph tile. */
+  glyph: 40,
+  glyphRadius: RADIUS['radius-12'],
+  /** Under this the tiles stack two to a row. */
+  narrowWidth: 640,
+} as const;
+
+export type EarningsGeometry = typeof EARNINGS_GEOMETRY;

package/src/earnings/index.ts

@@ -0,0 +1,24 @@
+export { EarningsBreakdown } from './EarningsBreakdown';
+export { EarningsPayoutRow } from './EarningsPayoutRow';
+export { EarningsSummary } from './EarningsSummary';
+export { EARNINGS_GEOMETRY, EARNINGS_LABELS, EARNINGS_PAYOUT_TONE } from './constants';
+export type { EarningsGeometry } from './constants';
+export {
+  earningsHeadline,
+  earningsHeadlineLabel,
+  joinEarningsName,
+  resolveEarningsPaint,
+  resolveEarningsPeriod,
+} from './shared';
+export type { EarningsPaint } from './shared';
+export type {
+  EarningsBar,
+  EarningsBreakdownProps,
+  EarningsLabels,
+  EarningsPayout,
+  EarningsPayoutRowProps,
+  EarningsPayoutState,
+  EarningsPeriod,
+  EarningsStat,
+  EarningsSummaryProps,
+} from './types';

package/src/earnings/shared.ts

@@ -0,0 +1,92 @@
+/**
+ * What the earnings panel paints, and the two pure decisions it is built on.
+ *
+ * The paint is RELATIVE for the reason every family here computes one the same
+ * way: the panel is on a page, in a sheet and inside a card, and a ramp stop
+ * picked here would be right for one of them and invisible on the others.
+ */
+import { hairlineOn, surfaceFillOn, surfaceTextOn } from '../styles/surface-levels';
+import type { SurfaceTextPaint } from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+import type { EarningsBar, EarningsPeriod } from './types';
+
+export interface EarningsPaint {
+  /** The fill the panel's own content lands on. */
+  surface: string;
+  /** The rule under a section heading. */
+  hairline: string;
+  /** The next fill UP: a stat tile, the payout row's glyph. */
+  tile: string;
+  text: string;
+  textSecondary: string;
+  textTertiary: string;
+  /** The text rungs that clear AA on a TILE, which is not the panel's fill. */
+  tileText: SurfaceTextPaint;
+}
+
+export function resolveEarningsPaint(theme: Theme, surface: string): EarningsPaint {
+  const text = surfaceTextOn(theme, surface);
+  const tile = surfaceFillOn(theme, surface);
+  return {
+    surface,
+    hairline: hairlineOn(theme, surface),
+    tile,
+    text: text.text,
+    textSecondary: text.textSecondary,
+    textTertiary: text.textTertiary,
+    tileText: surfaceTextOn(theme, tile),
+  };
+}
+
+/**
+ * The period the panel is showing, by id.
+ *
+ * An id that names no period falls back to the FIRST rather than to nothing: a
+ * panel with a stale id in its state would otherwise draw an empty figure, and
+ * an empty figure reads as "you earned nothing" rather than as "this app asked
+ * for a period that is not on the list".
+ */
+export function resolveEarningsPeriod(
+  periods: readonly EarningsPeriod[],
+  id: string | undefined,
+): EarningsPeriod | undefined {
+  return periods.find((period) => period.id === id) ?? periods[0];
+}
+
+/**
+ * What the chart's headline says, given which bar the reader is on.
+ *
+ * THE HEADLINE IS NEVER COMPUTED. At rest it is the period's own `total`; over
+ * a bar it is that bar's own `amount`. Both are strings the app formatted, so
+ * this function chooses between two answers rather than producing one — which
+ * is the whole of what "money arrives pre-formatted" means here.
+ *
+ * An index outside the bars is treated as no index: an active index that
+ * outlived its data must not read a hole.
+ */
+export function earningsHeadline(
+  total: string,
+  bars: readonly EarningsBar[] | undefined,
+  activeIndex: number | null,
+): string {
+  if (activeIndex === null || bars === undefined) return total;
+  return bars[activeIndex]?.amount ?? total;
+}
+
+/** The label over the headline: the period's own name, or the bar the reader is on. */
+export function earningsHeadlineLabel(
+  rest: string,
+  bars: readonly EarningsBar[] | undefined,
+  activeIndex: number | null,
+): string {
+  if (activeIndex === null || bars === undefined) return rest;
+  return bars[activeIndex]?.label ?? rest;
+}
+
+/** Joins the non-empty parts of an accessible name. */
+export function joinEarningsName(
+  parts: ReadonlyArray<string | false | null | undefined>,
+  separator = ', ',
+): string {
+  return parts.filter((part): part is string => typeof part === 'string' && part !== '').join(separator);
+}