@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/choosing-components/choosing-components.md

@@ -0,0 +1,76 @@
+# Atlantis Component Selection
+
+When implementing UI, default to importing Atlantis components before writing
+any JSX structure.
+
+Before writing any UI code, determine whether Atlantis already provides the
+needed component, pattern, or primitive.
+
+## Required Decision Process
+
+For every UI request, follow this process:
+
+1. Identify the UI elements being requested
+2. Map each element to an Atlantis component or Atlantis typography/layout
+   primitive
+3. Prefer Atlantis defaults over custom composition
+4. Only introduce custom markup/styling for product-specific layout or missing
+   behavior
+5. If Atlantis does not cover something, implement the smallest possible custom
+   layer
+
+## Atlantis-First Rule
+
+Always assume Atlantis has the right starting point.
+
+Check Atlantis first for:
+
+* page structure
+* headings and text
+* actions
+* forms
+* overlays
+* menus
+* banners and notices
+* empty/error/loading states
+* icons
+* containers and surfaces
+
+Do not jump straight to raw divs plus custom styling when Atlantis components
+could solve the problem.
+
+## Output Expectations
+
+When generating UI:
+
+* choose Atlantis components first
+* compose from Atlantis primitives
+* keep wrappers minimal
+* avoid custom components unless they add product-specific behavior
+
+## Forbidden Behavior
+
+Do not:
+
+* build a new Button when Atlantis has one
+* build custom text styles instead of using Heading or Text
+* build a custom modal, tooltip, menu, or input if Atlantis provides one
+* style raw HTML to imitate Atlantis
+
+## If No Atlantis Match Exists
+
+If Atlantis truly does not provide a direct match:
+
+* use the closest Atlantis primitives possible
+* keep the custom piece small
+* use Atlantis tokens
+* avoid inventing a new visual pattern
+* state the assumption in code comments only if necessary
+
+## Final Check Before Output
+
+Before finalizing code, verify:
+
+* Could any custom element be replaced with an Atlantis component?
+* Could any text element be replaced with Heading or Text?
+* Could any visual styling be removed in favor of Atlantis defaults?

package/dist/docs/customizing-components/customizing-components.md

