@jobber/components-native 0.108.2 → 0.109.0

package/src/Select/components/SelectContent.test.tsx

@@ -0,0 +1,67 @@
+import React from "react";
+import { render, screen, userEvent } from "@testing-library/react-native";
+import { SelectContent } from "./SelectContent";
+import { SelectItem } from "./SelectItem";
+import { SelectTrigger } from "./SelectTrigger";
+import { SelectRoot } from "../SelectRoot";
+import { SelectPrimitive } from "../../primitives/Select";
+import { PortalHostWrapper } from "../../utils/test";
+
+const user = userEvent.setup();
+
+beforeAll(() => {
+  const MockNativeMethods = require("react-native/jest/MockNativeMethods");
+  const mockedMethods = MockNativeMethods.default ?? MockNativeMethods;
+  mockedMethods.measure.mockImplementation(
+    (
+      callback: (
+        x: number,
+        y: number,
+        width: number,
+        height: number,
+        pageX: number,
+        pageY: number,
+      ) => void,
+    ) => {
+      callback(0, 0, 320, 48, 20, 100);
+    },
+  );
+});
+
+function renderContent() {
+  return render(
+    <SelectRoot>
+      <SelectTrigger>
+        <SelectPrimitive.Value placeholder="Select an option" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="tor" label="Toronto" />
+        <SelectItem value="van" label="Vancouver" />
+      </SelectContent>
+    </SelectRoot>,
+    { wrapper: PortalHostWrapper },
+  );
+}
+
+describe("Select.Content", () => {
+  it("renders nothing until the trigger opens it", async () => {
+    renderContent();
+
+    expect(screen.queryByText("Toronto")).toBeNull();
+
+    await user.press(screen.getByTestId("ATL-Select-Trigger"));
+
+    expect(screen.getByText("Toronto")).toBeDefined();
+  });
+
+  it("folds the portal, overlay, and viewport into one part", async () => {
+    renderContent();
+    await user.press(screen.getByTestId("ATL-Select-Trigger"));
+
+    // The single Select.Content renders the tap-outside overlay plus the items
+    // (portaled + scrolled via the folded Viewport).
+    expect(screen.getByTestId("ATL-Select-Overlay")).toBeDefined();
+    expect(screen.getByText("Toronto")).toBeDefined();
+    expect(screen.getByText("Vancouver")).toBeDefined();
+  });
+});

package/src/Select/components/SelectContent.tsx

@@ -0,0 +1,75 @@
+import React from "react";
+import type { PropsWithChildren, ReactElement } from "react";
+import { Platform, StyleSheet, useWindowDimensions } from "react-native";
+import {
+  GestureHandlerRootView,
+  ScrollView,
+} from "react-native-gesture-handler";
+import { FullWindowOverlay } from "react-native-screens";
+import { SelectPrimitive } from "../../primitives/Select";
+import type { SelectPrimitiveContentProps } from "../../primitives/Select";
+
+/**
+ * iOS: draw the dropdown in a top-level window so it sits above native-stack
+ * modals the app-root host can't reach. GestureHandlerRootView restores gestures
+ * there so the inner ScrollView scrolls. Passthrough elsewhere.
+ */
+function ModalSafeOverlay({ children }: PropsWithChildren): ReactElement {
+  if (Platform.OS !== "ios") {
+    return <>{children}</>;
+  }
+
+  return (
+    <FullWindowOverlay>
+      <GestureHandlerRootView style={styles.overlayRoot}>
+        {children}
+      </GestureHandlerRootView>
+    </FullWindowOverlay>
+  );
+}
+
+export type SelectContentProps = SelectPrimitiveContentProps;
+
+// Cap the dropdown height (rn-primitives positions it but never caps it) so long
+// lists scroll; a window fraction adapts across devices.
+const MAX_HEIGHT_RATIO = 0.55;
+
+/**
+ * Folds the primitive Portal / Overlay / Content / Viewport into one dropdown
+ * part. Positioning lives in the primitive `Content`; props pass through.
+ */
+export function SelectContent({
+  children,
+  ...props
+}: SelectContentProps): ReactElement {
+  const { height } = useWindowDimensions();
+  const maxHeight = Math.round(height * MAX_HEIGHT_RATIO);
+
+  return (
+    <SelectPrimitive.Portal>
+      <ModalSafeOverlay>
+        {/* Content nests inside Overlay so an item press beats the backdrop's
+            tap-to-dismiss and selects instead of closing. */}
+        <SelectPrimitive.Overlay>
+          <SelectPrimitive.Content {...props}>
+            <SelectPrimitive.Viewport>
+              <ScrollView
+                style={{ maxHeight }}
+                bounces={false}
+                keyboardShouldPersistTaps="handled"
+              >
+                {children}
+              </ScrollView>
+            </SelectPrimitive.Viewport>
+          </SelectPrimitive.Content>
+        </SelectPrimitive.Overlay>
+      </ModalSafeOverlay>
+    </SelectPrimitive.Portal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlayRoot: {
+    flex: 1,
+  },
+});

package/src/Select/components/SelectFieldContext.tsx

@@ -0,0 +1,46 @@
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+
+/** Where the field label renders relative to the trigger. */
+export type LabelPlacement = "above" | "inside";
+
+/**
+ * Sugar-owned field state, provided by `Select.Root` and read by the sugar parts
+ * (`Select.Trigger`, `Select.Label`). `Select.Label` registers its content here
+ * (rather than rendering in place); `Select.Root` / `Select.Trigger` render it in
+ * the slot `labelPlacement` selects. See `Select.guide.md` for the model.
+ */
+export interface SelectFieldState {
+  /** Chosen label placement — above the trigger or inside it. */
+  readonly labelPlacement: LabelPlacement;
+
+  /** The label content to render — the registered `Select.Label` children. */
+  readonly labelContent?: ReactNode;
+
+  /** Resolved accessible name applied to the trigger. */
+  readonly accessibilityLabel?: string;
+
+  /** Resolved critical state (from `invalid` / `status` / `error`). */
+  readonly invalid?: boolean;
+
+  /** Render the trigger as a static, non-pressable read-only display. */
+  readonly readOnly?: boolean;
+
+  /** Register the label content (+ its accessible name, when it is a string). */
+  registerLabel(content: ReactNode, accessibleName?: string): void;
+
+  /** Clear a previously registered label (on `Select.Label` unmount). */
+  unregisterLabel(): void;
+}
+
+const noop = (): void => undefined;
+
+export const SelectFieldContext = createContext<SelectFieldState>({
+  labelPlacement: "inside",
+  registerLabel: noop,
+  unregisterLabel: noop,
+});
+
+export function useSelectFieldState(): SelectFieldState {
+  return useContext(SelectFieldContext);
+}

package/src/Select/components/SelectItem.style.ts

@@ -0,0 +1,7 @@
+import { buildThemedStyles } from "../../AtlantisThemeContext";
+
+export const useStyles = buildThemedStyles(() => ({
+  slot: {
+    justifyContent: "center",
+  },
+}));

package/src/Select/components/SelectItem.test.tsx

@@ -0,0 +1,166 @@
+import React from "react";
+import type { ReactNode } from "react";
+import { render, screen, userEvent } from "@testing-library/react-native";
+import { SelectItem, SelectItemPrefix, SelectItemSuffix } from "./SelectItem";
+import { SelectTrigger } from "./SelectTrigger";
+import { SelectRoot } from "../SelectRoot";
+import { SelectPrimitive } from "../../primitives/Select";
+import { Icon } from "../../Icon";
+import { Text } from "../../Text";
+import { PortalHostWrapper } from "../../utils/test";
+import { tokens } from "../../utils/design";
+
+const user = userEvent.setup();
+
+beforeAll(() => {
+  const MockNativeMethods = require("react-native/jest/MockNativeMethods");
+  const mockedMethods = MockNativeMethods.default ?? MockNativeMethods;
+  mockedMethods.measure.mockImplementation(
+    (
+      callback: (
+        x: number,
+        y: number,
+        width: number,
+        height: number,
+        pageX: number,
+        pageY: number,
+      ) => void,
+    ) => {
+      callback(0, 0, 320, 48, 20, 100);
+    },
+  );
+});
+
+function renderItems(
+  items: ReactNode,
+  defaultValue?: { value: string; label: string },
+  onValueChange?: (option?: { value: string; label: string }) => void,
+) {
+  return render(
+    <SelectRoot defaultValue={defaultValue} onValueChange={onValueChange}>
+      <SelectTrigger>
+        <SelectPrimitive.Value placeholder="Select an option" />
+      </SelectTrigger>
+      <SelectPrimitive.Portal>
+        <SelectPrimitive.Overlay />
+        <SelectPrimitive.Content>
+          <SelectPrimitive.Viewport>{items}</SelectPrimitive.Viewport>
+        </SelectPrimitive.Content>
+      </SelectPrimitive.Portal>
+    </SelectRoot>,
+    { wrapper: PortalHostWrapper },
+  );
+}
+
+async function openSelect() {
+  await user.press(screen.getByTestId("ATL-Select-Trigger"));
+}
+
+describe("Select.Item", () => {
+  it("renders the option label from the label prop", async () => {
+    renderItems(<SelectItem value="tor" label="Toronto" />);
+    await openSelect();
+
+    expect(screen.getByText("Toronto")).toBeDefined();
+  });
+
+  it("shows the default checkmark on the selected row only", async () => {
+    renderItems(
+      <>
+        <SelectItem value="tor" label="Toronto" />
+        <SelectItem value="van" label="Vancouver" />
+      </>,
+      { value: "tor", label: "Toronto" },
+    );
+    await openSelect();
+
+    // The indicator self-hides on unselected rows, so only the selected row's
+    // checkmark is in the tree.
+    expect(screen.getAllByTestId("checkmark")).toHaveLength(1);
+  });
+
+  it("renders prefix and suffix slots around the label", async () => {
+    renderItems(
+      <SelectItem
+        value="tor"
+        label="Toronto"
+        prefix={
+          <SelectItemPrefix>
+            <Icon name="home" />
+          </SelectItemPrefix>
+        }
+        suffix={
+          <SelectItemSuffix>
+            <Text>ON</Text>
+          </SelectItemSuffix>
+        }
+      />,
+    );
+    await openSelect();
+
+    expect(screen.getByTestId("home")).toBeDefined();
+    expect(screen.getByText("ON")).toBeDefined();
+    expect(screen.getByText("Toronto")).toBeDefined();
+  });
+
+  it("shows the suffix alongside the checkmark on the selected row", async () => {
+    renderItems(
+      <SelectItem
+        value="tor"
+        label="Toronto"
+        suffix={
+          <SelectItemSuffix>
+            <Text>ON</Text>
+          </SelectItemSuffix>
+        }
+      />,
+      { value: "tor", label: "Toronto" },
+    );
+    await openSelect();
+
+    // The suffix coexists with the selected-state marker (it doesn't replace it).
+    expect(screen.getByText("ON")).toBeDefined();
+    expect(screen.getByTestId("checkmark")).toBeDefined();
+  });
+
+  it("overrides the default checkmark via the indicator prop", async () => {
+    renderItems(
+      <SelectItem
+        value="tor"
+        label="Toronto"
+        indicator={<Icon name="starFill" />}
+      />,
+      { value: "tor", label: "Toronto" },
+    );
+    await openSelect();
+
+    expect(screen.getByTestId("starFill")).toBeDefined();
+    expect(screen.queryByTestId("checkmark")).toBeNull();
+  });
+
+  it("selects an option on press (selection flows through the sugar)", async () => {
+    const onValueChange = jest.fn();
+    renderItems(
+      <SelectItem value="tor" label="Toronto" />,
+      undefined,
+      onValueChange,
+    );
+    await openSelect();
+
+    await user.press(screen.getByText("Toronto"));
+
+    expect(onValueChange).toHaveBeenCalledWith({
+      value: "tor",
+      label: "Toronto",
+    });
+  });
+
+  it("greys a disabled option's label", async () => {
+    renderItems(<SelectItem value="van" label="Vancouver" disabled />);
+    await openSelect();
+
+    expect(screen.getByText("Vancouver")).toHaveStyle({
+      color: tokens["color-disabled"],
+    });
+  });
+});

package/src/Select/components/SelectItem.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+import type { ReactElement, ReactNode } from "react";
+import { View } from "react-native";
+import { useStyles } from "./SelectItem.style";
+import { SelectPrimitive } from "../../primitives/Select";
+import { Icon } from "../../Icon";
+
+export interface SelectItemProps {
+  /** The option's value. */
+  readonly value: string;
+  /** The option's label — rendered as the row text and used as the value label. */
+  readonly label: string;
+  /** Disables selection and greys the label. */
+  readonly disabled?: boolean;
+  /** Close the dropdown when this option is pressed (default behaviour). */
+  readonly closeOnPress?: boolean;
+  /** Leading content, before the label — typically a `Select.ItemPrefix`. */
+  readonly prefix?: ReactNode;
+  /** Trailing content, after the label — typically a `Select.ItemSuffix`. */
+  readonly suffix?: ReactNode;
+  /** Overrides the default checkmark marker shown on the selected row. */
+  readonly indicator?: ReactNode;
+}
+
+/**
+ * An option row. Auto-composes the label + a default checkmark from its
+ * `value` / `label` / `disabled` props, and places the `prefix` / `suffix` slot
+ * content around the label (prefix → label → suffix → marker). `indicator`
+ * overrides the default checkmark; `disabled` greys the label and blocks
+ * selection.
+ */
+export function SelectItem({
+  value,
+  label,
+  disabled,
+  closeOnPress,
+  prefix,
+  suffix,
+  indicator,
+}: SelectItemProps): ReactElement {
+  return (
+    <SelectPrimitive.Item
+      value={value}
+      label={label}
+      disabled={disabled}
+      closeOnPress={closeOnPress}
+    >
+      {prefix}
+      <SelectPrimitive.ItemText disabled={disabled} />
+      {suffix}
+      <SelectPrimitive.ItemIndicator>
+        {indicator ?? <Icon name="checkmark" />}
+      </SelectPrimitive.ItemIndicator>
+    </SelectPrimitive.Item>
+  );
+}
+
+export interface SelectItemSlotProps {
+  readonly children?: ReactNode;
+}
+
+/** Styled leading slot — pass to `Select.Item`'s `prefix` prop. */
+export function SelectItemPrefix({
+  children,
+}: SelectItemSlotProps): ReactElement {
+  const styles = useStyles();
+
+  return <View style={styles.slot}>{children}</View>;
+}
+
+/** Styled trailing slot — pass to `Select.Item`'s `suffix` prop. */
+export function SelectItemSuffix({
+  children,
+}: SelectItemSlotProps): ReactElement {
+  const styles = useStyles();
+
+  return <View style={styles.slot}>{children}</View>;
+}

package/src/Select/components/SelectLabel.tsx

@@ -0,0 +1,57 @@
+import React, { useLayoutEffect } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { useSelectFieldState } from "./SelectFieldContext";
+import { Text } from "../../Text";
+
+export interface SelectLabelProps {
+  /**
+   * The label content. Its placement (above the trigger vs. inside it) is set by
+   * the `labelPlacement` prop on `Select.Root`, not by where this is written.
+   */
+  readonly children?: ReactNode;
+}
+
+/**
+ * The field label. Rather than render in place, it **registers** its `children`
+ * (and, when a string, the trigger's accessible name) into `Select.Root`, which
+ * renders the content in the slot `labelPlacement` selects. Renders nothing where
+ * it is composed. See `Select.guide.md`.
+ */
+export function SelectLabel({ children }: SelectLabelProps): null {
+  const { registerLabel, unregisterLabel } = useSelectFieldState();
+
+  useLayoutEffect(() => {
+    registerLabel(
+      children,
+      typeof children === "string" ? children : undefined,
+    );
+
+    return unregisterLabel;
+  }, [children, registerLabel, unregisterLabel]);
+
+  return null;
+}
+
+/**
+ * Internal renderer for the registered label content, shared by the above slot
+ * (`Select.Root`) and the inside slot (`Select.Trigger`). Sizes itself from
+ * `labelPlacement` (smaller when `inside`). Hidden from assistive tech — the
+ * trigger carries the accessible name.
+ */
+export function FieldLabel(): ReactElement | null {
+  const { labelContent, labelPlacement } = useSelectFieldState();
+  if (labelContent == null) return null;
+
+  return typeof labelContent === "string" ? (
+    <Text
+      variation="subdued"
+      level={labelPlacement === "inside" ? "textSupporting" : undefined}
+      maxLines="single"
+      hideFromScreenReader
+    >
+      {labelContent}
+    </Text>
+  ) : (
+    <>{labelContent}</>
+  );
+}

package/src/Select/components/SelectTrigger.style.ts

@@ -0,0 +1,29 @@
+import { buildThemedStyles } from "../../AtlantisThemeContext";
+
+export const useStyles = buildThemedStyles(tokens => ({
+  content: {
+    flex: 1,
+    justifyContent: "center",
+  },
+
+  // Inside-label placement: the Value's flex fills the column vertically and
+  // would otherwise pin the label flush to the top. This top inset gives the
+  // label the same breathing room as the shared input chrome's mini-label.
+  contentInside: {
+    paddingTop: tokens["space-small"] - tokens["space-smallest"],
+  },
+
+  // Static read-only surface — mirrors the trigger shape with a subtle fill, no chevron.
+  readOnly: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: tokens["space-small"],
+    minHeight: tokens["space-largest"] + tokens["space-small"],
+    paddingLeft: tokens["space-base"],
+    paddingRight: tokens["space-small"],
+    backgroundColor: tokens["color-surface--background--subtle"],
+    borderWidth: tokens["border-base"],
+    borderColor: tokens["color-border"],
+    borderRadius: tokens["radius-base"],
+  },
+}));

