@oxy.so/bloom 4.0.0 → 4.2.0

package/src/map-attribution/MapAttribution.tsx

@@ -0,0 +1,126 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { Button } from '../button';
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { MAP_ATTRIBUTION_GEOMETRY } from './constants';
+import { MapAttributionShell } from './MapAttributionShell';
+import { MapScaleBar } from './MapScaleBar';
+import { resolveMapAttributionPaint } from './shared';
+import type { MapAttributionProps } from './types';
+
+/**
+ * THE SMALL PRINT, which is not optional: who the map data belongs to, how big
+ * the map is, and when the tiles were last refreshed.
+ *
+ *   shell    `island` by default — the credit has to stay legible over a
+ *            satellite photo, a white street map and everything between, and
+ *            the only way to promise that is not to put it ON the map. The
+ *            island's fill is a surface Bloom owns; the tiles are not.
+ *   scale    `MapScaleBar`, drawn `inline` so the pane is one pane rather than
+ *            two stacked ones
+ *   credit   `caption-2-regular`. With `onPressCredit` it is `Button`'s `link`
+ *            variant at the same step — running text with the library's own
+ *            focus ring and hover underline, rather than a second pressable
+ *            with a ring of its own.
+ *   updated  after a separator, at the same step, one rung quieter
+ *
+ * ── THE CREDIT IS REQUIRED AND NEVER DEFAULTED ──────────────────────────────
+ *
+ * Every other string here has a sensible English default. This one does not,
+ * and that is the point: a component that invented a credit would put a WRONG
+ * attribution on a map, and a wrong attribution is a licence problem rather
+ * than a visual one. The app passes what its provider's licence says, verbatim.
+ *
+ * It reads no clock and knows no units. `updated` and every scale reading
+ * arrive pre-formatted.
+ */
+function MapAttributionComponent({
+  credit,
+  onPressCredit,
+  creditLabel,
+  scales,
+  scaleLabel,
+  updated,
+  variant = 'island',
+  accessibilityLabel = 'Map data',
+  style,
+  testID,
+}: MapAttributionProps) {
+  const theme = useTheme();
+  const paint = useMemo(() => resolveMapAttributionPaint(theme), [theme]);
+  const g = MAP_ATTRIBUTION_GEOMETRY;
+
+  return (
+    <MapAttributionShell
+      variant={variant}
+      role="group"
+      accessibilityLabel={accessibilityLabel}
+      style={style}
+      testID={testID}
+    >
+      {scales && scales.length > 0 ? (
+        <MapScaleBar
+          scales={scales}
+          scaleLabel={scaleLabel}
+          variant="inline"
+          testID={testID ? `${testID}-scale` : undefined}
+        />
+      ) : null}
+      {/*
+        Wrapping, not truncating. A credit is a licence requirement, so the one
+        thing it must never do is silently lose its second half on a narrow
+        phone — it takes a second line instead.
+      */}
+      <View
+        style={{ flexDirection: 'row', flexWrap: 'wrap', alignItems: 'center', gap: g.scaleGap }}
+      >
+        {onPressCredit ? (
+          <Button
+            variant="link"
+            linkTone="secondary"
+            textVariant="caption-2-regular"
+            underline="hover"
+            onPress={onPressCredit}
+            accessibilityLabel={creditLabel ?? credit}
+            testID={testID ? `${testID}-credit` : undefined}
+          >
+            {credit}
+          </Button>
+        ) : (
+          <Text
+            variant="caption-2-regular"
+            testID={testID ? `${testID}-credit` : undefined}
+            style={{ color: paint.textSecondary }}
+          >
+            {credit}
+          </Text>
+        )}
+        {updated ? (
+          <>
+            <Text
+              aria-hidden
+              accessibilityElementsHidden
+              importantForAccessibility="no"
+              variant="caption-2-regular"
+              style={{ color: paint.textGraphical }}
+            >
+              ·
+            </Text>
+            <Text
+              variant="caption-2-regular"
+              testID={testID ? `${testID}-updated` : undefined}
+              style={{ color: paint.textTertiary }}
+            >
+              {updated}
+            </Text>
+          </>
+        ) : null}
+      </View>
+    </MapAttributionShell>
+  );
+}
+
+export const MapAttribution = memo(MapAttributionComponent);
+MapAttribution.displayName = 'MapAttribution';

