@nypl/design-system-react-components 1.0.1 → 1.0.2

package/src/components/Chakra/Flex.stories.mdx

@@ -0,0 +1,111 @@
+import { Box, Flex, Spacer, VStack } from "@chakra-ui/react";
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+
+import Heading from "../Heading/Heading";
+import Link from "../Link/Link";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Flex")} component={Flex} />
+
+# Flex
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.10`  |
+| Latest            | `0.25.10`  |
+
+Note: This needs the use of the `DSProvider` component. See the
+[README](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/story/chakra-ui--page#dsprovider)
+for more information.
+
+This component is directly exported from Chakra UI. The `Flex` component is
+useful for simple layouts and can be used along with Chakra's `Spacer` component.
+The combination can be used to create a container where the children span the
+entire width of the container.
+
+Details about available props and related child components can be found on the
+[Flex component](https://chakra-ui.com/docs/layout/flex) page on the Chakra UI site.
+
+<Canvas>
+  <Story
+    name="Flex"
+    args={{
+      alignItems: "baseline",
+    }}
+  >
+    {(args) => (
+      <Flex {...args}>
+        <Box w="20" h="20" bg="brand.primary" />
+        <Box w="20" h="20" bg="brand.secondary" />
+        <Box w="20" h="20" bg="brand.primary" />
+        <Box w="20" h="20" bg="brand.secondary" />
+        <Box w="20" h="20" bg="brand.primary" />
+      </Flex>
+    )}
+  </Story>
+</Canvas>
+
+## Examples
+
+Use the `justify` prop to move the children around.
+
+<Canvas>
+  <DSProvider>
+    <VStack align="stretch">
+      <div>
+        <p>`justify` set to "center"</p>
+        <Flex alignItems="baseline" justify="center">
+          <Box w="20" h="20" bg="brand.primary" />
+          <Box w="20" h="20" bg="brand.secondary" />
+          <Box w="20" h="20" bg="brand.primary" />
+          <Box w="20" h="20" bg="brand.secondary" />
+          <Box w="20" h="20" bg="brand.primary" />
+        </Flex>
+      </div>
+      <div>
+        <p>`justify` set to "space-between"</p>
+        <Flex alignItems="baseline" justify="space-between">
+          <Box w="20" h="20" bg="brand.primary" />
+          <Box w="20" h="20" bg="brand.secondary" />
+          <Box w="20" h="20" bg="brand.primary" />
+          <Box w="20" h="20" bg="brand.secondary" />
+          <Box w="20" h="20" bg="brand.primary" />
+        </Flex>
+      </div>
+    </VStack>
+  </DSProvider>
+</Canvas>
+
+## With Spacer
+
+A common use-case is displaying a row with two children where the first aligns
+left and the second aligns right. Add the `Spacer` component between the children.
+This is similar to setting `justify="space-between"` on the `Flex` parent but
+the `Spacer` component is more flexible for most situations.
+
+<Canvas>
+  <DSProvider>
+    <Flex alignItems="baseline">
+      <Heading id="row-heading" level="three">
+        Heading
+      </Heading>
+      <Spacer />
+      <Link href="#viewmore" type="forwards">
+        View more
+      </Link>
+    </Flex>
+  </DSProvider>
+</Canvas>
+
+```jsx
+<Flex alignItems="baseline">
+  <Heading id="row-heading" level="three">
+    Heading
+  </Heading>
+  <Spacer />
+  <Link href="#viewmore" type="forwards">
+    View more
+  </Link>
+</Flex>
+```

package/src/components/Chakra/Grid.stories.mdx

@@ -0,0 +1,89 @@
+import { Box, Grid, GridItem } from "@chakra-ui/react";
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Grid")} component={Grid} />
+
+# Grid
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.1`   |
+| Latest            | `0.25.1`   |
+
+Note: This needs the use of the `DSProvider` component. See the
+[README](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/story/chakra-ui--page#dsprovider)
+for more information.
+
+This component is directly exported from Chakra UI. The `Grid` component is
+useful for grid layouts and offers more complexity and formatting options than
+the Reservoir Design System (DS) `SimpleGrid` component. `Grid` is `Box` with `display: grid` and it comes
+with helpful style shorthand. It renders a `div` element.
+
+Details about available props and related child components can be found on the
+[Grid component](https://chakra-ui.com/docs/layout/grid) page on the Chakra UI site.
+
+<Canvas>
+  <Story
+    name="Grid"
+    args={{
+      templateColumns: "repeat(5, 1fr)",
+      gap: "grid.default",
+    }}
+  >
+    {(args) => (
+      <Grid {...args}>
+        <Box w="100%" h="20" bg="brand.primary" />
+        <Box w="100%" h="20" bg="brand.secondary" />
+        <Box w="100%" h="20" bg="brand.primary" />
+        <Box w="100%" h="20" bg="brand.secondary" />
+        <Box w="100%" h="20" bg="brand.primary" />
+        <Box w="100%" h="20" bg="brand.secondary" />
+        <Box w="100%" h="20" bg="brand.primary" />
+        <Box w="100%" h="20" bg="brand.secondary" />
+        <Box w="100%" h="20" bg="brand.primary" />
+        <Box w="100%" h="20" bg="brand.secondary" />
+      </Grid>
+    )}
+  </Story>
+</Canvas>
+
+## Complex Layouts with Grid Child Components
+
+In some layouts, you may need certain grid items to span a specific amount of
+columns or rows instead of an even distribution. To achieve this, you need to
+pass the `colSpan` prop to the `GridItem` component to span across columns and
+also pass the `rowSpan` component to span across rows. You also need to specify
+the `templateColumns` and `templateRows`.
+
+<Canvas>
+  <DSProvider>
+    <Grid
+      height="200px"
+      templateRows="repeat(2, 1fr)"
+      templateColumns="repeat(5, 1fr)"
+      gap="grid.default"
+    >
+      <GridItem rowSpan={2} colSpan={1} bg="ui.link.primary" />
+      <GridItem colSpan={2} bg="ui.success.primary" />
+      <GridItem colSpan={2} bg="ui.success.secondary" />
+      <GridItem colSpan={4} bg="ui.link.secondary" />
+    </Grid>
+  </DSProvider>
+</Canvas>
+
+```jsx
+<Grid
+  height="200px"
+  templateRows="repeat(2, 1fr)"
+  templateColumns="repeat(5, 1fr)"
+  gap="grid.default"
+>
+  <GridItem rowSpan={2} colSpan={1} bg="ui.link.primary" />
+  <GridItem colSpan={2} bg="ui.success.primary" />
+  <GridItem colSpan={2} bg="ui.success.secondary" />
+  <GridItem colSpan={4} bg="ui.link.secondary" />
+</Grid>
+```

package/src/components/Chakra/Stack.stories.mdx

@@ -0,0 +1,109 @@
+import { Meta, Story, Canvas } from "@storybook/addon-docs";
+import { Box, Stack, HStack, VStack, Circle } from "@chakra-ui/react";
+
+import Icon from "../Icons/Icon";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Stack, HStack, VStack")} component={Stack} />
+
+# Stack, HStack, VStack
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.24.0`   |
+
+Note: This needs the use of the `DSProvider` component. See the
+[README](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/story/chakra-ui--page#dsprovider)
+for more information.
+
+These components are directly exported from Chakra UI. The `Stack`, `HStack`,
+and `VStack` are layout component that makes it easy to stack elements together
+with spacing between them.
+
+All available props can be found on the [Style Props](https://chakra-ui.com/docs/features/style-props)
+guide on the Chakra UI site.
+
+In all the following examples, Design System `Icon` components are wrapped in
+Chakra's `Circle` component.
+
+## Stack
+
+The `Stack` component is the most flexible component because it can stack
+elements both horizontally and vertically through the `direction` prop and the
+`"row"` and `"column"` values, respectively.
+
+<Canvas>
+  <Story
+    name="Stack, HStack, VStack"
+    args={{
+      direction: "column",
+      spacing: "s",
+    }}
+    argTypes={{
+      direction: {
+        control: {
+          type: "select",
+        },
+        options: ["column", "row"],
+      },
+    }}
+  >
+    {(args) => (
+      <Stack {...args}>
+        <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+          <Icon name="errorFilled" size="large" />
+        </Circle>
+        <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+          <Icon name="errorOutline" size="large" />
+        </Circle>
+        <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+          <Icon name="check" size="large" />
+        </Circle>
+      </Stack>
+    )}
+  </Story>
+</Canvas>
+
+## HStack
+
+Stacks components horizontally. This is the same as the `Stack` component with
+a `direction` value of `"row"`.
+
+<Canvas>
+  <DSProvider>
+    <HStack spacing="s">
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="errorFilled" size="large" />
+      </Circle>
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="errorOutline" size="large" />
+      </Circle>
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="check" size="large" />
+      </Circle>
+    </HStack>
+  </DSProvider>
+</Canvas>
+
+## VStack
+
+Stacks components vertically. This is the same as the `Stack` component with
+a `direction` value of `"column"`.Pass in a value to the `align` prop to align
+all the elements in the stack.
+
+<Canvas>
+  <DSProvider>
+    <VStack align="left" spacing="s">
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="errorFilled" size="large" />
+      </Circle>
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="errorOutline" size="large" />
+      </Circle>
+      <Circle size="50px" borderColor="ui.black" borderWidth="1px">
+        <Icon name="check" size="large" />
+      </Circle>
+    </VStack>
+  </DSProvider>
+</Canvas>

package/src/components/Checkbox/Checkbox.stories.mdx

@@ -0,0 +1,243 @@
+import { HStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Checkbox from "./Checkbox";
+import { onChangeDefault } from "./Checkbox";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Checkbox")}
+  component={Checkbox}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=11895%3A658",
+    },
+    jest: ["Checkbox.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    id: { control: false },
+    isChecked: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isIndeterminate: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    key: { table: { disable: true } },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: false } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: false } },
+    },
+  }}
+/>
+
+# Checkbox
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.1.0`    |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Checked](#checked)
+- [Indeterminate](#indeterminate)
+- [Focused](#focused)
+- [Errored](#errored)
+- [Disabled](#disabled)
+- [Helper Text](#helper-text)
+- [Error Text](#error-text)
+- [With JSX Element Label](#with-jsx-element-label)
+
+## Overview
+
+<Description of={Checkbox} />
+
+This component renders a Checkbox button form element. See below for configuration
+information. Note that the `id` property, while optional, will cause an
+accessibility violation if none is present.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Checkbox"
+    args={{
+      className: undefined,
+      helperText: "This is the helper text!",
+      id: "checkbox_id",
+      invalidText: "This is the error text :(",
+      isChecked: undefined,
+      isDisabled: false,
+      isIndeterminate: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Test Label",
+      name: "test_name",
+      onChange: undefined,
+      showHelperInvalidText: true,
+      showLabel: true,
+      value: "1",
+    }}
+  >
+    {(args) => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Checkbox" />
+
+## Accessibility
+
+The `Checkbox` component renders `<label>` and `<input type="checkbox" />`
+elements that are associated with each other; the label has a `for` attribute
+with the value of the `input`'s `id` element. If there is helper or invalid text,
+the `<input>` element will have a `aria-describedby` attribute with the value of
+the helper or invalid text.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+`<input>`'s `aria-label` attribute.
+
+Resources:
+
+- [W3C WAI ARIA Checkbox Example](https://www.w3.org/TR/wai-aria-practices-1.1/examples/checkbox/checkbox-1/checkbox-1.html)
+- [a11ymatters Accessible Checkbox](https://www.a11ymatters.com/pattern/checkbox/)
+- [MDN ARIA: checkbox role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role)
+- [Chakra UI Checkbox](https://chakra-ui.com/docs/components/form/checkbox)
+
+## Checked
+
+Note that the `isChecked` property in this example is set to `true` and clicking
+on it won't remove the checkmark; the `isChecked` prop must now be controlled
+and removed manually by the parent component that controls this state.
+
+<Canvas>
+  <DSProvider>
+    <Checkbox id="isChecked" labelText="I am checked" isChecked value="1" />
+  </DSProvider>
+</Canvas>
+
+## Indeterminate
+
+Note: This state only changes the icon through the `isIndeterminate` prop. This
+does not affect whether the checkbox is checked. The `isIndeterminate` prop must
+now be controlled and removed by the parent component in order to remove this state.
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="indeterminate"
+      labelText="I am indeterminate"
+      isIndeterminate
+    />
+  </DSProvider>
+</Canvas>
+
+## Focused
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="focused"
+      labelText="Click or tab to the Checkbox to see its focus state"
+    />
+  </DSProvider>
+</Canvas>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <HStack>
+      <Checkbox id="invalid" isInvalid labelText="I am in an error state" />
+      <Checkbox
+        id="invalid-checked"
+        isInvalid
+        isChecked
+        labelText="I am checked in an error state"
+      />
+    </HStack>
+  </DSProvider>
+</Canvas>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <HStack>
+      <Checkbox id="disabled" isDisabled labelText="I am disabled" />
+      <Checkbox
+        id="disabled-checked"
+        isDisabled
+        isChecked
+        labelText="I am checked and disabled"
+      />
+    </HStack>
+  </DSProvider>
+</Canvas>
+
+## Helper Text
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="helpertext"
+      name="testHelperText"
+      labelText="I have helper text"
+      helperText="I am the helper text for this Checkbox"
+    />
+  </DSProvider>
+</Canvas>
+
+## Error Text
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="invalid-text"
+      invalidText="I am the error text for this Checkbox"
+      isInvalid
+      name="testinvalidText"
+      labelText="I have error text"
+    />
+  </DSProvider>
+</Canvas>
+
+## With JSX Element Label
+
+This is useful when you want to add dynamic content to the label or add
+a layout to the label. View the `CheckboxGroup` documentation for this
+usage.
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="jsx-label"
+      labelText={<span>Arts</span>}
+      name="jsxElementLabel"
+    />
+  </DSProvider>
+</Canvas>