@jobber/components-native 0.109.1 → 0.111.0

package/src/ProgressIndicator/ProgressIndicator.test.tsx

@@ -0,0 +1,214 @@
+import React from "react";
+import { render, screen } from "@testing-library/react-native";
+import { ProgressIndicator } from ".";
+
+describe("ProgressIndicator", () => {
+  describe("public API", () => {
+    it("renders with role='progressbar'", () => {
+      render(<ProgressIndicator value={50} />);
+
+      expect(screen.getByRole("progressbar")).toBeTruthy();
+    });
+
+    it("sets accessibilityValue now/min/max", () => {
+      render(<ProgressIndicator value={50} />);
+
+      expect(screen.getByRole("progressbar").props.accessibilityValue).toEqual(
+        expect.objectContaining({ now: 50, min: 0, max: 100 }),
+      );
+    });
+
+    it("uses max in accessibilityValue when provided", () => {
+      render(<ProgressIndicator value={3} max={4} />);
+
+      expect(screen.getByRole("progressbar").props.accessibilityValue).toEqual(
+        expect.objectContaining({ now: 3, max: 4 }),
+      );
+    });
+
+    it("renders a continuous fill by default", () => {
+      render(<ProgressIndicator value={50} />);
+
+      expect(screen.getByTestId("progressindicator-fill")).toBeTruthy();
+      expect(screen.queryByTestId("progressindicator-step-filled")).toBeNull();
+    });
+
+    it("applies style to the root", () => {
+      render(<ProgressIndicator value={50} style={{ margin: 8 }} />);
+
+      expect(screen.getByRole("progressbar").props.style).toEqual(
+        expect.arrayContaining([expect.objectContaining({ margin: 8 })]),
+      );
+    });
+
+    it("rounds the continuous track so both ends are pill-shaped", () => {
+      render(<ProgressIndicator value={50} size="base" />);
+
+      // base height is 16px, so the track radius is 8. Without this the
+      // unfilled (right) end of the track renders with square corners.
+      expect(screen.getByRole("progressbar").props.style).toEqual(
+        expect.arrayContaining([expect.objectContaining({ borderRadius: 8 })]),
+      );
+    });
+
+    it("does not round the stepped root (segments carry their own radius)", () => {
+      render(<ProgressIndicator value={2} max={5} variation="stepped" />);
+
+      const rootStyles = screen
+        .getByRole("progressbar")
+        .props.style.filter(Boolean);
+      expect(rootStyles).not.toContainEqual(
+        expect.objectContaining({ borderRadius: expect.anything() }),
+      );
+    });
+  });
+
+  describe("accessibility label", () => {
+    it("defaults to '{value}%' when max is omitted", () => {
+      render(<ProgressIndicator value={42} />);
+
+      expect(screen.getByLabelText("42%")).toBeTruthy();
+    });
+
+    it("defaults to '{value}%' when max === 100", () => {
+      render(<ProgressIndicator value={42} max={100} />);
+
+      expect(screen.getByLabelText("42%")).toBeTruthy();
+    });
+
+    it("defaults to '{value} / {max}' when max !== 100", () => {
+      render(<ProgressIndicator value={3} max={4} />);
+
+      expect(screen.getByLabelText("3 / 4")).toBeTruthy();
+    });
+
+    it("defaults to the pending template when pendingValue > 0", () => {
+      render(<ProgressIndicator value={2} pendingValue={3} max={10} />);
+
+      expect(screen.getByLabelText("2 of 10, 3 pending")).toBeTruthy();
+    });
+
+    it("uses a consumer-supplied accessibilityLabel when provided", () => {
+      render(
+        <ProgressIndicator value={50} accessibilityLabel="Uploading file" />,
+      );
+
+      expect(screen.getByLabelText("Uploading file")).toBeTruthy();
+    });
+  });
+
+  /**
+   * Native screen readers (VoiceOver / TalkBack) announce a progressbar from
+   * its `accessibilityRole` plus the resolved `accessibilityValue.text` /
+   * `accessibilityLabel`. These assertions lock that announced payload
+   * deterministically — the automatable proxy for the on-device smoke, which
+   * cannot capture live screen-reader speech in CI.
+   */
+  describe("screen reader announcement contract", () => {
+    it.each([
+      ["percent (max omitted)", { value: 50 }, "50%"],
+      ["ratio (max !== 100)", { value: 3, max: 4 }, "3 / 4"],
+      ["pending", { value: 2, pendingValue: 3, max: 10 }, "2 of 10, 3 pending"],
+      [
+        "custom label",
+        { value: 50, accessibilityLabel: "Uploading file" },
+        "Uploading file",
+      ],
+    ])(
+      "announces %s as a progressbar with the derived text",
+      (_n, props, text) => {
+        render(<ProgressIndicator {...props} />);
+
+        const root = screen.getByRole("progressbar");
+        expect(root.props.accessibilityRole).toBe("progressbar");
+        expect(root.props.accessibilityLabel).toBe(text);
+        expect(root.props.accessibilityValue).toEqual(
+          expect.objectContaining({ text }),
+        );
+      },
+    );
+
+    it("carries the numeric value/min/max alongside the announced text", () => {
+      render(<ProgressIndicator value={3} max={4} />);
+
+      expect(screen.getByRole("progressbar").props.accessibilityValue).toEqual({
+        min: 0,
+        max: 4,
+        now: 3,
+        text: "3 / 4",
+      });
+    });
+  });
+
+  describe("sizes", () => {
+    it.each([
+      ["smaller", 4],
+      ["small", 8],
+      ["base", 16],
+    ] as const)("applies %s height (%dpx) to the root", (size, height) => {
+      render(<ProgressIndicator value={50} size={size} />);
+
+      expect(screen.getByRole("progressbar").props.style).toEqual(
+        expect.arrayContaining([expect.objectContaining({ height })]),
+      );
+    });
+  });
+
+  describe("pending overlay (continuous)", () => {
+    it("renders a pending band when pendingValue > 0", () => {
+      render(<ProgressIndicator value={2} pendingValue={3} max={10} />);
+
+      expect(screen.getByTestId("progressindicator-pending")).toBeTruthy();
+    });
+
+    it("renders no pending band when pendingValue is 0", () => {
+      render(<ProgressIndicator value={4} max={10} />);
+
+      expect(screen.queryByTestId("progressindicator-pending")).toBeNull();
+    });
+  });
+
+  describe("stepped variation", () => {
+    it("renders max segments with the first value filled", () => {
+      render(<ProgressIndicator value={2} max={5} variation="stepped" />);
+
+      expect(
+        screen.getAllByTestId("progressindicator-step-filled"),
+      ).toHaveLength(2);
+      expect(
+        screen.getAllByTestId("progressindicator-step-empty"),
+      ).toHaveLength(3);
+    });
+
+    it("classifies filled, pending, and empty segments", () => {
+      render(
+        <ProgressIndicator
+          value={3}
+          pendingValue={2}
+          max={6}
+          variation="stepped"
+        />,
+      );
+
+      expect(
+        screen.getAllByTestId("progressindicator-step-filled"),
+      ).toHaveLength(3);
+      expect(
+        screen.getAllByTestId("progressindicator-step-pending"),
+      ).toHaveLength(2);
+      expect(
+        screen.getAllByTestId("progressindicator-step-empty"),
+      ).toHaveLength(1);
+    });
+
+    it("keeps a single progressbar on the root and none on segments", () => {
+      render(<ProgressIndicator value={2} max={5} variation="stepped" />);
+
+      expect(screen.getAllByRole("progressbar")).toHaveLength(1);
+      screen.getAllByTestId(/progressindicator-step-/).forEach(segment => {
+        expect(segment.props.accessibilityRole).toBeUndefined();
+        expect(segment.props.accessibilityValue).toBeUndefined();
+      });
+    });
+  });
+});

package/src/ProgressIndicator/ProgressIndicator.tsx

@@ -0,0 +1,198 @@
+import React, { useEffect } from "react";
+import { View } from "react-native";
+import Animated, {
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from "react-native-reanimated";
+import type { ProgressIndicatorProps } from "./types";
+import { useStyles } from "./ProgressIndicator.style";
+import { sizeHeights, sizeStyles } from "./ProgressIndicator.size.style";
+import { useAtlantisI18n } from "../hooks/useAtlantisI18n";
+import { tokens } from "../utils/design";
+
+type RendererProps = Required<
+  Pick<ProgressIndicatorProps, "value" | "max" | "pendingValue" | "size">
+>;
+
+export function ProgressIndicator({
+  value,
+  max = 100,
+  pendingValue = 0,
+  variation = "continuous",
+  size = "base",
+  accessibilityLabel,
+  style,
+}: ProgressIndicatorProps) {
+  const styles = useStyles();
+  const { t } = useAtlantisI18n();
+
+  const label = accessibilityLabel ?? getA11yLabel();
+  const radius = sizeHeights[size] / 2;
+
+  return (
+    <View
+      accessible
+      accessibilityRole="progressbar"
+      accessibilityLabel={label}
+      accessibilityValue={{ min: 0, max, now: value, text: label }}
+      style={[
+        variation === "stepped" ? styles.stepped : styles.continuous,
+        sizeStyles[size],
+        // Round the continuous track so its trailing (unfilled) end is pill-
+        // shaped like the leading end; `overflow: "hidden"` clips the fill to
+        // match. The stepped variation rounds its individual segments instead.
+        variation === "continuous" && { borderRadius: radius },
+        style,
+      ]}
+    >
+      {variation === "stepped" ? (
+        <ProgressIndicatorStepped
+          value={value}
+          max={max}
+          pendingValue={pendingValue}
+          size={size}
+        />
+      ) : (
+        <ProgressIndicatorContinuous
+          value={value}
+          max={max}
+          pendingValue={pendingValue}
+          size={size}
+        />
+      )}
+    </View>
+  );
+
+  function getA11yLabel(): string {
+    if (pendingValue > 0) {
+      return t("ProgressIndicator.ariaLabelPending", {
+        value: String(value),
+        max: String(max),
+        pendingValue: String(pendingValue),
+      });
+    }
+
+    if (max === 100) {
+      return t("ProgressIndicator.ariaLabelPercent", { value: String(value) });
+    }
+
+    return t("ProgressIndicator.ariaLabelRatio", {
+      value: String(value),
+      max: String(max),
+    });
+  }
+}
+
+/**
+ * Clamp a raw progress amount to a percentage of `max` in the range 0..100.
+ */
+function toPercent(amount: number, max: number): number {
+  if (max <= 0) return 0;
+
+  return Math.min(100, Math.max(0, (amount / max) * 100));
+}
+
+/**
+ * File-private renderer for `variation="continuous"`. Renders the fill and,
+ * when `pendingValue > 0`, a pending band. The outer `ProgressIndicator` shell
+ * owns the accessibility contract; this renderer emits presentational children
+ * only.
+ */
+function ProgressIndicatorContinuous({
+  value,
+  max,
+  pendingValue,
+  size,
+}: RendererProps) {
+  const styles = useStyles();
+  const radius = sizeHeights[size] / 2;
+
+  const fillPercent = toPercent(value, max);
+  const pendingPercent = toPercent(value + pendingValue, max);
+
+  // The width transition is intentionally preserved regardless of the user's
+  // reduce-motion preference: the slide between progress values conveys
+  // functional progress and is exempt under WCAG 2.3.3 ("Animation from
+  // Interactions"). See design.md.
+  const fill = useSharedValue(fillPercent);
+  const pending = useSharedValue(pendingPercent);
+
+  useEffect(() => {
+    fill.value = withTiming(fillPercent, {
+      duration: tokens["timing-base"],
+      easing: Easing.out(Easing.ease),
+    });
+  }, [fillPercent]);
+
+  useEffect(() => {
+    pending.value = withTiming(pendingPercent, {
+      duration: tokens["timing-base"],
+      easing: Easing.out(Easing.ease),
+    });
+  }, [pendingPercent]);
+
+  const fillStyle = useAnimatedStyle(() => ({ width: `${fill.value}%` }));
+  const pendingStyle = useAnimatedStyle(() => ({ width: `${pending.value}%` }));
+
+  return (
+    <>
+      {pendingValue > 0 && (
+        <Animated.View
+          testID="progressindicator-pending"
+          style={[styles.pending, { borderRadius: radius }, pendingStyle]}
+        />
+      )}
+      <Animated.View
+        testID="progressindicator-fill"
+        style={[styles.fill, { borderRadius: radius }, fillStyle]}
+      />
+    </>
+  );
+}
+
+/**
+ * File-private renderer for `variation="stepped"`. Renders `max` presentational
+ * segments, each classified filled / pending / empty. No accessibility props on
+ * the segments — the outer shell announces once.
+ */
+function ProgressIndicatorStepped({
+  value,
+  max,
+  pendingValue,
+  size,
+}: RendererProps) {
+  const styles = useStyles();
+  const radius = sizeHeights[size] / 2;
+  const segmentCount = Math.max(0, Math.floor(max));
+
+  return (
+    <>
+      {Array.from({ length: segmentCount }).map((_, index) => {
+        const step = index + 1;
+        const isFilled = step <= value;
+        const isPending = !isFilled && step <= value + pendingValue;
+
+        return (
+          <View
+            key={step}
+            testID={
+              isFilled
+                ? "progressindicator-step-filled"
+                : isPending
+                ? "progressindicator-step-pending"
+                : "progressindicator-step-empty"
+            }
+            style={[
+              styles.segment,
+              { borderRadius: radius },
+              isFilled && styles.segmentFilled,
+              isPending && styles.segmentPending,
+            ]}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/ProgressIndicator/docs/ProgressIndicatorBasic.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { ProgressIndicator } from "@jobber/components-native";
+import type { ProgressIndicatorProps } from "@jobber/components-native";
+
+type ProgressIndicatorStoryArgs = Partial<
+  Pick<
+    ProgressIndicatorProps,
+    "value" | "max" | "pendingValue" | "variation" | "size"
+  >
+>;
+
+export function ProgressIndicatorBasic(props: ProgressIndicatorStoryArgs) {
+  return (
+    <ProgressIndicator
+      value={props.value ?? 75}
+      max={props.max}
+      pendingValue={props.pendingValue}
+      size={props.size}
+      variation={props.variation}
+    />
+  );
+}

package/src/ProgressIndicator/docs/ProgressIndicatorPending.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { ProgressIndicator } from "@jobber/components-native";
+import type { ProgressIndicatorProps } from "@jobber/components-native";
+
+type ProgressIndicatorStoryArgs = Partial<
+  Pick<
+    ProgressIndicatorProps,
+    "value" | "max" | "pendingValue" | "variation" | "size"
+  >
+>;
+
+export function ProgressIndicatorPending(props: ProgressIndicatorStoryArgs) {
+  return (
+    <ProgressIndicator
+      value={props.value ?? 2}
+      max={props.max ?? 10}
+      pendingValue={props.pendingValue ?? 3}
+      size={props.size}
+      variation={props.variation}
+    />
+  );
+}

package/src/ProgressIndicator/docs/index.ts

@@ -0,0 +1,2 @@
+export { ProgressIndicatorBasic } from "./ProgressIndicatorBasic";
+export { ProgressIndicatorPending } from "./ProgressIndicatorPending";

package/src/ProgressIndicator/guide.md

@@ -0,0 +1,104 @@
+# ProgressIndicator (mobile)
+
+## Purpose
+
+`ProgressIndicator` communicates **determinate** progress the user is advancing
+through — multi-step flows, uploads with a known size, and similar. It is the
+React Native counterpart to the web `@jobber/components` `ProgressIndicator` and
+the replacement for the mobile `ProgressBar`.
+
+For **indeterminate** activity the user cannot control (loading, fetching), use
+an activity indicator instead — not `ProgressIndicator`.
+
+## API
+
+| Prop                 | Type                             | Default        | Description                                                 |
+| -------------------- | -------------------------------- | -------------- | ----------------------------------------------------------- |
+| `value`              | `number` (required)              | —              | Current progress, in the range `0..max`.                    |
+| `max`                | `number`                         | `100`          | Maximum value.                                              |
+| `pendingValue`       | `number`                         | `0`            | Additive in-flight progress beyond `value` (mobile-only).   |
+| `variation`          | `"continuous" \| "stepped"`      | `"continuous"` | Single fill vs. one segment per integer step from `1..max`. |
+| `size`               | `"smaller" \| "small" \| "base"` | `"base"`       | Bar height: 4 / 8 / 16px.                                   |
+| `accessibilityLabel` | `string`                         | derived        | Accessible label override (see Accessibility).              |
+| `style`              | `StyleProp<ViewStyle>`           | —              | Applied to the root element.                                |
+
+## Accessibility
+
+The root renders `<View accessibilityRole="progressbar">` with
+`accessibilityValue={{ now: value, min: 0, max }}` and the resolved
+`accessibilityLabel`. The component is not focusable.
+
+When `accessibilityLabel` is omitted, it is derived via `useAtlantisI18n`:
+
+- `"{value}%"` when `max === 100` (or omitted) and `pendingValue` is `0`;
+- `"{value} / {max}"` when `max !== 100` and `pendingValue` is `0`;
+- `"{value} of {max}, {pendingValue} pending"` when `pendingValue > 0`.
+
+In the stepped variation the segments are presentational only — they carry no
+role or accessibility value. The whole indicator announces once as a single
+progressbar.
+
+## Animation Model
+
+The continuous fill (and the pending band, when present) animate their width
+with `react-native-reanimated` `withTiming` over the `timing-base` token. The
+stepped variation is not animated.
+
+The width transition is **preserved** under a reduce-motion preference. The
+slide between progress values conveys functional progress and is exempt under
+WCAG 2.3.3 ("Animation from Interactions"); removing it would make progress
+harder to perceive, not easier. This is the opposite of an indeterminate
+activity indicator, whose motion IS suppressed under reduced motion.
+
+### Pending overlay
+
+`pendingValue` is **additive**: with `value={2}`, `pendingValue={3}`,
+`max={10}`, the bar shows 2/10 completed and an additional 3/10 in flight, for
+5/10 visually filled. In the continuous variation the pending band spans
+`value .. value + pendingValue`; in the stepped variation the segments at
+`value < pos <= value + pendingValue` are the pending state.
+
+## Tokens
+
+- Fill / filled segments: `color-interactive--subtle`.
+- Track / empty segments: `color-surface--active`.
+- Pending band / pending segments: `color-informative`.
+
+The fill and track tokens mirror the web `ProgressIndicator`. The pending color
+is carried forward from today's `ProgressBar` `inProgress` overlay so the
+pending state keeps its established meaning; a dedicated pending tone is an open
+question for design. No hardcoded colors and no drop shadow are used; all colors
+resolve through `AtlantisThemeContext` and adapt across light and dark themes.
+
+## Relationship to `ProgressBar`
+
+`ProgressBar` is deprecated in favor of `ProgressIndicator` but continues to
+work unchanged. Migration mapping:
+
+| `ProgressBar`            | `ProgressIndicator`                                         |
+| ------------------------ | ----------------------------------------------------------- |
+| `current`                | `value`                                                     |
+| `total`                  | `max`                                                       |
+| `inProgress`             | `pendingValue` (same additive meaning)                      |
+| `variation="progress"`   | `variation="continuous"`                                    |
+| `loading`                | render `value={0}` or conditionally mount the component     |
+| `header`                 | wrap the indicator in your own `View` / `Content` / `Stack` |
+| `reverseTheme`           | wrap in `ThemeContextOverride` for the dark surface         |
+| `UNSAFE_style.container` | `style`                                                     |
+| other `UNSAFE_style.*`   | no direct replacement — compose around the component        |
+
+## Cross-Platform Note
+
+The `value` / `max` prop surface is aligned with the web `ProgressIndicator`.
+`pendingValue` is mobile-only — web deferred it to this component.
+
+## Ownership
+
+Owned by the Atlantis / UX Foundations team. Ticket: JOB-167172.
+
+## Out of Scope
+
+- A `variant="ring"` shape (deferred to v2, pending design).
+- Shimming `ProgressBar` onto `ProgressIndicator` (or removing it).
+- A mobile `ActivityIndicator` Atlantis wrapper.
+- Migrating jobber-mobile consumers off `ProgressBar`.

package/src/ProgressIndicator/index.ts

@@ -0,0 +1,2 @@
+export { ProgressIndicator } from "./ProgressIndicator";
+export type { ProgressIndicatorProps } from "./types";

package/src/ProgressIndicator/types.ts

@@ -0,0 +1,51 @@
+import type { StyleProp, ViewStyle } from "react-native";
+
+export interface ProgressIndicatorProps {
+  /**
+   * Current progress. Expected to be in the range `0..max` inclusive.
+   */
+  readonly value: number;
+
+  /**
+   * Maximum value.
+   * @default 100
+   */
+  readonly max?: number;
+
+  /**
+   * Additional in-flight progress beyond `value`, measured on the same scale as
+   * `value` and `max`. The bar visually fills `value + pendingValue` of `max`,
+   * with the `value` portion shown as completed and the `pendingValue` portion
+   * shown as pending. Mobile-only; there is no web counterpart.
+   * @default 0
+   */
+  readonly pendingValue?: number;
+
+  /**
+   * Set the variation of the progress indicator. `continuous` renders a single
+   * fill; `stepped` renders one segment per integer step from `1..max`.
+   * @default continuous
+   */
+  readonly variation?: "continuous" | "stepped";
+
+  /**
+   * Set the size of the progress indicator. Corresponds to bar heights of
+   * 4px / 8px / 16px.
+   * @default base
+   */
+  readonly size?: "smaller" | "small" | "base";
+
+  /**
+   * Accessible label override. When omitted, the label is derived via
+   * `useAtlantisI18n`: `"{value}%"` when `max` is `100` (or omitted) and
+   * `pendingValue` is `0`; `"{value} / {max}"` when `max` is not `100` and
+   * `pendingValue` is `0`; `"{value} of {max}, {pendingValue} pending"` when
+   * `pendingValue` is greater than `0`.
+   */
+  readonly accessibilityLabel?: string;
+
+  /**
+   * Custom style applied to the root element.
+   */
+  readonly style?: StyleProp<ViewStyle>;
+}

package/src/hooks/useAtlantisI18n/locales/en.json

@@ -26,6 +26,9 @@
   "networkUnavailableDescription": "Check your internet connection and try again later.",
   "ProgressBar.complete": "{current} of {total} complete",
   "ProgressBar.inProgress": "{current} of {total} complete, {inProgress} in progress",
+  "ProgressIndicator.ariaLabelPercent": "{value}%",
+  "ProgressIndicator.ariaLabelRatio": "{value} / {max}",
+  "ProgressIndicator.ariaLabelPending": "{value} of {max}, {pendingValue} pending",
   "save": "Save",
   "Select.a11yHint": "Select to open the picker",
   "Select.emptyValue": "Select an option",

package/src/hooks/useAtlantisI18n/locales/es.json

@@ -26,6 +26,9 @@
   "networkUnavailableDescription": "Compruebe su conexión a Internet e inténtelo de nuevo más adelante.",
   "ProgressBar.complete": "{current} de {total} completo",
   "ProgressBar.inProgress": "{current} de {total} completo, {inProgress} en progreso",
+  "ProgressIndicator.ariaLabelPercent": "{value}%",
+  "ProgressIndicator.ariaLabelRatio": "{value} / {max}",
+  "ProgressIndicator.ariaLabelPending": "{value} de {max}, {pendingValue} pendiente",
   "save": "Guardar",
   "Select.a11yHint": "Seleccionar para abrir el selector",
   "Select.emptyValue": "Seleccione una opción",

package/src/hooks/useAtlantisI18n/releasedLanguages.ts

@@ -0,0 +1,23 @@
+/**
+ * Languages that have been fully released and are safe to surface to users.
+ * Any locale not present in this list will fall back to "en".
+ *
+ * To release a new language, add its BCP 47 language tag here (e.g. "es").
+ */
+export const RELEASED_LANGUAGES: readonly string[] = ["en"];
+
+/**
+ * Returns the locale to use based on what has been released. Matches on the
+ * language part of the locale (before the "-") so that regional variants like
+ * "en-CA" or "es-US" resolve correctly:
+ *
+ * - "en-CA" → "en-CA"  (language "en" is released; full locale preserved for
+ *                        date/time formatting)
+ * - "es-US" → "en"     (language "es" not yet released; falls back to "en")
+ * - "fr"    → "en"     (language "fr" not released; falls back to "en")
+ */
+export function getReleasedLocale(locale: string): string {
+  const language = locale.split("-")[0];
+
+  return RELEASED_LANGUAGES.includes(language) ? locale : "en";
+}