@oxy.so/bloom 3.6.0 → 4.1.0

package/src/earnings/types.ts

@@ -0,0 +1,180 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { PriceLine, PriceTotal } from '../price-breakdown';
+
+/**
+ * Where a payout has got to.
+ *
+ * Five states, because "not in the account yet" is four different situations
+ * and a courier acts differently on each: `scheduled` waits, `processing` is
+ * already moving, `paid` is done, `held` needs the courier to do something,
+ * `failed` needs them to fix something. One "pending" would collapse the two
+ * that require action into the two that do not.
+ */
+export type EarningsPayoutState = 'scheduled' | 'processing' | 'paid' | 'held' | 'failed';
+
+/**
+ * One bar in the chart of the last weeks.
+ *
+ * It carries BOTH a number and an amount, and they are not the same fact.
+ * `value` is geometry — how tall the bar is, in whatever unit the app compares
+ * in — and is never drawn. `amount` is the money, PRE-FORMATTED, and is the
+ * only thing a reader ever sees. Nothing here parses one into the other.
+ */
+export interface EarningsBar {
+  /** The bar's foot — "W12", "Mon". */
+  label: string;
+  /** The bar's HEIGHT. Never drawn. */
+  value: number;
+  /** What that bar paid, PRE-FORMATTED: `"€312.80"`. */
+  amount: string;
+}
+
+/** One tile under the figure: a reading over what it is. */
+export interface EarningsStat {
+  /** The reading, PRE-FORMATTED — `"18"`, `"5 h 40"`, `"€2.14/km"`. */
+  value: string;
+  /** What it is — "Jobs done", "Online", "Per kilometre". */
+  label: string;
+}
+
+/** The money that is on its way out, and what is holding it up. */
+export interface EarningsPayout {
+  /** How much, PRE-FORMATTED. */
+  amount: string;
+  /** When — "Friday 26 September". The app's words: this family formats no date. */
+  date?: string;
+  /** Default `scheduled`. */
+  state?: EarningsPayoutState;
+  /** Where it lands — "Account ending 4417". */
+  destination?: string;
+  /** What the reader has to do about it, for `held` and `failed`. */
+  note?: string;
+}
+
+/**
+ * One period the switch offers, with everything that period says.
+ *
+ * Every field is the period's own, so switching the segment replaces the whole
+ * panel rather than just the chart. A field left out falls back to the
+ * panel-level prop of the same name, which is how a payout that does not change
+ * with the period is written once.
+ */
+export interface EarningsPeriod {
+  /** Identifies the period to `onPeriodChange`. */
+  id: string;
+  /** The segment's words — "Day", "Week", "Month". */
+  label: string;
+  /** What the period paid, PRE-FORMATTED. This is the figure. */
+  total: string;
+  /**
+   * The change on the period before, as a RATIO (`0.148` is up 14.8%). A ratio
+   * is not money, so it is a number here and the chip's words are derived from
+   * it; no chip without one.
+   */
+  deltaRatio?: number;
+  /** A line under the figure — "Before the platform fee". */
+  caption?: string;
+  /** The bars. */
+  bars?: readonly EarningsBar[];
+  /** The breakdown by kind, handed to `PriceSummary` unchanged. */
+  lines?: readonly PriceLine[];
+  /** The tiles under the chart. */
+  stats?: readonly EarningsStat[];
+  /** The next payout, when it is this period's. */
+  payout?: EarningsPayout;
+}
+
+/** Every word the family speaks, in one prop. */
+export interface EarningsLabels {
+  /** Over the figure. Default `"Earned"`. */
+  earned?: string;
+  /** Names the period switch. Default `"Earnings period"`. */
+  period?: string;
+  /** Over the breakdown. Default `"What it came from"`. */
+  breakdown?: string;
+  /** Over the payout row. Default `"Next payout"`. */
+  payout?: string;
+  /** The payout states. Defaults `"Scheduled"`, `"On its way"`, `"Paid"`, `"On hold"`, `"Failed"`. */
+  payoutState?: Partial<Record<EarningsPayoutState, string>>;
+  /** Names the chart. Default `` (label) => `${label} earnings, by period` ``. */
+  chart?: (label: string) => string;
+  /** The empty period's line. Default `"Nothing earned yet"`. */
+  empty?: string;
+}
+
+export interface EarningsBreakdownProps {
+  /** The kinds, in the order they should be read. */
+  lines: readonly PriceLine[];
+  /**
+   * The answer. Left out — which is what `EarningsSummary` does — the breakdown
+   * draws the kinds and no rule, because the figure above it is already the
+   * total and two totals on one panel is one too many.
+   */
+  total?: PriceTotal;
+  /** A heading over the list. Default `"What it came from"`. */
+  title?: string;
+  /** Hide the kinds behind a disclosure. Default `false`. */
+  collapsible?: boolean;
+  /** Starts the disclosure open. Default `false`. */
+  defaultExpanded?: boolean;
+  labels?: EarningsLabels;
+  /** Names the list. Defaults to `title`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface EarningsPayoutRowProps {
+  /** The payout. */
+  payout: EarningsPayout;
+  /** The line over the date. Default `"Next payout"`. */
+  title?: string;
+  /** Makes the row pressable — an app opens the payout's detail from here. */
+  onPress?: () => void;
+  /** A control after the row — "Change the account", "Try again". */
+  action?: ReactNode;
+  labels?: EarningsLabels;
+  /** Overrides the composed name of the row. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface EarningsSummaryProps {
+  /** The periods the switch offers, in the order they are drawn. At least one. */
+  periods: readonly EarningsPeriod[];
+  /** Controlled period id. */
+  period?: string;
+  /** Uncontrolled initial period id. Default the first. */
+  defaultPeriod?: string;
+  onPeriodChange?: (id: string) => void;
+  /** The payout, when it does not change with the period. A period's own wins. */
+  payout?: EarningsPayout;
+  /** Makes the payout row pressable. */
+  onPressPayout?: () => void;
+  /** A control after the payout row. */
+  payoutAction?: ReactNode;
+  /**
+   * The Y axis's tick words.
+   *
+   * THE AXIS IS THE ONE PLACE A NUMBER CANNOT ARRIVE PRE-FORMATTED: a tick is a
+   * position on a scale the chart chose, not a sum the app made, so there is no
+   * string for it to have formatted. The default prints the rounded number and
+   * no currency; an app that wants `"€200"` supplies this.
+   */
+  formatAxisValue?: (value: number) => string;
+  /** How tall the chart is. Default 329 — the height every chart card here is. */
+  chartHeight?: number;
+  /** Draws the breakdown. Default `true` when the period carries `lines`. */
+  breakdown?: boolean;
+  /** Draws the tiles. Default `true` when the period carries `stats`. */
+  stats?: boolean;
+  labels?: EarningsLabels;
+  /** Names the panel. Default `"Earnings"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Derives `-chart`, `-stats`, `-breakdown`, `-payout`. */
+  testID?: string;
+}

