@oxy.so/bloom 4.0.0 → 4.1.0

package/src/proof-of-delivery/shared.ts

@@ -0,0 +1,190 @@
+/**
+ * The pure decisions behind the door step: what a stroke looks like as a path,
+ * whether a proof has been given, and what is still missing.
+ *
+ * All of it is exported because none of it can be measured where it is used.
+ * **A jest test cannot see a canvas** — react-native-svg renders to a native
+ * view on one platform and to a `<path>` on the other, and jsdom paints
+ * neither — so the drawing is verified in a real browser
+ * (`scripts/verify-signature-pad.mjs`) and the GEOMETRY is verified here, as a
+ * function of points, where every boundary is reachable: no points, one point,
+ * two, a hundred.
+ */
+import { hairlineOn, surfaceFillOn, surfaceTextOn } from '../styles/surface-levels';
+import type { SurfaceTextPaint } from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+import { PROOF_GEOMETRY, PROOF_ORDER } from './constants';
+import type {
+  ProofKind,
+  ProofOfDeliveryValue,
+  SignaturePoint,
+  SignatureStroke,
+  SignatureValue,
+} from './types';
+
+export interface ProofPaint {
+  surface: string;
+  hairline: string;
+  /** The pad's own fill — the next level up from whatever it is drawn on. */
+  pad: string;
+  text: string;
+  textSecondary: string;
+  textTertiary: string;
+  /** The text rungs that clear AA on the PAD, which is not the form's fill. */
+  padText: SurfaceTextPaint;
+}
+
+export function resolveProofPaint(theme: Theme, surface: string): ProofPaint {
+  const text = surfaceTextOn(theme, surface);
+  const pad = surfaceFillOn(theme, surface);
+  return {
+    surface,
+    hairline: hairlineOn(theme, surface),
+    pad,
+    text: text.text,
+    textSecondary: text.textSecondary,
+    textTertiary: text.textTertiary,
+    padText: surfaceTextOn(theme, pad),
+  };
+}
+
+/** The empty value: nothing drawn, nothing typed, nothing photographed. */
+export const EMPTY_SIGNATURE: SignatureValue = { strokes: [], typedName: '' };
+
+export const EMPTY_PROOF: ProofOfDeliveryValue = {
+  signature: EMPTY_SIGNATURE,
+  photos: [],
+  code: '',
+  recipient: '',
+  note: '',
+};
+
+/** Fills the gaps in a partial value with the empty one, leaving the rest alone. */
+export function completeProofValue(
+  value: Partial<ProofOfDeliveryValue> | undefined,
+): ProofOfDeliveryValue {
+  return {
+    signature: value?.signature ?? EMPTY_SIGNATURE,
+    photos: value?.photos ?? EMPTY_PROOF.photos,
+    code: value?.code ?? '',
+    recipient: value?.recipient ?? '',
+    note: value?.note ?? '',
+  };
+}
+
+/**
+ * One stroke as SVG path data, smoothed.
+ *
+ *   no points     `''` — nothing drawn is not a path of length zero, it is no
+ *                 path at all, and an `<path d="">` is an element the browser
+ *                 still lays out
+ *   one point     a DOT: a zero-length line with a round cap, which is what a
+ *                 full stop in a signature is. Without this a tap lays down
+ *                 nothing and the reader taps harder
+ *   two or more   a move, then a quadratic through the MIDPOINTS of successive
+ *                 points, ending on the last point. Midpoint smoothing is what
+ *                 turns a 60-samples-a-second polyline into something that
+ *                 reads as handwriting; joining the raw points draws the
+ *                 pointer's own stair-stepping
+ *
+ * Coordinates are rounded to two places: a signature does not need a
+ * ten-thousandth of a pixel, and the untrimmed floats triple the size of a
+ * value an app is about to upload.
+ */
+export function signaturePath(stroke: SignatureStroke): string {
+  if (stroke.length === 0) return '';
+  const r = (n: number) => Math.round(n * 100) / 100;
+  const first = stroke[0]!;
+  if (stroke.length === 1) return `M${r(first.x)} ${r(first.y)}l0 0`;
+
+  let d = `M${r(first.x)} ${r(first.y)}`;
+  for (let i = 1; i < stroke.length - 1; i += 1) {
+    const point = stroke[i]!;
+    const next = stroke[i + 1]!;
+    d += `Q${r(point.x)} ${r(point.y)} ${r((point.x + next.x) / 2)} ${r((point.y + next.y) / 2)}`;
+  }
+  const last = stroke[stroke.length - 1]!;
+  d += `L${r(last.x)} ${r(last.y)}`;
+  return d;
+}
+
+/**
+ * Whether a point is far enough from the last one to be worth keeping.
+ *
+ * A pointer reports the same coordinate many times while a finger rests, and
+ * every repeat is a quadratic segment of length zero that the smoothing then
+ * has to average. Dropping them is what keeps the path proportional to the
+ * MOVEMENT rather than to the duration of the press.
+ */
+export function shouldKeepSignaturePoint(
+  last: SignaturePoint | undefined,
+  point: SignaturePoint,
+  minDistance: number = PROOF_GEOMETRY.smoothing,
+): boolean {
+  if (last === undefined) return true;
+  return Math.abs(point.x - last.x) + Math.abs(point.y - last.y) >= minDistance;
+}
+
+/** Whether anything has been drawn. A stroke with no points is not one. */
+export function hasSignatureInk(value: SignatureValue | undefined): boolean {
+  return (value?.strokes ?? []).some((stroke) => stroke.length > 0);
+}
+
+/**
+ * Whether a signature has been GIVEN, by either path.
+ *
+ * Drawn ink and a typed name are the same answer, and this is the one place
+ * that is decided — so a screen-reader user who typed their name is never told
+ * the signature is missing.
+ */
+export function isSignatureGiven(value: SignatureValue | undefined): boolean {
+  return hasSignatureInk(value) || (value?.typedName ?? '').trim() !== '';
+}
+
+/**
+ * Whether one proof has been given.
+ *
+ * A code counts only once it is FULL: `InputOtp` reports every keystroke, and
+ * "2 of 4 digits" is not a code the recipient read out. `codeLength` is
+ * therefore part of the question rather than something the caller checks after.
+ */
+export function isProofGiven(
+  kind: ProofKind,
+  value: ProofOfDeliveryValue,
+  codeLength: number,
+): boolean {
+  switch (kind) {
+    case 'signature':
+      return isSignatureGiven(value.signature);
+    case 'photo':
+      return value.photos.length > 0;
+    case 'code':
+      return value.code.length >= codeLength;
+    case 'recipient':
+      return value.recipient.trim() !== '';
+    case 'note':
+      return value.note.trim() !== '';
+  }
+}
+
+/**
+ * The required proofs that have not been given, in the order they were asked.
+ *
+ * A proof that is required but NOT DRAWN cannot be missing: an app that asks for
+ * four proofs and requires a fifth it never showed would refuse a delivery over
+ * a control nobody could see. The intersection is taken deliberately, and the
+ * ORDER is the drawn order so the summary reads down the form.
+ */
+export function missingProofs(
+  value: ProofOfDeliveryValue,
+  required: readonly ProofKind[],
+  shown: readonly ProofKind[],
+  codeLength: number,
+): ProofKind[] {
+  return shown.filter((kind) => required.includes(kind) && !isProofGiven(kind, value, codeLength));
+}
+
+/** The proofs to draw, in the canonical order, with anything unknown dropped. */
+export function orderProofs(proofs: readonly ProofKind[]): ProofKind[] {
+  return PROOF_ORDER.filter((kind) => proofs.includes(kind));
+}

