@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/Select/Select.md

@@ -0,0 +1,213 @@
+# Select
+
+A Select is used to present a defined list of options to choose from.
+
+## Design & usage guidelines
+
+Nested within the Select component, Option defines the options that can be
+selected. For grouping options with section headers, use Select.OptionGroup.
+
+#### Custom grouped menu and browser support
+
+V2 remains a native `<select>` by default. To enable the enhanced grouped menu
+styling (bold section headers, edge‑to‑edge dividers and hover backgrounds), set
+the `UNSAFE_experimentalStyles` prop on `Select`.
+
+* When `UNSAFE_experimentalStyles` is true and the browser supports
+  `appearance: base-select` (Chromium 123+), the select renders with the
+  customizable grouped menu.
+* In unsupported browsers, or when `UNSAFE_experimentalStyles` is not provided,
+  the select remains native while still rendering the same `OptionGroup`
+  structure.
+
+#### Option Props
+
+#### OptionGroup Props
+
+## States
+
+### Invalid
+
+```tsx
+import React from "react";
+import { Option, Select } from "@jobber/components/Select";
+
+export function SelectInvalidExample() {
+  return (
+    <Select invalid={true}>
+      <Option value="sad">Tony</Option>
+      <Option value="old">Steve</Option>
+    </Select>
+  );
+}
+```
+
+### Disabled
+
+```tsx
+import React from "react";
+import { Option, Select } from "@jobber/components/Select";
+
+export function SelectDisabledExample() {
+  return (
+    <Select disabled={true}>
+      <Option value="sad">Tony</Option>
+      <Option value="old">Steve</Option>
+    </Select>
+  );
+}
+```
+
+## Option Grouping
+
+Use `Select.OptionGroup` to organize options with section headers for better
+user experience and visual hierarchy. The `label` prop is required as it
+provides the section header text.
+
+### Basic Option Groups
+
+```tsx
+import React from "react";
+import { Select } from "@jobber/components/Select";
+
+export function SelectCustomOptionGroupsExample() {
+  return (
+    <Select
+      placeholder="Select an option"
+      version={2}
+      UNSAFE_experimentalStyles={true}
+    >
+      <Select.OptionGroup label="Team A">
+        <Select.Option value="alice">Alice</Select.Option>
+        <Select.Option value="bob">Bob</Select.Option>
+        <Select.Option value="charlie">Charlie</Select.Option>
+      </Select.OptionGroup>
+      <Select.OptionGroup label="Team B">
+        <Select.Option value="diana">Diana</Select.Option>
+        <Select.Option value="evan">Evan</Select.Option>
+        <Select.Option value="frank">Frank</Select.Option>
+      </Select.OptionGroup>
+      <Select.OptionGroup label="Team C">
+        <Select.Option value="grace">Grace</Select.Option>
+        <Select.Option value="hector">Hector</Select.Option>
+        <Select.Option value="isabel">Isabel</Select.Option>
+      </Select.OptionGroup>
+    </Select>
+  );
+}
+```
+
+### Disabled Option Groups
+
+```tsx
+import React from "react";
+import { Select } from "@jobber/components/Select";
+
+export function SelectCustomOptionGroupDisabledExample() {
+  return (
+    <Select
+      version={2}
+      UNSAFE_experimentalStyles
+      placeholder="Select an option"
+    >
+      <Select.OptionGroup label="Available Items">
+        <Select.Option value="option1">Option 1</Select.Option>
+        <Select.Option value="option2">Option 2</Select.Option>
+      </Select.OptionGroup>
+      <Select.OptionGroup label="Unavailable Items" disabled>
+        <Select.Option value="option3">Option 3</Select.Option>
+        <Select.Option value="option4">Option 4</Select.Option>
+      </Select.OptionGroup>
+      <Select.OptionGroup label="More Items">
+        <Select.Option value="option5">Option 5</Select.Option>
+        <Select.Option value="option6">Option 6</Select.Option>
+      </Select.OptionGroup>
+    </Select>
+  );
+}
+```
+
+
+## Configuration
+
+### Custom (Chromium) vs native
+
+Select (V2) is native by default. Opt into the customizable Chrome UI with
+`UNSAFE_experimentalStyles`. This enhances grouped menus in Chromium 123+ when
+the browser supports `appearance: base-select`.
+
+#### Alignment limitation (custom UI)
+
+When using `UNSAFE_experimentalStyles`, the closed control (what you see as the
+displayed value) is still rendered by the browser's picker. As a result,
+right/center alignment of the displayed value is not configurable in Chromium's
+customizable select.
+
+* Need right/center alignment? Use the native Select (omit
+  `UNSAFE_experimentalStyles`).
+* You can still style the grouped dropdown (optgroup/option) in the custom UI,
+  but the closed value alignment will remain default.
+
+## Component customization
+
+### Composable usage
+
+Select supports composition via subcomponents:
+
+* `Select.Option`: item in the list. Provide `value` and children as the label.
+* `Select.OptionGroup`: group options under a `label`. Use with
+  `UNSAFE_experimentalStyles` to opt into the customizable grouped menu in
+  Chromium.
+
+#### Customization links
+
+* See
+  ["A customizable select"](https://developer.chrome.com/blog/a-customizable-select)
+  article for what the Chrome UI exposes: `::picker(select)`, option/optgroup
+  styling, and transitions.
+
+## UNSAFE\_ props (advanced usage)
+
+General guidance on `UNSAFE_` props can be found in
+[Customizing components](../customizing-components/customizing-components.md).
+
+Select subcomponents allow `UNSAFE_className` and `UNSAFE_style` to target the
+native elements:
+
+* `Select.OptionGroup` maps to `<optgroup>`
+* `Select.Option` maps to `<option>`
+
+Note that native `<select>` UX differs per browser. Use `UNSAFE_` props with
+caution and test across environments. In the custom UI (Chromium), only the
+dropdown content is stylable; the closed value alignment is not.
+
+
+## Props
+
+### Mobile
+
+#### Select
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactElement<SelectOption, string | JSXElementConstructor<any>>[]` | Yes | — | The options to select from |
+| `accessibilityHint` | `string` | No | — | Helps users understand what will happen when they perform an action |
+| `accessibilityLabel` | `string` | No | — | VoiceOver will read this string when a user selects the element |
+| `assistiveText` | `string` | No | — | Help text shown below the control. |
+| `defaultValue` | `string` | No | — | Default value for when the component is uncontrolled |
+| `disabled` | `boolean` | No | — | Disables input selection |
+| `invalid` | `boolean` | No | — | Indicates the current selection is invalid |
+| `label` | `string` | No | — | Label text shown above the selection. |
+| `name` | `string` | No | — | Name of the input. |
+| `onChange` | `(newValue?: string) => void` | No | — | Callback that provides the new value when the selection changes |
+| `placeholder` | `string` | No | — | Adds a first option to let users select a "no value". Placeholder item selected by default until a selection is made. |
+| `testID` | `string` | No | — | Used to locate this view in end-to-end tests. |
+| `validations` | `RegisterOptions` | No | — | The validations that will mark this component as invalid |
+| `value` | `string` | No | — | Current value of the component |
+
+#### Option
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `string` | Yes | — | Text that shows up as the option |
+| `value` | `string` | Yes | — | The value that gets returned when an option is selected |

package/dist/docs/Spacing/Spacing.md

@@ -0,0 +1,103 @@
+# Spacing
+
+Our spacing system exists to support the foundational visual design principle of
+[proximity-based grouping:](https://www.nngroup.com/articles/gestalt-proximity/)
+
+> Using varying amounts of whitespace to either unite or separate elements is
+> key to communicating meaningful groupings.
+
+In the shortest, simplest terms: the closer two elements are related, the
+tighter the spacing between them should be.
+
+With this in mind, let's start small and work our way up.
+
+## Design & usage guidelines
+
+### Minuscule and Smallest
+
+At their respective sizes (`1px` and `2px` equivalent), these values should
+mostly be used to provide optical adjustments where an element is visually
+misaligned.
+
+### Smaller
+
+The `smaller` spacing value can be used between contents of a single component.
+For example, see the spacing between an Icon and the label inside of a
+[Button.](../Button/Button.md)
+
+### Small
+
+Sibling items within a container can be separated by the `small` value to
+reflect their relation to each other. An example would be the spacing between
+[Chips in a selection group.](/components/Chips)
+
+### Slim
+
+Use `slim` spacing when you don't quite need a `small` space, but `base` is just
+too much. This is often useful for optically balancing the internal padding of a
+UI element.
+
+### Base
+
+Use `base` as the default spacing in larger content containers with multiple
+children of their own, such as [Card.](../Card/Card.md)
+
+`Base` should also be used as the default starting point for spacing
+form elements.
+
+### Large
+
+Use `large` spacing for higher-level "parent" containers.
+[Modal](/components/Modal) uses `large` spacing in its header and around the
+edges to give itself a bit more prominence as a standalone view, in a similar
+manner to [Page](/components/Page).
+
+`Large` can also be used to help give a "floating" element some clear separation
+from the edge of the viewport, as seen in [Toast](../Toast/Toast.md).
+
+### Larger
+
+`Larger` doubles the value of `base` to very clearly delineate two groups of
+content. It can be useful if you have a long list of mixed content types that
+need to be broken up.
+
+### Largest
+
+`Largest` is useful for giving content-rich containers ample breathing room to
+create hierarchy. When the parent has such generous spacing, it allows for the
+children to leverage a broader range of techniques for grouping amongst
+themselves.
+
+### Extravagant
+
+`Extravagant` is used infrequently in Jobber’s web and mobile applications, but
+can be useful for lower-density consumer applications like websites.
+
+***
+
+## Implementation
+
+### Content
+
+Use the [Content component](../Content/Content.md) for any instances where you
+need uniform spacing between elements.
+
+Content can set its spacing to any of the spacing token values; follow the
+guidelines above as needed.
+
+### Values
+
+You can use spacing tokens directly in your stylesheets using the values below.
+
+| Name                  | Visual | Value |
+| :-------------------- | :----- | :---- |
+| `--space-minuscule`   |        |       |
+| `--space-smallest`    |        |       |
+| `--space-smaller`     |        |       |
+| `--space-small`       |        |       |
+| `--space-slim`        |        |       |
+| `--space-base`        |        |       |
+| `--space-large`       |        |       |
+| `--space-larger`      |        |       |
+| `--space-largest`     |        |       |
+| `--space-extravagant` |        |       |

package/dist/docs/StatusLabel/StatusLabel.md

@@ -0,0 +1,119 @@
+# Status Label
+
+The StatusLabel component is a visual component that allows users to quickly
+determine the status of an item (e.g., "Active", "Overdue").
+
+## Design & usage guidelines
+
+StatusLabel is a more opinionated version of
+[InlineLabel](/components/InlineLabel) and offers only 5 possible status
+representations:
+
+### Success
+
+Convey that an item is in a successful state, such as approved or paid.
+
+### Critical
+
+Alert the user to a critically important issue such as a late appointment or an
+overdue payment.
+
+### Warning
+
+Warn the user of a potential forthcoming issue like an upcoming deadline or an
+item awaiting response.
+
+### Informative
+
+Inform the user about something that may not require action, such as a quote
+that has already been converted into a job.
+
+### Inactive
+
+Signify that an item has been archived, closed, or otherwise removed from an
+active workflow.
+
+```tsx
+import React from "react";
+import { Content } from "@jobber/components/Content";
+import { StatusLabel } from "@jobber/components/StatusLabel";
+
+export function StatusLabelAllStatusesExample() {
+  return (
+    <Content>
+      <StatusLabel label="Success" status="success" alignment="start" />
+      <StatusLabel label="Critical" status="critical" alignment="start" />
+      <StatusLabel label="Informative" status="informative" alignment="start" />
+      <StatusLabel label="Warning" status="warning" alignment="start" />
+      <StatusLabel label="Inactive" status="inactive" alignment="start" />
+    </Content>
+  );
+}
+```
+
+### Alignment
+
+Align the color indicator with the start or end of a layout as needed.
+
+For example, in a [List](/components/List) where the StatusLabel is on the
+right, use the `end` alignment.
+
+```tsx
+import React from "react";
+import { StatusLabel } from "@jobber/components/StatusLabel";
+
+export function StatusLabelAlignmentExample() {
+  return (
+    <div style={{ display: "flex", justifyContent: "space-between" }}>
+      <StatusLabel label="Start" status="inactive" alignment="start" />
+      <StatusLabel label="End" status="inactive" alignment="end" />
+    </div>
+  );
+}
+```
+
+## Related components
+
+[InlineLabel](/components/InlineLabel) is a more generic badging element that
+can be used in non-"status"-y ways
+
+* counts
+* trends
+* tags
+* labels that need to be distinguished from other typographic content
+
+## Content guidelines
+
+StatusLabel does not accept any child content. It presents only a text-based
+label describing the status, and a visual color indicator to reinforce the
+status.
+
+The label should be short, ideally no longer than two words.
+
+## Accessibility
+
+The StatusLabel has a `role` of `status` which is communicated to assistive
+technology. It does not pull focus to itself but informs the user of its'
+purpose.
+
+The label portion of StatusLabel should be readable by assistive technology.
+
+The color indicator is always used with a text label so that color is not the
+only method of communicating status.
+
+## Responsiveness
+
+StatusLabel should "hug" it's contents, but otherwise grow as long as needed in
+the available space. If StatusLabel's label is longer than the space available,
+the label should wrap.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `text` | `string` | Yes | — | Text to display. |
+| `alignment` | `"start" | "end"` | No | `end` | Alignment of text |
+| `status` | `StatusType` | No | `success` | Status color of the square beside text |

package/dist/docs/Switch/Switch.md

@@ -0,0 +1,54 @@
+# Switch
+
+A Switch toggles the state of a single setting to on or off.
+
+## Design & usage guidelines
+
+The Switch is a useful component for manipulating settings with binary
+(true/false, yes/no, on/off) conditions. For this reason its' label is limited
+to ON/OFF.
+
+### Disabled
+
+A disabled switch cannot be operated by the user. If presenting a disabled "On"
+switch to the user, provide a clear description for the user on how to enable
+the switch to avoid creating a sense that the user has lost control of the
+interface.
+
+```tsx
+import React from "react";
+import { Switch } from "@jobber/components/Switch";
+
+export function SwitchDisabledExample() {
+  return (
+    <Switch value={false} ariaLabel="Visible to clients" disabled={true} />
+  );
+}
+```
+
+### Related components
+
+A Switch, a [Checkbox](../Checkbox/Checkbox.md), and a pair of
+[RadioButton](/components/RadioGroup) can seem similar in theory, as all can
+represent an `either/or decision` for the user.
+
+Use a Switch when the user must make a decision to turn something on or off, and
+a single Checkbox when a user is opting in to a choice. A pair of RadioButtons
+can be used to help the user decide between two discrete options, such as "fixed
+price" and "per visit" invoicing options.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `accessibilityLabel` | `string` | No | — | Accessibility label for this switch |
+| `defaultValue` | `boolean` | No | — | Default value of the switch when uncontrolled |
+| `description` | `string` | No | — | Optional descriptive text to display under the switch |
+| `disabled` | `boolean` | No | — | When true, the switch cannot be toggled |
+| `label` | `string` | No | — | Optional label to display in front of the switch |
+| `name` | `string` | No | — | Name of the input. |
+| `onValueChange` | `(val: boolean) => void` | No | — | Callback to handle value changes |
+| `value` | `boolean` | No | — | Value of the switch |