package/src/empty-state/EmptyState.tsx

@@ -0,0 +1,184 @@
+import React, { memo, useMemo, type ComponentType, type ReactNode } from 'react';
+import { View } from 'react-native';
+
+import { Button } from '../button';
+import { IconCircle } from '../icon-circle';
+import type { Props as IconProps } from '../icons/shared';
+import { useSurfaceFill } from '../styles/surface-levels';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { EMPTY_STATE_ACTION_GAP, EMPTY_STATE_GEOMETRY } from './constants';
+import { joinEmptyStateName, resolveEmptyStatePaint } from './shared';
+import type { EmptyStateAction, EmptyStateProps } from './types';
+
+/**
+ * Nothing to show, said once.
+ *
+ *   mark      the glyph in the GRAPHICAL rung (`textGraphical`, the stop the
+ *             ladder sizes for a line rather than for text, so it clears 3:1 on
+ *             whatever is behind it), or `IconCircle`'s tinted disc, or an
+ *             arbitrary `illustration`
+ *   title     headline-semibold (panel: body-medium), `heading` level 3
+ *   line      body-regular secondary (panel: body-2-regular), capped at 360 so
+ *             a centred paragraph does not run the width of a 1440 page
+ *   children  stretched full width, laid out by whatever was passed
+ *   actions   up to two, primary then secondary, wrapping
+ *   footer    centred, under the actions
+ *
+ * The whole block is ONE named `group`: a screen reader reaching an empty list
+ * should be told the situation, not handed a heading, a paragraph and a button
+ * with nothing joining them.
+ *
+ * Bloom had no such family and a dozen components had each drawn their own —
+ * five of them the same glyph-over-headline-over-line, at five different
+ * paddings, with the two text slots spelled `emptyTitle`/`emptyDescription`,
+ * `emptyMessage`, `emptyQueueHint`, `emptyLabel`, `emptyText` and
+ * `noResultsLabel`. This is the one shape; migrating those call sites is a
+ * separate change, and this family is designed to cover them as they stand.
+ */
+function EmptyStateComponent({
+  icon: Icon,
+  media = 'glyph',
+  illustration,
+  title,
+  description,
+  action,
+  secondaryAction,
+  children,
+  footer,
+  variant = 'comfortable',
+  minHeight,
+  accessibilityLabel,
+  style,
+  testID,
+}: EmptyStateProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolveEmptyStatePaint(theme, surface), [theme, surface]);
+  const g = EMPTY_STATE_GEOMETRY[variant];
+  const id = (part: string) => (testID ? `${testID}-${part}` : undefined);
+
+  // `illustration` wins, and it is read for PRESENCE rather than truthiness so
+  // an explicit `illustration={null}` draws no mark at all even with an `icon`
+  // set by a default two levels up.
+  const mark: ReactNode =
+    illustration !== undefined ? (
+      illustration
+    ) : Icon ? (
+      media === 'circle' ? (
+        // `IconCircle` asks for an icon's FULL props (it sets `size`), which is
+        // narrower than `BloomIconComponent`'s three optional ones. Every Bloom
+        // glyph satisfies both; this is the boundary between the two spellings,
+        // and the only place in the family that needs to know there are two.
+        <IconCircle icon={Icon as ComponentType<IconProps>} size={g.circle} />
+      ) : (
+        // Hidden from assistive technology: the glyph repeats what the title
+        // says, and an unnamed image between a heading and its paragraph is a
+        // stop that announces nothing. The hiding goes on a WRAPPER — an icon
+        // component takes width, height and fill, and drops anything else.
+        <View aria-hidden importantForAccessibility="no-hide-descendants">
+          <Icon width={g.glyph} height={g.glyph} fill={paint.textGraphical} />
+        </View>
+      )
+    ) : null;
+
+  const renderAction = (a: EmptyStateAction, kind: 'primary' | 'secondary') => (
+    <Button
+      variant={kind}
+      size={variant === 'compact' ? 'small' : 'medium'}
+      onPress={a.onPress}
+      disabled={a.disabled}
+      loading={a.loading}
+      leadingIcon={a.icon}
+      accessibilityLabel={a.accessibilityLabel}
+      testID={a.testID ?? id(kind === 'primary' ? 'action' : 'secondary-action')}
+    >
+      {a.label}
+    </Button>
+  );
+
+  return (
+    <View
+      testID={testID}
+      role="group"
+      accessibilityLabel={accessibilityLabel ?? joinEmptyStateName([title, description])}
+      style={[
+        {
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: g.gap,
+          paddingTop: g.paddingVertical,
+          paddingBottom: g.paddingVertical,
+          ...(minHeight != null ? { minHeight } : null),
+        },
+        style,
+      ]}
+    >
+      {mark != null ? (
+        <View testID={id('mark')} style={{ alignItems: 'center' }}>
+          {mark}
+        </View>
+      ) : null}
+
+      {title != null || description != null ? (
+        <View style={{ alignItems: 'center', gap: g.textGap, maxWidth: g.maxWidth }}>
+          {title != null ? (
+            <Text
+              variant={g.title}
+              role="heading"
+              aria-level={3}
+              testID={id('title')}
+              style={{ color: paint.text, textAlign: 'center' }}
+            >
+              {title}
+            </Text>
+          ) : null}
+          {description != null ? (
+            <Text
+              variant={g.description}
+              testID={id('description')}
+              style={{ color: paint.textSecondary, textAlign: 'center' }}
+            >
+              {description}
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
+
+      {children != null ? (
+        // `alignSelf: 'stretch'` and `minWidth: 0`: what goes here is a strip, a
+        // fact box or a list, none of which is centred text — and a flex child
+        // without the floor takes its content's min-content width as the
+        // block's own, which is how a nowrap line inside one widens the page.
+        <View testID={id('content')} style={{ alignSelf: 'stretch', minWidth: 0 }}>
+          {children}
+        </View>
+      ) : null}
+
+      {action || secondaryAction ? (
+        <View
+          testID={id('actions')}
+          style={{
+            flexDirection: 'row',
+            flexWrap: 'wrap',
+            justifyContent: 'center',
+            alignItems: 'center',
+            gap: EMPTY_STATE_ACTION_GAP,
+          }}
+        >
+          {action ? renderAction(action, 'primary') : null}
+          {secondaryAction ? renderAction(secondaryAction, 'secondary') : null}
+        </View>
+      ) : null}
+
+      {footer != null ? (
+        <View testID={id('footer')} style={{ alignItems: 'center' }}>
+          {footer}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+export const EmptyState = memo(EmptyStateComponent);
+EmptyState.displayName = 'EmptyState';

package/src/empty-state/constants.ts

@@ -0,0 +1,55 @@
+import type { TypeScaleVariant } from '../typography/scale';
+import type { EmptyStateVariant } from './types';
+
+export interface EmptyStateGeometry {
+  /** The bare glyph's box. */
+  glyph: number;
+  /** `IconCircle`'s rung. `lg` is 52, `xl` is 64. */
+  circle: 'lg' | 'xl';
+  /** Above and below the block. */
+  paddingVertical: number;
+  /** Between the mark, the text block, the children, the actions and the footer. */
+  gap: number;
+  /** Between the title and the description. */
+  textGap: number;
+  /** How wide the centred text is allowed to run before it wraps. */
+  maxWidth: number;
+  title: TypeScaleVariant;
+  description: TypeScaleVariant;
+}
+
+/**
+ * The two rungs, written out rather than scaled from one another.
+ *
+ * `maxWidth` is the number worth defending: the five hand-rolled empties this
+ * family replaces used 280, 260, 360, 340 and none, and a line of explanation
+ * that runs the full width of a 1440 page is the reason they each picked one.
+ * 360 is roughly 60 characters at `body-regular`, which is where a centred
+ * paragraph stops needing a second fixation per line; the panel rung is
+ * narrower because the panel is.
+ */
+export const EMPTY_STATE_GEOMETRY: Record<EmptyStateVariant, EmptyStateGeometry> = {
+  comfortable: {
+    glyph: 32,
+    circle: 'xl',
+    paddingVertical: 48,
+    gap: 16,
+    textGap: 6,
+    maxWidth: 360,
+    title: 'headline-semibold',
+    description: 'body-regular',
+  },
+  compact: {
+    glyph: 24,
+    circle: 'lg',
+    paddingVertical: 24,
+    gap: 12,
+    textGap: 4,
+    maxWidth: 280,
+    title: 'body-medium',
+    description: 'body-2-regular',
+  },
+};
+
+/** Between the two actions, in both directions — they wrap on a narrow block. */
+export const EMPTY_STATE_ACTION_GAP = 8;

package/src/empty-state/index.ts

@@ -0,0 +1,11 @@
+export { EmptyState } from './EmptyState';
+export { EMPTY_STATE_ACTION_GAP, EMPTY_STATE_GEOMETRY } from './constants';
+export type { EmptyStateGeometry } from './constants';
+export { joinEmptyStateName, resolveEmptyStatePaint } from './shared';
+export type { EmptyStatePaint } from './shared';
+export type {
+  EmptyStateAction,
+  EmptyStateMedia,
+  EmptyStateProps,
+  EmptyStateVariant,
+} from './types';

package/src/empty-state/shared.ts

@@ -0,0 +1,26 @@
+/**
+ * What an empty state paints, read RELATIVE to the surface it was dropped on
+ * (`styles/surface-levels.ts`) rather than from a ramp stop — the same block
+ * goes on a page, inside a card and inside a popover, and a glyph picked by eye
+ * disappears on one of the three.
+ *
+ * Pure, so `EmptyState.test.tsx` can walk presets and modes without rendering.
+ */
+import { surfaceTextOn, type SurfaceTextPaint } from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+
+export type EmptyStatePaint = SurfaceTextPaint;
+
+export function resolveEmptyStatePaint(theme: Theme, surface: string): EmptyStatePaint {
+  return surfaceTextOn(theme, surface);
+}
+
+/** The announced name: the title, then the explanation, as one utterance. */
+export function joinEmptyStateName(
+  parts: ReadonlyArray<string | null | undefined>,
+): string | undefined {
+  const joined = parts
+    .filter((part): part is string => typeof part === 'string' && part !== '')
+    .join('. ');
+  return joined === '' ? undefined : joined;
+}

package/src/empty-state/types.ts

@@ -0,0 +1,101 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { BloomIconComponent } from '../icons/icon-component';
+
+/**
+ * How loud the block is, which is a question about WHERE it is, not about how
+ * much there is to say.
+ *
+ * `comfortable` is the screen rung: a 32 glyph, a headline, 48 of air above and
+ * below. `compact` is the PANEL rung — a side panel, a popover, a card that is
+ * already inside something — where the same three lines have to read without
+ * pushing the panel's own chrome off screen: a 24 glyph, a body title, 24 of
+ * air. Nothing else changes, so a list that moves from a screen into a panel
+ * does not change components.
+ */
+export type EmptyStateVariant = 'comfortable' | 'compact';
+
+/**
+ * What the glyph is drawn ON.
+ *
+ * `glyph` is the bare mark in the graphical rung — the shape twelve of Bloom's
+ * lists already draw by hand. `circle` is `IconCircle`, the tinted disc: it is
+ * LOUDER, and it is right when the empty state is the whole screen or is
+ * inviting an action rather than reporting a count. There is no third: a well
+ * with a neutral fill and a tinted disc side by side were two answers to the
+ * same question.
+ */
+export type EmptyStateMedia = 'glyph' | 'circle';
+
+/**
+ * One of the two actions, as DATA.
+ *
+ * A node would have worked, and the six hand-rolled empties this family
+ * replaces each passed one — which is how three of them ended up with three
+ * different button sizes for the same "there is nothing here, do this" button.
+ * As data, the family owns the size, the order and the wrap, and the caller
+ * still owns the words and the handler. Anything that is not a button goes in
+ * `footer`.
+ */
+export interface EmptyStateAction {
+  /** The words on the button. Also its accessible name. */
+  label: string;
+  onPress?: () => void;
+  /** A glyph before the label. */
+  icon?: BloomIconComponent;
+  disabled?: boolean;
+  /** Spinner in the button; presses are ignored. */
+  loading?: boolean;
+  /** Overrides the announced name — for a label that reads as a fragment. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+export interface EmptyStateProps {
+  /**
+   * The glyph. Omit it (and `illustration`) for a block that is text only —
+   * a table band, a search result count — which is a real shape and not a
+   * degraded one.
+   */
+  icon?: BloomIconComponent;
+  /** Default `glyph`. Ignored when `illustration` is set. */
+  media?: EmptyStateMedia;
+  /**
+   * An arbitrary mark above the title — an image, a `Skeleton` stack, an
+   * `AnimatedCheck`. WINS over `icon`, and takes no tile of its own: whatever
+   * is passed is drawn exactly as it comes.
+   */
+  illustration?: ReactNode;
+  /** "Nothing here yet". A block with no title is a single explanatory line. */
+  title?: string;
+  /** The one line that says why, and what would change it. */
+  description?: string;
+  /** The thing to do about it. */
+  action?: EmptyStateAction;
+  /** The other thing to do about it. Drawn beside `action`, quieter. */
+  secondaryAction?: EmptyStateAction;
+  /**
+   * Anything between the explanation and the actions — a reference chip, a
+   * status strip, a list of facts. Stretched to the block's full width and
+   * left to lay itself out, because the things that go here are not centred
+   * text.
+   */
+  children?: ReactNode;
+  /** Under the actions: a note, a link, a row of suggestions. Centred. */
+  footer?: ReactNode;
+  /** Default `comfortable`. */
+  variant?: EmptyStateVariant;
+  /**
+   * A floor for the block, for an empty state that has to hold a band open —
+   * a table body, a panel that must not collapse. The content centres in it.
+   */
+  minHeight?: number;
+  /**
+   * Names the block. Defaults to the title, so a screen reader reaches one
+   * named `group` instead of three unrelated strings.
+   */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}