@jobber/components-native 0.108.1 → 0.109.0

package/src/Select/Select.guide.md

@@ -0,0 +1,197 @@
+# Select Spec
+
+## Purpose
+
+`Select` lets a person choose a single option from a list. On mobile it renders
+an anchored dropdown (never a bottom sheet or the native OS picker), styled with
+Atlantis design tokens.
+
+There are two APIs on the same `Select` export:
+
+- The **composable API** (`Select.Root`, `Select.Trigger`, …) is the supported
+  long-term direction. It is a thin, styled passthrough over
+  [`@rn-primitives/select`](https://rnprimitives.com/select/).
+- The **legacy props-driven API** (`<Select label … value … onChange>` with
+  `Option`) continues to work unchanged for existing usage.
+
+## API Status
+
+### Legacy props-driven API
+
+```tsx
+<Select label="City" value={value} onChange={setValue}>
+  <Option value="tor">Toronto</Option>
+  <Option value="van">Vancouver</Option>
+</Select>
+```
+
+Still supported for existing usage; renders through the native OS picker. Do not
+use it for new work — prefer the composable API below.
+
+### Composable API
+
+```tsx
+<Select.Root onValueChange={setValue}>
+  <Select.Label>City</Select.Label>
+  <Select.Trigger>
+    <Select.Value placeholder="Select a city" />
+  </Select.Trigger>
+  <Select.Content>
+    <Select.Item value="tor" label="Toronto" />
+    <Select.Item value="van" label="Vancouver" />
+  </Select.Content>
+</Select.Root>
+```
+
+Parts:
+
+- `Select.Root` — field chrome (`labelPlacement`, `description` / `error`,
+  `invalid` / `status`, `readOnly`, `accessibilityLabel`) wrapped around the
+  state container.
+- `Select.Trigger` — the styled field; renders the chevron and the open,
+  pressed, disabled, readOnly, and critical states. Forwards a `ref` exposing
+  imperative `open()` / `close()` (null when `readOnly`).
+- `Select.Value` — shows the selected option's label, or the `placeholder`.
+- `Select.Label` — the field label. Its content is authored as `children`; its
+  placement (above the trigger vs. a small label inside it) is set by
+  `labelPlacement` on `Select.Root`, **not** by where it is written. It renders
+  nothing where composed — it registers its content into `Select.Root`, which
+  places it in the chosen slot.
+- `Select.Content` — the anchored dropdown surface (folds the portal, overlay,
+  and viewport internally).
+- `Select.Item` — an option row; auto-composes its label and a selected
+  checkmark from `value` / `label` / `disabled`. Optional **slot props** add
+  content: `prefix` / `suffix` (pass a `Select.ItemPrefix` /
+  `Select.ItemSuffix`), and `indicator` overrides the default checkmark.
+- `Select.ItemPrefix` / `Select.ItemSuffix` — styled leading / trailing slots to
+  pass into `Select.Item`'s `prefix` / `suffix` props.
+- `Select.Group` + `Select.GroupLabel` — a labelled group of options (the
+  in-dropdown heading; distinct from the field `Select.Label`).
+- `Select.Separator` — a divider between groups.
+
+### Value model
+
+Single-select only. The value is a `{ value, label }` object; `Select.Root`
+takes `value` / `defaultValue` and `onValueChange((option) => void)`. There is
+no multi-select, numeric value, or computed display value — `Select.Value` shows
+the selected option's label.
+
+## Composition model
+
+A few decisions shape how the composable parts fit together:
+
+- **The primitive is dumb; the sugar adds the Atlantis behavior.**
+  `SelectPrimitive` (`@jobber/components-native/primitives`) is a styling-only
+  passthrough with no field chrome, field state, chevron, read-only, or row
+  composition. Those live in the `Select.*` sugar: `Select.Root` owns the
+  field-state context, `Select.Trigger` composes the chevron / read-only /
+  `invalid` styling, `Select.Content` folds the overlay parts, and `Select.Item`
+  composes the row. (Most statics are these compositions; `Value` / `Group` /
+  `GroupLabel` / `Separator` are direct passthroughs.)
+
+- **Content is composed; placement is a prop.** `Select.Label` bears the label
+  content as `children`; `labelPlacement` on `Select.Root` decides where it
+  lands. Because "above the field" and "inside the field border" are different
+  parents in the view tree, `Select.Label` can't render in place — it registers
+  its content into `Select.Root`, which renders it in the above slot, or
+  `Select.Trigger` renders it in the inside slot. So the part's JSX position is
+  irrelevant; only `labelPlacement` matters.
+
+- **Accessibility names the trigger directly.** The accessible name is applied
+  as the trigger's `accessibilityLabel` — not via the rn-primitives `Label` / a
+  `nativeID`+`accessibilityLabelledBy` association (unsupported on iOS). It is
+  auto-derived from a string `Select.Label`; for non-string content (or a field
+  with no visible label), pass `accessibilityLabel` on `Select.Root`. The
+  visible label is hidden from assistive tech (the trigger already carries the
+  name), so it isn't announced twice — mirroring `InputText` /
+  `InputFieldWrapper`.
+
+### Rendering above native-stack modals
+
+`Select.Content` renders correctly inside iOS native-stack full-screen modals
+(`presentation: "fullScreenModal" | "modal"`) with no per-screen setup — the
+single app-root `AtlantisPortalHost` is enough on both platforms.
+
+The problem it solves: on iOS a native-stack modal is a separate
+`UIViewController` presented above the app's root window, so a host mounted at
+the app root lives _behind_ it — a dropdown portalled into that host would be
+hidden by the modal. (On Android the modal shares the window hierarchy, so the
+root host already reaches it.) `Select.Content` handles this internally, so a
+consumer writes the same `<Select.Content>…</Select.Content>` whether or not the
+field is inside a modal:
+
+- **`FullWindowOverlay`** (react-native-screens, iOS only) — renders the
+  dropdown into a native top-level `UIWindow` that sits above every view
+  controller, including modals. It decouples _where the dropdown mounts in the
+  React tree_ (still the root host) from _where it draws on screen_ (the top
+  window). On Android it is a passthrough — the root host already suffices.
+- **`GestureHandlerRootView`** (inside that overlay window) — the new window has
+  no gesture context of its own, so a root view is re-established here to make
+  touches and scrolling work inside the dropdown.
+- **`ScrollView`** (react-native-gesture-handler) + a **`maxHeight`** (a
+  fraction of the window height) — cap the dropdown and make long lists scroll
+  instead of overflowing. rn-primitives positions the dropdown but never caps
+  its height, so the cap comes from here; a window-height fraction adapts across
+  devices and mirrors the native picker, which grows toward the screen height
+  before scrolling. The gesture-handler ScrollView (rather than a plain React
+  Native one) is required because the primitive `Content` claims the JS touch
+  responder, which would otherwise stop scrolling.
+- **Nesting order** — the scrollable `Content` nests _inside_ the tap-to-dismiss
+  overlay, so an item press (deeper in the tree) wins the responder over the
+  backdrop and selects, instead of falling through and dismissing.
+
+This relies on `react-native-screens` and `react-native-gesture-handler`, which
+a navigation-based app already has.
+
+## Setup: adopting `Select` in an app
+
+The dropdown renders through `@rn-primitives/portal`, so an app must do two
+things before the composable `Select` works. (These are one-time host-app setup;
+Atlantis does not do them for you.)
+
+**1. Mount one `AtlantisPortalHost` at the app root.** Import it from
+`@jobber/components-native/primitives` — it is the bundled
+`@rn-primitives/portal` host, so mounting it (rather than a `PortalHost` from a
+separate copy of the package) guarantees the dropdown resolves against the same
+portal instance Atlantis renders into. Mount exactly one, as the last child of
+the root layout:
+
+```tsx
+import { AtlantisPortalHost } from "@jobber/components-native/primitives";
+
+export function App() {
+  return (
+    <Providers>
+      <Navigation />
+      <AtlantisPortalHost />
+    </Providers>
+  );
+}
+```
+
+This one host is sufficient even for fields inside native-stack full-screen
+modals — `Select.Content` lifts its dropdown above the modal on iOS, so no
+per-screen host is needed (see
+[Rendering above native-stack modals](#rendering-above-native-stack-modals)).
+
+**2. Let Jest transpile `@rn-primitives`.** The packages ship ESM, so the host
+app's Jest config must not ignore them — add `@rn-primitives` to
+`transformIgnorePatterns`:
+
+```js
+// jest.config.js
+transformIgnorePatterns: [
+  "node_modules/(?!((jest-)?react-native|@react-native|@rn-primitives)/)",
+];
+```
+
+For Atlantis' own tests, wrap renders with the `PortalHostWrapper` test util so
+the dropdown renders into the test tree:
+
+```tsx
+render(ui, { wrapper: PortalHostWrapper });
+```
+
+> `@rn-primitives/select` declares a transitive dependency on
+> `@radix-ui/react-select`, which is web-only and imported only by the
+> primitive's web platform entries — Metro never bundles it on native.

package/src/Select/Select.tsx

@@ -4,6 +4,16 @@ import { View } from "react-native";
 import type { RegisterOptions } from "react-hook-form";
 import { useStyles } from "./Select.style";
 import { SelectInternalPicker } from "./components/SelectInternalPicker";
+import { SelectRoot } from "./SelectRoot";
+import { SelectTrigger } from "./components/SelectTrigger";
+import { SelectLabel } from "./components/SelectLabel";
+import { SelectContent } from "./components/SelectContent";
+import {
+  SelectItem,
+  SelectItemPrefix,
+  SelectItemSuffix,
+} from "./components/SelectItem";
+import { SelectPrimitive } from "../primitives/Select";
 import { InputFieldWrapper } from "../InputFieldWrapper";
 import { Icon } from "../Icon";
 import type { TextVariation } from "../Typography";
@@ -225,6 +235,27 @@ export function Select({
   }
 }
 
+/**
+ * The composable `Select.*` parts, attached as statics on the function
+ * declaration in this file — the docs site's prop generation
+ * (react-docgen-typescript) only discovers parts assigned here at compile
+ * time, not runtime attachments like `Object.assign`. Additive — the legacy
+ * props-driven `Select` + `Option` are unchanged (props, native picker,
+ * `ATL-Select` testID). See `Select.guide.md` for the parts and the
+ * composition model.
+ */
+Select.Root = SelectRoot;
+Select.Trigger = SelectTrigger;
+Select.Value = SelectPrimitive.Value;
+Select.Label = SelectLabel;
+Select.Content = SelectContent;
+Select.Item = SelectItem;
+Select.ItemPrefix = SelectItemPrefix;
+Select.ItemSuffix = SelectItemSuffix;
+Select.Group = SelectPrimitive.Group;
+Select.GroupLabel = SelectPrimitive.Label;
+Select.Separator = SelectPrimitive.Separator;
+
 function getTextVariation({
   invalid,
   disabled,

package/src/Select/SelectComposableTypes.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+import type { SelectPrimitiveRootProps } from "../primitives/Select";
+
+/**
+ * Props for the composable `Select.Root` chrome — a presentational
+ * composition over `SelectPrimitive.Root`. Adds the optional field chrome
+ * (label, description / error) and the field-state flags (`invalid`,
+ * `status`, `readOnly`) that the styled trigger reads. Everything else passes
+ * through to `SelectPrimitive.Root` (and therefore `@rn-primitives/select`).
+ *
+ * Deliberately RHF-free: no `name`, no `validations`.
+ */
+export interface SelectRootProps extends SelectPrimitiveRootProps {
+  /**
+   * Where the field label renders: `"inside"` the trigger (small, above the value)
+   * or `"above"` it. DS-owned default (`"inside"`); overridable per instance.
+   * The label content itself is authored via `Select.Label`.
+   */
+  readonly labelPlacement?: "above" | "inside";
+
+  /**
+   * Explicit accessible name for the trigger. Auto-derived from a string
+   * `Select.Label`; supply this when the label content is a non-string
+   * `ReactNode`, or to name a field that has no visible `Select.Label`.
+   */
+  readonly accessibilityLabel?: string;
+
+  /**
+   * Supporting text rendered below the trigger. A string renders as neutral
+   * `HelperText`; a `ReactNode` renders verbatim. Suppressed when `error` is
+   * present.
+   */
+  readonly description?: string | ReactNode;
+
+  /**
+   * Error message rendered below the trigger as critical `HelperText` (string)
+   * or verbatim (`ReactNode`). Takes priority over `description` and applies
+   * the critical trigger styling.
+   */
+  readonly error?: string | ReactNode;
+
+  /**
+   * Applies the critical trigger styling without rendering an error message.
+   */
+  readonly invalid?: boolean;
+
+  /**
+   * `critical` applies the critical trigger styling. Defaults to `neutral`.
+   */
+  readonly status?: "neutral" | "critical";
+
+  /**
+   * Renders the trigger as non-interactive read-only presentation (subtle
+   * surface, no chevron, value as text). `disabled` takes precedence.
+   */
+  readonly readOnly?: boolean;
+}

package/src/Select/SelectRoot.style.ts

@@ -0,0 +1,10 @@
+import { buildThemedStyles } from "../AtlantisThemeContext";
+
+export const useStyles = buildThemedStyles(tokens => ({
+  container: {
+    gap: tokens["space-smaller"],
+  },
+  field: {
+    gap: tokens["space-small"],
+  },
+}));

package/src/Select/SelectRoot.test.tsx

@@ -0,0 +1,245 @@
+import React from "react";
+import { render, screen, within } from "@testing-library/react-native";
+import type { TriggerRef } from "@rn-primitives/select";
+import { SelectRoot } from "./SelectRoot";
+import { SelectTrigger } from "./components/SelectTrigger";
+import { SelectLabel } from "./components/SelectLabel";
+import type { SelectRootProps } from "./SelectComposableTypes";
+import { SelectPrimitive } from "../primitives/Select";
+import { Text } from "../Text";
+import { tokens } from "../utils/design";
+
+function renderRoot(props: Partial<SelectRootProps> = {}) {
+  return render(
+    <SelectRoot {...props}>
+      <SelectTrigger>
+        <SelectPrimitive.Value placeholder="Select an option" />
+      </SelectTrigger>
+    </SelectRoot>,
+  );
+}
+
+describe("SelectRoot chrome", () => {
+  it("renders a composed label (visible, hidden from assistive tech)", () => {
+    render(
+      <SelectRoot>
+        <SelectLabel>City</SelectLabel>
+        <SelectTrigger>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+
+    // The label renders but is hidden from a11y (the trigger carries the name).
+    expect(screen.queryByText("City")).toBeNull();
+    expect(
+      screen.getByText("City", { includeHiddenElements: true }),
+    ).toBeDefined();
+  });
+
+  it("renders a string description as neutral helper text", () => {
+    renderRoot({ description: "Pick your city" });
+
+    expect(screen.getByText("Pick your city")).toBeDefined();
+    // Neutral helper text has no alert icon.
+    expect(screen.queryByTestId("alert")).toBeNull();
+  });
+
+  it("renders an error as critical helper text", () => {
+    renderRoot({ error: "This field is required" });
+
+    expect(screen.getByText("This field is required")).toBeDefined();
+    expect(screen.getByTestId("alert")).toBeDefined();
+  });
+
+  it("gives error priority over description", () => {
+    renderRoot({ description: "Pick your city", error: "Required" });
+
+    expect(screen.getByText("Required")).toBeDefined();
+    expect(screen.queryByText("Pick your city")).toBeNull();
+  });
+
+  it("treats an empty-string error as no error", () => {
+    renderRoot({ error: "", description: "Pick your city" });
+
+    // No critical styling, no error helper — the description shows instead.
+    expect(screen.getByTestId("ATL-Select-Trigger")).not.toHaveStyle({
+      borderColor: tokens["color-critical"],
+    });
+    expect(screen.queryByTestId("alert")).toBeNull();
+    expect(screen.getByText("Pick your city")).toBeDefined();
+  });
+
+  it.each([
+    ["error", { error: "Required" }],
+    ["status critical", { status: "critical" as const }],
+    ["invalid", { invalid: true }],
+  ])("applies critical trigger styling from %s", (_label, props) => {
+    renderRoot(props);
+
+    expect(screen.getByTestId("ATL-Select-Trigger")).toHaveStyle({
+      borderColor: tokens["color-critical"],
+    });
+  });
+
+  it("makes the trigger read-only (no chevron) via the Root prop", () => {
+    renderRoot({ readOnly: true });
+
+    expect(screen.getByTestId("ATL-Select-Trigger")).toHaveStyle({
+      backgroundColor: tokens["color-surface--background--subtle"],
+    });
+    expect(screen.queryByTestId("arrowDown")).toBeNull();
+  });
+
+  it.each([false, true])(
+    "uses a provided trigger testID verbatim (readOnly=%s)",
+    readOnly => {
+      render(
+        <SelectRoot readOnly={readOnly}>
+          <SelectTrigger testID="city">
+            <SelectPrimitive.Value placeholder="Select an option" />
+          </SelectTrigger>
+        </SelectRoot>,
+      );
+
+      expect(screen.getByTestId("city")).toBeDefined();
+      expect(screen.queryByTestId("ATL-Select-Trigger")).toBeNull();
+    },
+  );
+
+  it("greys the value when disabled via the Root prop", () => {
+    renderRoot({
+      disabled: true,
+      defaultValue: { value: "tor", label: "Toronto" },
+    });
+
+    expect(screen.getByText("Toronto")).toHaveStyle({
+      color: tokens["color-disabled"],
+    });
+  });
+});
+
+describe("SelectRoot label placement", () => {
+  const hidden = { includeHiddenElements: true } as const;
+
+  function renderComposed(props: Partial<SelectRootProps> = {}) {
+    return render(
+      <SelectRoot {...props}>
+        <SelectLabel>City</SelectLabel>
+        <SelectTrigger>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+  }
+
+  it("places the label inside the trigger by default (labelPlacement inside)", () => {
+    renderComposed();
+
+    const trigger = screen.getByTestId("ATL-Select-Trigger");
+    expect(within(trigger).getByText("City", hidden)).toBeDefined();
+  });
+
+  it("places the label above the trigger with labelPlacement='above'", () => {
+    renderComposed({ labelPlacement: "above" });
+
+    // Rendered exactly once, and outside the trigger.
+    expect(screen.getAllByText("City", hidden)).toHaveLength(1);
+    const trigger = screen.getByTestId("ATL-Select-Trigger");
+    expect(within(trigger).queryByText("City", hidden)).toBeNull();
+  });
+
+  it("ignores where Select.Label is written — placement follows the prop", () => {
+    render(
+      <SelectRoot labelPlacement="inside">
+        <SelectTrigger>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+        {/* Written last, but still renders inside the trigger. */}
+        <SelectLabel>City</SelectLabel>
+      </SelectRoot>,
+    );
+
+    const trigger = screen.getByTestId("ATL-Select-Trigger");
+    expect(within(trigger).getByText("City", hidden)).toBeDefined();
+  });
+
+  it("auto-publishes a string Select.Label as the trigger's accessible name", () => {
+    renderComposed();
+
+    expect(
+      screen.getByTestId("ATL-Select-Trigger").props.accessibilityLabel,
+    ).toBe("City");
+  });
+
+  it("uses an explicit accessibilityLabel for non-string label content", () => {
+    render(
+      <SelectRoot accessibilityLabel="City">
+        <SelectLabel>
+          <Text>City</Text>
+        </SelectLabel>
+        <SelectTrigger>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+
+    expect(
+      screen.getByTestId("ATL-Select-Trigger").props.accessibilityLabel,
+    ).toBe("City");
+  });
+
+  it("warns when more than one Select.Label is composed", () => {
+    const warn = jest
+      .spyOn(console, "warn")
+      .mockImplementation(() => undefined);
+
+    render(
+      <SelectRoot>
+        <SelectLabel>City</SelectLabel>
+        <SelectLabel>Town</SelectLabel>
+        <SelectTrigger>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("multiple <Select.Label>"),
+    );
+    warn.mockRestore();
+  });
+});
+
+describe("SelectTrigger ref", () => {
+  it("forwards a ref exposing open/close", () => {
+    const triggerRef = React.createRef<TriggerRef>();
+    render(
+      <SelectRoot>
+        <SelectTrigger ref={triggerRef}>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+
+    expect(triggerRef.current).not.toBeNull();
+    expect(typeof triggerRef.current?.open).toBe("function");
+    expect(typeof triggerRef.current?.close).toBe("function");
+  });
+
+  it("does not attach a ref when readOnly (no interactive trigger)", () => {
+    const triggerRef = React.createRef<TriggerRef>();
+    render(
+      <SelectRoot readOnly defaultValue={{ value: "tor", label: "Toronto" }}>
+        <SelectTrigger ref={triggerRef}>
+          <SelectPrimitive.Value placeholder="Select an option" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+
+    // readOnly mounts a static surface, so the ref stays null and an
+    // optional-chained open()/close() is a safe no-op.
+    expect(triggerRef.current).toBeNull();
+    expect(() => triggerRef.current?.open()).not.toThrow();
+  });
+});

package/src/Select/SelectRoot.tsx

@@ -0,0 +1,120 @@
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { View } from "react-native";
+import { useStyles } from "./SelectRoot.style";
+import type { SelectRootProps } from "./SelectComposableTypes";
+import { SelectFieldContext } from "./components/SelectFieldContext";
+import { FieldLabel } from "./components/SelectLabel";
+import { HelperText } from "../primitives/HelperText";
+import { SelectPrimitive } from "../primitives/Select";
+
+/**
+ * Composable `Select.Root` chrome: renders the optional `description` / `error`
+ * below the field (via `HelperText`), owns the field-state context, and places the
+ * field label. The label content is authored via `Select.Label` (registered into
+ * this context); `labelPlacement` decides whether it renders in the above slot
+ * (here) or the inside slot (`Select.Trigger`). `error` takes priority over
+ * `description`. See `Select.guide.md` for the label / accessibility / layering
+ * model.
+ */
+export function SelectRoot({
+  labelPlacement = "inside",
+  accessibilityLabel: accessibilityLabelProp,
+  description,
+  error,
+  invalid,
+  status,
+  readOnly,
+  children,
+  ...rootProps
+}: SelectRootProps) {
+  const styles = useStyles();
+  // An empty / whitespace-only string error counts as "no error".
+  const hasError =
+    typeof error === "string" ? error.trim().length > 0 : error != null;
+  const isInvalid = invalid === true || status === "critical" || hasError;
+
+  // A composed `Select.Label` registers its content + (for a string) its
+  // accessible name here.
+  const [registered, setRegistered] = useState<{
+    content: ReactNode;
+    name?: string;
+  }>();
+  // Track how many `Select.Label`s are mounted to warn on unsupported
+  // multi-label usage (the registry holds a single label — the last one wins).
+  const labelCount = useRef(0);
+  const registerLabel = useCallback((content: ReactNode, name?: string) => {
+    labelCount.current += 1;
+
+    if (labelCount.current > 1) {
+      console.warn(
+        "Select: multiple <Select.Label> are composed — only one is supported; the last one wins.",
+      );
+    }
+    setRegistered({ content, name });
+  }, []);
+  const unregisterLabel = useCallback(() => {
+    labelCount.current = Math.max(0, labelCount.current - 1);
+    setRegistered(undefined);
+  }, []);
+
+  const labelContent = registered?.content;
+  const accessibilityLabel = accessibilityLabelProp ?? registered?.name;
+
+  const fieldState = useMemo(
+    () => ({
+      labelPlacement,
+      labelContent,
+      accessibilityLabel,
+      invalid: isInvalid,
+      readOnly,
+      registerLabel,
+      unregisterLabel,
+    }),
+    [
+      labelPlacement,
+      labelContent,
+      accessibilityLabel,
+      isInvalid,
+      readOnly,
+      registerLabel,
+      unregisterLabel,
+    ],
+  );
+
+  return (
+    <View style={styles.container}>
+      <SelectFieldContext.Provider value={fieldState}>
+        <SelectPrimitive.Root style={styles.field} {...rootProps}>
+          {labelPlacement === "above" && <FieldLabel />}
+          {children}
+        </SelectPrimitive.Root>
+      </SelectFieldContext.Provider>
+
+      {renderBelowField(hasError ? error : undefined, description)}
+    </View>
+  );
+}
+
+function renderBelowField(
+  error: SelectRootProps["error"],
+  description: SelectRootProps["description"],
+): ReactNode {
+  if (error != null) {
+    return typeof error === "string" ? (
+      <HelperText message={error} status="critical" />
+    ) : (
+      error
+    );
+  }
+
+  if (description != null) {
+    return typeof description === "string" ? (
+      <HelperText message={description} status="neutral" />
+    ) : (
+      description
+    );
+  }
+
+  return null;
+}