@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/Chip/Chip.md

@@ -0,0 +1,371 @@
+# Chip
+
+Chip is a flexible component that can be used for
+
+* inline single- or multi-selection of items
+* triggering filtering and selection components like
+  [Combobox](/components/Combobox)
+* presenting grouped items that can be added or removed
+
+```tsx
+import type { ComponentProps } from "react";
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Avatar } from "@jobber/components/Avatar";
+import { Icon } from "@jobber/components/Icon";
+
+export function ChipWithAvatarExample(
+  props: Partial<ComponentProps<typeof Chip>>,
+) {
+  return (
+    <Chip label="Gavin Messina" {...props}>
+      <Chip.Prefix>
+        <Avatar
+          size="small"
+          imageUrl="https://images.unsplash.com/photo-1669475535925-a011d7c31d45?q=80&w=1886&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
+        />
+      </Chip.Prefix>
+      <Chip.Suffix>
+        <Icon name="cross" size="small" />
+      </Chip.Suffix>
+    </Chip>
+  );
+}
+```
+
+## Design & usage guidelines
+
+See the
+[Comparison story](/storybook/web/?path=/story/components-selections-chip-comparisons--all)
+for a full overview of potential Chip variants.
+
+### Variations
+
+The base variation of Chip should be used in most cases. When a lighter-weight
+approach is desired, use the subtle variation.
+
+```tsx
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Flex } from "@jobber/components/Flex";
+
+export function ChipVariationsExample() {
+  return (
+    <Flex template={["shrink", "shrink"]} direction="row" gap="small">
+      <Chip label="Base" />
+      <Chip label="Subtle" variation="subtle" />
+    </Flex>
+  );
+}
+```
+
+### Selection
+
+Chip allows users to make selections in scenarios where space is at a premium.
+It has three high-level usages: single-select, multi-select, and add/dismiss
+selection.
+
+#### Single-select
+
+If you need the user to make a selection of a single item from among several
+items, and those items all have short (1–2 word) labels, single-select Chips
+will allow the user to choose one of those items.
+
+This preserves vertical space while allowing the user to clearly identify which
+item they have selected.
+
+Unlike [Radio](/components/RadioGroup), the selected single-select Chip can be
+de-selected by the user, leaving all selections blank.
+
+```tsx
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Flex } from "@jobber/components/Flex";
+import { Icon } from "@jobber/components/Icon";
+
+export function ChipSingleSelectExample() {
+  return (
+    <Flex
+      template={["shrink", "shrink", "shrink", "shrink"]}
+      direction="row"
+      gap="small"
+    >
+      <Chip label="Option 1" variation="subtle" />
+      <Chip label="Option 2">
+        <Chip.Suffix>
+          <Icon name="checkmark" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 3" variation="subtle" />
+      <Chip label="Option 4" variation="subtle" />
+    </Flex>
+  );
+}
+```
+
+#### Multi-select
+
+If you need the user to make a selection of one *or more* items from amongst
+several items, and those items all have short (1–2 word) labels, a multi-select
+Chips will allow the user to choose as many items from the group as they wish.
+
+This preserves vertical space while allowing the user to clearly identify which
+items they have selected. To signify to the user that multiple selections are
+possible, a checkmark icon is present to reinforce the conceptual similarity to
+a [Checkbox](../Checkbox/Checkbox.md).
+
+Similar to Checkbox, a selected multi-select Chip can be de-selected by the
+user, leaving all selections blank.
+
+```tsx
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Flex } from "@jobber/components/Flex";
+import { Icon } from "@jobber/components/Icon";
+
+export function ChipMultiSelectExample() {
+  return (
+    <Flex
+      template={["shrink", "shrink", "shrink", "shrink"]}
+      direction="row"
+      gap="small"
+    >
+      <Chip label="Option 1">
+        <Chip.Suffix>
+          <Icon name="checkmark" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 2">
+        <Chip.Suffix>
+          <Icon name="checkmark" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 3" variation="subtle" />
+      <Chip label="Option 4">
+        <Chip.Suffix>
+          <Icon name="checkmark" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+    </Flex>
+  );
+}
+```
+
+#### Add/dismiss selection
+
+When the user will be selecting one or more items by inputting their own Chip
+options, use a dismissible Chip. Think of a case like team assignment, where the
+user can add multiple users represented as Chips, and click on the dismiss
+suffix of the Chip to remove a user.
+
+The dismissible Chip allows them to remove previous selections from the Chips.
+Use this option when the full list of possible selections is too great to
+reasonably display in one group of Chip. For example, "all of my phone contacts"
+would be far too many Chip options to present in one group, and would be
+overwhelming for the user to interpret.
+
+```tsx
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Flex } from "@jobber/components/Flex";
+import { Icon } from "@jobber/components/Icon";
+
+export function ChipAddDismissExample() {
+  return (
+    <Flex
+      template={["shrink", "shrink", "shrink", "shrink", "shrink"]}
+      direction="row"
+      gap="small"
+    >
+      <Chip label="Add" variation="subtle">
+        <Chip.Suffix>
+          <Icon name="add" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 1">
+        <Chip.Suffix>
+          <Icon name="cross" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 2">
+        <Chip.Suffix>
+          <Icon name="cross" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 3">
+        <Chip.Suffix>
+          <Icon name="cross" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+      <Chip label="Option 4">
+        <Chip.Suffix>
+          <Icon name="cross" size="small" color="interactiveSubtle" />
+        </Chip.Suffix>
+      </Chip>
+    </Flex>
+  );
+}
+```
+
+### Invalid
+
+If something goes awry with a selection or you otherwise need to convey to the
+user that something's gone wrong in relation to the Chip, you can use the
+invalid state.
+
+```tsx
+import type { ComponentProps } from "react";
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Icon } from "@jobber/components/Icon";
+
+export function ChipInvalidExample(
+  props: Partial<ComponentProps<typeof Chip>>,
+) {
+  return (
+    <Chip label="Select team" invalid {...props}>
+      <Chip.Prefix>
+        <Icon name="alert" size="small" />
+      </Chip.Prefix>
+    </Chip>
+  );
+}
+```
+
+## Related components
+
+* [Chips](/components/Chips) is a convenience wrapper that offers the
+  single-select, multi-select, and add/dismiss functionality "out of the box"
+* [Combobox](/components/Combobox) is most commonly triggered by a Chip, but is
+  a separate component
+* [Select](../Select/Select.md) is a simpler single-select "dropdown" that
+  presents as a form element and should be preferred in forms
+* [RadioGroup](/components/RadioGroup) should be used to allow the user to
+  select "one-of-many" items (single-select) and the labels for the items are
+  longer than 1 or 2 words.
+* [Checkbox](../Checkbox/Checkbox.md) should be used to allow the user to select
+  "one-or-more-of-many" items (multi-select) and the labels for the items are
+  longer than 1 or 2 words.
+* [InlineLabel](/components/InlineLabel) should be used when you just need a
+  rounded-rectangular element that displays metadata about an element
+
+## Content guidelines
+
+Chip headings and labels for single- or multi-select should be succinct -
+ideally 1–2 words. If any of the options in the group may have longer labels,
+consider Checkbox or Radio as necessary for your selection type.
+
+In cases where a Chip displays name of its selections, such as when used to
+trigger a Combobox or a date range selector, use the heading to identify the
+"category" and the label to identify the selected items.
+
+## Accessibility
+
+Chips should convey to the user whether it is a "checkbox" or "radio" element
+based on single or multi-select. The Chips in this group have the appropriate
+roles and keyboard operation to allow the user to interact as though they are
+dealing with a checkbox or radio button.
+
+If Chips is set for add/dismiss selections, the dismiss button should notify the
+user that they will "dismiss {label name}" upon press.
+
+## Responsiveness
+
+The Chips themselves will take up as much space as their container allows, and
+the Chips will flow left to right. Chips may re-flow into new rows, or scroll
+out of view in a single row, depending on your use case.
+
+Chip can truncate if its' container is limited in space, but does not inherently
+cap its own width and will default to "hug" its contents.
+
+
+## Configuration
+
+### Chip.Prefix
+
+When `Chip.Prefix` is provided with an Icon or Avatar as its immediate child,
+default markup and styles are automatically applied. If these styles and markup
+are not desired, or if you would like to provide your own child, you should
+provide your own wrapper element and layout.
+
+```tsx
+import React from "react";
+import { Chip } from "@jobber/components/Chip";
+import { Box } from "@jobber/components/Box";
+import { Icon } from "@jobber/components/Icon";
+import { Text } from "@jobber/components/Text";
+import { StatusLabel } from "@jobber/components/StatusLabel";
+
+export function ChipPrefixConfigExample() {
+  return (
+    <Box direction="column" gap="base">
+      <Box direction="row" alignItems="center" gap="base">
+        <Chip label="Select team">
+          <Chip.Prefix>
+            <Icon name="person" size="small" />
+          </Chip.Prefix>
+        </Chip>
+        <Text>Default styling</Text>
+      </Box>
+      <Box direction="row" alignItems="center" gap="large">
+        <Chip label="Select team">
+          <Chip.Prefix>
+            <div style={{ display: "flex", marginRight: 20 }}>
+              <Icon name="person" size="small" />
+            </div>
+          </Chip.Prefix>
+        </Chip>
+        <Text>Custom wrapper around Icon to add larger margin</Text>
+      </Box>
+      <Box direction="row" alignItems="center" gap="base">
+        <Chip label="Select team">
+          <Chip.Prefix>
+            <div style={{ display: "flex", marginRight: 15 }}>
+              <StatusLabel status="success" label="Ready" />
+            </div>
+          </Chip.Prefix>
+        </Chip>
+        <Text>Custom wrapper around child</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Component customization
+
+### Base Chip Color Overrides
+
+If you wish to modify the colors of the Base variant, you may do so with CSS
+custom properties (variables).
+
+For the resting background color: `--public-chip-base-bg-color`
+
+For the hover/focused background color: `--public-chip-base-hover-bg-color`
+
+For the text content and miscellaneous content such as the line separator
+between the `label` and `heading`: `--public-chip-base-content-color`
+
+## Developer notes
+
+Chip is in the process of being applied to the more opinionated Chips
+convenience wrapper, but by design does not carry the same level of "out of the
+box" functionality as it is a more "atomic" element that can be used outside of
+those more complex selection flows.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `isActive` | `boolean` | Yes | — | chip's active status |
+| `accent` | `AccentType` | No | — | Background color to be used for Active chips |
+| `accessibilityLabel` | `string` | No | — | Accessibility label for the component. It's also used for testing |
+| `accessibilityRole` | `AccessibilityRole` | No | `radio` | Accessibility role for the component |
+| `icon` | `IconNames` | No | — | Optional Icon |
+| `inactiveBackgroundColor` | `"surface" | "background"` | No | `background` | Background color to be used for inactive chips |
+| `isDismissible` | `boolean` | No | — | Boolean for chip's ability to be dismissed |
+| `label` | `string` | No | — | label of the chip. |
+| `onPress` | `() => void` | No | — | Press handler |

package/dist/docs/Colors/Colors.md

@@ -0,0 +1,217 @@
+# Colors
+
+Color can provide a visual cue for users to navigate and understand an
+interface.
+
+Atlantis is built with a
+[semantic layer](https://dev.to/ynab/a-semantic-color-system-the-theory-hk7)
+overtop of a base palette. Use the semantic color values defined in the usage
+guidelines whenever possible to ensure you are using colors for their intended
+purpose.
+
+## Accessibility
+
+Color should never be the single means of conveying information in an interface.
+Use labels, iconography, or hints for assistive technology alongside color to
+ensure your content can be understood by everyone.
+
+## Color Token Search
+
+## Design & usage guidelines
+
+### Typography
+
+Typographic elements in Jobber should use consistent colors to ensure
+readability.
+
+#### Heading
+
+Headings have a bold, high-contrast color to cement their hierarchy.
+
+#### Text
+
+A slightly softer color is used for body text for greater readability.
+
+Text that is relevant but less important ("secondary") can be lower-contrast to
+suggest its' reduced importance. This color should only be used when there is
+more important text content already present.
+
+##### Text--Reverse
+
+When used against a [reversed surface](#surface--reverse), reversed text should
+be used to maintain readability.
+
+Reverse text also has a secondary value following the same rules outlined for
+standard secondary text.
+
+### Interactions
+
+Use these colors in buttons and form controls to communicate the presence and
+meaning of interaction. In cases such as [Buttons](../Button/Button.md) where the
+interactive color is functioning as a background color or the text color, the
+alternative color should be `--color-surface` so that the label matches the
+theme of the application's background.
+
+#### Interactive
+
+The default color used for interactive elements.
+
+##### Interactive--Subtle
+
+Use for interactive elements that should be less visually pronounced, such as an
+icon action in main navigation, or buttons to dismiss or cancel a workflow.
+
+##### Interactive--Background
+
+Use for the background of interactive elements to ensure separation from the
+surface they appear on.
+
+#### Destructive
+
+Use to signify that an interaction will destroy something in the users' account
+or workflow.
+
+#### Disabled
+
+Use to signify that an interactive element is disabled.
+
+Use `secondary` when a disabled element needs more than one color to be readable
+in a disabled state; for example, a button's background and label colors must be
+different.
+
+#### Focus
+
+Used by the `--shadow-focus` property to indicate that an element has received
+focus. Avoid using `--color-focus` directly on UI elements.
+
+### Status
+
+Use these colors in labels, icons, filters, alerts, and other elements where
+color can add meaning to the state of the system or an item in the system.
+
+All status colors have a main color, a surface color, and an on-surface color.
+The on-surface color should be used for an element when it sits inside of an
+element with the status' surface color to maintain a cohesive tone and ensure
+sufficient color contrast.
+
+#### Critical
+
+Action required; user must see this status to be unblocked.
+
+#### Warning
+
+Action *may* be required as a consequence of current state.
+
+#### Success
+
+No action required; an action has completed successfully.
+
+#### Informative
+
+No action required; but helpful to know about.
+
+#### Inactive
+
+No action required; not part of an active workflow.
+
+### Surfaces
+
+Surfaces are the background-colors of almost every element in Jobber. Overlays
+act as supplementary surfaces that mask areas of the interface to adjust visual
+focus.
+
+#### Surface
+
+Most elements in Jobber have a light surface to indicate their nearness to the
+user; if interactive, they have a hover color and an active color to indicate
+state.
+
+#### Surface--Background
+
+A slightly darker surface gives a receded appearance relative to main surfaces.
+
+#### Surface--Background--Subtle
+
+Use when you need a surface that's distinct from the main `surface` without
+appearing *too* receded.
+
+#### Surface--Reverse
+
+Use a reversed surface when a strong contrast is needed with the rest of the
+application.
+
+#### Overlay
+
+Use to mask an area of the interface to promote focus to a foreground action,
+such as a [Modal](/components/Modal)'s appearance. Overlay includes built-in
+opacity values.
+
+#### Overlay--Dimmed
+
+A transparent version of [Surface](#surface), this masks an area of the
+interface to indicate inactivity (i.e. waiting for updates). Overlay--Dimmed
+includes built-in opacity values.
+
+### Borders
+
+Defining the edges of elements on the same elevation plane, border colors are
+the subtle maintainers of layout structure. Learn more about borders in our
+[Borders guide.](../Borders/Borders.md)
+
+Most borders should use `--color-border` for subtle definition.
+
+Use `--color-border--section` where other bordered content is being further
+sectioned, such as table headers or list sections.
+
+Use `--color-border--interactive` for interactive elements to ensure accessible
+contrast.
+
+### Workflow
+
+These colors are associated with steps of the home services workflow. These
+should be used sparingly and only on elements that are directly related to the
+workflow.
+
+#### Requests and assessments
+
+Requests and assessments use orange to convey a "warm handoff" from the service
+consumer to the service provider.
+
+#### Quotes
+
+Quotes use pink to suggest the likelihood of the service provider winning the
+work is getting warmer relative to a request.
+
+#### Jobs and visits
+
+Jobs are green because of their core association to Jobber, which has
+historically used some shade of green for branding.
+
+Visits inherit the job color as they are closely related to jobs.
+
+#### Invoices and payments
+
+Invoices are blue as this is a common color associated with banking and finance.
+
+Payments inherit the invoice color as they are closely related to invoices.
+
+#### Tasks
+
+Tasks use a deeper shade of blue than invoices and the two rarely share
+interfaces as tasks are generally isolated to scheduling.
+
+### Brand
+
+Use these colors to represent the Jobber brand visual language.
+
+#### Brand
+
+The primary color associated with our brand, from website to ads to product; AKA
+"Jobber Green".
+
+#### Brand--Highlight
+
+Use to highlight an element in a way that aligns with our website. Use with
+caution, it's *bright!*
+
+## Base colors

package/dist/docs/Content/Content.md

@@ -0,0 +1,67 @@
+# Content
+
+Content is a container component that provides it's child elements with
+consistent vertical or horizontal spacing and padding.
+
+This is useful for when you want to include internal details like text within a
+parent component, such as a [Card](../Card/Card.md), while maintaining
+consistent spacing between the elements.
+
+## Design & usage guidelines
+
+Content should be used whenever you have a container with children that requires
+consistent spacing between the elements.
+
+## Related components
+
+Use [Flex](../Flex/Flex.md) and [Grid](/components/Grid) to create more complex
+layouts.
+
+## Accessibility
+
+Content supports the use of semantic HTML5 region elements like `<main>`,
+`<section>`, `<article>` etc. to further enhance accessibility when used
+appropriately. Consider using these if the Content represents a meaningful
+region or section of your content. The default tag is a `<div>`.
+
+Children of the Content component should be presented in a logical order, and
+follow a sensible hierarchy that can be followed by screen readers.
+
+
+## Component customization
+
+### UNSAFE\_style (mobile)
+
+General information for using `UNSAFE_` props can be found
+[here](../customizing-components/customizing-components.md).
+
+**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
+considered a **last resort**. Future Content updates may lead to unintended
+breakages.
+
+The Content component has two elements that can be targeted to apply custom
+styles. These are the container and child wrapper.
+
+```tsx
+UNSAFE_style: {
+    container: {
+      paddingHorizontal: tokens["space-large"],
+    },
+    childWrapper: {
+      backgroundColor: tokens["color-surface--background"],
+    },
+  },
+```
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | Yes | — | The child or children that will be given spacing. |
+| `childSpacing` | `Spacing` | No | `base` | The amount of spacing that will be applied between children. |
+| `direction` | `"horizontal" | "vertical"` | No | `vertical` |  |
+| `spacing` | `Spacing` | No | `base` | The amount of spacing that content will give. |
+| `UNSAFE_style` | `ContentUnsafeStyle` | No | — | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |