@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/ButtonGroup/ButtonGroup.md

@@ -0,0 +1,89 @@
+# Button Group
+
+The ButtonGroup component is used to horizontally group one or more actions
+represented by buttons. The layout of the buttons is dependent on the number and
+type of actions provided.
+
+Up to 2 primary actions are displayed as buttons, in the order provided.
+Additional primary actions are hidden in a `More` menu.
+
+Secondary actions can also be specified which are always displayed in the `More`
+menu.
+
+The `More` button opens the additional actions in a `BottomSheet`.
+
+It can optionally display a heading above the Secondary actions bottom sheet. It
+can also optionally display a cancel button in the footer, which closes the
+sheet.
+
+## Design & usage guidelines
+
+Actions will be displayed in the order provided. Secondary actions will always
+be placed in the `More` menu. In general, at least one primary action should be
+provided.
+
+Primary actions can optionally specify alternative button types and variations
+depending on use case.
+
+## Content guidelines
+
+A ButtonGroup must contain one or more children that are of the type
+`ButtonGroup.PrimaryAction` or `ButtonGroup.SecondaryAction`
+
+## Accessibility
+
+Each button within the group will support all the accessibility attributes that
+the Button component provides.
+
+The ButtonGroup itself does not have additional accessibility attributes.
+
+## Responsiveness
+
+On wider screens such as on tablets, additional buttons will be shown in the
+horizontal list (up to 4), rather than hidden under the "More" button.
+
+Secondary actions are always hidden in "More", regardless of space.
+
+Button labels will overlap multiple lines. All buttons in the group should size
+to match the height of the largest button.
+
+## Mockup
+
+
+## Props
+
+### Mobile
+
+#### ButtonGroup
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `allowTapWhenOffline` | `boolean` | No | `false` | Allows you to Tap the button while offline |
+| `bottomSheetHeading` | `string` | No | — | An optional heading to display in the secondary bottom sheet header. |
+| `onCloseBottomSheet` | `() => void` | No | — | Callback that is called when the secondary actions bottom sheet is closed. |
+| `onOpenBottomSheet` | `() => void` | No | — | Callback that is called when the secondary actions bottom sheet is opened. |
+| `showCancelInBottomSheet` | `boolean` | No | — | Display a cancel button in the secondary bottom sheet footer. |
+
+#### ButtonGroup.PrimaryAction
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `label` | `string` | Yes | — | Text to be displayed on the action button |
+| `onPress` | `() => void` | Yes | — | Press handler for the action button |
+| `buttonType` | `ButtonType` | No | — | Sets the action button style (default: "primary") |
+| `buttonVariation` | `ButtonVariation` | No | — | Themes the action button to the type of action it performs (default: "work") |
+| `customButton` | `ReactElement<unknown, string | JSXElementConstructor<any>>` | No | — | Optional custom button that can be rendered in place of the primary action button |
+| `icon` | `IconNames` | No | — | Icon to be displayed on the action button |
+| `iconColor` | `"destructive" | "task" | "text" | "warning" | "icon" | "white" | "grey" | "greyBlue" | "greyBlueDark" | "greyBlueLighter" | "blue" | "lightBlue" | "green" | "yellow" | "red" | ... 34 more ... | "brandHighlight"` | No | — | Determines the color of the icon. If not specified, some icons have a default system colour which will be used Others... |
+| `loading` | `boolean` | No | — |  |
+
+#### ButtonGroup.SecondaryAction
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `label` | `string` | Yes | — | Text to be displayed on the action button |
+| `onPress` | `() => void` | Yes | — | Press handler for the action button |
+| `destructive` | `boolean` | No | — | Indicates whether the secondary action is destructive in nature. |
+| `icon` | `IconNames` | No | — | Icon to be displayed on the action button |
+| `iconColor` | `"destructive" | "task" | "text" | "warning" | "icon" | "white" | "grey" | "greyBlue" | "greyBlueDark" | "greyBlueLighter" | "blue" | "lightBlue" | "green" | "yellow" | "red" | ... 34 more ... | "brandHighlight"` | No | — | Determines the color of the icon. If not specified, some icons have a default system colour which will be used Others... |
+| `loading` | `boolean` | No | — |  |

package/dist/docs/Card/Card.md

