@jobber/components-native 0.113.3 → 0.113.4

package/dist/docs/Select/Select.md

@@ -1,8 +1,12 @@
 # Select
 
-Select presents a defined list of options to choose from. It is a prop-driven,
-labelled dropdown wrapped in a field structure that handles the label,
-description, and error messaging for you.
+## Summary
+
+Select presents a defined list of options and lets the user pick a single value.
+Use it when the choice is one of a known, reasonably short list that lives
+inside a form. For longer lists or free-text search, use
+[Autocomplete](/components/Autocomplete); for triggering an action rather than
+picking a value, use [Menu](/components/Menu).
 
 ```tsx
 import React, { useState } from "react";
@@ -21,21 +25,30 @@ export function SelectBasicExample() {
 }
 ```
 
-## Design & usage guidelines
+## Anatomy
 
-Use Select when a user needs to pick a single value from a known, reasonably
-short list of options. Each option is declared with `Select.Item`, where the
-`value` is submitted and the children are shown as the label.
+| Part          | Description                                                                                                                         |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Trigger       | The field the user clicks to open the list                                                                                          |
+| Label         | Names the field. Sits inside the trigger when empty, floats to a mini-label once a value is chosen. Doubles as the empty-state hint |
+| Value         | The selected option, shown inside the trigger                                                                                       |
+| Dropdown      | The floating panel of options on large screens                                                                                      |
+| Bottom sheet  | The panel of options on small screens (≤490px). Automatic                                                                           |
+| Item          | An individual option in the list                                                                                                    |
+| Group         | Optional — wraps related items under a shared heading                                                                               |
+| Group label   | Optional — the heading shown above a group                                                                                          |
+| Separator     | Optional — a divider between items outside of groups                                                                                |
+| Description   | Optional — helper text shown beneath the field                                                                                      |
+| Error message | Optional — replaces the description while an error is present                                                                       |
 
-Select is controlled: pass the current `value` and an `onValueChange` handler to
-keep your state in sync.
+## Behaviour
 
-## Empty state
+#### Label as placeholder
 
-The `label` doubles as the placeholder: while no value is selected it sits
-centered inside the field, then rises to a floating mini-label once the user
-picks an option. There is no separate `placeholder` prop — the label fills that
-role.
+The `label` names the field and doubles as the empty state. While no value is
+selected it sits centered inside the trigger; once the user picks an option it
+floats up as a mini-label. There is no separate `placeholder` prop — the label
+fills that role.
 
 ```tsx
 import React, { useState } from "react";
@@ -54,89 +67,62 @@ export function SelectEmptyExample() {
 }
 ```
 
-## Description
+#### Selected value display
 
-Use `description` to add supporting help text beneath the field.
+The closed trigger shows the selected `value`, capitalized (e.g. `"active"` →
+`"Active"`). It does **not** read the item's children. When the display label
+differs from the capitalized value, pass `renderValue` to control what the
+trigger shows — otherwise the trigger will silently drift from the list.
 
 ```tsx
 import React, { useState } from "react";
 import { Select } from "@jobber/components/Select";
 
-export function SelectDescriptionExample() {
-  const [value, setValue] = useState<string | undefined>();
-
-  return (
-    <Select
-      label="Status"
-      description="This controls who can see the record."
-      value={value}
-      onValueChange={setValue}
-    >
-      <Select.Item value="active">Active</Select.Item>
-      <Select.Item value="archived">Archived</Select.Item>
-      <Select.Item value="draft">Draft</Select.Item>
-    </Select>
-  );
-}
-```
-
-## States
-
-### Error
-
-Pass an `error` message to mark the field invalid and show the message beneath
-the field. The error replaces the description while it is present. Use `invalid`
-instead to apply the invalid styling without a message — for example when a form
-library such as React Hook Form renders the error text itself.
-
-```tsx
-import React, { useState } from "react";
-import { Select } from "@jobber/components/Select";
+const PRIORITY_LABELS: Record<string, string> = {
+  low: "Low priority",
+  medium: "Medium priority",
+  high: "High priority",
+};
 
-export function SelectErrorExample() {
-  const [value, setValue] = useState<string | undefined>();
+export function SelectRenderValueExample() {
+  const [value, setValue] = useState<string | undefined>("high");
 
   return (
     <Select
-      label="Status"
-      description="This controls who can see the record."
-      error="Please choose a status."
+      label="Priority"
       value={value}
       onValueChange={setValue}
+      renderValue={selected => PRIORITY_LABELS[selected]}
     >
-      <Select.Item value="active">Active</Select.Item>
-      <Select.Item value="archived">Archived</Select.Item>
-      <Select.Item value="draft">Draft</Select.Item>
+      <Select.Item value="low">Low</Select.Item>
+      <Select.Item value="medium">Medium</Select.Item>
+      <Select.Item value="high">High</Select.Item>
     </Select>
   );
 }
 ```
 
