@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/InputText/InputText.md

@@ -0,0 +1,324 @@
+# Input Text
+
+Input text is used in forms that accept short or long answers from users.
+
+## Design & usage guidelines
+
+### Controlled
+
+Use this to allow users to provide short answers.
+
+```tsx
+import React, { useState } from "react";
+import type { InputTextRebuiltProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export const ControlledExample = ({
+  onChange,
+  ...props
+}: Partial<InputTextRebuiltProps>) => {
+  const [age, setAge] = useState("Veintisiete");
+
+  return (
+    <InputText
+      version={2}
+      name="age"
+      placeholder="Age in words"
+      {...props}
+      value={age}
+      onChange={newValue => {
+        setAge(newValue);
+        onChange?.(newValue);
+      }}
+    />
+  );
+};
+```
+
+**Show code**
+
+### Multiline
+
+Use this to allow users to provide long answers. The default number of rows is
+three. Note that `loading={true}` is unimplemented for multiline input text.
+
+For web, you can set a minimum and maximum number of rows. See:
+[Web/rows example](/storybook/web/?path=/story/components-forms-and-inputs-inputtext--multiline).
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export function InputTextMultilineExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline">>,
+) {
+  return (
+    <InputText multiline={true} placeholder="Describe your age" {...props} />
+  );
+}
+```
+
+### Prefix/suffix
+
+Use a prefix or suffix when additional visual cues about an input's function may
+be helpful.
+
+Some fields have common visual patterns such as "search" having a magnifying
+glass icon, "Select" having a downwards arrow, or currency inputs having a
+currency symbol. These signifiers reinforce the purpose of the input to increase
+[Recognition over Recall](https://www.nngroup.com/articles/ten-usability-heuristics/)
+and align the input with
+[Consistency and Standards](https://www.nngroup.com/articles/ten-usability-heuristics/).
+With clearer guidance around the purpose of inputs, the user is able to better
+focus on the task at hand.
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+import { Content } from "@jobber/components/Content";
+
+export function InputTextPrefixSuffixExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <Content>
+      <InputText
+        defaultValue="1,000,000"
+        placeholder="Invoice Total"
+        prefix={{ label: "$", icon: "invoice" }}
+        suffix={{ label: ".00" }}
+        {...props}
+      />
+      <InputText
+        placeholder="Search"
+        prefix={{ icon: "search" }}
+        suffix={{
+          icon: "cross",
+          ariaLabel: "clear search",
+          onClick: () => alert("This could clear a search value"),
+        }}
+        {...props}
+      />
+    </Content>
+  );
+}
+```
+
+### Validation message
+
+You can add your own custom validation messages on a field to assist the user in
+successfully completing a form. This doesn't *replace* server-side validation,
+but minimizes the need for it as the user should be set up for success by proper
+guidance pre-submission before any "bad" data gets to the server.
+
+Follow the
+[product vocabulary](/content/product-vocabulary#component-view-general-phrasing)
+for guidance on writing helpful error messages.
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export function InputTextValidationExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <InputText
+      placeholder="What's your age"
+      validations={{
+        required: {
+          value: true,
+          message: "You have to tell us your age",
+        },
+        validate: val => {
+          if (val.length > 0 && !isNaN(val)) {
+            return "Type your age in words please.";
+          }
+
+          if (val.length >= 10) {
+            return "That seems too old.";
+          }
+
+          return true;
+        },
+      }}
+      {...props}
+    />
+  );
+}
+```
+
+## States
+
+### Disabled
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export function InputTextDisabledExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <InputText
+      placeholder="Credit card"
+      value="**** **** **** 1234"
+      disabled={true}
+      {...props}
+    />
+  );
+}
+```
+
+### Invalid
+
+For mobile, you can pass a string to the `invalid` prop to display an error.
+See:
+[Mobile/invalid example](/storybook/mobile/?path=/story/components-forms-and-inputs-inputtext--invalid).
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export function InputTextInvalidExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <InputText placeholder="Email" value="atlantis" invalid={true} {...props} />
+  );
+}
+```
+
+### External label
+
+You can use `FormFieldLabel` to provide a label outside of the input. The
+`showMiniLabel` prop on `InputText` can be used to hide the mini label that
+appears when a value is provided.
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+import { FormFieldLabel } from "@jobber/components/FormField";
+
+export function InputTextExternalLabelExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <div style={{ width: "100%" }}>
+      <FormFieldLabel external={true} htmlFor="ext-input">
+        External label
+      </FormFieldLabel>
+      <InputText
+        id="ext-input"
+        name="name"
+        clearable="always"
+        showMiniLabel={false}
+        {...props}
+      />
+    </div>
+  );
+}
+```
+
+### Keyboard
+
+Determine what default keyboard appears on mobile.
+
+```tsx
+import React from "react";
+import type { InputTextLegacyProps } from "@jobber/components/InputText";
+import { InputText } from "@jobber/components/InputText";
+
+export function InputTextKeyboardExample(
+  props: Partial<Omit<InputTextLegacyProps, "multiline" | "rows">>,
+) {
+  return (
+    <InputText placeholder="Describe your age" keyboard="numeric" {...props} />
+  );
+}
+```
+
+
+## Configuration
+
+### react-hook-form
+
+Atlantis utilizes [React Hook Form](https://react-hook-form.com/) to handle
+`input` and `form` validation. This means that the
+[React Hook Form validation options](https://react-hook-form.com/api#register)
+are available out of the box.
+
+This includes, but is not limited to:
+
+* `required` - A Boolean which, if true, indicates that the input must have a
+  value.
+* `maxLength` - The maximum length of the value to accept for this input.
+* `minLength` - The minimum length of the value to accept for this input.
+* `pattern` - The regex pattern for the input.
+* `validate` - You can pass a callback function as the argument to validate, or
+  you can pass an object of callback functions to validate all of them.
+
+### Using onValidation (Web)
+
+If you need to capture the error message and render it outside of the component.
+Read the [InputValidation](/components/InputValidation) documentation.
+
+### Version 2 Shim (Experimental)
+
+If you need to use the version 2 shim, you can pass `version={2}` to the
+`InputText` and provide the required props. Due to issues with typescript
+[see](https://github.com/microsoft/TypeScript/issues/32447) the aria attributes
+(and other props separated by `-`) are not typed correctly. This means that the
+shim will not enforce the version to be set to `2` when using these props. As a
+result version 1 usages will have these props appear in the intellisense but
+they will not do anything.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `accessibilityHint` | `string` | No | — | An accessibility hint helps users understand what will happen when they perform an action on the accessibility elemen... |
+| `accessibilityLabel` | `string` | No | — | VoiceOver will read this string when a user selects the associated element |
+| `assistiveText` | `string` | No | — | Text that helps the user understand the input |
+| `autoCapitalize` | `"characters" | "words" | "sentences" | "none"` | No | — | Determines where to autocapitalize |
+| `autoComplete` | `"name" | "additional-name" | "address-line1" | "address-line2" | "birthdate-day" | "birthdate-full" | "birthdate-month" | "birthdate-year" | "cc-csc" | "cc-exp" | "cc-exp-day" | ... 45 more ... | "off"` | No | — | Determines which content to suggest on auto complete, e.g.`username`. Default is `off` which disables auto complete  ... |
+| `autoCorrect` | `boolean` | No | — | Turn off autocorrect |
+| `autoFocus` | `boolean` | No | — | Automatically focus the input after it is rendered |
+| `clearable` | `Clearable` | No | — | Add a clear action on the input that clears the value.  You should always use `while-editing` if you want the input t... |
+| `defaultValue` | `string` | No | — | Default value for when component is uncontrolled |
+| `disabled` | `boolean` | No | — | Disable the input |
+| `invalid` | `string | boolean` | No | — | Highlights the field red and shows message below (if string) to indicate an error |
+| `keyboard` | `"default" | "numeric" | "phone-pad" | "email-address" | "numbers-and-punctuation" | "decimal-pad"` | No | — | Determines what keyboard is shown |
+| `loading` | `boolean` | No | — | Show loading indicator. |
+| `loadingType` | `"spinner" | "glimmer"` | No | — | Change the type of loading indicator to spinner or glimmer. |
+| `multiline` | `boolean` | No | — | Determines if inputText will span multiple lines. Default is `false`  https://reactnative.dev/docs/textinput#multiline |
+| `name` | `string` | No | — | Name of the input. |
+| `onBlur` | `(event?: FocusEvent) => void` | No | — | Callback that is called when the text input is blurred |
+| `onChangeText` | `(newValue: string) => void` | No | — | Simplified callback that only provides the new value @param newValue |
+| `onFocus` | `(event?: FocusEvent) => void` | No | — | Callback that is called when the text input is focused @param event |
+| `onSubmitEditing` | `(event?: SyntheticEvent<Element, Event>) => void` | No | — | Callback that is called when the text input's submit button is pressed @param event |
+| `placeholder` | `string` | No | — | Hint text that goes above the value once the field is filled out |
+| `prefix` | `{ icon?: IconNames; label?: string; }` | No | — | Symbol to display before the text input |
+| `readonly` | `boolean` | No | — | Makes the input read-only |
+| `ref` | `Ref<InputTextRef>` | No | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (... |
+| `secureTextEntry` | `boolean` | No | — | Use secure text entry |
+| `showMiniLabel` | `boolean` | No | `true` | Controls the visibility of the mini label that appears inside the input when a value is entered. By default, the plac... |
+| `spellCheck` | `boolean` | No | — | Determines whether spell check is used. Turn it off to hide empty autoCorrect suggestions when autoCorrect is off.  *... |
+| `styleOverride` | `InputTextStyleOverride` | No | — | Custom styling to override default style of the input text |
+| `suffix` | `{ icon?: IconNames; label?: string; onPress?: () => void; }` | No | — | Symbol to display after the text input |
+| `testID` | `string` | No | — | Used to locate this view in end-to-end tests |
+| `textContentType` | `"name" | "none" | "nickname" | "password" | "username" | "URL" | "addressCity" | "addressCityAndState" | "addressState" | "countryName" | "creditCardNumber" | "creditCardExpiration" | ... 33 more ... | "shipmentTrackingNumber"` | No | — | Determines which content to suggest on auto complete, e.g.`username`. Default is `none` which disables auto complete ... |
+| `toolbar` | `ReactNode` | No | — | Add a toolbar below the input field for actions like rewriting the text. |
+| `toolbarVisibility` | `"while-editing" | "always"` | No | — | Change the behaviour of when the toolbar becomes visible. |
+| `transform` | `{ input?: (v: any) => string; output?: (v: string) => any; }` | No | — | transform object is used to transform the internal TextInput value It's useful for components like InputNumber where ... |
+| `validations` | `RegisterOptions` | No | — | Shows an error message below the field and highlight the field red when value is invalid |
+| `value` | `string` | No | — | Set the component to a given value |

package/dist/docs/InputTime/InputTime.md

@@ -0,0 +1,54 @@
+# Input Time
+
+The InputTime component is a text input that allows the user to enter a time
+value.
+
+## Design & usage guidelines
+
+This component obeys the system locale settings to determine 24 or 12 hour time.
+
+### States
+
+A
+[disabled](/storybook/web/?path=/story/components-forms-and-inputs-inputtime--disabled)
+state will be visually muted and the input will not be editable. This is similar
+to the
+[read-only](/storybook/web/?path=/story/components-forms-and-inputs-inputtime--read-only)
+state, but the input is not muted.
+
+An
+[invalid](/storybook/web/?path=/story/components-forms-and-inputs-inputtime--invalid)
+state will indicate that the input is not valid. This can be used when the input
+is required and the user has not entered a value.
+
+
+## Controlled & Uncontrolled
+
+### Controlled component
+
+Web's
+[Controlled](/storybook/web/?path=/story/components-forms-and-inputs-inputtime--controlled)
+version includes a type-ahead feature where typing at least 1 number
+automatically fills in the rest of the time. For example, typing `2` will fill
+in `2:00 PM` and typing `1` waits for a few milliseconds in case the user wants
+to type `10`, `11`, or `12`.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `clearable` | `"never" | "always"` | No | — | Defaulted to "always" so user can clear the time whenever there's a value. |
+| `disabled` | `boolean` | No | — | Disable the input |
+| `emptyValueLabel` | `string` | No | `undefined` | Add a custom value to display when no time is selected |
+| `invalid` | `string | boolean` | No | — | Highlights the field red and shows message below (if string) to indicate an error |
+| `name` | `string` | No | — | Adding a `name` would make this component "Form controlled" and must be nested within a `<Form />` component.  Cannot... |
+| `onChange` | `((value?: Date) => void) | ((value?: Date) => void)` | No | — | The callback that fires whenever a time gets selected. |
+| `placeholder` | `string` | No | — | Hint text that goes above the value once the field is filled out |
+| `showIcon` | `boolean` | No | — | Hide or show the timer icon. |
+| `showMiniLabel` | `boolean` | No | `true` | Controls the visibility of the mini label that appears inside the input when a value is entered. By default, the plac... |
+| `type` | `"granular" | "scheduling"` | No | `scheduling` | Adjusts the UX of the time picker based on where you'd use it.  - `"granular"` - allows the user to pick a very speci... |
+| `validations` | `Omit<RegisterOptions<FieldValues, string>, "disabled" | "valueAsNumber" | "valueAsDate" | "setValueAs">` | No | — | Shows an error message below the field and highlights it red when the value is invalid. Only applies when nested with... |
+| `value` | `string | Date` | No | — | The value shown on the field. This gets automatically formatted to the account's time format. |

package/dist/docs/Opacity/Opacity.md

@@ -0,0 +1,12 @@
+# Opacity
+
+Opacity is used to adjust the transparency of an element.
+
+These tokens should be used for particular instances where the transparency of
+an element needs to be altered when pressed, or to modify the transparency of an
+overlay.
+
+| Opacity             | Visual | Value |
+| :------------------ | :----- | :---- |
+| `--opacity-overlay` |        | 0.8   |
+| `--opacity-pressed` |        | 0.6   |

package/dist/docs/ProgressBar/ProgressBar.md

@@ -0,0 +1,39 @@
+# Progress Bar
+
+A ProgressBar is a visual indicator of how close something is to completion.
+
+## Design & usage guidelines
+
+The ProgressBar should be used to show "definite" progress; we know exactly how
+close the process is to completion. For "indefinite" progress, where we may not
+know exactly how much longer something might take, use a
+[Spinner](/components/Spinner).
+
+Some great use cases for a ProgressBar include:
+
+* Setup wizard, where we know how many steps the user has completed and how many
+  steps remain.
+* File uploads, where we know the total file size and how much data has already
+  been sent.
+
+An example where you might be better served using a Spinner:
+
+* Loading a calendar within a view, where we do not know it's "complete" until
+  there's no more data left to load.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `current` | `number` | Yes | — | The number of items that are currently completed |
+| `total` | `number` | Yes | — | The total number of items to be completed |
+| `header` | `ReactNode` | No | — | Component to render above the progress bar. |
+| `inProgress` | `number` | No | `0` | The number of items in progress (not completed, but to be less than the total); not applicable with stepped variation |
+| `loading` | `boolean` | No | — | If the progress bar is loading, the progress indicators aren't rendered on the screen |
+| `reverseTheme` | `boolean` | No | `false` | If the amountFormatted and totalAmountFormatted text needs to appear more visibile because of the background, for exa... |
+| `size` | `"smaller" | "small" | "base"` | No | `base` | Set the size of the progress bar |
+| `UNSAFE_style` | `ProgressBarUnsafeStyle` | No | — | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |
+| `variation` | `"progress" | "stepped"` | No | `progress` | Set the variation of the progress bar |

package/dist/docs/Radii/Radii.md

@@ -0,0 +1,23 @@
+# Border Radius
+
+This base radius can be found in almost all of our components that have a
+defined "edge": [Button](../Button/Button.md), [Card](../Card/Card.md),
+[InputText](../InputText/InputText.md), and [Menu](/components/Menu) are all
+examples of this in practice.
+
+If an element is nested directly inside of a container with the base radius, or
+is itself smaller than the base radius, the small radius may be applied.
+
+Larger rounded corners should be used sparingly, but are available for cases
+where the user may expect a smoother corner, such as
+[ProgressBar](../ProgressBar/ProgressBar.md). `--radius-circle` can be used for
+circular elements like [Radio](/components/RadioGroup) options or the "pip" in
+[Switch](../Switch/Switch.md).
+
+| Radius            | Visual |
+| :---------------- | :----- |
+| `--radius-small`  |        |
+| `--radius-base`   |        |
+| `--radius-large`  |        |
+| `--radius-larger` |        |
+| `--radius-circle` |        |

package/dist/docs/ResponsiveBreakpoint/ResponsiveBreakpoint.md

@@ -0,0 +1,74 @@
+# Responsive Breakpoints
+
+We have 3 different ways to deal with responsive breakpoints in our components.
+
+1. CSS variables (`@custom-media`) that are relative to the browser size.
+2. [`useBreakpoints` hook](/hooks/useBreakpoints) that is the JS counterpart of
+   the CSS variables.
+3. [`useResizeObserver` hook](/hooks/useResizeObserver) that is used to make
+   components responsive depending on the size of its container rather than the
+   browser.
+
+## CSS variables
+
+We have 5 CSS breakpoints that you can choose from when styling your components.
+
+| Breakpoint                     | Width       |
+| :----------------------------- | :---------- |
+| `--small-screens-and-below`    | `< 490px`   |
+| `--small-screens-and-up`       | `>= 490px`  |
+| `--medium-screens-and-up`      | `>= 768px`  |
+| `--large-screens-and-up`       | `>= 1080px` |
+| `--extra-large-screens-and-up` | `>= 1440px` |
+
+### Usage
+
+Components should be styled mobile-first, meaning that they should be styled for
+small screens and then scaled up. This means that the
+`--small-screens-and-below` breakpoint should be rarely considered.
+
+Media queries can also be nested inside selectors. This will help with clarity
+when reading your CSS.
+
+```css
+.foo {
+  /** small screens first **/
+  padding: var(--space-base);
+
+  @media (--medium-screens-and-up) {
+    padding: var(--space-large);
+  }
+
+  @media (--large-screens-and-up) {
+    padding: var(--space-extravagant);
+  }
+}
+```
+
+#### Caveat
+
+We use [custom-media](https://www.w3.org/TR/mediaqueries-5/#custom-mq) that
+creates a CSS variable-like pattern for media queries. It isn't widely supported
+yet so you'd have to install
+[postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media) on
+your compiler to transform them back to normal media queries.
+
+### Deprecated breakpoints
+
+| Breakpoint         | Width       |
+| :----------------- | :---------- |
+| `--handhelds`      | `< 640px`   |
+| `--medium-screens` | `>= 640px`  |
+| `--wide-screens`   | `>= 1024px` |
+
+## 2. useBreakpoints hook
+
+This closely mimics the CSS breakpoints but you can use within a JS code. Read
+more about useBreakpoints [here](/hooks/useBreakpoints).
+
+## 3. useResizeObserver hook
+
+To make components responsive depending on the size of its container rather than
+the browser, you should use the
+[useResizeObserver hook](/hooks/useResizeObserver) so that the component can be
+responsive based on its container.