@@ -0,0 +1,270 @@
+# Card
+
+A card is used to group related information and tasks so our users can scan and
+prioritize information more easily.
+
+## Design & usage guidelines
+
+A card is useful for grouping content because of its distinct visual boundaries.
+However, similar to the idea that "making everything stand out means that
+nothing stands out", you should be mindful in your application of cards.
+
+A card should be the smallest-possible self-contained section of content. If you
+find yourself putting a card inside of another card, the outer card should be
+removed, and it may be worth re-assessing the hierarchy of your interface.
+
+### Clickable
+
+If clicking on the entire Card will navigate the user to a new view or perform
+an action, the Card will have interactive hover and focus states.
+
+It is important to signify to the user that the Card is clickable. This can be
+done by using elevation or by using the `arrowRight` chevron icon in the Card.
+Common examples of this pattern can be found in the
+[Card Figma.](https://www.figma.com/design/rIIhulZvcp9M82lNOCGv16/Product%2FOnline?m=auto\&node-id=22677-10476\&t=YbmsOsxL9J6ggqVA-1)
+
+### Elevation
+
+By default, it should be assumed that a Card is on the same "plane" as the
+surface it sits on and has no elevation.
+
+If the Card benefits from having elevation indicated, such as when it sits
+overtop another Card or is used in a Carousel fashion, the appropriate elevation
+level can be set. See
+[Mobile/Elevation](/storybook/mobile/?path=/story/components-layouts-and-structure-card--elevation)
+for an example.
+
+## Related components
+
+[Content](../Content/Content.md) and [Flex](../Flex/Flex.md) are the most common
+layout tools for managing the Card's children. Generally, Card is un-opinionated
+about what goes inside of it.
+
+If you require more customization over the appearance of your container,
+[Box](/components/Box) is the preferred way to achieve this without writing CSS.
+
+## Content guidelines
+
+Card headers should be sentence-cased.
+
+| ✅ Do                    | ❌ Don't                 |
+| ----------------------- | ----------------------- |
+| Client property details | Client Property Details |
+| Assigned team           | ASSIGNED TEAM           |
+| Required deposit        | Required Deposit        |
+
+As previously mentioned, a Card should be "self-contained" and nesting Cards
+inside of other Cards should be avoided.
+
+## Accessibility
+
+The Card itself is already accessible and does not require any additional setup.
+
+With that said, it should not be wrapped in an element with an `aria-label` or
+`accessibilityLabel` describing it as a card. This is redundant and will cause
+unexpected behaviour for screen readers. For example, wrapping a Card with an
+`accessibilityLabel` on mobile hides the entire Card from screen readers.
+
+
+## Configuration
+
+### Card Types
+
+The Card component supports three distinct types of cards:
+
+1. **Regular Card** - A basic card without any click behavior
+2. **Link Card** - A card that navigates to a URL when clicked
+3. **Clickable Card** - A card that triggers a custom click handler
+
+### Component Customization
+
+#### Composable Usage
+
+The Card component supports both prop-driven and composable approaches. The
+standard prop-driven usage with `title` and `header` props is straightforward
+and suitable for most use cases. For advanced customization needs, the Card
+component also provides `Card.Header` and `Card.Body` components.
+
+`Card.Header` is used to display custom header content of the card. `Card.Body`
+is used to display the main content of the card.
+
+Here's an example of converting a prop-driven card to a composable one when more
+customization is needed:
+
+```tsx
+<Card title="Card Title" header="Header Text">
+  <p>Card content</p>
+</Card>
+```
+
+becomes
+
+```tsx
+<Card>
+  <Card.Header>
+    <Text>Card Title</Text>
+  </Card.Header>
+  <Card.Body>
+    <p>Card content</p>
+  </Card.Body>
+</Card>
+```
+
+#### Link Card Example
+
+```tsx
+<Card url="/dashboard" external={true}>
+  <Card.Header>
+    <Text>External Link</Text>
+  </Card.Header>
+  <Card.Body>
+    <p>Click to navigate to dashboard</p>
+  </Card.Body>
+</Card>
+```
+
+#### Clickable Card Example
+
+```tsx
+<Card onClick={handleClick}>
+  <Card.Header>
+    <Text>Interactive Card</Text>
+  </Card.Header>
+  <Card.Body>
+    <p>Click to trigger action</p>
+  </Card.Body>
+</Card>
+```
+
+### Props Compatibility
+
+The Card component uses a discriminated union pattern to ensure proper usage.
+This means that the component can be one of three distinct types, each with its
+own set of valid props:
+
+* A Link Card must have a `url` prop and cannot have an `onClick` handler
+* A Clickable Card must have an `onClick` prop and cannot have a `url`
+* A Regular Card has neither `url` nor `onClick`
+
+This type system ensures that each card has a clear and single responsibility
+for its interaction behavior, making it impossible to create ambiguous card
+states (like having both a URL and click handler).
+
+### Styling
+
+Cards can be customized with the following props:
+
+* `accent`: Applies an accent color to the card
+* `elevation`: Controls the card's shadow elevation ("none" | "base" | "raised"
+  \| "floating")
+
+Example with styling:
+
+```tsx
+<Card accent="purple" elevation="raised">
+  <Card.Header>
+    <Text>Styled Card</Text>
+  </Card.Header>
+  <Card.Body>
+    <p>Card with purple accent and raised elevation</p>
+  </Card.Body>
+</Card>
+```
+
+### UNSAFE\_ props (advanced usage)
+
+General information for using `UNSAFE_` props can be found
+[here](../customizing-components/customizing-components.md).
+
+Card has two elements that can be targeted with classes or styles. These are the
+container and the header.
+
+**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
+considered a **last resort**. Future Card updates may lead to unintended
+breakages.
+
+#### UNSAFE\_className
+
+Use `UNSAFE_className` to apply custom classes to the Card. This can be useful
+for applying styles via CSS Modules.
+
+```tsx
+// YourComponent.tsx
+<Card
+  header="Custom Styled Card"
+  UNSAFE_className={{
+    container: styles.customCardContainer,
+    header: styles.customCardHeader,
+  }}
+>
+  <p>Card content with custom styling</p>
+</Card>
+
+// YourComponent.module.css
+.customCardContainer {
+  border: 2px solid var(--color-blue);
+  border-radius: var(--radius-large);
+}
+
+.customCardHeader {
+  background-color: var(--color-surface--background);
+  border-bottom: 1px solid var(--color-border);
+}
+```
+
+#### UNSAFE\_style
+
+Use `UNSAFE_style` to apply inline custom styles to the Card.
+
+```tsx
+<Card
+  header="Inline Styled Card"
+  UNSAFE_style={{
+    container: {
+      backgroundColor: "var(--color-surface--hover)",
+      transform: "rotate(1deg)",
+    },
+    header: {
+      backgroundColor: "var(--color-blue)",
+      color: "white",
+    },
+  }}
+>
+  <p>Card content with inline styling</p>
+</Card>
+```
+
+### Compound Component Card
+
+If you're using Card with its composable subcomponents, note that currently
+these subcomponents are simply fragments. As such, you are free to provide any
+desired markup and have no need for either UNSAFE.
+
+```
+<Card>
+ <Card.Header>
+  <div className="custom" style={{padding: "var(--space-base)}}>
+   <Heading level={3}>My Custom Header</Heading>
+  </div>
+ </Card.Header>
+ <Card.Body>
+  <div style={{ background: "#29d", padding: "var(--space-base)"}}>
+   <Text>Card content</Text>
+  </div>
+ </Card.Body>
+</Card>
+```
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `elevation` | `elevationProp` | No | `none` |  |
+| `error` | `string` | No | — |  |
+| `footer` | `FooterProps` | No | — |  |
+| `header` | `HeaderProps` | No | — | @deprecated Use <ActionItem /> with the title and onPress properties instead |
+| `reportCardHeight` | `(height: number) => void` | No | — |  |
+| `testID` | `string` | No | `card` |  |

