@oxy.so/bloom 3.5.0 → 4.0.0

package/src/pipeline/shared.ts

@@ -0,0 +1,91 @@
+/**
+ * What the pipeline paints, and the pure helpers the components and their tests
+ * both read.
+ *
+ * One resolver, asked once per PART, with the fill that part actually paints:
+ * a column is a step off whatever is behind it (`surfaceFillOn`), a deal card is
+ * the `card` role. Both then read their hairline and their three text rungs off
+ * the colour they are really on, so the same column reads on a page, inside a
+ * panel and inside a dialog without being told which one it is.
+ */
+import { interactiveWebCss } from '../styles/interactive-web-css';
+import { hairlineOn, surfaceFillOn, surfaceTextOn } from '../styles/surface-levels';
+import type { AccentTone } from '../theme/accent-colors';
+import type { Theme } from '../theme/types';
+import { DEAL_HEALTH } from './constants';
+import type { DealCardProps, DealHealth } from './types';
+
+export interface PipelinePaint {
+  /** The fill this part paints. Every other member is read off it. */
+  surface: string;
+  /** The rule under a column header, and a card's edge. */
+  hairline: string;
+  /** One step above `surface` — an empty state's tile, a skeleton block. */
+  raised: string;
+  text: string;
+  textSecondary: string;
+  textTertiary: string;
+  ring: string;
+}
+
+/** Everything a pipeline part paints, given the fill it actually has. */
+export function resolvePipelinePaint(theme: Theme, surface: string): PipelinePaint {
+  const text = surfaceTextOn(theme, surface);
+  return {
+    surface,
+    hairline: hairlineOn(theme, surface),
+    raised: surfaceFillOn(theme, surface),
+    text: text.text,
+    textSecondary: text.textSecondary,
+    textTertiary: text.textTertiary,
+    ring: theme.colors.primary,
+  };
+}
+
+/** A column's own fill: one step off whatever is behind the board. */
+export function pipelineColumnFill(theme: Theme, behind: string): string {
+  return surfaceFillOn(theme, behind);
+}
+
+/**
+ * The health signal's word. `stalledFor` turns the stalled state into a
+ * DURATION — "Stalled for 14 days" — and is ignored on every other health,
+ * because a deal that is moving has not stalled for anything.
+ */
+export function dealHealthLabel(
+  props: Pick<DealCardProps, 'health' | 'healthLabel' | 'stalledFor'>,
+): string | null {
+  const { health, healthLabel, stalledFor } = props;
+  if (health === undefined) return healthLabel ?? null;
+  if (healthLabel !== undefined) return healthLabel;
+  if (health === 'stalled' && stalledFor) return `Stalled for ${stalledFor}`;
+  return DEAL_HEALTH[health].label;
+}
+
+/** The tone a health draws in, or the neutral one when the card has no health. */
+export function dealHealthTone(health: DealHealth | undefined): AccentTone {
+  return health === undefined ? 'default' : DEAL_HEALTH[health].tone;
+}
+
+/** Joins the non-empty parts of an accessible name. */
+export function joinDealName(
+  parts: ReadonlyArray<string | false | null | undefined>,
+  separator = ', ',
+): string {
+  return parts.filter((part): part is string => typeof part === 'string' && part !== '').join(separator);
+}
+
+// ---------------------------------------------------------------------------
+//  Keyboard focus on web — the same mechanism `contact-card` uses, for the same
+//  reason: a react-native-web `Pressable` is focusable with the outline reset,
+//  and an inline style carries no `:focus-visible`.
+// ---------------------------------------------------------------------------
+
+export const PIPELINE_STYLE_ID = 'bloom-pipeline-web-css';
+
+export const PIPELINE_WEB_CSS = interactiveWebCss({
+  selector: '[data-bloom-deal-subject]',
+  varPrefix: 'bloom-deal',
+  reset: 'none',
+  transition: 'background-color 150ms ease',
+});

package/src/pipeline/types.ts

@@ -0,0 +1,126 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { AccentTone } from '../theme/accent-colors';
+
+/**
+ * How the deal is DOING — one axis, not two. "Health" and "priority" are the
+ * same question asked twice (a high-priority deal that is fine needs no flag, a
+ * stalled one is already the loudest thing on the card), and drawing both is the
+ * "two controls that mean the same thing" the card exists to avoid.
+ */
+export type DealHealth = 'on-track' | 'at-risk' | 'stalled';
+
+/** Who on the team is carrying the deal. */
+export interface DealOwner {
+  name: string;
+  /** A URL or an `ImageResolver` id. Without it the avatar draws initials. */
+  avatar?: string;
+}
+
+export interface DealCardProps {
+  title: string;
+  /** The company the deal is with. */
+  account?: string;
+  /**
+   * PRE-FORMATTED ("€48,000", "$1.2M"). Bloom never does money maths and never
+   * picks a currency, a locale or a rounding — the app has all three and the
+   * card would have to guess. It is drawn on one line and never wraps.
+   */
+  amount?: string;
+  /** Pre-formatted ("Closes 30 Sep"). */
+  closeDate?: string;
+  owner?: DealOwner;
+  /** The stage word, for a card drawn OUTSIDE a column (a search result, a list). */
+  stage?: string;
+  health?: DealHealth;
+  /** Overrides the health's own word. */
+  healthLabel?: string;
+  /**
+   * How long it has been stalled, pre-formatted ("14 days"). With
+   * `health="stalled"` the signal reads "Stalled for 14 days"; on any other
+   * health it is ignored, because a deal that is moving has not stalled.
+   */
+  stalledFor?: string;
+  /** Opens the deal. Bound to the title block — see `docs/pipeline.mdx`. */
+  onPress?: () => void;
+  /**
+   * Move the deal to another stage. The BOARD DOES NOT DRAG: this is the
+   * affordance that replaces it, and the app decides what it opens (a menu, a
+   * sheet, a dialog).
+   */
+  onMove?: () => void;
+  /** The move action's accessible name. Default `"Move {title}"`. */
+  moveLabel?: string;
+  /** Trailing slot beside the move action: a `DropdownMenu` trigger, an assign button. */
+  actions?: ReactNode;
+  /** Names the press target. Defaults to the title, the account and the amount. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** One stage of the pipeline, as data the board can lay out without rendering it. */
+export interface PipelineStage {
+  /** Stable identity. Also the key the single-column layout selects by. */
+  id: string;
+  name: string;
+  /** Deals in the stage. Drawn as a counter beside the name. */
+  count?: number;
+  /**
+   * The summed amount, PRE-FORMATTED by the app for the same reason
+   * {@link DealCardProps.amount} is.
+   */
+  total?: string;
+  /** The stage's dot. Default `primary`. */
+  tone?: AccentTone;
+  /** What an empty column says. Default `"No deals in this stage"`. */
+  emptyLabel?: string;
+  /** Draws placeholder cards instead of the children. */
+  loading?: boolean;
+  /** Renders the "load more" action under the cards. */
+  onLoadMore?: () => void;
+  /** Default `"Load more"`. */
+  loadMoreLabel?: string;
+}
+
+export interface PipelineColumnProps extends Omit<PipelineStage, 'id'> {
+  /** The deal cards. */
+  children?: ReactNode;
+  /** A fixed width, for a column inside a horizontal board. Omitted, it fills its parent. */
+  width?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/**
+ * `board` draws every column side by side in a horizontal scroller, `single`
+ * draws one at a time behind a tab row, and `auto` measures its own width and
+ * picks — so a board in a side panel behaves like a phone without asking the
+ * window.
+ */
+export type PipelineBoardLayout = 'auto' | 'board' | 'single';
+
+export interface PipelineBoardProps {
+  stages: readonly PipelineStage[];
+  /**
+   * The CARDS of one stage. Called per rendered column — once in `single`,
+   * once per stage in `board`. The board never inspects what it returns.
+   */
+  renderStage: (stage: PipelineStage) => ReactNode;
+  /** Default `auto`. */
+  layout?: PipelineBoardLayout;
+  /** The visible stage in the `single` layout. Controlled. */
+  stageId?: string;
+  /** The stage the `single` layout opens on. Uncontrolled; defaults to the first. */
+  defaultStageId?: string;
+  onStageChange?: (stageId: string) => void;
+  /** Column width in the `board` layout. Default 288. */
+  columnWidth?: number;
+  /** At or below this width `auto` picks `single`. Default 700. */
+  singleMaxWidth?: number;
+  /** Names the board. Required by the tab row in the `single` layout. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/price-breakdown/PriceSummary.tsx

@@ -0,0 +1,158 @@
+import React, { memo, useCallback, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { Button } from '../button';
+import { Divider } from '../divider';
+import { useControllableState } from '../hooks/use-controllable-state';
+import { RiArrowDownSLine } from '../icons/remix/RiArrowDownSLine';
+import { RiArrowUpSLine } from '../icons/remix/RiArrowUpSLine';
+import { useSurfaceFill } from '../styles/surface-levels';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import {
+  PRICE_LINE_GAP,
+  PRICE_PENDING_PLACEHOLDER,
+  PRICE_RULE_SPACING,
+  PRICE_STATE_LABELS,
+} from './constants';
+import { PriceSummaryLine } from './PriceSummaryLine';
+import { resolvePricePaint } from './shared';
+import type { PriceSummaryProps } from './types';
+
+/**
+ * What a price is made of: the charges, and the number they add up to.
+ *
+ *   lines     a `list` of `PriceSummaryLine`s, 4 apart
+ *   rule      a hairline above the total, 8 either side
+ *   total     title-3-semibold on BOTH sides. The total is the answer, so it is
+ *             a type step above the charges rather than the same size in bold —
+ *             a reader scanning for the number finds it without reading any of
+ *             the lines.
+ *   collapse  the LINES fold, never the total: the number stays on screen and
+ *             the itemisation is what a reader opts into. The disclosure is a
+ *             `text` button carrying `aria-expanded`, so it announces the state
+ *             it controls on both platforms.
+ *
+ * It adds nothing up. Every amount here — each line's and the total's — is a
+ * string the app formatted, because currency, locale, rounding and the sign on
+ * a credit are all decisions this component cannot make correctly for three
+ * different apps.
+ */
+function PriceSummaryComponent({
+  lines,
+  total,
+  collapsible = false,
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  expandLabel = 'Show price details',
+  collapseLabel = 'Hide price details',
+  stateLabels,
+  pendingPlaceholder = PRICE_PENDING_PLACEHOLDER,
+  accessibilityLabel = 'Price breakdown',
+  style,
+  testID,
+}: PriceSummaryProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolvePricePaint(theme, surface), [theme, surface]);
+  const [open, setOpen] = useControllableState<boolean>({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+  });
+  const toggle = useCallback(() => setOpen(!open), [open, setOpen]);
+
+  const words = { ...PRICE_STATE_LABELS, ...stateLabels };
+  const totalCaveat = total && total.state && total.state !== 'final' ? words[total.state] : undefined;
+  const showLines = !collapsible || open;
+
+  return (
+    <View testID={testID} style={style}>
+      {showLines ? (
+        <View
+          role="list"
+          accessibilityLabel={accessibilityLabel}
+          testID={testID ? `${testID}-lines` : undefined}
+          style={{ gap: PRICE_LINE_GAP }}
+        >
+          {lines.map((line, index) => (
+            <PriceSummaryLine
+              key={line.id ?? index}
+              label={line.label}
+              sublabel={line.sublabel}
+              amount={line.amount}
+              tone={line.tone}
+              state={line.state}
+              info={line.info}
+              infoAccessibilityLabel={line.infoAccessibilityLabel}
+              stateLabels={stateLabels}
+              pendingPlaceholder={pendingPlaceholder}
+              testID={testID ? `${testID}-line-${index}` : undefined}
+            />
+          ))}
+        </View>
+      ) : null}
+      {collapsible ? (
+        <View style={{ alignItems: 'flex-start', paddingTop: showLines ? PRICE_LINE_GAP : 0 }}>
+          <Button
+            variant="text"
+            size="small"
+            trailingIcon={open ? RiArrowUpSLine : RiArrowDownSLine}
+            onPress={toggle}
+            aria-expanded={open}
+            testID={testID ? `${testID}-disclosure` : undefined}
+          >
+            {open ? collapseLabel : expandLabel}
+          </Button>
+        </View>
+      ) : null}
+      {total ? (
+        <>
+          <Divider color={paint.rule} spacing={PRICE_RULE_SPACING} />
+          <View style={{ flexDirection: 'row', alignItems: 'flex-start', gap: 12 }}>
+            <View style={{ flex: 1, minWidth: 0 }}>
+              <Text
+                variant="title-3-semibold"
+                testID={testID ? `${testID}-total-label` : undefined}
+                style={{ color: paint.text }}
+              >
+                {total.label}
+              </Text>
+              {total.note ? (
+                <Text
+                  variant="body-2-regular"
+                  testID={testID ? `${testID}-total-note` : undefined}
+                  style={{ color: paint.textSecondary }}
+                >
+                  {total.note}
+                </Text>
+              ) : null}
+            </View>
+            <View style={{ alignItems: 'flex-end' }}>
+              <Text
+                variant="title-3-semibold"
+                testID={testID ? `${testID}-total-amount` : undefined}
+                style={{ color: paint.text, fontVariant: ['tabular-nums'], textAlign: 'right' }}
+              >
+                {total.amount ?? pendingPlaceholder}
+              </Text>
+              {totalCaveat ? (
+                <Text
+                  variant="caption-1-regular"
+                  testID={testID ? `${testID}-total-state` : undefined}
+                  style={{ color: paint.textTertiary, textAlign: 'right' }}
+                >
+                  {totalCaveat}
+                </Text>
+              ) : null}
+            </View>
+          </View>
+        </>
+      ) : null}
+    </View>
+  );
+}
+
+export const PriceSummary = memo(PriceSummaryComponent);
+PriceSummary.displayName = 'PriceSummary';

package/src/price-breakdown/PriceSummaryLine.tsx

@@ -0,0 +1,138 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { GlyphButton } from '../button';
+import { RiInformationLine } from '../icons/remix/RiInformationLine';
+import { Popover, PopoverContent, PopoverTrigger } from '../popover';
+import { useSurfaceFill } from '../styles/surface-levels';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import {
+  PRICE_INFO_GLYPH,
+  PRICE_INFO_SIZE,
+  PRICE_LINE_HEIGHT,
+  PRICE_PENDING_PLACEHOLDER,
+  PRICE_STATE_LABELS,
+} from './constants';
+import { resolvePricePaint } from './shared';
+import type { PriceSummaryLineProps } from './types';
+
+/**
+ * ONE charge: what it is on the left, what it costs on the right.
+ *
+ *   label     body-regular; `sublabel` body-2-regular secondary beneath it
+ *   amount    body-regular, TABULAR figures, right-aligned — a column of
+ *             proportional digits does not line up and a price column that does
+ *             not line up cannot be scanned
+ *   state     "Estimated" / "Pending" in caption-1 under the amount, so the
+ *             caveat travels with the NUMBER rather than with the label; the
+ *             row keeps its own reading order for a screen reader
+ *   info      a 32 round glyph after the label, opening a `Popover`
+ *   height    32 minimum, whether or not the line has the info affordance
+ *
+ * The amount is drawn exactly as it arrives. Nothing here parses a number,
+ * applies a sign or picks a currency: `tone="discount"` colours a credit, it
+ * does not negate one.
+ */
+function PriceSummaryLineComponent({
+  label,
+  sublabel,
+  amount,
+  tone = 'default',
+  state = 'final',
+  info,
+  infoAccessibilityLabel,
+  stateLabels,
+  pendingPlaceholder = PRICE_PENDING_PLACEHOLDER,
+  style,
+  testID,
+}: PriceSummaryLineProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolvePricePaint(theme, surface), [theme, surface]);
+  const words = { ...PRICE_STATE_LABELS, ...stateLabels };
+
+  const muted = tone === 'muted';
+  const labelColor = muted ? paint.textSecondary : paint.text;
+  const amountColor =
+    tone === 'discount' ? paint.discount : muted ? paint.textSecondary : paint.text;
+  const caveat = state === 'final' ? undefined : words[state];
+
+  return (
+    <View
+      role="listitem"
+      testID={testID}
+      style={[
+        {
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: 12,
+          minHeight: PRICE_LINE_HEIGHT,
+        },
+        style,
+      ]}
+    >
+      <View style={{ flex: 1, minWidth: 0, flexDirection: 'row', alignItems: 'center', gap: 2 }}>
+        <View style={{ flexShrink: 1, minWidth: 0 }}>
+          <Text variant="body-regular" testID={testID ? `${testID}-label` : undefined} style={{ color: labelColor }}>
+            {label}
+          </Text>
+          {sublabel ? (
+            <Text
+              variant="body-2-regular"
+              testID={testID ? `${testID}-sublabel` : undefined}
+              style={{ color: paint.textSecondary }}
+            >
+              {sublabel}
+            </Text>
+          ) : null}
+        </View>
+        {info != null ? (
+          <Popover>
+            <PopoverTrigger asChild>
+              <GlyphButton
+                size={PRICE_INFO_SIZE}
+                glyphSize={PRICE_INFO_GLYPH}
+                icon={RiInformationLine}
+                color={paint.textTertiary}
+                hoverColor={paint.text}
+                accessibilityLabel={infoAccessibilityLabel ?? `About ${label}`}
+                testID={testID ? `${testID}-info` : undefined}
+              />
+            </PopoverTrigger>
+            <PopoverContent label={label} side="top" align="start" maxWidth={280}>
+              {typeof info === 'string' ? (
+                <Text variant="body-2-regular" style={{ color: paint.text }}>
+                  {info}
+                </Text>
+              ) : (
+                info
+              )}
+            </PopoverContent>
+          </Popover>
+        ) : null}
+      </View>
+      <View style={{ alignItems: 'flex-end' }}>
+        <Text
+          variant="body-regular"
+          testID={testID ? `${testID}-amount` : undefined}
+          style={{ color: amountColor, fontVariant: ['tabular-nums'], textAlign: 'right' }}
+        >
+          {amount ?? pendingPlaceholder}
+        </Text>
+        {caveat ? (
+          <Text
+            variant="caption-1-regular"
+            testID={testID ? `${testID}-state` : undefined}
+            style={{ color: paint.textTertiary, textAlign: 'right' }}
+          >
+            {caveat}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+export const PriceSummaryLine = memo(PriceSummaryLineComponent);
+PriceSummaryLine.displayName = 'PriceSummaryLine';

package/src/price-breakdown/constants.ts

@@ -0,0 +1,26 @@
+import type { PriceLineState } from './types';
+
+/** The word drawn beside an amount that is not the answer yet. */
+export const PRICE_STATE_LABELS: Record<Exclude<PriceLineState, 'final'>, string> = {
+  estimated: 'Estimated',
+  pending: 'Pending',
+};
+
+/** Drawn where the amount would be on a line that has none. */
+export const PRICE_PENDING_PLACEHOLDER = '—';
+
+/**
+ * One line's minimum height. It is the 32 rung rather than the 20 a body line
+ * needs, so that a line carrying the info affordance is the same height as the
+ * lines around it — the glyph is a 32 round target and a row that grew only
+ * where an explanation happened to exist read as a ragged column.
+ */
+export const PRICE_LINE_HEIGHT = 32;
+
+/** The info affordance: a 32 round target with a 16 glyph. */
+export const PRICE_INFO_SIZE = 32;
+export const PRICE_INFO_GLYPH = 16;
+
+/** Space between two lines, and around the rule above the total. */
+export const PRICE_LINE_GAP = 4;
+export const PRICE_RULE_SPACING = 8;

package/src/price-breakdown/index.ts

@@ -0,0 +1,17 @@
+export { PriceSummary } from './PriceSummary';
+export { PriceSummaryLine } from './PriceSummaryLine';
+export {
+  PRICE_PENDING_PLACEHOLDER,
+  PRICE_STATE_LABELS,
+} from './constants';
+export { resolvePricePaint } from './shared';
+export type { PricePaint } from './shared';
+export type {
+  PriceLine,
+  PriceLineState,
+  PriceLineTone,
+  PriceStateLabels,
+  PriceSummaryLineProps,
+  PriceSummaryProps,
+  PriceTotal,
+} from './types';

package/src/price-breakdown/shared.ts

@@ -0,0 +1,30 @@
+/**
+ * What the price rows paint, read RELATIVE to the surface they were dropped on
+ * (`styles/surface-levels.ts`) — a breakdown sits inside a checkout card as
+ * often as on a page, and a rule or a quiet caption picked by eye disappears on
+ * one of the two.
+ *
+ * Pure, so `PriceSummary.test.tsx` can walk presets and modes without rendering.
+ */
+import { hairlineOn, surfaceTextOn, type SurfaceTextPaint } from '../styles/surface-levels';
+import { resolveAccentColors } from '../theme/accent-colors';
+import type { Theme } from '../theme/types';
+
+export interface PricePaint extends SurfaceTextPaint {
+  /** The rule above the total, and any divider between groups of lines. */
+  rule: string;
+  /**
+   * A discount's amount. The tone's SUBTLE foreground, which is the member the
+   * palette sizes to be legible as text on a surface — the solid fill is sized
+   * to carry a white label and is too loud to read as a number.
+   */
+  discount: string;
+}
+
+export function resolvePricePaint(theme: Theme, surface: string): PricePaint {
+  return {
+    ...surfaceTextOn(theme, surface),
+    rule: hairlineOn(theme, surface),
+    discount: resolveAccentColors(theme.colors, 'success', 'subtle').foreground,
+  };
+}