package/src/map-attribution/MapAttributionShell.tsx

@@ -0,0 +1,81 @@
+import React, { memo, type ReactNode } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { GlassIsland } from '../glass';
+import { MAP_ATTRIBUTION_GEOMETRY } from './constants';
+import type { MapAttributionVariant } from './types';
+
+/**
+ * The box the small print sits in — the ONE place the two components in this
+ * family decide what "legible over any tile" means, so they cannot drift apart.
+ *
+ * `island` is `GlassIsland` at the 8 rung: a translucent pane with a hairline
+ * and a shadow, over content Bloom does not own. It is asked for a SURFACE
+ * radius rather than its default capsule, because the small print is a surface
+ * and the pill rung belongs to button-like controls. `inline` renders a plain
+ * `View` with the same padding, for a strip already inside a surface the app
+ * painted — a legend panel, a settings row — where a second pane would be a
+ * second card.
+ *
+ * Internal: not on the barrel. It is the shell, not a component a consumer
+ * should mount around something else.
+ */
+export interface MapAttributionShellProps {
+  variant: MapAttributionVariant;
+  children?: ReactNode;
+  role?: 'group';
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+function MapAttributionShellComponent({
+  variant,
+  children,
+  role,
+  accessibilityLabel,
+  style,
+  testID,
+}: MapAttributionShellProps) {
+  const g = MAP_ATTRIBUTION_GEOMETRY;
+  const box: ViewStyle = {
+    flexDirection: 'column',
+    alignSelf: 'flex-start',
+    paddingTop: g.paddingVertical,
+    paddingBottom: g.paddingVertical,
+    paddingLeft: g.paddingHorizontal,
+    paddingRight: g.paddingHorizontal,
+    gap: g.gap,
+  };
+
+  if (variant === 'inline') {
+    return (
+      <View
+        role={role}
+        accessibilityLabel={accessibilityLabel}
+        testID={testID}
+        // No padding at all: `inline` is the words and nothing else, and a pane
+        // that kept the island's inset would show as a margin nobody asked for
+        // inside the surface the app already painted.
+        style={[box, { paddingTop: 0, paddingBottom: 0, paddingLeft: 0, paddingRight: 0 }, style]}
+      >
+        {children}
+      </View>
+    );
+  }
+
+  return (
+    <GlassIsland
+      radius={g.radius}
+      role={role}
+      accessibilityLabel={accessibilityLabel}
+      style={[box, style]}
+      testID={testID}
+    >
+      {children}
+    </GlassIsland>
+  );
+}
+
+export const MapAttributionShell = memo(MapAttributionShellComponent);
+MapAttributionShell.displayName = 'MapAttributionShell';

package/src/map-attribution/MapScaleBar.tsx

@@ -0,0 +1,107 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import { MAP_ATTRIBUTION_GEOMETRY } from './constants';
+import { MapAttributionShell } from './MapAttributionShell';
+import { describeScale, resolveMapAttributionPaint } from './shared';
+import type { MapScaleBarProps } from './types';
+
+/**
+ * HOW BIG THE MAP IS: a measured span with a tick at each end, and what that
+ * span is worth.
+ *
+ *   bar      the app's own width in pixels, a 1px rule along the bottom and a
+ *            5px tick rising from each end — the ticks are what make it read as
+ *            a measurement BETWEEN TWO MARKS rather than as an underline
+ *   reading  `caption-2-medium`, at the end of the bar, on the baseline
+ *   two bars  metric over imperial, sharing a left edge, so the eye compares
+ *            them as one instrument rather than reading two
+ *
+ * The rule takes the GRAPHICAL contrast rung and the reading a TEXT one. They
+ * are different jobs: a line has to be seen, a number has to be read, and
+ * flooring the line at text contrast would make the quietest thing on the map
+ * the loudest thing on the strip.
+ *
+ * It converts nothing. Every width and every reading comes from the app,
+ * because the projection does — see `MapScale`.
+ *
+ * The whole thing is one `img` named by `describeScale`: a bar and two ticks
+ * say nothing aloud, and "500 m" on its own is as likely to be a distance to
+ * somewhere as a scale.
+ */
+function MapScaleBarComponent({
+  scales,
+  variant = 'island',
+  scaleLabel,
+  accessibilityLabel,
+  style,
+  testID,
+}: MapScaleBarProps) {
+  const theme = useTheme();
+  const paint = useMemo(() => resolveMapAttributionPaint(theme), [theme]);
+  const g = MAP_ATTRIBUTION_GEOMETRY;
+
+  return (
+    <MapAttributionShell variant={variant} style={style} testID={testID}>
+      <View
+        role="img"
+        accessibilityLabel={accessibilityLabel ?? describeScale(scales, scaleLabel)}
+        style={{ gap: g.scaleStack }}
+      >
+        {scales.map((scale, index) => (
+          <View
+            key={scale.id ?? index}
+            testID={testID ? `${testID}-bar-${index}` : undefined}
+            style={{ flexDirection: 'row', alignItems: 'flex-end', gap: g.scaleGap }}
+          >
+            <View style={{ width: Math.max(0, scale.width), height: g.tick }}>
+              <View
+                testID={testID ? `${testID}-rule-${index}` : undefined}
+                style={{
+                  position: 'absolute',
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: g.rule,
+                  backgroundColor: paint.rule,
+                }}
+              />
+              <View
+                style={{
+                  position: 'absolute',
+                  left: 0,
+                  bottom: 0,
+                  width: g.rule,
+                  height: g.tick,
+                  backgroundColor: paint.rule,
+                }}
+              />
+              <View
+                style={{
+                  position: 'absolute',
+                  right: 0,
+                  bottom: 0,
+                  width: g.rule,
+                  height: g.tick,
+                  backgroundColor: paint.rule,
+                }}
+              />
+            </View>
+            <Text
+              variant="caption-2-medium"
+              numberOfLines={1}
+              style={{ color: paint.textSecondary, fontVariant: ['tabular-nums'] }}
+            >
+              {scale.label}
+            </Text>
+          </View>
+        ))}
+      </View>
+    </MapAttributionShell>
+  );
+}
+
+export const MapScaleBar = memo(MapScaleBarComponent);
+MapScaleBar.displayName = 'MapScaleBar';

package/src/map-attribution/constants.ts

@@ -0,0 +1,39 @@
+import { borderRadius } from '../styles/tokens';
+
+export interface MapAttributionGeometry {
+  /** The island's radius. The small print is a surface, so it takes a rung of the scale. */
+  radius: number;
+  /** The island's padding. */
+  paddingVertical: number;
+  /** The island's padding, sideways — wider, so short words are not pinched. */
+  paddingHorizontal: number;
+  /** Between the scale, the credit and the date. */
+  gap: number;
+  /** The scale bar's rule. */
+  rule: number;
+  /** The tick at each end of a bar, measured from the rule. */
+  tick: number;
+  /** Between the bar and its reading. */
+  scaleGap: number;
+  /** Between two stacked bars. */
+  scaleStack: number;
+}
+
+/**
+ * 6 and 10 of padding, and a radius of 8: the strip has to be the smallest
+ * thing on the map and still be a surface rather than a shadow of one.
+ *
+ * The tick is 5 either side of the rule — long enough that the bar's ENDS are
+ * what you read (a scale bar is a measurement between two marks, not a line),
+ * short enough that it does not become a bracket.
+ */
+export const MAP_ATTRIBUTION_GEOMETRY: MapAttributionGeometry = {
+  radius: borderRadius.sm,
+  paddingVertical: 6,
+  paddingHorizontal: 10,
+  gap: 8,
+  rule: 1,
+  tick: 5,
+  scaleGap: 6,
+  scaleStack: 3,
+};

package/src/map-attribution/index.ts

@@ -0,0 +1,12 @@
+export { MapAttribution } from './MapAttribution';
+export { MapScaleBar } from './MapScaleBar';
+export { MAP_ATTRIBUTION_GEOMETRY } from './constants';
+export type { MapAttributionGeometry } from './constants';
+export { describeScale, resolveMapAttributionPaint } from './shared';
+export type { MapAttributionPaint } from './shared';
+export type {
+  MapAttributionProps,
+  MapAttributionVariant,
+  MapScale,
+  MapScaleBarProps,
+} from './types';

package/src/map-attribution/shared.ts

@@ -0,0 +1,59 @@
+/**
+ * What the small print paints, and how it reads aloud. Pure, so a gate can walk
+ * every preset x mode without rendering.
+ */
+import {
+  hairlineOn,
+  resolveSurfaceLevel,
+  surfaceTextOn,
+  type SurfaceTextPaint,
+} from '../styles/surface-levels';
+import type { Theme } from '../theme/types';
+import type { MapScale } from './types';
+
+export interface MapAttributionPaint extends SurfaceTextPaint {
+  /** The island's own fill — what every rung here is measured against. */
+  surface: string;
+  /** The scale bar's rule and its end ticks. */
+  rule: string;
+  /** A separator between two readings. */
+  border: string;
+}
+
+/**
+ * Measured against the ISLAND's fill, not against the page and not against the
+ * map.
+ *
+ * The map is content Bloom does not own — it can be a night satellite tile, a
+ * white street map or a photograph — so no text rung can be floored against it.
+ * The island's rung 1 fill is a surface Bloom DOES own, which is the whole
+ * reason the small print sits on one: over a photo the credit stays legible
+ * because it is not on the photo.
+ *
+ * The rule takes the GRAPHICAL rung (3:1) rather than a text one: a scale bar
+ * is a line, and flooring it at text contrast would make the quietest thing on
+ * the map the loudest thing on the strip.
+ */
+export function resolveMapAttributionPaint(theme: Theme): MapAttributionPaint {
+  const level = resolveSurfaceLevel(theme, 1);
+  const text = surfaceTextOn(theme, level.background);
+  return {
+    surface: level.background,
+    rule: text.textGraphical,
+    border: hairlineOn(theme, level.background),
+    ...text,
+  };
+}
+
+/**
+ * "Scale, 500 m, 1000 ft".
+ *
+ * A bar and two ticks say nothing aloud, and the reading beside them is a
+ * number with no noun — "500 m" on its own is as likely to be a distance to
+ * somewhere as a scale. The word comes first so it is the first thing heard.
+ */
+export function describeScale(scales: readonly MapScale[], scaleLabel: string = 'Scale'): string {
+  const readings = scales.map((scale) => scale.label).filter(Boolean);
+  if (readings.length === 0) return scaleLabel;
+  return `${scaleLabel}, ${readings.join(', ')}`;
+}

package/src/map-attribution/types.ts

@@ -0,0 +1,79 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * One bar of the scale: how WIDE it is on screen, and what that width is worth.
+ *
+ * Both come from the app, because only the app knows its projection — the
+ * width in pixels for a round number of metres at this latitude and zoom, and
+ * the formatted words for that number. Bloom converts nothing and rounds
+ * nothing: a scale bar that guessed its own units would be a measuring
+ * instrument that measures the component rather than the map.
+ */
+export interface MapScale {
+  /** The bar's drawn length, in pixels. */
+  width: number;
+  /** What that length is worth, pre-formatted — "500 m", "1000 ft". */
+  label: string;
+  /** Stable key. Defaults to the index. */
+  id?: string;
+}
+
+/**
+ * `island` floats the small print over tiles Bloom does not own and gives it
+ * the one material priced for that. `inline` draws the words and nothing else,
+ * for a strip that is already inside a surface the app painted.
+ */
+export type MapAttributionVariant = 'island' | 'inline';
+
+export interface MapScaleBarProps {
+  /**
+   * One bar, or two — a metric bar and an imperial one, in that order. Two is
+   * the case this takes a list for: they are the same measurement in two
+   * vocabularies and must line up under each other rather than appear as two
+   * separate instruments.
+   */
+  scales: readonly MapScale[];
+  /** Default `island`. */
+  variant?: MapAttributionVariant;
+  /** The word before the readings in the announcement. Default `"Scale"`. */
+  scaleLabel?: string;
+  /** Defaults to `"Scale, 500 m, 1000 ft"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Parts get `<testID>-bar-<n>`, `<testID>-rule-<n>`. */
+  testID?: string;
+}
+
+export interface MapAttributionProps {
+  /**
+   * The credit the data's licence requires, as the licence words it. NOT
+   * optional and NOT defaulted: a component that invented a default credit
+   * would put a wrong attribution on a map, which is the one failure in this
+   * family that is a legal problem rather than a visual one.
+   */
+  credit: string;
+  /**
+   * Opens the provider's own attribution page. With it the credit becomes a
+   * link; without it, plain text.
+   */
+  onPressCredit?: () => void;
+  /** The link's announced name. Defaults to `credit`. */
+  creditLabel?: string;
+  /** The scale bar, drawn before the credit. Without it none is drawn. */
+  scales?: readonly MapScale[];
+  /** The word before the readings in the scale's announcement. Default `"Scale"`. */
+  scaleLabel?: string;
+  /**
+   * When the tiles were last refreshed, pre-formatted by the app — "Updated 12
+   * March", "Updated 3 days ago". Never computed here: this component does not
+   * read a clock.
+   */
+  updated?: string;
+  /** Default `island`. */
+  variant?: MapAttributionVariant;
+  /** Names the strip. Default `"Map data"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Parts get `<testID>-scale`, `-credit`, `-updated`. */
+  testID?: string;
+}

package/src/map-controls/MapCompass.tsx

@@ -0,0 +1,77 @@
+import React, { memo, useContext } from 'react';
+import { View } from 'react-native';
+
+import { ButtonGroupItem } from '../button-group';
+import { GlassIsland } from '../glass';
+import { RiCompass3Line } from '../icons/remix/RiCompass3Line';
+import type { BloomIconComponent } from '../icons/icon-component';
+import { MAP_CONTROL_BOX, MAP_CONTROLS_GEOMETRY } from './constants';
+import { MapHeadingContext } from './context';
+import type { MapCompassProps } from './types';
+
+/**
+ * The compass that floats over a map: a needle that keeps pointing at north
+ * while the map turns under it, and a press that puts the map back.
+ *
+ *   island   `GlassIsland` — one translucent capsule over content Bloom does
+ *            not own. It mounts the `ControlSurface` the item inside reads, so
+ *            the button paints flush with no `variant` written on it.
+ *   control  `ButtonGroupItem`, the island-aware control, at the 44 map rung.
+ *   needle   `RiCompass3Line` turned by MINUS the heading. The map rotates
+ *            clockwise by `heading`; the needle rotates back by the same amount
+ *            and so stays pointing north, which is the only thing a compass is
+ *            for.
+ *
+ * IT HIDES ITSELF AT NORTH by default. A compass on a map that is already
+ * pointing north is a control whose press changes nothing, and a reader has to
+ * press it to find that out.
+ */
+
+/**
+ * The needle, at module scope so its identity never changes — see
+ * `context.ts` for why the heading arrives through a context rather than
+ * through a component built per frame.
+ */
+const CompassNeedle: BloomIconComponent = ({ width, height, fill }) => {
+  const heading = useContext(MapHeadingContext);
+  return (
+    <View style={{ transform: [{ rotate: `${-heading}deg` }] }}>
+      <RiCompass3Line width={width} height={height} fill={fill} />
+    </View>
+  );
+};
+CompassNeedle.displayName = 'CompassNeedle';
+
+function MapCompassComponent({
+  heading,
+  onPress,
+  hideAtNorth = true,
+  disabled = false,
+  accessibilityLabel,
+  style,
+  testID,
+}: MapCompassProps) {
+  const pointsNorth = Math.abs(((heading % 360) + 360) % 360) <= MAP_CONTROLS_GEOMETRY.northTolerance;
+  if (hideAtNorth && pointsNorth) return null;
+
+  const name = accessibilityLabel ?? `Facing ${Math.round(heading)} degrees. Reset to north`;
+
+  return (
+    <MapHeadingContext.Provider value={heading}>
+      <GlassIsland style={style} testID={testID}>
+        <ButtonGroupItem
+          iconOnly
+          leadingIcon={CompassNeedle}
+          accessibilityLabel={name}
+          onPress={onPress}
+          disabled={disabled}
+          style={MAP_CONTROL_BOX}
+          testID={testID ? `${testID}-button` : undefined}
+        />
+      </GlassIsland>
+    </MapHeadingContext.Provider>
+  );
+}
+
+export const MapCompass = memo(MapCompassComponent);
+MapCompass.displayName = 'MapCompass';