package/dist/docs/Checkbox/Checkbox.md

@@ -0,0 +1,69 @@
+# Checkbox
+
+A checkbox lets a user select one or more items from a set of options.
+
+## Design & usage guidelines
+
+A checkbox is a familiar pattern for users who need to choose from a set of
+options, or opt in to a single choice. It allows a user to provide boolean
+input. It can also be in an indeterminate state when we don't know if the
+checkbox is considered checked or not.
+
+A single checkbox, a [Switch](../Switch/Switch.md), and a pair of
+[radio buttons](/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 radio buttons can be used to help the user
+decide between two discrete options, such as “fixed price” and “per visit”
+invoicing options.
+
+Of note: when a single selection is to be made, a Switch should be used rather
+than a single Checkbox. Use a Checkbox only when there are multiple selection
+options to choose from. when the volume of Radio options is greater than 5 (or
+there are otherwise critical vertical space constraints) use Select. when the
+labels on a set of Radio options are consistently small (1–2 words), use Chip.
+
+## Related components
+
+* To let people turn a setting on or off instantly, use a
+  [Switch](../Switch/Switch.md).
+* To present a set of options where people can only make a single choice, use a
+  [RadioGroup](/components/RadioGroup).
+
+## Mockup
+
+
+## Platform considerations
+
+### Event Handlers
+
+While Checkbox exposes mouse event handlers like `onClick`, the recommended way
+to access the new value is via the `onChange` prop.
+
+### CheckboxGroup (mobile)
+
+The `<CheckboxGroup>` component is a component that provides a grouping of
+checkboxes. It allows you to optionally provide a label which will allow you to
+control the Checkbox children with a single parent checkbox. If some but not all
+children are checked then the parent checkbox will show the indeterminate state.
+An important thing to note is that when using `<CheckboxGroup>` the child
+Checkboxes must have a name provided as a prop. This is so the CheckboxGroup is
+able to keep track the state of the child Checkboxes. See
+[Checkbox/Mobile/Checkbox Group Example](/storybook/mobile/?path=/story/components-selections-checkbox--checkbox-group-example)
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `accessibilityLabel` | `string` | No | — | Accessibility Label for the checkbox. Defaults to label |
+| `assistiveText` | `string` | No | — | Assistive Text, shown under label |
+| `checked` | `boolean` | No | — | If the checkbox is checked. This should be set when this is intended as a controlled component |
+| `defaultChecked` | `boolean` | No | — | Default value for when the checkbox is uncontrolled |
+| `disabled` | `boolean` | No | — | Checkbox is disabled |
+| `indeterminate` | `boolean` | No | — | When true, the checkbox is shown as indeterminate |
+| `label` | `string` | No | — | Label to be displayed beside the checkbox |
+| `name` | `string` | No | — | Name of the checkbox; this is important when using in a form component |
+| `onChange` | `((value: boolean) => void) | ((value: boolean) => void)` | No | — | Press handler |