-### Disabled
+#### Small screens
 
-Set `disabled` to prevent interaction with the field.
+On viewports ≤490px the options open as a bottom sheet instead of an anchored
+dropdown, matching the pattern used by [Menu](/components/Menu) and
+[Dialog](/components/Dialog). This is automatic — the same authored child tree
+renders on both. Resize the preview narrow to see the sheet.
 
-```tsx
-import React from "react";
-import { Select } from "@jobber/components/Select";
+#### Controlled only
 
-export function SelectDisabledExample() {
-  return (
-    <Select label="Status" disabled value="active">
-      <Select.Item value="active">Active</Select.Item>
-      <Select.Item value="archived">Archived</Select.Item>
-      <Select.Item value="draft">Draft</Select.Item>
-    </Select>
-  );
-}
-```
+Select is controlled: always pass `value` and `onValueChange`. There is no
+uncontrolled `defaultValue`. The change prop is named `onValueChange` (not
+`onChange`) to match the Base UI foundation and to encode the payload — the
+value, not an event — in its name. See [Content guidelines](#content-guidelines)
+for how this affects form-library wiring.
 
-## Grouping
+#### Grouping
 
 Organize related options under section headers with `Select.Group` and
 `Select.GroupLabel`. Adjacent groups are divided automatically, so you don't
-need to add a separator between them. `Select.Separator` is available for adding
-a divider elsewhere in the list.
+need a `Select.Separator` between them — reach for `Select.Separator` only to
+divide items that sit outside groups.
 
 ```tsx
 import React, { useState } from "react";
@@ -162,47 +148,85 @@ export function SelectGroupedExample() {
 }
 ```
 
-## Custom selected value
+#### States
 
-The closed trigger shows the selected value capitalized by default. Pass
-`renderValue` to display something different from the option's label — here the
-list shows short labels (`Low`, `Medium`, `High`) while the trigger shows the
-full `"High priority"`. The open list always shows each `Select.Item`'s
-children.
+* **Description** — pass `description` to add supporting help text beneath the
+  field.
+* **Error** — pass an `error` message to mark the field invalid and show the
+  message beneath the field. The error replaces the description while it is
+  present.
+* **Invalid without a message** — use `invalid` on its own to apply the invalid
+  styling without a message, for example when a form library renders the error
+  text itself.
+* **Disabled** — set `disabled` to prevent interaction with the field.
 
 ```tsx
 import React, { useState } from "react";
 import { Select } from "@jobber/components/Select";
 
-const PRIORITY_LABELS: Record<string, string> = {
-  low: "Low priority",
-  medium: "Medium priority",
-  high: "High priority",
-};
+export function SelectDescriptionExample() {
+  const [value, setValue] = useState<string | undefined>();
 
-export function SelectRenderValueExample() {
-  const [value, setValue] = useState<string | undefined>("high");
+  return (
+    <Select
+      label="Status"
+      description="This controls who can see the record."
+      value={value}
+      onValueChange={setValue}
+    >
+      <Select.Item value="active">Active</Select.Item>
+      <Select.Item value="archived">Archived</Select.Item>
+      <Select.Item value="draft">Draft</Select.Item>
+    </Select>
+  );
+}
+```
+
+```tsx
+import React, { useState } from "react";
+import { Select } from "@jobber/components/Select";
+
+export function SelectErrorExample() {
+  const [value, setValue] = useState<string | undefined>();
 
   return (
     <Select
-      label="Priority"
+      label="Status"
+      description="This controls who can see the record."
+      error="Please choose a status."
       value={value}
       onValueChange={setValue}
-      renderValue={selected => PRIORITY_LABELS[selected]}
     >
-      <Select.Item value="low">Low</Select.Item>
-      <Select.Item value="medium">Medium</Select.Item>
-      <Select.Item value="high">High</Select.Item>
+      <Select.Item value="active">Active</Select.Item>
+      <Select.Item value="archived">Archived</Select.Item>
+      <Select.Item value="draft">Draft</Select.Item>
     </Select>
   );
 }
 ```
 
-## Sizes
+```tsx
+import React from "react";
+import { Select } from "@jobber/components/Select";
+
+export function SelectDisabledExample() {
+  return (
+    <Select label="Status" disabled value="active">
+      <Select.Item value="active">Active</Select.Item>
+      <Select.Item value="archived">Archived</Select.Item>
+      <Select.Item value="draft">Draft</Select.Item>
+    </Select>
+  );
+}
+```
+
+## Variants
+
+### Sizes
 
-Use the `size` prop to render a `small` control for tighter layouts. The
-floating mini-label is hidden at the `small` size, so the compact control keeps
-a single-line height.
+Use `size="small"` for tighter layouts. The floating mini-label is hidden at the
+small size, so the compact control keeps a single-line height. Prefer the
+default (large) size in forms so the label remains visible after selection.
 
 ```tsx
 import React, { useState } from "react";
@@ -221,10 +245,11 @@ export function SelectSizeExample() {
 }
 ```
 
-## Inline
+### Inline
 
 Set `inline` to embed the Select within a line of text. The description and
-error messaging are suppressed in inline mode.
+error messaging are suppressed in inline mode, so pair it with validation that
+lives elsewhere in the surrounding sentence or paragraph.
 
 ```tsx
 import React, { useState } from "react";
@@ -247,48 +272,170 @@ export function SelectInlineExample() {
 }
 ```
 
-## Mobile
+## Content guidelines
 
-On small (touch-sized) web screens — viewport widths of `490px` or less — the
-options open as a bottom sheet instead of an anchored dropdown, matching the
-mobile pattern used by `Menu` and `Dialog`. This is automatic and requires no
-props; selection, keyboard, and focus behaviour are unchanged. Resize the
-preview narrow (or open the examples above on a phone) to see the sheet.
+Option labels are scanned quickly while the list is open and then read back as
+the chosen value once it's closed so they have to work in both places. And
+because the `label` prop doubles as the empty-state hint, it has to work as a
+field name and as an invitation to pick.
 
+#### Sentence case
 
-## Content
+Option labels and group labels are sentence-cased. Capitalize only the first
+letter unless there is a proper noun (a person's name, a brand). Jobber features
+like jobs, quotes, and invoices are not proper nouns.
 
-### Options and labels
+| ✅ Do              | ❌ Don't           |
+| ----------------- | ----------------- |
+| Credit/debit card | Credit/Debit Card |
+| Bank transfer     | BANK TRANSFER     |
+| Authorize.net     | authorize.net     |
+| Jasmine Williams  | jasmine williams  |
 
-Declare each option with `Select.Item`. The `value` prop is what `onValueChange`
-reports and what is submitted with a form; the children are the human-readable
-label shown in the open list.
+#### Noun-first labels
 
-### The selected value display
+Select options represent things the user is picking, not actions they're taking.
+Lead with the noun. If a label reads like an imperative verb phrase, reach for
+[Menu](/components/Menu) or a set of buttons instead.
 
-The closed trigger shows the selected **value**, capitalized by default (e.g.
-`"active"` → `"Active"`). It does not read the option's children — so when the
-label differs from the capitalized value, pass `renderValue` to control what the
-trigger shows:
+| ✅ Do    | ❌ Don't              |
+| ------- | -------------------- |
+| Cash    | Paid by cash         |
+| Draft   | Save as draft        |
+| Overdue | Show overdue only    |
+| Active  | Set status to active |
+
+#### Keep labels short and parallel
+
+Aim for 1–3 words. Every item in the same list should follow the same
+grammatical shape.
 
-```tsx
-<Select
-  label="Status"
-  value={value}
-  onValueChange={setValue}
-  renderValue={value => STATUS_LABELS[value]}
->
-  {/* Select.Item options */}
-</Select>
-```
+| ✅ Do                               | ❌ Don't                                              |
+| ---------------------------------- | ---------------------------------------------------- |
+| Small / Medium / Large             | Small / 12px / Large                                 |
+| Draft / Sent / Paid                | Draft / Sent to client / Payment received            |
+| Bank transfer / Credit card / Cash | Bank transfer / Charge to credit card / Cash on hand |
+
+#### The `label` prop names the field and is the empty state
+
+The `label` is both the field heading and, before a value is picked, the
+placeholder inside the trigger. Use a noun or short noun phrase (1–3 words).
+Don't include the word "Select" or "Choose"; the field itself is the invitation.
+
+| ✅ Do           | ❌ Don't                     |
+| -------------- | --------------------------- |
+| Payment method | Select a payment method     |
+| Status         | Choose a status             |
+| Team member    | Please assign a team member |
+
+#### Don't repeat the label in every option
+
+The `label` already names the category. Repeating it in each option adds noise
+and eats horizontal space in the trigger. With a `label` of "Payment method":
+
+| ✅ Do       | ❌ Don't               |
+| ---------- | --------------------- |
+| Cash       | Cash payment method   |
+| Cheque     | Cheque payment method |
+| E-transfer | Payment by e-transfer |
+
+#### Group labels describe, don't instruct
+
+Keep group labels to 1–2 words that name the category. Don't phrase them as
+prompts to the user.
+
+| ✅ Do            | ❌ Don't                   |
+| --------------- | ------------------------- |
+| Jobber Payments | Payments through Jobber   |
+| Manual entry    | Record a payment manually |
+| Active          | Currently active statuses |
+
+#### Use `renderValue` when the trigger should differ from the item
+
+By default the trigger shows the selected `value` capitalized. Pass
+`renderValue` when the item label carries detail the trigger doesn't need, when
+the underlying value is a raw enum, or when items include an icon or adornment.
+The item shows what the user is choosing between; the trigger
+shows what they chose.
+
+| Scenario                        | Item label                    | `renderValue` returns |
+| ------------------------------- | ----------------------------- | --------------------- |
+| Item has qualifying detail      | `High — needs response today` | `High`                |
+| Item includes an icon adornment | `🔒 Private`                  | `Private`             |
+
+## Do's and Don'ts
+
+#### Do:
+
+* ✅ Use sentence case for option and group labels
+* ✅ Pass `renderValue` whenever the item label differs from the capitalized
+  `value`
+* ✅ Wire `value`, `onValueChange`, `onBlur`, and `ref` explicitly when using a
+  form library
+* ✅ Group options with `Select.Group` + `Select.GroupLabel` when they fall into
+  two or more categories
+* ✅ Reach for [Autocomplete](/components/Autocomplete) instead when the list is
+  long or benefits from typeahead
+
+#### Don't:
 
-### Grouping
+* ❌ Don't spread a React Hook Form `field` object into Select — `onValueChange`
+  won't wire from `field.onChange` and the field will silently stop updating
+* ❌ Don't include "Select" or "Choose" in the `label` — the field itself is the
+  invitation
+* ❌ Don't mix noun options and verb options in the same list; if the items are
+  actions, use [Menu](/components/Menu) instead
+* ❌ Don't repeat the field's label as a prefix in every option
+* ❌ Don't assume the trigger shows the item's children — it shows the `value`,
+  capitalized, unless you pass `renderValue`
+
+## Accessibility
+
+Select is built on Base UI's `Field` and `Select` primitives, which handle label
+wiring, ARIA state, and the interaction model.
+
+#### Keyboard navigation
+
+| Key                | Behaviour                                                           |
+| ------------------ | ------------------------------------------------------------------- |
+| Tab                | Moves focus to the trigger                                          |
+| Enter or Space     | Opens the dropdown / bottom sheet                                   |
+| Up and Down arrows | Move through the list. Wrap at the ends                             |
+| Home / End         | Jump to the first or last option                                    |
+| Enter              | Selects the highlighted option and closes                           |
+| Esc                | Closes without selecting                                            |
+| Type-to-select     | Typing letters jumps to the next option starting with those letters |
+
+#### Screen readers
+
+The `label` is wired to the trigger via `Field.Label`, so screen readers
+announce the field's purpose along with the selected value. When `error` or
+`invalid` is set, the field is announced as invalid; the `error` message is
+associated with the field so it is read after the label.
+
+#### Focus management
+
+Select exposes an imperative `ref.focus()` handle that moves focus to the
+trigger. Use it to implement focus-on-error in a form — for example, focusing
+the first invalid Select when the SP tries to submit.
+
+#### Touch targets
+
+On small screens (≤490px) the options open as a bottom sheet, so each item gets
+the vertical space needed to hit standard touch-target sizing. No per-item
+configuration required.
+
+## Related components
+
+* Use [LegacySelect](/components/LegacySelect) if you are working in an app that
+  has not yet migrated off the previous native `<select>`-based implementation.
+* Use [Autocomplete](/components/Autocomplete) when the list is long, needs
+  typeahead search, or when the user might type a value that isn't in the list.
+* Use [Menu](/components/Menu) when the choice triggers an action rather than
+  picking a value that persists in the form.
+* Use [RadioGroup](/components/RadioGroup) when the set of options is small
+  (roughly five or fewer) and it helps the SP to see all of them at once.
 
-* `Select.Group`: wraps a set of related options.
-* `Select.GroupLabel`: the section header text for a group.
-* `Select.Separator`: an optional visual divider. Adjacent `Select.Group`s are
-  already divided automatically, so reach for this only to divide options
-  elsewhere in the list.
 
 ## Component customization
 
@@ -298,16 +445,7 @@ than the full underlying API. The subcomponents (`Select.Item`, `Select.Group`,
 per-option styling; reach out to UXF if you need behaviour beyond what the props
 provide.
 
-### Controlled usage
-
-Select is controlled only. Always pass `value` and `onValueChange`; there is no
-uncontrolled `defaultValue`. The `id` and `name` are generated for you and wired
-to the label automatically.
-
-The change handler is named `onValueChange` to stay isomorphic with Base UI, and
-to encode the payload (the value, not an event) in its name.
-
-### Using with a form library
+## Using with a form library
 
 Select is form-library-agnostic — it exposes plain controlled props, so any
 system (React Hook Form, Formik, TanStack Form, or plain `useState`) drives it
@@ -364,11 +502,6 @@ const toValueField = ({ onChange, ...field }) => ({
 > prop and `Form`-driven focus-on-error do not reach Select. Drive validation
 > through the `error` / `invalid` props for now.
 
-## Related components
-
-* [LegacySelect](/components/LegacySelect): the previous native `<select>`-based
-  implementation.
-
 
 ## Props
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jobber/components-native",
-    "version": "0.113.3",
+    "version": "0.113.4",
     "license": "MIT",
     "description": "React Native implementation of Atlantis",
     "repository": {
@@ -124,5 +124,5 @@
         "react-native-screens": ">=4.18.0",
         "react-native-svg": ">=12.0.0"
     },
-    "gitHead": "895ad886700e1a7e11927702a0e5f49cb554c4e3"
+    "gitHead": "b151fce2d669e8b85cea91becf7d9aacee827c3e"
 }

package/dist/src/Button/Button.js

@@ -58,7 +58,7 @@ function getIconColorVariation(variation, type, disabled) {
         return "disabled";
     }
     if (type === "primary" && variation !== "cancel") {
-        return "white";
+        return "surface"; // This should be a text color token instead, but the action label also uses this
     }
     switch (variation) {
         case "learning":