@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/Text/Text.md

@@ -0,0 +1,368 @@
+# Text
+
+Text is used to add an additional visual meaning on your content
+
+## Design & usage guidelines
+
+The default styling of a text is used as the body text for almost everything.
+
+```tsx
+import React from "react";
+import { Text } from "@jobber/components/Text";
+
+export function TextDefaultExample() {
+  return (
+    <Text>Ask the information you need upfront from clients and new leads</Text>
+  );
+}
+```
+
+### Subdued
+
+De-emphasize a piece of text that is less important to the user.
+
+```tsx
+import React from "react";
+import { Text } from "@jobber/components/Text";
+
+export function TextSubduedExample() {
+  return <Text variation="subdued">Job note linked to related invoice</Text>;
+}
+```
+
+### Feedback message
+
+The variation also includes text that conveys feedback messages.
+
+```tsx
+import React from "react";
+import { Content } from "@jobber/components/Content";
+import { Text } from "@jobber/components/Text";
+
+export function TextFeedbackExample() {
+  return (
+    <Content>
+      <Text variation="success">Invoice sent</Text>
+      <Text variation="error">Name is required</Text>
+      <Text variation="warn">Your message is over 160 characters</Text>
+      <Text variation="info">
+        Drag to rearrange the order that the fields show up in Jobber
+      </Text>
+    </Content>
+  );
+}
+```
+
+### Disabled
+
+Use when the text is part of a disabled section of the interface.
+
+Do not use `disabled` text to explain why an element is disabled. That text
+should be default text with full intended contrast so that the user can clearly
+identify why an element is disabled.
+
+```tsx
+import React from "react";
+import { Checkbox } from "@jobber/components/Checkbox";
+import { Content } from "@jobber/components/Content";
+import { Text } from "@jobber/components/Text";
+
+export function TextDisabledExample() {
+  return (
+    <Content>
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "var(--space-small)",
+          marginBottom: "var(--space-small)",
+        }}
+      >
+        <Checkbox disabled checked={false} />
+        <Text variation="disabled">A checkbox option</Text>
+      </div>
+      <Text>
+        You must enable your other settings before you can select this option.
+      </Text>
+    </Content>
+  );
+}
+```
+
+## Alignment
+
+Use left-aligned text for the the vast majority of use cases, particularly when
+setting paragraphs. You may need to right-align text in cases where a label or
+other small typographic element helps maintain vertical alignment on the right
+side of a layout.
+
+Centered text should be used sparingly, and largely in standalone cases like
+empty states where the content is vertically and horizontally centered.
+
+For text alignment, we use `start` and `end` instead of `left` and `right`. This
+allows us to support
+[bi-directionality](https://material.io/design/usability/bidirectionality.html#mirroring-layout)
+when needed.
+
+```tsx
+import React from "react";
+import { Text } from "@jobber/components/Text";
+import { ContentBlock } from "@jobber/components/ContentBlock";
+
+export function TextAlignmentExample() {
+  return (
+    <ContentBlock maxWidth="100%">
+      <Text align="start">
+        Start aligns text to the left in Latin and other LTR scripts
+      </Text>
+      <Text align="center">Center is always in... the center</Text>
+      <Text align="end">
+        End aligns text to the right in Latin and other LTR scripts
+      </Text>
+    </ContentBlock>
+  );
+}
+```
+
+## maxLines
+
+Used to truncate large text with `...` based on line wrapping, such that the
+total number of lines does not exceed the preset. This is an optional prop. If
+left undefined all the contents are shown.
+
+```tsx
+import React from "react";
+import { Content } from "@jobber/components/Content";
+import { Text } from "@jobber/components/Text";
+
+export function TextMaxLinesExample() {
+  return (
+    <Content>
+      <Text maxLines="single">
+        This will show 1 line. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vestibulum nec pulvinar nunc. Suspendisse nec eros
+        pretium, rutrum purus sit amet, finibus ante. Donec pretium condimentum
+        scelerisque.
+      </Text>
+      <Text maxLines="small">
+        This will show 2 lines. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vestibulum nec pulvinar nunc. Suspendisse nec eros
+        pretium, rutrum purus sit amet, finibus ante. Donec pretium condimentum
+        scelerisque. Duis eu ligula nec metus suscipit feugiat.Etiam sapien
+        sapien, mattis eu tincidunt quis, pretium sed metus. Maecenas quis dolor
+        lacinia libero rhoncus fringilla. Cras mi ante, euismod nec tortor in,
+        tempus mollis nulla.
+      </Text>
+      <Text maxLines="base">
+        This will show 4 lines. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vestibulum nec pulvinar nunc. Suspendisse nec eros
+        pretium, rutrum purus sit amet, finibus ante. Donec pretium condimentum
+        scelerisque. Duis eu ligula nec metus suscipit feugiat.Etiam sapien
+        sapien, mattis eu tincidunt quis, pretium sed metus. Maecenas quis dolor
+        lacinia libero rhoncus fringilla. Cras mi ante, euismod nec tortor in,
+        tempus mollis nulla.
+      </Text>
+      <Text maxLines="large">
+        This will show 8 lines. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vestibulum nec pulvinar nunc. Suspendisse nec eros
+        pretium, rutrum purus sit amet, finibus ante. Donec pretium condimentum
+        scelerisque. Duis eu ligula nec metus suscipit feugiat.Etiam sapien
+        sapien, mattis eu tincidunt quis, pretium sed metus. Maecenas quis dolor
+        lacinia libero rhoncus fringilla. Cras mi ante, euismod nec tortor in,
+        tempus mollis nulla. Etiam eu lacus nibh. Donec tristique lacus magna,
+        vulputate tristique lacus blandit vitae. Aenean vitae commodo metus.
+        Fusce eu risus quis orci pharetra consequat nec nec libero.
+      </Text>
+      <Text maxLines="larger">
+        This will show 16 lines. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vestibulum nec pulvinar nunc. Suspendisse nec eros
+        pretium, rutrum purus sit amet, finibus ante. Donec pretium condimentum
+        scelerisque. Duis eu ligula nec metus suscipit feugiat.Etiam sapien
+        sapien, mattis eu tincidunt quis, pretium sed metus. Maecenas quis dolor
+        lacinia libero rhoncus fringilla. Cras mi ante, euismod nec tortor in,
+        tempus mollis nulla. Etiam eu lacus nibh. Donec tristique lacus magna,
+        vulputate tristique lacus blandit vitae. Aenean vitae commodo metus.
+        Fusce eu risus quis orci pharetra consequat nec nec libero. Lorem ipsum
+        dolor sit amet, consectetur adipiscing elit. Vestibulum nec pulvinar
+        nunc. Suspendisse nec eros pretium, rutrum purus sit amet, finibus ante.
+        Donec pretium condimentum scelerisque. Duis eu ligula nec metus suscipit
+        feugiat.Etiam sapien sapien, mattis eu tincidunt quis, pretium sed
+        metus. Maecenas quis dolor lacinia libero rhoncus fringilla. Cras mi
+        ante, euismod nec tortor in, tempus mollis nulla. Etiam eu lacus nibh.
+        Donec tristique lacus magna, vulputate tristique lacus blandit vitae.
+        Aenean vitae commodo metus. Fusce eu risus quis orci pharetra consequat
+        nec nec libero.
+      </Text>
+    </Content>
+  );
+}
+```
+
+## Platform Considerations (Web)
+
+### Sizes
+
+Text can be used with different sizes.
+
+```tsx
+import React from "react";
+import { Content } from "@jobber/components/Content";
+import { Text } from "@jobber/components/Text";
+
+export function TextSizesExample() {
+  return (
+    <Content>
+      <Text size="base">
+        Both Trains and Text come in all different kinds of sizes
+      </Text>
+      <Text size="small">Sometimes they are small</Text>
+      <Text size="large">Other times they are large</Text>
+    </Content>
+  );
+}
+```
+
+#### Base
+
+Base is the default size and is optimized for the widest range of uses,
+including:
+
+* Long paragraphs of text content
+* Descriptions of subsequent UI elements
+* Labels on UI elements such as checkboxes and radio buttons
+* Freeform user-generated content
+
+#### Large
+
+Typically large is to be used as an introductory paragraph that gives important
+information about a page, and requires greater prominence.
+
+#### Small
+
+The small size is intended to be used as helper content on things like
+checkboxes, radio buttons, inputs or any other UI elements that need help
+provided.
+
+
+## Component customization
+
+### UNSAFE\_ props (advanced usage)
+
+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 Text updates may lead to unintended
+breakages.
+
+#### UNSAFE\_ props (web)
+
+### UNSAFE\_className
+
+Use `UNSAFE_className` to apply custom classes to the Text component. This
+can be useful for applying styles via CSS Modules.
+
+```tsx
+// YourComponent.tsx
+<Text UNSAFE_className={{ textStyle: styles.customText }}>
+  Custom text style
+</Text>
+
+// YourComponent.module.css
+.customText {
+  color: var(--color-purple);
+}
+```
+
+### UNSAFE\_style
+
+Use `UNSAFE_style` to apply inline custom styles to the Text component.
+
+```tsx
+<Text UNSAFE_style={{ textStyle: { color: "var(--color-purple)" } }}>
+  Custom text style
+</Text>
+```
+
+#### UNSAFE\_style (mobile)
+
+The mobile Text component can be custom styled using the `textStyle` type via
+the `UNSAFE_style` prop.
+
+React Native does not support className. Instead, you can use `UNSAFE_style` to
+apply styles either inline or through a StyleSheet.
+
+##### Inline styles
+
+```tsx
+UNSAFE_style={{ textStyle: { color: tokens["color-purple--light"] } }}
+```
+
+##### StyleSheet
+
+```tsx
+// Text.tsx
+  UNSAFE_style={{
+    textStyle: styles.customTextStyle,
+  }}
+
+// Text.style.ts
+export const styles = StyleSheet.create({
+  customTextStyle: {
+    color: tokens["color-purple--light"],
+  },
+});
+```
+
+## Platform Considerations (Mobile)
+
+### Notes
+
+Text uses the core component [Text](https://reactnative.dev/docs/text) from
+`react-native`.
+
+#### Nested text (mobile)
+
+The mobile `Text` component now supports nested children like React Native’s
+`Text`. You can compose inline layouts and mixed formatting:
+
+```tsx
+<Text>
+  Normal <Text emphasis="strong">Bold</Text> and
+  <Text italic> italic</Text> text
+</Text>
+```
+
+Transforms (e.g., `transform="uppercase"`) apply only to string children of the
+component they are set on. Nested `Text`/`Typography` elements can set their own
+`transform` independently.
+
+### Copying text
+
+There are a few caveats around copying text on Android and iOS that you can read
+under the [Typography](../Typography/Typography.md) documentation.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `adjustsFontSizeToFit` | `boolean` | No | `false` | Determines whether text should be scaled down to fit based on maxLines prop |
+| `align` | `TextAlign` | No | — | Alignment of text |
+| `allowFontScaling` | `boolean` | No | `true` | Allow text to be resized based on user's device display scale |
+| `children` | `ReactNode` | No | — | Text to display. Supports nesting text elements. |
+| `emphasis` | `"strong"` | No | — | Change the appearance of the text |
+| `hideFromScreenReader` | `boolean` | No | `false` | This will make the text inaccessible to the screen reader. This should be avoided unless there is a good reason. For ... |
+| `italic` | `boolean` | No | `false` | Use italic font style |
+| `level` | `TextLevel` | No | `text` | Visual hierarchy of the text |
+| `maxFontScaleSize` | `number` | No | — | Set the maximum font the text can go to size when the user scales their device font size |
+| `maxLines` | `TruncateLength` | No | `unlimited` | The maximum amount of lines the text can occupy before being truncated with "...". Uses predefined string values that... |
+| `onTextLayout` | `(event: TextLayoutEvent) => void` | No | — | Callback that is called when the text is laid out. |
+| `reverseTheme` | `boolean` | No | `false` | Reverse theme for better display on dark background |
+| `selectable` | `boolean` | No | `true` | Lets the user select text, to use the native copy and paste functionality. WARNING: if true, this prevents ellipsis f... |
+| `strikeThrough` | `boolean` | No | `false` | Have text styled with strike through |
+| `underline` | `"solid" | "dotted"` | No | — | Underline style to use for the text. The non-solid style is only supported on iOS, as per React Native's Text compone... |
+| `UNSAFE_style` | `TypographyUnsafeStyle` | No | — | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |
+| `variation` | `TextVariation` | No | `base` | Color variation of text |

package/dist/docs/TextList/TextList.md

@@ -0,0 +1,29 @@
+# TextList
+
+The TextList is a component that displays a text of unordered list.
+
+## Design & usage guidelines
+
+Utilizing TextList is quite simple - it should typically appear following any
+relevant text or content. TextList manages the presentation of a list of text
+items, rendering them in a clear, organized bullet-point format. It aids in
+making the content easily digestible for the user.
+
+## Related components
+
+This component is uses the [Content](../Content/Content.md) and
+[Text](../Text/Text.md) components for displaying. This is also used for
+displaying the error list in [Banner](../Banner/Banner.md) component.
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `childSpacing` | `Spacing` | No | `none` | The amount of spacing that will be applied between the list items. |
+| `emphasis` | `"strong"` | No | — | Change the appearance of the text |
+| `items` | `string[]` | No | — | Text to display. |
+| `level` | `TextLevel` | No | `text` | Visual hierarchy of the text. |
+| `spacing` | `Spacing` | No | `none` | The amount of spacing that content will give. |

package/dist/docs/ThumbnailList/ThumbnailList.md

@@ -0,0 +1,16 @@
+# Thumbnail List
+
+For guidelines on using this component, see the documentation for web equivalent
+component, [Gallery](/components/Gallery).
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `files` | `File[]` | Yes | — |  |
+| `createThumbnail` | `CreateThumbnail` | No | — |  |
+| `handleOpenFile` | `({ file, index, imageList, }: { file: File; index: number; imageList: File[]; }) => void` | No | — |  |
+| `rowCount` | `RowCount` | No | `RowCount.TwoRows` |  |

package/dist/docs/Toast/Toast.md

@@ -0,0 +1,71 @@
+# Toast
+
+Toasts are short, temporary messages used to inform users that a process was
+performed. They provide visual feedback on the outcome of an action and require
+minimal user interaction.
+
+Toast, unlike common React components, is not a component that will be added to
+your view. Instead, Toast is used by importing and calling the `showToast()`
+function.
+
+## Design & usage guidelines
+
+Use `Toast` to present non-blocking feedback about the system to a user.
+
+### Related components
+
+For more persistent feedback (such as displaying errors), communicating a
+background process that is ongoing, or for feedback that has a longer reading
+length or CTA, use [Banner.](../Banner/Banner.md)
+
+### Variation (Web only)
+
+The primary use case for Toast is success messages.
+
+In some cases, an informational Toast may be used to inform the user of some
+background system activity. See
+[Web/Info example](/storybook/web/?path=/story/components-status-and-feedback-toast--variation)
+
+### Errors
+
+> Do not use Toast for errors. This is currently an available variation, but
+> should be considered deprecated and not propagated.
+
+Use [Banner](../Banner/Banner.md) and, where necessary, targeted error messaging
+(such as [InputValidation](/components/InputValidation)) so that the user can
+appropriately assess and recover from the error.
+
+## Content guidelines
+
+The Toast label should be clear and concise, and should not take up more than
+one line.
+
+Use the pattern "action + subject" to maintain
+[active voice](/content/voice-and-tone). The subject should be specific without
+overloading too much detail for the user to parse at a quick glance.
+
+| ✅ Do              | ❌ Don't                                            |
+| ----------------- | -------------------------------------------------- |
+| Saved job         | Saved job #216 - Weekly mowing for Nathaniel Lewis |
+| Archived property | Archived 289 NW 198th St, Shoreline, WA 98177, USA |
+
+* No need to use "Successfully", should be implicit in the Toast
+* Don't use `Dismiss` or `Cancel` as an action label
+  * Examples of action labels: `Undo`, `View`, `Refresh`
+* Toast's label does not require a period
+* Use sentence case, and only capitalize
+  ["branded"](/content/product-vocabulary) Jobber features
+
+| ✅ Do       | ❌ Don't                 |
+| ---------- | ----------------------- |
+| Saved job  | Saved Job Successfully. |
+| Sent quote | Sent Quote              |
+
+
+## Props
+
+### Mobile
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `bottomOffset` | `number` | No | `40` | Offset from the bottom of the screen in px. Has effect only when the position is "bottom". |

package/dist/docs/Typography/Typography.md

@@ -0,0 +1,170 @@
+# Typography
+
+When a designer is talking about "type", it's unlikely they're asking about the
+latest Typescript linting rules! Typography is a core aspect of any user
+interface, and we've built a system that should make it simple for our
+interfaces to be built with consistent, considered typographic elements.
+
+The Atlantis typography system is based on the core components of
+[Heading](../Heading/Heading.md) and [Text](../Text/Text.md).
+
+```tsx
+<Content>
+    <Heading level={1} element="h2">
+      A <Emphasis variation="highlight">prominent</Emphasis> heading
+    </Heading>
+    <Text>
+      A longer body of text that&apos;s better suited for readabilty at smaller
+      sizes. Typically a paragraph should be displayed in a typeface that has a
+      moderate weight, and is <Emphasis variation="italic">relatively</Emphasis>{" "}
+      free of flourish.
+    </Text>
+  </Content>
+```
+
+Heading and Text are extended by the ability to add
+[Emphasis](/components/Emphasis) to these components as needed.
+
+There are some foundational elements that make up these components:
+
+## Font families
+
+### Display
+
+Jobber Pro is Jobber's internal typeface and is only suitable for use in Jobber
+products. It lends a hefty-but-professional face to larger usages such as page
+titles.
+
+As Jobber Pro is a custom typeface licensed specifically for Jobber usage, it
+will be rendered in any environments where it is licensed for use. In external
+usages, [Poppins](https://fonts.google.com/specimen/Poppins) is Atlantis'
+fallback display face. It has similar structural features and optical sizing as
+Jobber Pro.
+
+```tsx
+<Content>
+    <Heading level={1}>Jobber Pro is used for page titles</Heading>
+  </Content>
+```
+
+### Base
+
+[Inter](https://fonts.google.com/specimen/Inter) is our most broadly-used
+typeface. It is used for body copy, most headings, data display, form inputs,
+labels, and more!
+
+```tsx
+<Content spacing="large">
+    <Heading level={3}>Inter is for less prominent headings</Heading>
+    <Text>
+      You can also use it for longer, more readable statements in paragraphs,
+      descriptive text, in lists, and more. If you&apos;ve been paying careful
+      attention, you might have noticed that Atlantis even uses Inter for
+      presenting documentation!
+    </Text>
+    <Checkbox checked label="Inter can label inputs nicely"></Checkbox>
+    <InputText
+      defaultValue="It's great for input values too"
+      placeholder="Inter for labels"
+    />
+    <Table>
+      <Header>
+        <Cell>Inter</Cell>
+        <Cell>Renders</Cell>
+        <Cell align="right">Data</Cell>
+      </Header>
+      <Body>
+        <Row>
+          <Cell>Data point</Cell>
+          <Cell>More data</Cell>
+          <Cell align="right">$280</Cell>
+        </Row>
+        <Row>
+          <Cell>Another data point</Cell>
+          <Cell>Additional values</Cell>
+          <Cell align="right">$200</Cell>
+        </Row>
+      </Body>
+    </Table>
+  </Content>
+```
+
+## Font-size
+
+### Web
+
+At the default zoom level for web applications, our base font-size is equivalent
+to `14px`. Depending on the context in which your typography is being used,
+font-size can be adjusted to be larger or smaller than the base font-size.
+
+Suggestions for when to use varying font-sizes are discussed in the
+[Heading](../Heading/Heading.md) component, and within the
+[Sizes](../Text/Text.md) section of the Text component.
+
+| Name                                 | Visual | Value |
+| :----------------------------------- | :----- | :---- |
+| `--typography--fontSize-smaller`     |        |       |
+| `--typography--fontSize-small`       |        |       |
+| `--typography--fontSize-base`        |        |       |
+| `--typography--fontSize-large`       |        |       |
+| `--typography--fontSize-larger`      |        |       |
+| `--typography--fontSize-largest`     |        |       |
+| `--typography--fontSize-jumbo`       |        |       |
+| `--typography--fontSize-extravagant` |        |       |
+
+### Mobile
+
+Jobber's mobile platform uses the following sizing tokens for typography.
+
+The mobile platform has a base font-size equivalent to `16px`, with options for
+a larger or smaller font-size depending on the use case.
+
+| Name                                 | Visual | Value |
+| :----------------------------------- | :----- | :---- |
+| `--typography--fontSize-smallest`    |        |       |
+| `--typography--fontSize-smaller`     |        |       |
+| `--typography--fontSize-small`       |        |       |
+| `--typography--fontSize-base`        |        |       |
+| `--typography--fontSize-large`       |        |       |
+| `--typography--fontSize-larger`      |        |       |
+| `--typography--fontSize-largest`     |        |       |
+| `--typography--fontSize-jumbo`       |        |       |
+| `--typography--fontSize-extravagant` |        |       |
+
+## Line-height
+
+### Web
+
+Line-height, or
+[leading](https://www.shillingtoneducation.com/blog/leading-typography/), is the
+space between subsequent lines of type. The line-heights in the `Heading` and
+`Text` components are optimized for each variation's unique combination of
+font-size, weight, and family, so you don't need to adjust their line-height
+manually when you use them.
+
+At smaller sizes, a more generous line-height relative to the font-size allows
+the user to more easily parse multiple lines of small text. As font-size
+increases into "display" sizes such as a level 1 `Heading`, the ratio of
+line-height to font-size decreases as the larger font-size is more readable and
+requires less line-to-line breathing room.
+
+| Name                                 | Visual | Value |
+| :----------------------------------- | :----- | :---- |
+| `--typography--lineHeight-large`     |        |       |
+| `--typography--lineHeight-base`      |        |       |
+| `--typography--lineHeight-tight`     |        |       |
+| `--typography--lineHeight-tighter`   |        |       |
+| `--typography--lineHeight-tightest`  |        |       |
+| `--typography--lineHeight-minuscule` |        |       |
+
+### Mobile
+
+| Name                                   | Visual | Value |
+| :------------------------------------- | :----- | :---- |
+| `--typography--lineHeight-extravagant` |        |       |
+| `--typography--lineHeight-jumbo`       |        |       |
+| `--typography--lineHeight-largest`     |        |       |
+| `--typography--lineHeight-larger`      |        |       |
+| `--typography--lineHeight-large`       |        |       |
+| `--typography--lineHeight-base`        |        |       |
+| `--typography--lineHeight-tight`       |        |       |