package/src/Select/components/SelectTrigger.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import type { ReactElement, ReactNode, Ref } from "react";
+import { Keyboard, View } from "react-native";
+import { type TriggerRef, useRootContext } from "@rn-primitives/select";
+import { useStyles } from "./SelectTrigger.style";
+import { useSelectFieldState } from "./SelectFieldContext";
+import { FieldLabel } from "./SelectLabel";
+import {
+  SELECT_TRIGGER_DEFAULT_TEST_ID,
+  SelectPrimitive,
+} from "../../primitives/Select";
+import { Icon } from "../../Icon";
+
+export interface SelectTriggerProps {
+  /** Trigger content — typically `Select.Value` (and optionally a label part). */
+  readonly children?: ReactNode;
+  /** Used verbatim to locate the trigger in end-to-end tests. Defaults to `ATL-Select-Trigger`. */
+  readonly testID?: string;
+  /**
+   * Imperative handle exposing `open()` / `close()`. Stays `null` when the field
+   * is `readOnly` (no interactive trigger is mounted).
+   */
+  readonly ref?: Ref<TriggerRef>;
+}
+
+/**
+ * The styled field trigger: composes the chevron, the resolved `invalid` styling,
+ * the accessible name, the inside label placement, and the static `readOnly`
+ * presentation over `SelectPrimitive.Trigger`. State comes from `Select.Root`
+ * (field context) and the primitive root context.
+ */
+export function SelectTrigger({
+  children,
+  testID,
+  ref,
+}: SelectTriggerProps): ReactElement {
+  const styles = useStyles();
+  const { invalid, readOnly, accessibilityLabel, labelPlacement } =
+    useSelectFieldState();
+  const { open, value, disabled } = useRootContext();
+
+  const isDisabled = disabled ?? false;
+  // `disabled` wins over `readOnly`.
+  const isReadOnly = !isDisabled && (readOnly ?? false);
+
+  const isInsideLabel = labelPlacement === "inside";
+
+  const content = (
+    <View style={[styles.content, isInsideLabel && styles.contentInside]}>
+      {isInsideLabel && <FieldLabel />}
+      {children}
+    </View>
+  );
+
+  if (isReadOnly) {
+    return (
+      <View
+        testID={testID ?? SELECT_TRIGGER_DEFAULT_TEST_ID}
+        accessible={true}
+        accessibilityLabel={accessibilityLabel}
+        accessibilityValue={value?.label ? { text: value.label } : undefined}
+        style={styles.readOnly}
+      >
+        {content}
+      </View>
+    );
+  }
+
+  return (
+    <SelectPrimitive.Trigger
+      ref={ref}
+      testID={testID}
+      invalid={invalid}
+      accessibilityLabel={accessibilityLabel}
+      // Dismiss any open keyboard so it doesn't cover the dropdown (matches the
+      // native picker's on-device behaviour; rn-primitives doesn't do this).
+      onPressIn={() => Keyboard.dismiss()}
+    >
+      {content}
+      <Chevron open={open} disabled={isDisabled} />
+    </SelectPrimitive.Trigger>
+  );
+}
+
+/** Trailing chevron: tinted `iconSecondary`, greyed when disabled, rotated when open. */
+function Chevron({
+  open,
+  disabled,
+}: {
+  readonly open: boolean;
+  readonly disabled: boolean;
+}): ReactElement {
+  return (
+    <View style={{ transform: [{ rotate: open ? "180deg" : "0deg" }] }}>
+      <Icon name="arrowDown" color={disabled ? "disabled" : "iconSecondary"} />
+    </View>
+  );
+}

package/src/Select/docs/SelectComposableBasic.tsx

@@ -0,0 +1,18 @@
+import React from "react";
+import { Select } from "@jobber/components-native";
+import { ProvinceItems } from "./SelectComposableProvinces";
+
+/** Default placement: the composed `Select.Label` renders inside the trigger. */
+export function SelectComposableBasic() {
+  return (
+    <Select.Root>
+      <Select.Label>Province</Select.Label>
+      <Select.Trigger>
+        <Select.Value placeholder="Select a province" />
+      </Select.Trigger>
+      <Select.Content>
+        <ProvinceItems />
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/Select/docs/SelectComposableControlledWithRef.tsx

@@ -0,0 +1,28 @@
+import React, { useRef } from "react";
+import { View } from "react-native";
+import type { TriggerRef } from "@rn-primitives/select";
+import { Button, Select } from "@jobber/components-native";
+import { ProvinceItems } from "./SelectComposableProvinces";
+
+/** The trigger ref exposes imperative `open()` / `close()`. */
+export function SelectComposableControlledWithRef() {
+  const triggerRef = useRef<TriggerRef>(null);
+
+  return (
+    <View style={{ gap: 16 }}>
+      <Select.Root>
+        <Select.Label>Province</Select.Label>
+        <Select.Trigger ref={triggerRef}>
+          <Select.Value placeholder="Select a province" />
+        </Select.Trigger>
+        <Select.Content>
+          <ProvinceItems />
+        </Select.Content>
+      </Select.Root>
+      <Button
+        label="Open the dropdown"
+        onPress={() => triggerRef.current?.open()}
+      />
+    </View>
+  );
+}