package/src/proof-of-delivery/types.ts

@@ -0,0 +1,174 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { SortablePhoto } from '../sortable-media';
+
+/** One point of a drawn stroke, in the pad's own coordinates. */
+export interface SignaturePoint {
+  x: number;
+  y: number;
+}
+
+/** One unbroken line: the points between a finger going down and coming up. */
+export type SignatureStroke = readonly SignaturePoint[];
+
+/**
+ * A signature, which is EITHER drawn OR typed and never has to be both.
+ *
+ * Both halves live in one value because they are one answer to one question.
+ * A pad that reported only strokes would make the typed name a second field the
+ * app had to remember to collect, and the first app that forgot it would ship a
+ * signature step no screen-reader user could complete.
+ */
+export interface SignatureValue {
+  /** What was drawn, oldest stroke first. */
+  strokes: readonly SignatureStroke[];
+  /** What was typed instead. */
+  typedName?: string;
+}
+
+/**
+ * The five things an app can ask for at the door.
+ *
+ * Each is independent: an app asks for none, one, or all five, and says
+ * separately which of the ones it asked for it will not accept a delivery
+ * without.
+ */
+export type ProofKind = 'signature' | 'photo' | 'code' | 'recipient' | 'note';
+
+/** Everything collected at the door. */
+export interface ProofOfDeliveryValue {
+  signature: SignatureValue;
+  /** The photos, in order, handed to `SortablePhotoGrid` unchanged. */
+  photos: readonly SortablePhoto[];
+  /** The code the recipient read out. Digits only — `InputOtp` cleans it. */
+  code: string;
+  /** Who took it. */
+  recipient: string;
+  /** Anything else about how it went. */
+  note: string;
+}
+
+/** What the whole thing reports: the value, and what is still missing from it. */
+export interface ProofOfDeliveryResult extends ProofOfDeliveryValue {
+  /**
+   * The REQUIRED proofs that have not been given, in the order they were asked.
+   * Empty means the delivery can be recorded.
+   */
+  missing: readonly ProofKind[];
+}
+
+/** Every word the family speaks, in one prop. */
+export interface ProofOfDeliveryLabels {
+  /** Over the signature block. Default `"Signature"`. */
+  signature?: string;
+  /** The pad's own name and hint. Defaults `"Signature"` / `"Sign with your finger"`. */
+  signaturePad?: string;
+  signatureHint?: string;
+  /** Said instead of the hint once something has been drawn. Default `"Signed"`. */
+  signed?: string;
+  /** The clear control. Default `"Clear the signature"`. */
+  clear?: string;
+  /** The typed alternative's label and placeholder. Defaults `"Or type your name"` / `"Full name"`. */
+  typeName?: string;
+  typeNamePlaceholder?: string;
+  /** Over the photo block. Default `"Photo"`. */
+  photo?: string;
+  /** Under it. Default `"Where you left it, or the parcel with the recipient."`. */
+  photoHint?: string;
+  /** Over the code block. Default `"Delivery code"`. */
+  code?: string;
+  /** Under it. Default `"Ask the recipient to read out the code in their app."`. */
+  codeHint?: string;
+  /** Over the recipient block. Default `"Who received it"`. */
+  recipient?: string;
+  recipientPlaceholder?: string;
+  /** Over the note block. Default `"Note"`. */
+  note?: string;
+  notePlaceholder?: string;
+  /** The submit control. Default `"Confirm the delivery"`. */
+  submit?: string;
+  /** Marks a block the app will not accept without. Default `"Required"`. */
+  required?: string;
+  /** Shown on a required block that is still empty, after a submit. Default `"This is needed before you can confirm."`. */
+  missing?: string;
+  /** The line over the missing list, after a failed submit. Default `` (n) => n === 1 ? 'One thing is still missing' : `${n} things are still missing` ``. */
+  missingSummary?: (count: number) => string;
+}
+
+export interface SignaturePadProps {
+  /** Controlled value. */
+  value?: SignatureValue;
+  /** Uncontrolled initial value. Default no strokes and no typed name. */
+  defaultValue?: SignatureValue;
+  onChange?: (value: SignatureValue) => void;
+  /** Called with the finished stroke each time the finger comes up. */
+  onStrokeEnd?: (stroke: SignatureStroke) => void;
+  /** How tall the drawing surface is. Default 180. */
+  height?: number;
+  /** The ink. Default the theme's text colour — a signature is writing, not a brand mark. */
+  ink?: string;
+  /** How thick the ink is. Default 2.5. */
+  strokeWidth?: number;
+  /**
+   * Draws the "or type your name" field under the pad. Default `true`.
+   *
+   * SETTING IT TO `false` REMOVES THE ONLY PATH A SCREEN-READER USER HAS. Do it
+   * only where the app collects the name somewhere else on the same screen.
+   */
+  typed?: boolean;
+  /** Stops drawing and typing, and dims the whole block. */
+  disabled?: boolean;
+  labels?: ProofOfDeliveryLabels;
+  /** Names the block. Default `"Signature"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Derives `-pad`, `-stroke-<n>`, `-clear`, `-typed`. */
+  testID?: string;
+}
+
+export interface ProofOfDeliveryProps {
+  /** Which proofs are drawn, in the order they are asked. Default all five. */
+  proofs?: readonly ProofKind[];
+  /**
+   * Which of the drawn proofs the app will not record a delivery without.
+   * Default none — every proof is optional until an app says otherwise.
+   */
+  required?: readonly ProofKind[];
+  /** Controlled value. Any field left out falls back to the empty one. */
+  value?: Partial<ProofOfDeliveryValue>;
+  /** Uncontrolled initial value. */
+  defaultValue?: Partial<ProofOfDeliveryValue>;
+  onChange?: (value: ProofOfDeliveryValue) => void;
+  /**
+   * The one result. It fires on EVERY press, with `missing` filled in — see
+   * `ProofOfDelivery`'s note on why the confirm control is never disabled.
+   */
+  onSubmit?: (result: ProofOfDeliveryResult) => void;
+  /** Opens the app's own picker. Without it the photo block draws no add tile. */
+  onAddPhoto?: () => void;
+  /** Draws the retry control on a failed photo. */
+  onRetryPhoto?: (id: string) => void;
+  /** How many boxes the code has. Default `4`. */
+  codeLength?: number;
+  /** How tall the signature pad is. Default 180. */
+  signatureHeight?: number;
+  /** Hides the add tile once this many photos are in. Default `4`. */
+  maxPhotos?: number;
+  /** Dims the confirm control and stops the press while the app is saving. */
+  submitting?: boolean;
+  /** Stops every control. */
+  disabled?: boolean;
+  /** A heading over the whole thing. */
+  title?: string;
+  /** A line under the heading. */
+  description?: string;
+  /** Replaces the confirm control entirely. */
+  actions?: ReactNode;
+  labels?: ProofOfDeliveryLabels;
+  /** Names the form. Default `"Proof of delivery"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Derives `-signature`, `-photo`, `-code`, `-recipient`, `-note`, `-submit`. */
+  testID?: string;
+}

