@jobber/components-native 0.103.1 → 0.104.1

package/dist/types/src/primitives/HelperText/HelperText.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+export interface HelperTextProps {
+    /**
+     * The helper message.
+     */
+    readonly message: string;
+    /**
+     * `neutral` renders subdued supporting text. `critical` renders an `alert`
+     * icon followed by error-coloured supporting text.
+     *
+     * @default "neutral"
+     */
+    readonly status?: "neutral" | "critical";
+}
+export declare function HelperText({ message, status }: HelperTextProps): React.JSX.Element;

package/dist/types/src/primitives/HelperText/HelperText.style.d.ts

@@ -0,0 +1,16 @@
+export declare const useStyles: () => {
+    row: {
+        flexDirection: "row";
+        alignItems: "flex-start";
+    };
+    rowNeutral: {
+        gap: number;
+    };
+    rowCritical: {
+        gap: number;
+    };
+    iconContainer: {
+        height: number;
+        justifyContent: "center";
+    };
+};

package/dist/types/src/primitives/HelperText/HelperText.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/primitives/HelperText/index.d.ts

@@ -0,0 +1,2 @@
+export { HelperText } from "./HelperText";
+export type { HelperTextProps } from "./HelperText";

package/dist/types/src/primitives/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * This file exports styled components-native primitives.
  */
-export {};
+export * from "./HelperText";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/components-native",
-  "version": "0.103.1",
+  "version": "0.104.1",
   "license": "MIT",
   "description": "React Native implementation of Atlantis",
   "repository": {
@@ -72,7 +72,7 @@
     "@babel/runtime": "^7.29.2",
     "@gorhom/bottom-sheet": "^5.2.8",
     "@jobber/design": "0.101.1",
-    "@jobber/hooks": "2.20.1",
+    "@jobber/hooks": "2.21.0",
     "@react-native-community/datetimepicker": "^8.4.5",
     "@react-native/babel-preset": "^0.82.1",
     "@storybook/addon-a11y": "10.3.5",
@@ -122,5 +122,5 @@
     "react-native-screens": ">=4.18.0",
     "react-native-svg": ">=12.0.0"
   },
-  "gitHead": "87938ccef4ab0c51ab356fd1b19c9a20ca1a73ab"
+  "gitHead": "60b75a0d6a64b67dcb6607c474ed7aa469474f98"
 }

package/src/primitives/HelperText/HelperText.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { HelperText } from "./HelperText";
+import { HelperTextCriticalExample, HelperTextNeutralExample } from "./docs";
+
+const meta = {
+  title: "Components/Primitives/HelperText",
+  component: HelperText,
+  parameters: {
+    viewport: { defaultViewport: "mobile1" },
+  },
+  argTypes: {
+    status: {
+      control: "select",
+      options: ["neutral", "critical"],
+    },
+    message: { control: "text" },
+  },
+} satisfies Meta<typeof HelperText>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Neutral: Story = {
+  render: HelperTextNeutralExample,
+  args: {
+    message:
+      "This is some helper text to aid users. It should be short and to the point.",
+  },
+};
+
+export const Critical: Story = {
+  render: HelperTextCriticalExample,
+  args: {
+    message:
+      "This is some helper text to aid users. It should be short and to the point.",
+  },
+};

package/src/primitives/HelperText/HelperText.style.ts

@@ -0,0 +1,21 @@
+import { tokens as staticTokens } from "../../utils/design";
+import { buildThemedStyles } from "../../AtlantisThemeContext";
+
+const tightLineHeight = staticTokens["typography--lineHeight-tight"];
+
+export const useStyles = buildThemedStyles(tokens => ({
+  row: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+  },
+  rowNeutral: {
+    gap: 0,
+  },
+  rowCritical: {
+    gap: tokens["space-smaller"],
+  },
+  iconContainer: {
+    height: tightLineHeight,
+    justifyContent: "center",
+  },
+}));

package/src/primitives/HelperText/HelperText.test.tsx

@@ -0,0 +1,80 @@
+import React from "react";
+import { render } from "@testing-library/react-native";
+import { AccessibilityInfo } from "react-native";
+import { HelperText } from ".";
+import { Icon } from "../../Icon";
+
+describe("HelperText", () => {
+  describe("neutral status (default)", () => {
+    it("renders the message as subdued supporting text without an alert icon or role", () => {
+      const { getByText, queryByRole } = render(
+        <HelperText message="Pick a status" />,
+      );
+
+      expect(getByText("Pick a status")).toBeDefined();
+      expect(queryByRole("alert")).toBeNull();
+    });
+
+    it("renders identically when status is explicitly neutral", () => {
+      const { getByText, queryByRole } = render(
+        <HelperText status="neutral" message="Pick a status" />,
+      );
+
+      expect(getByText("Pick a status")).toBeDefined();
+      expect(queryByRole("alert")).toBeNull();
+    });
+  });
+
+  describe("critical status", () => {
+    it("renders the alert icon, error text, alert role, and assertive live region", () => {
+      const { getByText, getByRole, UNSAFE_getByType } = render(
+        <HelperText
+          status="critical"
+          message="Pick a status before continuing"
+        />,
+      );
+
+      expect(getByText("Pick a status before continuing")).toBeDefined();
+
+      const alertWrapper = getByRole("alert");
+      expect(alertWrapper.props.accessibilityLiveRegion).toBe("assertive");
+
+      // Confirms the alert icon is present alongside the message.
+      const icon = UNSAFE_getByType(Icon);
+      expect(icon.props.name).toBe("alert");
+      expect(icon.props.size).toBe("small");
+      expect(icon.props.color).toBe("critical");
+    });
+  });
+
+  describe("leaf invariants", () => {
+    it("does not fire imperative accessibility announcements", () => {
+      jest.spyOn(AccessibilityInfo, "announceForAccessibility");
+
+      render(<HelperText status="neutral" message="Neutral" />);
+      render(<HelperText status="critical" message="Critical" />);
+
+      expect(AccessibilityInfo.announceForAccessibility).not.toHaveBeenCalled();
+
+      jest.mocked(AccessibilityInfo.announceForAccessibility).mockRestore();
+    });
+
+    it("renders successfully outside of any Atlantis context", () => {
+      // Renders bare (no providers) and asserts no warning or throw.
+      const warn = jest.spyOn(console, "warn").mockImplementation(() => {
+        // swallow warnings; we'll inspect the spy below
+      });
+      const error = jest.spyOn(console, "error").mockImplementation(() => {
+        // swallow errors; we'll inspect the spy below
+      });
+
+      expect(() => render(<HelperText message="Bare render" />)).not.toThrow();
+
+      expect(warn).not.toHaveBeenCalled();
+      expect(error).not.toHaveBeenCalled();
+
+      warn.mockRestore();
+      error.mockRestore();
+    });
+  });
+});

package/src/primitives/HelperText/HelperText.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { View } from "react-native";
+import { useStyles } from "./HelperText.style";
+import { Text } from "../../Text";
+import { Icon } from "../../Icon";
+
+export interface HelperTextProps {
+  /**
+   * The helper message.
+   */
+  readonly message: string;
+
+  /**
+   * `neutral` renders subdued supporting text. `critical` renders an `alert`
+   * icon followed by error-coloured supporting text.
+   *
+   * @default "neutral"
+   */
+  readonly status?: "neutral" | "critical";
+}
+
+export function HelperText({ message, status = "neutral" }: HelperTextProps) {
+  const styles = useStyles();
+  const isCritical = status === "critical";
+
+  return (
+    <View
+      style={[styles.row, isCritical ? styles.rowCritical : styles.rowNeutral]}
+      accessible={isCritical || undefined}
+      accessibilityRole={isCritical ? "alert" : undefined}
+      accessibilityLiveRegion={isCritical ? "assertive" : undefined}
+    >
+      {isCritical && (
+        <View style={styles.iconContainer}>
+          <Icon name="alert" size="small" color="critical" />
+        </View>
+      )}
+      <Text level="textSupporting" variation={isCritical ? "error" : "subdued"}>
+        {message}
+      </Text>
+    </View>
+  );
+}

package/src/primitives/HelperText/docs/HelperTextCriticalExample.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { HelperText } from "../HelperText";
+import type { HelperTextProps } from "../HelperText";
+
+export function HelperTextCriticalExample({
+  message = "This is some helper text to aid users. It should be short and to the point.",
+}: Partial<HelperTextProps>) {
+  return <HelperText status="critical" message={message} />;
+}

package/src/primitives/HelperText/docs/HelperTextNeutralExample.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { HelperText } from "../HelperText";
+import type { HelperTextProps } from "../HelperText";
+
+export function HelperTextNeutralExample({
+  message = "This is some helper text to aid users. It should be short and to the point.",
+}: Partial<HelperTextProps>) {
+  return <HelperText status="neutral" message={message} />;
+}

package/src/primitives/HelperText/docs/index.ts

@@ -0,0 +1,2 @@
+export { HelperTextNeutralExample } from "./HelperTextNeutralExample";
+export { HelperTextCriticalExample } from "./HelperTextCriticalExample";

package/src/primitives/HelperText/index.ts

@@ -0,0 +1,2 @@
+export { HelperText } from "./HelperText";
+export type { HelperTextProps } from "./HelperText";

package/src/primitives/index.ts

@@ -1,4 +1,4 @@
 /**
  * This file exports styled components-native primitives.
  */
-export {};
+export * from "./HelperText";