@@ -0,0 +1,167 @@
+# Customizing components
+
+## Balancing simplicity, flexibility, and consistency
+
+Atlantis is designed to make building consistent, accessible, and visually
+appealing user interfaces as effortless as possible for you.
+
+We strive to speed up building the most common use cases "out of the box" with
+thoughtful defaults that create consistency for users. When unique scenarios
+arise that may require customization, we provide flexible mechanisms to extend
+or modify our components without compromising the integrity of their most common
+use cases.
+
+We recommend using the default implementations wherever possible to benefit
+from:
+
+* consistency
+* improvements from the design system "for free"
+* built-in accessibility
+
+If you choose to customize components, you assume responsibility for these
+concerns and any issues that may arise in future versions.
+
+## Compound components
+
+Some components expose their foundational building blocks. This usually includes
+subcomponents and hooks for providing styles, state, and additional logic.
+
+These components provide greater flexibility, giving you much more control over
+their appearance and behaviour.
+
+### Example: [Button](../Button/Button.md)
+
+The `Button` component offers a very simple API allowing you to specify a label,
+icon, and icon position. However, because it doesn't accept children, it's very
+inflexible.
+
+```tsx
+<Button label="Home" icon="home" iconOnRight />
+```
+
+For greater control, `Button` is also available as a compound component and has
+exposed `Button.Label` and `Button.Icon` as subcomponents. This allows complete
+customization of the button's underlying content.
+
+Using the provided subcomponents, it's possible to build something more complex
+like this:
+
+```tsx
+function Example() {
+  const [created, setCreated] = useState(false);
+
+  return (
+    <Button
+      onClick={() => setCreated(!created)}
+      variation={created ? "destructive" : "work"}
+    >
+      {created ? <Avatar initials="AB" /> : <Button.Icon name="person" />}
+      <Button.Label>{created ? "Delete user" : "Create user"}</Button.Label>
+    </Button>
+  );
+}
+```
+
+`Button` also exposes a few hooks that can be used within your own components:
+
+* `useButtonStyles`: Returns a map of css classes that `Button` uses internally.
+  Consumers might use this to make something else look like a `Button`.
+* `useButtonContext`: Returns internal context that the `Button` shares with its
+  subcomponents. Consumers might use Button's context within a custom child
+  component, allowing that child to adapt to the `size` prop for example.
+
+## Named `customRender____` props
+
+Some of our components use render props following the `customRender____` naming
+convention.
+
+This allows you to both:
+
+* inject your own UI logic
+* retain the default behaviors and functionality of the component
+
+[Reference implementation](https://github.com/GetJobber/atlantis/blob/304e776cf7fc1b9683cecbb1d7a0d8dbebdb60bb/packages/components/src/List/List.tsx#L25C3-L25C60)
+
+### Example: [List](../components/List) customRenderItem
+
+```tsx
+const renderProductItem = item => (
+  <Flex template={["shrink", "grow"]} align="start">
+    <Text>{item.price}</Text>
+    <Heading level={4}>{item.name}</Heading>
+  </Flex>
+);
+
+export const CustomRenderExample = () => (
+  <List items={items} customRenderItem={renderProductItem} />
+);
+```
+
+## Slot props with ReactNode
+
+Extending prop types to allow a `ReactNode` to be inserted is useful for simpler
+cases where your:
+
+* customization does not depend on internal state
+* design is relatively simple
+
+[Reference implementation](https://github.com/GetJobber/atlantis/blob/master/packages/components/src/Tabs/Tabs.tsx#L119C3-L119C38)
+
+### Example: [Tab](../components/Tabs) label
+
+```tsx
+<Tab label={<MyCustomLabel />} />
+```
+
+Customizing the `label` doesn’t require exposing or interacting with the `Tab`’s
+internal state (e.g., active state styling).
+
+## UNSAFE\_ props
+
+> **WARNING:** These properties are prefixed `UNSAFE_` for a reason! Their usage is **at your
+> own risk** and should be considered a **last resort**. Atlantis updates may
+> break these usages.
+
+`UNSAFE_` props are used to allow for advanced styling customization of:
+
+* a component's container
+* in some cases, a component's sub-components
+
+If you are considering using an `UNSAFE_` prop, we encourage you to
+[talk to us](https://getjobber.slack.com/archives/C03BJHV3PMG) to look for safer
+ways to meet your needs.
+
+[Reference implementation](https://github.com/GetJobber/atlantis/blob/304e776cf7fc1b9683cecbb1d7a0d8dbebdb60bb/packages/components/src/Popover/Popover.tsx#L36-L56)
+
+### Example: `UNSAFE_className`
+
+```tsx
+<Component UNSAFE_className={{ container: styles.customClass }} />
+
+.customClass {
+  background-color: var(--color-surface--background);
+  padding-right: var(--space-larger);
+}
+```
+
+```tsx
+<Component UNSAFE_className={{ container: "custom-container-class" }} />
+```
+
+### Example: `UNSAFE_style`
+
+```tsx
+<Component
+  UNSAFE_style={{
+    container: { backgroundColor: "var(--color-surface--background)" },
+    dismissArrow: { paddingRight: "var(--space-larger)" },
+  }}
+/>
+```
+
+**Note:** Inspiration for this approach was taken from:
+
+* React Spectrum's
+  [UNSAFE\_ escape hatches](https://react-spectrum.adobe.com/react-spectrum/styling.html#escape-hatches)
+* Gestalt's
+  [dangerouslySet\*\*\_\*\* pattern](https://gestalt.pinterest.systems/get_started/developers/hacking_gestalt#Box's-dangerouslySetInlineStyle)

package/dist/docs/disabled-states/disabled-states.md

@@ -0,0 +1,86 @@
+# Disabled states
+
+| **Platform** | **Status** |
+| :----------- | :--------- |
+| Web Mobile   | Ready      |
+
+This pattern involves how we disable, show, or hide actions based on different
+criteria. It becomes a balance in explaining the interface and not overwhelming
+users with choice. Below are a few of the common examples and accompanying
+guidelines for handling those situations.
+
+## Goal
+
+Avoid placing the user in a frustrating state where actions are unavailable and
+they do not know how to enable.
+
+## Use when…
+
+There's absolutely no other way to avoid a disabled state. This should be a last
+resort. This flowchart can help you find alternatives:
+
+## Solution
+
+### Avoid disabled states
+
+Your first goal should be to avoid disabled states entirely. If there is a
+condition required for the user to take an action, present the opportunity to
+set the required condition before the user is blocked by a disabled state. An
+example of this is on our “work objects” which all require a client to be saved.
+If the user makes it to the bottom of the form and has not added a client, the
+primary CTA is “Select Client“.
+
+#### Permissions-related unavailability
+
+When functionality or a feature isn't available because of a user's permissions,
+hide the action altogether.
+
+#### Account-tier-related unavailability
+
+If functionality is unavailable because of a user’s subscription tier, but we
+want to introduce the functionality to encourage them to upgrade, use an inline
+element near where the unavailable UI would exist, or a
+`Button variation="learning"` in place of the UI to nudge the user to learn
+more.
+
+### Why
+
+Avoiding disabled states is an accessibility best practice and also generally
+helpful from a usability perspective. The more time a user spends trying to
+understand why they can’t take an action, the less time they spend getting sh\*t
+done.
+
+Disabling elements is often the easiest path for a development team to manage
+conditional states of an interface to design and build, but results in a
+less-friendly interface for the user.
+
+### Implementation
+
+While you should avoid disabled states, many Atlantis components do offer a
+`disabled` boolean property for absolutely necessary cases. If you use the
+disabled state, you must ensure that the user can understand *why* the element
+is disabled.
+
+### Web
+
+A [Tooltip](../components/Tooltip) may help explain to the user why they
+can’t select an element. Make sure the Tooltip can be triggered both by
+focus and hover.
+
+### Mobile
+
+[Text](../Text/Text.md) (level="supportingText") is more helpful for users
+in the mobile app as it does not require an additional interaction to
+uncover. If an input element (such as a Select or InputText) has “assistive
+text” built in, do not use the assistive text in a disabled state, but
+provide the supporting Text as a separate element.
+
+## Related
+
+* [Interaction](../interaction/interaction.md)
+* [Empty states](../empty-states/empty-states.md)
+
+## Principles
+
+* [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/)
+* [Recognition over recall](https://www.nngroup.com/articles/recognition-and-recall/)

package/dist/docs/empty-states/empty-states.md

@@ -0,0 +1,126 @@
+# Empty states
+
+| **Platform** | **Status** |
+| :----------- | :--------- |
+| Web Mobile   | Ready      |
+
+## Goal
+
+Ensure the user does not hit a dead end when there is no content to display.
+
+## Use when...
+
+Use when there *could* be content in a view, but there is none. Possible reasons
+for the “emptiness” may include, but are not limited to…
+
+* A notifications panel when the user hasn't received any notifications
+* A list of user-generated content before user has created any content (for
+  example, a list of clients when the user doesn’t yet have any clients)
+* Dashboards or other data-centric views when the user has not generated any
+  data (ie Home)
+* Search results with no match
+* An error has resulted in the user not being able to access content they
+  otherwise could
+
+## Solution
+
+A successful empty state should:
+
+* communicate system status
+* increase learnability of the system
+* deliver direct pathways for key tasks
+
+[Designing Empty States in Complex Applications: 3 Guidelines](https://www.nngroup.com/articles/empty-state-interface-design/#:~:text=Empty%20states%20that%20are%20intentionally,getting%20started%20with%20key%20tasks)
+
+#### When *not* to add a CTA
+
+You might not use a direct CTA in the empty state if:
+
+* The action to populate the empty state has dependencies on another action
+  being taken
+  * Example: Quotes must be approved by clients before they appear in a list of
+    "approved quotes"
+  * Example: A payment requires creation and delivery of an invoice, and the
+    client to make a payment, before it exists
+
+### In lists
+
+Adjust your context and actions if the user has no content because of a search
+or filter, vs when they have no content at all.
+
+### Error states
+
+A full-screen "empty" error state can help the user make sense of what's going
+on, and how to get back on track. If an entire view goes blank due to an error,
+a single Banner can look out of place.
+
+```tsx
+<Box direction="column" alignItems="center" gap="base" width="100%">
+    <Icon size="large" name="alert" color="critical" />
+    <Heading level={4}>Something went wrong</Heading>
+    <Text>Couldn't load content. Refresh to try again.</Text>
+    <Button label="Refresh" />
+  </Box>
+```
+
+### When the user can't add content
+
+When a card is empty, and there is no way for the user to add content, you
+should still show some form of empty state, but without a CTA.
+
+Do not hide the card, as this state-based hiding and showing may not be
+intuitive for the user. For example, see the ”Payments” card here, where the
+user needs to create an invoice and interact with their client before they can
+create a payment against a job.
+
+## Why
+
+By considering and accounting for these often “un-happy” paths in the user’s
+journey, we can allow the user to learn how to use Jobber more effectively,
+guide them out of troublesome scenarios, and ensure that they never feel like
+they’ve hit a dead-end in the product.
+
+## Implementation
+
+### Web
+
+There's no component but these are some common patterns:
+
+```tsx
+<Box direction="column" alignItems="center" gap="base" width="100%">
+      <Icon size="large" name="alert" />
+      <Heading level={4}>No results found</Heading>
+      <Text>Try adjusting your search criteria or clearing filters</Text>
+      <Button variation="subtle" label="Clear Filters" />
+    </Box>
+```
+
+### Mobile
+
+[EmptyState](../EmptyState/EmptyState.md) gives you the boilerplate
+`Icon` + `Heading` + `Text` + `Button` out of the box but you can also compose it
+similar to the web implementation if more flexibility is needed.
+
+## Not obvious details
+
+In some cases, illustrations may be useful in an empty state to bring some
+personality to the scenario. If this fits your use case, work with the design
+team to find or create an appropriate illustration.
+
+## Related
+
+### Patterns
+
+* [Errors](../errors/errors.md)
+* [Disabled states](../disabled-states/disabled-states.md)
+
+### Components
+
+* [Empty state](../EmptyState/EmptyState.md) mobile component
+
+## Principles
+
+* [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/)
+* [Consistency and standards](https://www.nngroup.com/articles/consistency-and-standards/)
+* [Aesthetics and minimalist design](https://www.nngroup.com/videos/aesthetic-and-minimalist-design/)
+* [Help users recognize, diagnose and recover from errors](https://www.nngroup.com/articles/ten-usability-heuristics/#toc-9-help-users-recognize-diagnose-and-recover-from-errors-9)

package/dist/docs/errors/errors.md

@@ -0,0 +1,114 @@
+# Errors
+
+| **Platform** | **Status** |
+| :----------- | :--------- |
+| Web Mobile   | Ready      |
+
+## Goal
+
+Inform the user when something is wrong, and equip them with the resources to
+set it right whenever possible.
+
+> Good error messages are important, but the best designs carefully prevent
+> problems from occurring in the first place. Either eliminate error-prone
+> conditions, or check for them and present users with a confirmation option
+> before they commit to the action.
+> [– 10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/#toc-5-error-prevention-5)
+
+While avoiding errors is the ideal, it’s largely impossible to avoid *all* of
+the errors, *all* of the time. By being proactive, we can help users recover
+effectively to reduce disruption to their task-at-hand.
+
+## Solution
+
+First and foremost: design to avoid the possibility of errors!
+
+#### Effective content
+
+Follow the guidance in our [product vocabulary](../content/product-vocabulary)
+and [voice & tone](../content/voice-and-tone) guides to help you craft effective
+error messages.
+
+#### Validation and form inputs
+
+Provide a clear, concise message as close as possible to the impacted or
+offending elements.
+
+```tsx
+<InputText invalid placeholder="First name" />
+  <InputValidation message="First name is required" />
+```
+
+#### System or network errors
+
+When an error isn't tied to an inidivual UI element, place a Banner near the
+impacted area. If the issue impacts the entire view, place the banner at the top
+of the view.
+
+```tsx
+<Content>
+    <Text>Be specific about what went wrong when possible</Text>
+    <Banner type="error">
+      <Text>Could not connect to the server</Text>
+    </Banner>
+    <Banner type="error">
+      <Text>The network is taking too long to respond</Text>
+    </Banner>
+    <Text>
+      If for whatever reason, we can't provide more detail to the user, use this
+      generic fallback message:
+    </Text>
+    <Banner type="error">
+      <Text>Something went wrong. Please try again later.</Text>
+    </Banner>
+  </Content>
+```
+
+Whenever possible, avoid showing raw error messages (like
+`500 response timeout`) in the app. Write like a human and explain if there's
+anything the user can do to resolve the issue.
+
+#### System-wide errors
+
+If an issue is not specific to a given screen or user flow, use a "global" error
+message. This should be a banner that runs across the top of the application.
+
+#### Empty states
+
+If content is missing as a result of the error, follow guidance around
+[empty states.](../empty-states/empty-states.md)
+
+## Implementation
+
+### Forms and inputs
+
+Atlantis inputs like [InputText](../InputText/InputText.md) have input validation
+built-in for ease of use. The input validation is integrated with the
+[Form](../Form/Form.md) components on both web and mobile as well.
+
+You can also provide [InputValidation](../components/InputValidation) externally
+if needed.
+
+### System-wide feedback
+
+Jobber has an internal system called "GlobalBanner" that consolidates all
+system-wide messages for presentation on web and mobile. If something critical
+is occurring related to the user's account, it should be displayed in this
+banner.
+
+## Related
+
+### Patterns
+
+* [Empty states](../empty-states/empty-states.md)
+
+### Components
+
+* [Banner](../Banner/Banner.md)
+* [InputText](../components/InputValidation)
+* [InputValidation](../components/InputValidation)
+
+## Principles
+
+* [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/)
+* [Help users recognize, diagnose and recover from errors](https://www.nngroup.com/articles/ten-usability-heuristics/#toc-9-help-users-recognize-diagnose-and-recover-from-errors-9)

package/dist/docs/index.md

@@ -0,0 +1,64 @@
+[ActionItem](./ActionItem/ActionItem.md)
+[ActionItemGroup](./ActionItemGroup/ActionItemGroup.md)
+[ActionLabel](./ActionLabel/ActionLabel.md)
+[ActivityIndicator](./ActivityIndicator/ActivityIndicator.md)
+[Animation](./Animation/Animation.md)
+[AtlantisThemeContext](./AtlantisThemeContext/AtlantisThemeContext.md)
+[AutoLink](./AutoLink/AutoLink.md)
+[Banner](./Banner/Banner.md)
+[Borders](./Borders/Borders.md)
+[BottomSheet](./BottomSheet/BottomSheet.md)
+[Button](./Button/Button.md)
+[ButtonGroup](./ButtonGroup/ButtonGroup.md)
+[Card](./Card/Card.md)
+[Checkbox](./Checkbox/Checkbox.md)
+[Chip](./Chip/Chip.md)
+[choosing-components](./choosing-components/choosing-components.md)
+[Colors](./Colors/Colors.md)
+[Content](./Content/Content.md)
+[ContentOverlay](./ContentOverlay/ContentOverlay.md)
+[customizing-components](./customizing-components/customizing-components.md)
+[disabled-states](./disabled-states/disabled-states.md)
+[Disclosure](./Disclosure/Disclosure.md)
+[Divider](./Divider/Divider.md)
+[Elevations](./Elevations/Elevations.md)
+[empty-states](./empty-states/empty-states.md)
+[EmptyState](./EmptyState/EmptyState.md)
+[errors](./errors/errors.md)
+[Flex](./Flex/Flex.md)
+[Form](./Form/Form.md)
+[FormatFile](./FormatFile/FormatFile.md)
+[FormField](./FormField/FormField.md)
+[Glimmer](./Glimmer/Glimmer.md)
+[Heading](./Heading/Heading.md)
+[Icon](./Icon/Icon.md)
+[IconButton](./IconButton/IconButton.md)
+[InputCurrency](./InputCurrency/InputCurrency.md)
+[InputDate](./InputDate/InputDate.md)
+[InputEmail](./InputEmail/InputEmail.md)
+[InputFieldWrapper](./InputFieldWrapper/InputFieldWrapper.md)
+[InputNumber](./InputNumber/InputNumber.md)
+[InputPassword](./InputPassword/InputPassword.md)
+[InputPressable](./InputPressable/InputPressable.md)
+[InputSearch](./InputSearch/InputSearch.md)
+[InputText](./InputText/InputText.md)
+[InputTime](./InputTime/InputTime.md)
+[interaction](./interaction/interaction.md)
+[Opacity](./Opacity/Opacity.md)
+[page-layouts](./page-layouts/page-layouts.md)
+[ProgressBar](./ProgressBar/ProgressBar.md)
+[Radii](./Radii/Radii.md)
+[ResponsiveBreakpoint](./ResponsiveBreakpoint/ResponsiveBreakpoint.md)
+[scaffolding](./scaffolding/scaffolding.md)
+[Select](./Select/Select.md)
+[settings](./settings/settings.md)
+[Spacing](./Spacing/Spacing.md)
+[StatusLabel](./StatusLabel/StatusLabel.md)
+[Switch](./Switch/Switch.md)
+[Text](./Text/Text.md)
+[TextList](./TextList/TextList.md)
+[ThumbnailList](./ThumbnailList/ThumbnailList.md)
+[Toast](./Toast/Toast.md)
+[Typography](./Typography/Typography.md)
+[Typography](./Typography/Typography.md)
+[usage-guidelines](./usage-guidelines/usage-guidelines.md)