package/src/screen/Screen.tsx

@@ -4,9 +4,10 @@ import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
 import { windowEdgeGap } from '../layout/edge';
 import { useSharedValue } from 'react-native-reanimated';
 import { useTheme } from '../theme/use-theme';
-import { WEB_POSITION_STICKY } from '../styles/web-view-style';
+import { WEB_POSITION_STICKY, WEB_VIEWPORT_HEIGHT } from '../styles/web-view-style';
 import { Z_INDEX } from '../styles/z-index';
 import { ScreenContext, ScreenNavigationContext } from './context';
+import { useScreenWindowBinding } from './use-screen-window-scroll';
 import type { ScreenProps } from './types';
 
 /** One continuous canvas; chrome overlays it and content reserves its measured footprint. */
@@ -34,18 +35,23 @@ export function Screen({ header, bottomBar, primaryAction, active: requestedActi
     return () => { show.remove(); hide.remove(); };
   }, []);
   const hasBottom = !keyboardVisible && Boolean(bottomBar || primaryAction);
-  const value = useMemo(() => ({ active, scrollY, collapseProgress, collapseTarget, activeScrollerId,
-    topInset: header ? top : 0, bottomInset: hasBottom ? bottom + contentClearance : navigationScope === 'inherit' ? inheritedNavigation?.bottomInset ?? contentClearance : contentClearance,
-  }), [active, scrollY, collapseProgress, collapseTarget, activeScrollerId, header, hasBottom, top, bottom, contentClearance, navigationScope, inheritedNavigation?.bottomInset]);
   const document = documentScroll && Platform.OS === 'web';
