@jobber/components-native 0.109.1 → 0.110.0

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/index.ts

@@ -37,6 +37,7 @@ export * from "./InputSearch";
 export * from "./InputText";
 export * from "./InputTime";
 export * from "./ProgressBar";
+export * from "./ProgressIndicator";
 export * from "./Select";
 export * from "./StatusLabel";
 export * from "./Switch";

package/src/utils/meta/meta.json

@@ -59,6 +59,7 @@
     "InputTime",
     "Option",
     "ProgressBar",
+    "ProgressIndicator",
     "Select",
     "Select.Content",
     "Select.Group",