@jobber/components-native 0.101.5 → 0.101.6

package/dist/docs/interaction/interaction.md

@@ -0,0 +1,109 @@
+# Interaction
+
+| **Platform** | **Status** |
+| :----------- | :--------- |
+| Web Mobile   | Ready      |
+
+## Goal
+
+Provide feedback (or feedforward) to the user in a consistent way to help them
+predict what will happen when they engage with Jobber.
+
+## Use when...
+
+An interactive element is... being interacted with.
+
+## Solution
+
+### Web
+
+```tsx
+<Card header="Interactive element example" url="#">
+            <Content>
+            <Text>This card has examples of hover and focus states for the web</Text>
+            <InputText placeholder="Inputs change too" />
+            </Content>
+        </Card>
+```
+
+#### Hover
+
+* background-color increases contrast with the surface
+* cursor changes to a pointer
+
+#### Focused with keyboard (:focus-visible)
+
+* background-color increases contrast with the surface
+* a custom focus ring is applied
+
+#### Timing
+
+Most state transitions use `var(--timing-base) ease-out` for a pleasant
+transition.
+
+#### CSS implementation
+
+Atlantis components come with these states handled, but if you're extending or
+creating custom elements, this is the general pattern used to achieve an "Atlantis"
+interactive state.
+
+```css
+.myElement {
+    background-color: var(--color-surface);
+    /* apply consistent transitions to background and box-shadow */
+    transition: all var(--timing-base) ease-out;
+    cursor: pointer;
+    /* hide the default focus ring, but still support "high contrast" modes */
+    outline: transparent;
+}
+
+.myElement:hover,
+/* use :focus-visible instead of :focus to reduce visual noise for mouse users */
+.myElement:focus-visible {
+    background-color: var(--color-surface--hover);
+}
+
+.myElement:focus-visible {
+    box-shadow: var(--shadow-focus);
+}
+```
+
+### Mobile
+
+#### Pressed
+
+* Most elements will reduce in opacity using the `opacity-pressed` token
+
+#### Focused inputs
+
+* While there is no system-wide "focus ring" in mobile, input borders change color when focused
+
+#### React Native implementation
+
+```.ts
+// as a classname in styles.ts files
+
+pressed {
+    opacity: tokens["opacity-pressed"]
+}
+```
+
+```.ts
+// as a property on react-native core components
+
+<TouchableOpacity
+    activeOpacity={tokens["opacity-pressed"]}
+    onPress={yourActionHere}
+>
+```
+
+## Related
+
+* [Disabled states](../disabled-states/disabled-states.md)
+* [Color](../design/color)
+* [Animation](../Animation/Animation.md)
+
+## Principles
+
+* [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/)
+* [Consistency and standards](https://www.nngroup.com/articles/consistency-and-standards/)

package/dist/docs/page-layouts/page-layouts.md

@@ -0,0 +1,323 @@
+# Page layouts
+
+These layout components are designed to help you easily build smaller-scale layouts without needing to reach for CSS.  
+More complex full-page scaffolding can be found on the [Scaffolding](../scaffolding/scaffolding.md) page.  
+
+```tsx
+<Stack>
+    <Heading level={1}>Stack</Heading>
+    <Text>The Stack component is used to create a vertical stack of elements. It is a flex container that aligns items in a column direction.</Text>
+  </Stack>
+```
+
+```tsx
+<Stack>
+    <Heading level={2}>Stack Form Layouts</Heading>
+    <Text>Every item stacks with equal spacing and a responsive vertical rhythm.</Text>
+    <Stack>
+      <FormFieldLabel external>Name</FormFieldLabel>
+      <InputText label="Name" />
+      <FormFieldLabel external>Email</FormFieldLabel>
+      <InputText label="Email" />
+    </Stack>
+  </Stack>
+```
+
+```tsx
+<Stack>
+    <Heading level={2}>Stack Card Layouts</Heading>
+    <Text>Stacks are a great way to layout content in a card format. They are responsive and easy to read.</Text>
+    <Cluster>
+      <Card elevation="base">
+        <Box padding="base">
+          <Stack>
+            <Heading level={3}>Card Layout</Heading>
+            <Text>A card with a header, body text, and footer</Text>
+            <Button label="Button" />
+            <Text>And they're all stacked vertically</Text>
+            <Text>with equal spacing</Text>
+          </Stack>
+        </Box>
+      </Card>
+    </Cluster>
+  </Stack>
+```
+
+```tsx
+<Stack>
+    <Heading level={1}>Cluster</Heading>
+    <Text>The Cluster component is used to create a horizontal stack of elements. It is a flex container that aligns items in a row direction.</Text>
+    <Cluster>
+      <Chip label="Cluster Chip" />
+      <Heading level={5}>These are all in a cluster</Heading>
+      <Button label="Clustered items have variable widths" />
+      <Text>They wrap when they run out of space</Text>
+      </Cluster>
+  </Stack>
+```
+
+```tsx
+<Stack>
+    <Heading level={2}>Spaced Out Cluster</Heading>
+    <Text>The Cluster component has a default space of 12px between items. You can customize this space by passing the gap prop.</Text>
+
+      <Cluster gap="larger">
+        <Chip label="There" />
+        <Chip label="is" />
+        <Chip label="a" />
+        <Chip label="default" />
+        <Chip label="space" />
+        <Chip label="between" />
+        <Chip label="items" />
+        <Chip label="that" />
+        <Chip label="you" />
+        <Chip label="can" />
+        <Chip label="customize" />
+      </Cluster>
+      </Stack>
+```
+
+```tsx
+<Stack>
+  <Typography size="largest" align="end" fontWeight="bold">Justified Cluster</Typography>
+  <Text align="end">The Cluster component has a default horizontal alignment of start. You can customize this alignment by passing the justify prop.</Text>
+  <Cluster justify="end">
+        <Chip label="You" />
+        <Chip label="can" />
+        <Chip label="justify" />
+        <Chip label="the items" />
+        <Chip label="in the cluster" />
+        <Chip label="horizontally" />
+      </Cluster>
+</Stack>
+```
+
+```tsx
+<Stack>
+  <Heading level={2}>Aligned Cluster</Heading>
+  <Text>The Cluster component has a default vertical alignment of top/start. You can customize this alignment by passing the align prop.</Text>
+  <Cluster align="center">
+        <Chip label="You can also align" />
+          <Text>  
+            items vertically
+          </Text>
+          <div style={{ height: "100px", backgroundColor: "var(--color-surface--background)", width:200 }}>
+          &nbsp;
+          </div>
+      </Cluster>
+  </Stack>
+```
+
+```tsx
+<Stack>
+  <Heading level={1}>Tiles</Heading>
+    <Text>The Tiles component is used to create a horizontal grid of fixed-width items. 
+    It is a flexible container that aligns items horizontally and will start moving items to the next row when there is no more room.</Text>
+  <Tiles minSize="15ch" gap="12px">
+    <Text>Here is a longer bit of repeated copy that will surely cause the tile to wrap.</Text>
+    <Text>Here is a longer bit of repeated copy that will surely cause the tile to wrap.</Text>
+    <Text>Here is a longer bit of repeated copy that will surely cause the tile to wrap.</Text>
+    <Text>Here is a longer bit of repeated copy that will surely cause the tile to wrap.</Text>
+  </Tiles>
+  </Stack>
+```
+
+```tsx
+<Stack>
+    <Heading level={1}>Cover</Heading>
+    <Text>The Cover component is used to create an arbitrary height layout with an option to center content and have content above/below the centered content.</Text>
+    <Cover minHeight="30vh">
+      <Cover.Center>
+        <Box padding="base" background="surface--background">
+        <Stack>
+        <Heading level={2}>Centered Content</Heading>
+        <Box colorSurface="color-text" colorInverse="color-surface" invert>
+            <Text>This is a square</Text>
+        </Box>
+        </Stack>
+      </Box>
+      </Cover.Center>
+    </Cover>
+  </Stack>
+```
+
+```tsx
+<Cover minHeight="40vh">
+      <Stack>
+        <Heading level={2}>Cover with a heading</Heading>
+        <Text>You can place content above and below the centered content and align it any way you want, and the centered content will always be centered in the provided parent space.</Text>
+      </Stack>
+      <Cover.Center>
+        <Box background="color-surface--background">
+          <Text>This is the centered content</Text>
+        </Box>
+      </Cover.Center>
+        <Box background="color-surface--background">
+        <Stack>
+          <Heading level={2}>Cover Footer Content</Heading>
+          <Text>This is the footer content</Text>
+        </Stack>
+      </Box>
+    </Cover>
+```
+
+```tsx
+<ContentBlock maxWidth="100%">
+      <Stack>
+        <Heading level={1}>Content Block</Heading>
+        <Text>The ContentBlock component is used to horizontally justify and limit content.</Text>
+      </Stack>
+      </ContentBlock>
+```
+
+```tsx
+<ContentBlock maxWidth="300px" justify="center" andText>
+      <Stack>
+      <Heading level={1}>Text Center</Heading>
+      <Text>The `andText` prop will center the text as well as the content.</Text>
+      </Stack>
+      </ContentBlock>
+```
+
+```tsx
+<ContentBlock maxWidth="200px">
+      <Stack>
+        <Heading level={2}>Max Width</Heading>
+        <Text>The Center component can also take a `maxWidth` prop to limit the width of the content.</Text>
+      </Stack>  
+    </ContentBlock>
+```
+
+```tsx
+<ContentBlock gutters="largest">
+      <Stack>
+        <Heading level={2}>Gutters</Heading>
+        <Text>The Center component can also take a `gutters` prop to add minimum space between the content and the edges of the parent so the content never touches the edge of the parent/screen. This space only applies to the element when required, not by default.</Text>
+      </Stack>
+    </ContentBlock>
+```
+
+```tsx
+<Stack>
+  <Heading level={1}>Frame</Heading>
+  <Text>The Frame component is used to create an aspect ratio with a layout. It's especially good at handling images and videos and cropping them to fit the aspect ratio (default 16x9).</Text>
+  <Frame>
+    <img src="/img_collage.jpg" alt="Placeholder" />
+  </Frame>
+ 
+  </Stack>
+```
+
+```tsx
+<Stack>
+      <Heading level={2}>1x1</Heading>
+        <Frame aspectX={1} aspectY={1}>
+          <img src="/img_collage.jpg" alt="Placeholder" />
+        </Frame>
+    </Stack>
+```
+
+```tsx
+<Stack>
+      <Heading level={2}>4x3</Heading>
+        <Frame aspectX={4} aspectY={3}>
+          <img src="/img_collage.jpg" alt="Placeholder" />
+        </Frame>
+    </Stack>
+```
+
+```tsx
+<Frame>
+    <Cover>
+      <Heading level={2}>It Works for Content As Well</Heading>
+      <Text>Everything is centered and cropped to fit the aspect ratio.</Text>
+    </Cover>
+  </Frame>
+```
+
+```tsx
+<Stack>
+    <Heading level={1}>Responsive Switcher</Heading>
+    <Text>The Responsive Switcher component is used to create a responsive layout that will automatically swap from horizontal to vertical when the content exceeds the threshold.</Text>
+    <ResponsiveSwitcher threshold="60ch" gap="12px" limit={2}>
+      <Box padding="base" background="surface--background">
+          <Heading level={3}>Content on the left/top</Heading>
+      </Box>
+      <Box padding="base" background="surface--background">
+        <Heading level={3}>Content on the right/bottom</Heading>
+      </Box>
+    </ResponsiveSwitcher>
+  </Stack>
+```
+
+```tsx
+<ResponsiveSwitcher threshold="50ch" limit={3}>
+      <Card elevation="base">
+          <Box padding="base">
+          <Heading level={3}>Some Card Content</Heading>
+        </Box>
+      </Card>
+       <Card elevation="base">
+        <Box padding="base">
+          <Heading level={3}>Some Card Content</Heading>
+        </Box>
+      </Card>
+      <Card elevation="base">
+        <Box padding="base">
+          <Heading level={3}>Some Card Content</Heading>
+        </Box>
+      </Card>
+      </ResponsiveSwitcher>
+```
+
+```tsx
+<Stack>
+  <Heading level={1}>Sidekick</Heading>
+  <Text>The Sidekick component is used to create a horizontal layout where one half of the content is fixed width, and the other half is fluid. Where there is no longer the specified sideWidth space remaining, the content will wrap to the next line.</Text>
+  <SideKick sideWidth="120px" contentMinWidth="60%">
+      <InputText placeholder="Sidekick Input" />
+      <Button label="Sidekick Button" />
+    </SideKick>
+  </Stack>
+```
+
+```tsx
+<SideKick sideWidth="60%" contentMinWidth="200px">
+      <Cover>
+        <Cover.Center>
+        <Stack>
+        <Heading level={2}>Sidekick Content</Heading>
+        <Text>The Sidekick component is used to create a horizontal layout where one half of the content is fixed width, and the other half is fluid. Where there is no longer the specified sideWidth space remaining, the content will wrap to the next line.</Text>
+        </Stack>
+        </Cover.Center>
+        </Cover>
+      <Frame aspectX={9} aspectY={16}>
+         <img src="/img_collage.jpg" alt="Placeholder" />
+      </Frame>
+    </SideKick>
+```
+
+Container
+Containers are for isolating style overrides to a specific layout. Set a container name, and apply associated styles where needed.
+Containers are just container queries, and are fairly advanced. Only use them when absolutely necessary.
+We will soon provide a set of predfined Containers and styles for common layout pattern adjustments.
+You can also create your own containers and portable style overrides with these tools.
+
+Container Example
+We've overridden the default styles without having to modify any existing code or styles.
+
+Container Example
+These cards are functionally identical except they have different container queries based on their content widths.
+
+Container Example
+They're also perfectly portable. If you just need the layout, take everything under the Container.Apply. If you want the wrapper but not the container styles, grab the Container.Apply as well. Or, just re-use the container elsewhere to wrap other content.
+
+Container Example
+This last example is exactly the same as the others, except it's not in the container.
+
+```tsx
+<Stack>
+  <Heading level={1}>Looking For More?</Heading>
+  <Text>Check out the [Scaffolding](../scaffolding/scaffolding.md) page to see how to layout full pages with these components</Text>
+  </Stack>
+```

package/dist/docs/scaffolding/scaffolding.md

@@ -0,0 +1,109 @@
+# Scaffolding
+
+Scaffolding are full-page layouts to ensure consistency across the app and full
+responsive behavior for free.
+
+Legacy Page
+
+```tsx
+<Page
+    title="Page"
+    subtitle="Subtitle goes here"
+    primaryAction={{ label: "Action 1" }}
+    secondaryAction={{ label: "Action 2" }}
+    moreActionsMenu={[
+      {
+        actions: [
+          {
+            label: "Action 1",
+            onClick: () => {
+              console.log("Action 1");
+            },
+          },
+          {
+            label: "Action 2",
+            onClick: () => {
+              console.log("Action 2");
+            },
+          },
+        ],
+      },
+    ]}
+  >
+    <Text>Children Go Here</Text>
+  </Page>
+```
+
+Composed Page With New Layout Components
+
+```tsx
+<ContentBlock align="left" maxWidth="1285px">
+    <Box padding="base">
+      <Stack gap="larger">
+        <SideKick contentMinWidth="40%" sideWidth="20ch" collapseBelow="1285px">
+          <Stack>
+            <Heading level={1}>Page</Heading>
+            <Text size="large" variation="subdued">
+              <Emphasis variation="bold">Subtitle goes here</Emphasis>
+            </Text>
+          </Stack>
+          <Cluster justify="end" gap="small" collapseBelow="1285px">
+            <Button label="Action 1" />
+            <Button label="Action 2" type="secondary" />
+            <Menu
+              items={[
+                {
+                  actions: [{ label: "Action 1" }, { label: "Action 2" }],
+                  label: "Action 3",
+                },
+              ]}
+            />
+          </Cluster>
+        </SideKick>
+        <Text>Children Go Here</Text>
+      </Stack>
+    </Box>
+  </ContentBlock>
+```
+
+Composed Page With New Layout Components + Container Query
+
+```tsx
+<Container name="container-items">
+    <Box padding="base">
+      <ContentBlock align="left" maxWidth="1285px">
+        <Stack gap="larger">
+          <SideKick
+            collapseBelow="1285px"
+            contentMinWidth="30%"
+            sideWidth="20ch"
+          >
+            <Stack>
+              <Heading level={1}>Page</Heading>
+              <Text size="large" variation="subdued">
+                <Emphasis variation="bold">Subtitle goes here</Emphasis>
+              </Text>
+            </Stack>
+            <Box>
+              <Container.Apply className={styles.actions}>
+                <Cluster justify="end" gap="small">
+                  <Button label="Action 1" />
+                  <Button label="Action 2" type="secondary" />
+                  <Menu
+                    items={[
+                      {
+                        actions: [{ label: "Action 1" }, { label: "Action 2" }],
+                        label: "Action 3",
+                      },
+                    ]}
+                  />
+                </Cluster>
+              </Container.Apply>
+            </Box>
+          </SideKick>
+          <Text>Children Go Here</Text>
+        </Stack>
+      </ContentBlock>
+    </Box>
+  </Container>
+```

package/dist/docs/settings/settings.md

@@ -0,0 +1,58 @@
+# Settings
+
+| **Platform** | **Status** |
+| :----------- | :--------- |
+| Web          | Ready      |
+
+## Goal
+
+Allow the user to consistently manage settings for their account or for specific
+features within the application.
+
+## Use when…
+
+Something about the user's account or functionality needs to be managed and it
+
+* can't be done in the context of the main application
+* involves setting a default that does not frequently change
+* has a group of related options that are better managed in a single place
+
+## Solution
+
+Under the appropriate section in the Settings menu, add a setting for the
+feature.
+
+Most settings can be managed with the
+[FeatureSwitch](../components/FeatureSwitch) component, which allows:
+
+* turning functionality on and off
+* editing aspects of the feature via a [Modal](../components/Modal)
+* if the page supports it, live updates to the setting
+
+### Grouping settings
+
+Use a [Card](../Card/Card.md) to group related settings together.
+
+## Implementation
+
+The [FeatureSwitch](../components/FeatureSwitch) component is a good starting
+point for most settings. If the setting is more complex, you can trigger a
+[Modal](../components/Modal) to edit the setting.
+
+For cases where you don't need the full functionality of the `FeatureSwitch`,
+you can either opt out of props like `onSwitch` or `onEdit`, or compose a layout
+of the pieces you do need.
+
+## Related
+
+### Components
+
+* [FeatureSwitch](../components/FeatureSwitch)
+* [Card](../Card/Card.md)
+* [Modal](../components/Modal)
+* [Switch](../Switch/Switch.md)
+
+## 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)