+  const value = useMemo(() => ({ active, scrollY, collapseProgress, collapseTarget, activeScrollerId,
+    contentInsetsHandled: document, topInset: header ? top : 0, bottomInset: hasBottom ? bottom + contentClearance : navigationScope === 'inherit' ? inheritedNavigation?.bottomInset ?? contentClearance : contentClearance,
+  }), [active, scrollY, collapseProgress, collapseTarget, activeScrollerId, header, hasBottom, top, bottom, contentClearance, navigationScope, inheritedNavigation?.bottomInset, document]);
+  useScreenWindowBinding(value, { active: document });
   const headerNode = header ? <View testID={testID ? `${testID}-header` : undefined} pointerEvents="box-none" onLayout={event => setTop(event.nativeEvent.layout.height)} style={document ? { position: WEB_POSITION_STICKY, top: 0, zIndex: Z_INDEX.floating, marginBottom: -top } : { position: 'absolute', top: 0, left: 0, right: 0 }}>{header}</View> : null;
   const bottomNode = hasBottom ? <View testID={testID ? `${testID}-bottom` : undefined} pointerEvents="box-none" onLayout={event => setBottom(event.nativeEvent.layout.height)} style={document ? { position: WEB_POSITION_STICKY, bottom: 0, zIndex: Z_INDEX.floating, marginTop: -bottom } : { position: 'absolute', bottom: 0, left: 0, right: 0 }}>{bottomBar ?? <View pointerEvents="box-none" style={{ alignItems: 'flex-end', paddingHorizontal: 16, paddingBottom: windowEdgeGap(insets?.bottom ?? 0), minHeight: bottom }}>{primaryAction}</View>}</View> : null;
   return (
     <ScreenNavigationContext.Provider value={navigationScope === 'inherit' ? inheritedNavigation : { ...navigation, bottomInset: value.bottomInset }}>
     <ScreenContext.Provider value={value}>
-      <View {...props} testID={testID} style={[{ flex: 1, minHeight: 0, position: 'relative', backgroundColor: colors.background }, style]}>
+      <View {...props} testID={testID} style={[document ? { minHeight: WEB_VIEWPORT_HEIGHT, width: '100%', position: 'relative', backgroundColor: colors.background } : { flex: 1, minHeight: 0, position: 'relative', backgroundColor: colors.background }, style]}>
         {document ? headerNode : null}
-        {children}
+        {document ? <View testID={testID ? `${testID}-content` : undefined} style={{
+          flexGrow: 1, flexShrink: 0,
+          paddingTop: header ? top : 0,
+          paddingBottom: hasBottom ? bottom + contentClearance : 0,
+        }}>{children}</View> : children}
         {document ? null : headerNode}
         {bottomNode}
       </View>

package/src/screen/context.ts

@@ -7,6 +7,8 @@ export interface ScreenContextValue {
   collapseProgress: SharedValue<number>;
   collapseTarget: SharedValue<number>;
   activeScrollerId: SharedValue<string | null>;
+  /** Document-flow Screen has already reserved its content clearance. */
+  contentInsetsHandled?: boolean;
   topInset: number;
   bottomInset: number;
 }

package/src/screen/types.ts

@@ -9,7 +9,7 @@ export interface ScreenProps extends ViewProps {
   active?: boolean;
   /** inherit shell navigation motion; shared establishes a shell; isolated resets it for a modal. */
   navigationScope?: 'inherit' | 'shared' | 'isolated';
-  /** Web document scroller: keep chrome sticky inside this column. */
+  /** Web document flow: bind window scrolling automatically, reserve chrome clearance, and keep chrome sticky within this column. Explicit list bindings take priority. */
   documentScroll?: boolean;
   bottomBar?: ReactNode;
   /** Standalone action; with navigation use BottomBar.action instead. */

package/src/screen/use-screen-scroll.ts

@@ -34,5 +34,5 @@ export function useScreenScroll({ active: requestedActive = true, handler = null
     }
   } }, [screen, active, id, previousY, reducedMotion, hasRestoration, record, restoring]);
   const onScroll = useComposedEventHandler([ownHandler, handler]);
