@nypl/design-system-react-components 1.0.0 → 1.0.3-beta

package/src/docs/Chakra.stories.mdx

@@ -1,563 +0,0 @@
-import { Meta } from "@storybook/addon-docs";
-
-import Button from "../components/Button/Button";
-import Text from "../components/Text/Text";
-import DSProvider from "../theme/provider";
-
-<Meta title="Chakra UI" />
-
-# Chakra UI
-
-| Table of Contents                   |
-| ----------------------------------- |
-| 1. [Why Chakra UI?](#why-chakra-ui) |
-| 2. [DSProvider](#dsprovider)        |
-| 3. [Components](#components)        |
-| 4. [Styling](#styling)              |
-| 5. [Style Props](#style-props)      |
-| 6. [Hooks](#hooks)                  |
-| 7. [Testing](#testing)              |
-
-## Why Chakra UI?
-
-The Reservoir Design System (DS) project was influenced by other design systems but
-ultimately we decided to initially build DS components from scratch rather than
-use another design system as its foundation. To better help all the projects at
-NYPL and to better scale with all the components we have built and still need to
-build, we decided to integrate Chakra UI into the DS.
-
-Chakra UI is an open source component library that is opinionated and uses design
-and development patterns that various projects at NYPL use. Since the DS
-will be the foundation for all NYPL projects moving forward, using Chakra will
-help us align all projects so similar patterns are used throughout various teams
-and projects.
-
-Chakra follows WAI-ARIA and WCAG 2.1 standards and guidelines which aligns with
-the standards that NYPL follows for its own components and applications.
-
-With design and development consistency, the ability to customize components
-_if necessary_, and accessibility standards in place, developers at NYPL using
-the Design System will be able to build out applications faster.
-
-We recommend to read Chakra's own [documentation](https://chakra-ui.com/docs/getting-started)
-to get up to speed on it. This file will provide information on how it is used
-in the DS but we rely on Chakra's documentation.
-
-If you need help updating to a newer version of the DS, check out
-our [Chakra Migration Guide](https://github.com/NYPL/nypl-design-system/blob/development/CHAKRA_MIGRATION_GUIDE.md).
-
-## DSProvider
-
-In order to use DS components in a consuming application, there is a necessary
-step that must be done for component styles to properly render. Consuming
-applications need to wrap all the DS components with a simple provider
-component. Fortunately, this only needs to be done once at the top level of the
-consuming application.
-
-Once the following is completed, DS components that internally use Chakra UI
-will render styles properly. Internally, the `DSProvider` is built on top of
-Chakra's `ChakraProvider` component with NYPL's custom theme as input. This sets
-up the style context to propogate through all the children nodes in the DOM tree.
-
-```tsx
-// your main application file
-import { DSProvider } from "@nypl/design-system-react-components";
-
-// ...
-const Application = (props) => {
-  // ...
-  return (
-    <DSProvider>
-      <header>...</header>
-      <div className="my-app">
-        // ...
-        {children}
-      </div>
-      <footer>...</footer>
-    </DSProvider>
-  );
-};
-```
-
-### Chakra Components in Storybook
-
-Storybook is configured to use the `DSProvider` so that components can render
-appropriately. Unfortunately, this only works within the `Story` component.
-When rendering components in documentation examples within a `Canvas` component,
-wrap the elements in the `DSProvider` component.
-
-```tsx
-// These buttons are not a part of a "story" but still appear only
-// in the documentation.
-<Canvas>
-  <DSProvider>
-    <ButtonGroup>
-      <Button id="enabled" isDisabled={false}>
-        Enabled
-      </Button>
-      <Button id="disabled" isDisabled>
-        Disabled
-      </Button>
-    </ButtonGroup>
-  </DSProvider>
-</Canvas>
-```
-
-## Components
-
-Although Chakra is integrated into the DS repo, we are still working to compose
-DS components with Chakra components or patterns. For example, both the DS and
-Chakra have a `Button` component so we will use Chakra's `Button` component to
-compose the DS `Button` component. However, the DS has a `Hero` component that
-is not already built by Chakra. In this case, the DS `Hero` component will
-internally use `Chakra` components such as `Box`.
-
-### Components Composed with Chakra
-
-While we can directly use Chakra components that align with DS components, we
-want to compose DS components using the Chakra component as a base instead. This
-pattern allows the Design System to have control over props and standard styles.
-
-These components composed from Chakra, therefore, do not have all styled props
-available. For example, whereas `m` (`margin`), `mr` (`marginright`), and similar
-props can be used in Chakra components, those props are not available for DS
-components that internally are composed with Chakra components.
-
-Components built from Chakra rename the component with the `Chakra` name prefix.
-
-```tsx
-import { Tabs as ChakraTabs, useStyleConfig } from "@chakra-ui/react";
-```
-
-In this example, the `ChakraTabs` component is returned with NYPL specific
-functionality, styles, and other requirements.
-
-```tsx
-function Tabs(props) {
-  // ...
-  const styles = useStyleConfig("Tabs", { variant: props.tabsType });
-
-  return (
-    <ChakraTabs
-      id={id}
-      __css={styles}
-      // ... other props
-    >
-      {children}
-    </ChakraTabs>
-}
-```
-
-#### Patterns
-
-We are writing CSS style object rules into Javascript objects that work with
-Chakra's theme. Instead of creating a variant for a component with a class name,
-now different props or internal logic are used to get the appropriate variant.
-Internally, the right variant will be mapped to a Chakra theme variant that will
-provide all the necessary styles.
-
-For the `Button` component, for example, we would convert a SCSS class rule such
-as `.button-outline` to a Javascript object (more on this in the [Anatomy of a
-Component Styling Object](#anatomy-of-a-component-styling-object) section).
-
-### Components re-exported from Chakra
-
-Some components are directly exported from Chakra. These components can be found
-in the `/src/index.ts` file. Note that not _all_ Chakra components are re-exported
-because we want to limit what developers should use in consuming applications.
-They include:
-
-- `Box`, `Center`, `Circle`, `Grid`, `GridItem`, `HStack`, `Square`, `Stack`, `VStack`
-
-Note: These components are harder to have snapshot tests for because, internally,
-these components autogenerate ids and class names on every new render. We can't
-override them so snapshot tests will fail.
-
-Update: Newer Chakra UI versions have mostly fixed this issue. Still, since
-Chakra components have already been tested, we don't necessarily want or need
-to test them ourselves.
-
-## Styling
-
-The NYPL DS' theme file can be found at `src/theme/index.ts`. This creates a new
-theme that extends Chakra's theme and is set in the `DSProvider` component. Note
-that the example below is the general structure of the `theme` object but the DS
-`theme` object has values already set so it may look different. You would generally
-only work and add new object values in the `components` obejct key for new
-components and their theme or variants.
-
-_Note_: There are some SCSS files used to style third party plugins and to
-generate SCSS mixins.
-
-```ts
-const theme = extendTheme({
-  styles: { ... },
-  breakpoints: { ... },
-  colors: { ... },
-  typography: { ... },
-  space: { ... },
-  components: {
-    Button,
-    // ...
-  },
-});
-```
-
-### Anatomy of a Component Styling Object
-
-For in-depth information, read Chakra's [Component Style documentation](https://chakra-ui.com/docs/theming/component-style).
-
-Component theme files can be found in the `src/theme/components/` directory.
-Here is an example using the `Button` component.
-
-```ts
-// The basic structure for all component style objects.
-const Button = {
-  baseStyle: {},
-  sizes: {},
-  variants: {},
-  defaultProps: {},
-};
-```
-
-A current variant class rule can be converted to a Javascript object and go in
-the `variants` object as in the following example.
-
-```scss
-// Button.scss
-// This is the "Secondary" variant.
-.button--outline {
-  @include button-base;
-
-  background-color: var(--nypl-colors-ui-white);
-  border: 1px solid var(--nypl-colors-ui-gray-light-cool);
-  color: inherit;
-
-  &:hover {
-    background-color: var(--nypl-colors-ui-gray-xx-light-cool);
-  }
-}
-```
-
-```ts
-// button.ts
-const Button = {
-  baseStyle: { ... },
-  sizes: { ... },
-  variants: {
-    secondary: {
-      bg: "ui.white",
-      border: "1px solid",
-      borderColor: "ui.gray.light-cool",
-      color: "inherit",
-      _hover: {
-        bg: "ui.gray.xx-light-cool",
-      },
-    },
-    // ... other variants,
-  },
-  defaultProps: { ... },
-};
-```
-
-Now this variant can be rendered:
-
-```tsx
-<Button buttonType="secondary" id="secondary">
-  Press me
-</Button>
-```
-
-### Breakpoints
-
-There are currently five (5) breakpoint values used in the DS:
-
-| Key Name | EM/PX value |
-| -------- | ----------- |
-| sm       | 20em/320px  |
-| md       | 38em/600px  |
-| lg       | 60em/960px  |
-| xl       | 80em/1280px |
-| 2xl      | 96em/1536px |
-
-There are two ways to set breakpoint values for a style rule: the array method
-and the object method. We prefer the object method and recommend to use the
-object method since it is easier to read and readily know what values take
-effect at defined breakpoint values. Note that the Chakra `"base"` key value is
-the same as `"sm"`.
-
-#### Object Method
-
-We recommend and follow this pattern in the DS. As an example, let's say we want
-to increase the width of the `Button` component as the device width increases.
-We start at value "100px" and increase by "50px" at every breakpoint. In the
-`button.ts` style file, we can define it as in the example below:
-
-```ts
-// button.ts
-const Button = {
-  baseStyle: {
-    width: {
-      base: "100px",
-      md: "150px",
-      lg: "200px",
-      xl: "250px",
-      "2xl": "300px",
-    },
-  },
-  // ...
-};
-```
-
-You do not have to define every breakpoint. If you only want to change the width
-of the `Button` at the `lg` breakpoint, it can be defined as:
-
-```ts
-// button.ts
-const Button = {
-  baseStyle: {
-    width: {
-      base: "100px",
-      lg: "200px",
-    },
-  },
-  // ...
-};
-```
-
-#### Array Method
-
-We do not recommend this pattern because it is harder to read and implicit on
-breakpoint values. Following the same example as the one above, the width of the
-`Button` component can be updated wiht all five values in an array:
-
-```ts
-// button.ts
-const Button = {
-  baseStyle: {
-    width: ["100px", "150px", "200px", "250px", "300px"],
-  },
-  // ...
-};
-```
-
-### Colors
-
-All available colors can be found in `src/theme/foundations/colors.ts`. Chakra
-autogenerates the `colors` object into CSS variables. We will rely on these
-variables rather than creating our own.
-
-```tsx
-const colors: Colors = {
-  // ui fills
-  ui: {
-    /// State and link utilities
-    focus: "#4181F1",
-    link: {
-      primary: "#0576D3",
-      secondary: "#004B98",
-    },
-    // ...
-  },
-  section: {
-    /** What's On is used for Exhibitions & Events. */
-    "whats-on": {
-      primary: "#242424",
-      secondary: "#000000",
-    },
-  },
-  // ...
-};
-```
-
-In the shorten object example above, the following will be generated by Chakra:
-
-| Theme object value                     | CSS variable                               |
-| -------------------------------------- | ------------------------------------------ |
-| `colors.ui.focus`                      | `--nypl-colors-ui-focus`                   |
-| `colors.ui.link.primary`               | `--nypl-colors-ui-link-primary`            |
-| `colors.ui.link.secondary`             | `--nypl-colors-ui-link-secondary`          |
-| `colors.section["whats-on"].primary`   | `--nypl-colors-section-whats-on-primary`   |
-| `colors.section["whats-on"].secondary` | `--nypl-colors-section-whats-on-secondary` |
-
-Note: while each Chakra color has number range values from 50 to 900 (such as
-`red.400`, `blue.600`, etc) and each one is based on the color coming from
-DS' Figma documentation, we recommend NOT to use them.
-
-### Spacing
-
-All the spacing values can be found in the `src/theme/foundations/spacing.ts`
-file. While Chakra provides many values, only use the eight DS defined values.
-
-| NYPL name Value | Chakra Value | DS Variable       |
-| --------------- | ------------ | ----------------- |
-| xxs             | 1            | --nypl-space-xxs  |
-| xs              | 2            | --nypl-space-xs   |
-| s               | 4            | --nypl-space-s    |
-| m               | 6            | --nypl-space-m    |
-| l               | 8            | --nypl-space-l    |
-| xl              | 12           | --nypl-space-xl   |
-| xxl             | 16           | --nypl-space-xxl  |
-| xxxl            | 24           | --nypl-space-xxxl |
-
-For example, to make all `button`s have a `padding: 8px 16px` value:
-
-```jsx
-// src/theme/components/button.ts
-const Button = {
-  baseStyle: {
-    py: "xs", // var(--nypl-space-xs) which results in a value of 8px or 0.5rem.
-    px: "s", // var(--nypl-space-s) which results in a value of 16px or 1rem.
-    // ... other styles
-  },
-  sizes: { ... },
-  variants: { ... },
-  defaultProps: { ... },
-};
-```
-
-### Typography
-
-All typography values can be found in the `src/theme/foundations/typography.ts`
-file. These values declare the font family, font sizes, and font weights to use
-for all text.
-
-## Style Props
-
-NYPL Reservoir components are built around the Chakra UI library. While Reservoir
-components may use the corresponding Chakra UI component, that is not always the
-case. Every Reservoir component, however, does make use of the Chakra UI
-"style props" pattern. This means that it is possible to pass in CSS rules to a
-component, including the shorthand versions. These style props will target the
-wrapper element of the component; this means if you want to target a specific
-element or component in a Reservoir component, you won't be able to with style
-props.
-
-<DSProvider>
-  <Text isBold>
-    While this is available to use, it is not recommended. If you see a need to
-    override styles, please reach out to the NYPL Reservoir team for assistance.
-  </Text>
-</DSProvider>
-
-In the following example, the `Button` component has been passed `p` and `maxW`
-props which are shorthand for "padding" and "max-width", respectively.
-
-```jsx
-<Button id="styleprops" p="s" maxW="200px">
-  Button
-</Button>
-```
-
-<DSProvider>
-  <Button id="styleprops" p="s" maxW="200px">
-    Button
-  </Button>
-</DSProvider>
-
-Find more information and a full list of all the available props, check the Chakra
-UI [Style Props page](https://chakra-ui.com/docs/styled-system/features/style-props).
-
-## Hooks
-
-The following hooks are available to use and can be imported from
-`@nypl/design-system-react-components`.
-
-### useNYPLTheme
-
-If your application does not use CSS or SCSS files and you want to write
-CSS-in-JS styles in your React components, the `useNYPLTheme` hook will provide
-you with NYPL-specific style values. This hook depends on the `DSProvider`
-component and if the function is used outside of this wrapper component, then
-the theme object will be empty.
-
-After importing and rendering the `DSProvider` wrapper component, as explained
-in the [DSProvider](#dsprovider) section, your children components can use this
-hook function.
-
-```tsx
-import { useNYPLTheme } from "@nypl/design-system-react-components";
-// ...
-
-const theme = useNYPLTheme();
-```
-
-The `theme` variable will be a JS object with style values discussed in the
-sections above. This will allow you to use NYPL-specific styles in your
-components through CSS-in-JS.
-
-```ts
-// theme:
-{
-  breakpoints: { ... },
-  colors: {
-    brand: { ... },
-    section: { ... },
-    transparent: { ... },
-    ui: { ... },
-  },
-  fontSizes: { ... },
-  fontWeights: { ... },
-  fonts: { ... },
-  radii: { ... },
-  space: { ... },
-}
-```
-
-#### Usage
-
-_Note: more patterns will be added._
-
-1. NYPL DS Components
-
-All DS components _should_ be used with their current styles. If a DS component
-needs an updated style, first contact the Design System and UX teams about this
-update. If you really _need_ to update a style and there is no available
-variant, then you can add styles directly as style prop.
-
-For example, if the `Heading` component should render the text in NYPL's green
-color used for "success primary" and add a bold font weight, then you can do
-the following:
-
-```tsx
-const theme = useNYPLTheme();
-
-// ...
-return (
-  <div>
-    <Heading
-      level={2}
-      color={theme.colors.ui.success.primary}
-      fontWeight={theme.fontWeights.bold}
-    >
-      Get a Digital Library Card Today in a Few Easy Steps
-    </Heading>
-
-    {/* Other components */}
-  </div>
-);
-```
-
-Of course, you can destructure the `theme` object to only get the object keys
-you need for your component (this is a general example). Log the object to the
-console to see all the available styles.
-
-2. HTML Components
-
-Use the `style` attribute in HTML components to add inline styles.
-
-```tsx
-<p style={{ color: theme.colors.ui.success.primary }}>
-  If you are 13 or older and live, work, attend school, or pay property taxes in
-  New York State, you can get a free digital library card right now using this
-  online form. Visitors to New York State can also use this form to apply for a
-  temporary card.
-</p>
-```
-
-## Testing
-
-Do not re-test Chakra components that are re-exported since they are already
-tested in the `@chakra-ui/react` package. We expect all new components composed
-with Chakra components to have tests for functionality and styling, including
-snapshot tests.

package/src/docs/Welcome.stories.mdx

@@ -1,148 +0,0 @@
-import { Meta } from "@storybook/addon-docs";
-
-import { Box, Center, Circle, VStack, Square } from "@chakra-ui/react";
-import Card, { CardHeading, CardContent } from "../components/Card/Card";
-import Heading from "../components/Heading/Heading";
-import Icon from "../components/Icons/Icon";
-import Image from "../components/Image/Image";
-import Link from "../components/Link/Link";
-import Logo from "../components/Logo/Logo";
-import SimpleGrid from "../components/Grid/SimpleGrid";
-import Text from "../components/Text/Text";
-import DSProvider from "../theme/provider";
-
-<Meta title="Welcome" />
-
-<DSProvider>
-  <VStack spacing="s">
-    <Center>
-      <Logo name="reservoirVerticalColor" size="small" />
-    </Center>
-    <Box>
-      <Center>
-        <Heading level="one" size="tertiary">
-          The React Component Library of the New York Public Library
-        </Heading>
-      </Center>
-      <Text>
-        Reservoir is NYPL's open-source extensible React component library for
-        products and experiences, with accessibility as its core. Aiming to
-        provide design and user experience consistency, Reservoir is the
-        foundation for all digital properties in the NYPL landscape, offering
-        functional components that implement the NYPL style standards.
-      </Text>
-    </Box>
-    <SimpleGrid>
-      <Box
-        style={{
-          alignItems: "center",
-          border: "1px solid #ccc",
-          display: "flex",
-          flexDirection: "column",
-          padding: "24px",
-        }}
-      >
-        <Icon
-          name="actionCheckCircle"
-          size="xxlarge"
-          color="section.education.secondary"
-          marginBottom="s"
-        />
-        <Card isCentered>
-          <CardHeading id="main-heading1" level="three">
-            Get Started
-          </CardHeading>
-          <CardContent>
-            <Text size="caption">
-              To start using Reservoir Design System, refer to Reservoir's
-              Github{" "}
-              <Link
-                href="https://github.com/NYPL/nypl-design-system/wiki"
-                type="external"
-              >
-                Wiki
-              </Link>{" "}
-              and{" "}
-              <Link
-                href="https://github.com/NYPL/nypl-design-system/blob/development/README.md"
-                type="external"
-              >
-                ReadMe
-              </Link>{" "}
-              to setup your project. You can also learn about our component
-              architecture and additional documentation.
-            </Text>
-          </CardContent>
-        </Card>
-      </Box>
-      <Box
-        style={{
-          alignItems: "center",
-          border: "1px solid #ccc",
-          display: "flex",
-          flexDirection: "column",
-          padding: "24px",
-        }}
-      >
-        <Icon
-          name="search"
-          size="xxlarge"
-          color="section.education.secondary"
-          marginBottom="s"
-        />
-        <Card isCentered>
-          <CardHeading id="main-heading1" level="three">
-            Find Components
-          </CardHeading>
-          <CardContent>
-            <Text size="caption">
-              For your convenience, the Reservoir Design System components have
-              been organized into logical categories based on both form and
-              function. Please refer to the <b>COMPONENTS</b> section in the
-              Storybook sidebar.
-            </Text>
-          </CardContent>
-        </Card>
-      </Box>
-      <Box
-        style={{
-          alignItems: "center",
-          border: "1px solid #ccc",
-          display: "flex",
-          flexDirection: "column",
-          padding: "24px",
-        }}
-      >
-        <Icon
-          name="fileTypeSpreadsheet"
-          size="xxlarge"
-          color="section.education.secondary"
-          marginBottom="s"
-        />
-        <Card isCentered>
-          <CardHeading id="main-heading1" level="three">
-            View the Code
-          </CardHeading>
-          <CardContent>
-            <Text size="caption">
-              The Reservoir Design System React component library is currently
-              published on{" "}
-              <Link
-                href="https://www.npmjs.com/package/@nypl/design-system-react-components"
-                type="external"
-              >
-                npm
-              </Link>
-              . If you're looking to contribute to this project, checkout the <Link
-                href="https://github.com/NYPL/nypl-design-system"
-                type="external"
-              >
-                nypl-design-system
-              </Link> repo on Github for more information.
-            </Text>
-          </CardContent>
-        </Card>
-      </Box>
-    </SimpleGrid>
-  </VStack>
-</DSProvider>

package/src/helpers/types.ts

@@ -1 +0,0 @@
-export type LayoutTypes = "column" | "row";