-  return { onScroll, contentInsets: { top: screen.topInset, bottom: screen.bottomInset }, scrollY: screen.scrollY, collapseProgress: screen.collapseProgress };
+  return { onScroll, scrollerId: id, contentInsets: { top: screen.contentInsetsHandled ? 0 : screen.topInset, bottom: screen.contentInsetsHandled ? 0 : screen.bottomInset }, scrollY: screen.scrollY, collapseProgress: screen.collapseProgress };
 }

package/src/screen/use-screen-window-scroll.ts

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import { useReducedMotion, withSpring } from 'react-native-reanimated';
-import { useScreen } from './context';
+import { useScreen, type ScreenContextValue } from './context';
 import { useScreenScroll } from './use-screen-scroll';
 import type { ScreenScrollOptions } from './types';
 
@@ -8,16 +8,21 @@ import type { ScreenScrollOptions } from './types';
 export function useScreenWindowScroll(options: ScreenScrollOptions = {}) {
   const binding = useScreenScroll(options);
   const screen = useScreen();
+  useScreenWindowBinding(screen, options, binding.scrollerId);
+  return binding;
+}
+
+/** Internal default listener yields to a registered list/virtualizer. */
+export function useScreenWindowBinding(screen: ScreenContextValue, options: ScreenScrollOptions = {}, owner: string | null = null) {
   const reducedMotion = useReducedMotion();
   useEffect(() => {
     if (!screen.active || options.active === false || typeof window === 'undefined') return;
-    const owner = screen.activeScrollerId.value;
     let previous = window.scrollY;
     const update = () => {
-      if (screen.activeScrollerId.value !== owner) return;
       const y = Math.max(0, window.scrollY);
       const delta = y - previous;
       previous = y;
+      if (screen.activeScrollerId.value !== owner) return;
       screen.scrollY.value = y;
       if (options.restoration?.restorePending) return;
       const target = y < 24 ? 0 : delta > 3 ? 1 : delta < -3 ? 0 : screen.collapseTarget.value;
@@ -26,9 +31,8 @@ export function useScreenWindowScroll(options: ScreenScrollOptions = {}) {
         screen.collapseProgress.value = reducedMotion ? target : withSpring(target, { duration: 380, dampingRatio: 1 });
       }
     };
-    screen.scrollY.value = previous;
+    if (screen.activeScrollerId.value === owner) screen.scrollY.value = previous;
     window.addEventListener('scroll', update, { passive: true });
     return () => window.removeEventListener('scroll', update);
-  }, [screen, options.active, options.restoration?.restorePending, reducedMotion]);
-  return binding;
+  }, [screen, options.active, options.restoration?.restorePending, reducedMotion, owner]);
 }

package/src/settings-list/SettingsList.tsx

@@ -19,6 +19,7 @@ import type {
 export const SettingsListItem = memo<SettingsListItemProps>(function SettingsListItem({
   icon,
   title,
+  titleNumberOfLines = 1,
   description,
   value,
   rightElement,
@@ -59,7 +60,7 @@ export const SettingsListItem = memo<SettingsListItemProps>(function SettingsLis
       <View style={styles.textContainer}>
         <Text
           style={[styles.title, { color: titleColor }]}
-          numberOfLines={1}
+          numberOfLines={titleNumberOfLines === 0 ? undefined : titleNumberOfLines}
         >
           {title}
         </Text>

package/src/settings-list/types.ts

@@ -5,6 +5,16 @@ export interface SettingsListItemProps {
   icon?: React.ReactNode;
   /** Primary label */
   title: string;
+  /**
+   * How many lines the title may take before it truncates. Default `1`.
+   *
+   * One line is right for a setting, whose title is a NOUN ("Language",
+   * "Notifications") and whose value sits on the right. It is wrong for a row
+   * whose title is the CONTENT — a postal address, a full file name — where
+   * the tail that gets cut is the part that identifies it. `0` never
+   * truncates.
+   */
+  titleNumberOfLines?: number;
   /** Secondary description text below title */
   description?: string;
   /** Right-side value text (e.g. "English", "On") */