@mitodl/smoot-design 1.0.0

package/src/components/Button/Button.test.tsx

@@ -0,0 +1,56 @@
+import * as React from "react"
+import { render, screen } from "@testing-library/react"
+import { ThemeProvider, createTheme } from "../ThemeProvider/ThemeProvider"
+import { ButtonLink, ActionButtonLink } from "./Button"
+
+const withLinkOverride = createTheme({
+  custom: {
+    LinkAdapter: React.forwardRef<HTMLAnchorElement, React.ComponentProps<"a">>(
+      (props, ref) => (
+        // eslint-disable-next-line jsx-a11y/anchor-has-content
+        <a ref={ref} data-custom="theme-default" {...props} />
+      ),
+    ),
+  },
+})
+
+describe.each([
+  //
+  { ButtonComponent: ButtonLink },
+  { ButtonComponent: ActionButtonLink },
+])("$ButtonComponent.displayName overrides", ({ ButtonComponent }) => {
+  test("Uses anchor by default", () => {
+    render(<ButtonComponent href="/test">Link text here</ButtonComponent>, {
+      wrapper: ThemeProvider,
+    })
+    const link = screen.getByRole("link")
+    expect(link.dataset.custom).toBe(undefined)
+  })
+
+  test("Uses theme's override if supplied", () => {
+    render(<ButtonComponent href="/test">Link text here</ButtonComponent>, {
+      wrapper: (props) => <ThemeProvider theme={withLinkOverride} {...props} />,
+    })
+    const link = screen.getByRole("link")
+    expect(link.dataset.custom).toBe("theme-default")
+  })
+
+  test("Uses component's override if supplied", () => {
+    const LinkImplementation = (props: React.ComponentProps<"a">) => (
+      // eslint-disable-next-line jsx-a11y/anchor-has-content
+      <a data-custom="anchor-override" {...props} />
+    )
+    render(
+      <ButtonComponent Component={LinkImplementation} href="/test">
+        Link text here
+      </ButtonComponent>,
+      {
+        wrapper: (props) => (
+          <ThemeProvider theme={withLinkOverride} {...props} />
+        ),
+      },
+    )
+    const link = screen.getByRole("link")
+    expect(link.dataset.custom).toBe("anchor-override")
+  })
+})

package/src/components/Button/Button.tsx

@@ -0,0 +1,418 @@
+import * as React from "react"
+import styled from "@emotion/styled"
+import { css } from "@emotion/react"
+import { pxToRem } from "../ThemeProvider/typography"
+import type { Theme, ThemeOptions } from "@mui/material/styles"
+import {
+  LinkAdapter,
+  LinkAdapterPropsOverrides,
+} from "../LinkAdapter/LinkAdapter"
+
+type ButtonVariant =
+  | "primary"
+  | "secondary"
+  | "tertiary"
+  | "text"
+  | "unstable_noBorder"
+  | "unstable_inverted"
+  | "unstable_success"
+type ButtonSize = "small" | "medium" | "large"
+type ButtonEdge = "circular" | "rounded" | "none"
+
+type ButtonStyleProps = {
+  variant?: ButtonVariant
+  size?: ButtonSize
+  edge?: ButtonEdge
+  /**
+   * Display an icon before the button text.
+   */
+  startIcon?: React.ReactNode
+  /**
+   * Display an icon after the button text.
+   */
+  endIcon?: React.ReactNode
+  /**
+   * If true (default: `false`), the button will become one size smaller at the
+   * `sm` breakpoint.
+   *  - large -> medium
+   *  - medium -> small
+   *  - small -> small
+   */
+  responsive?: boolean
+  color?: "secondary"
+}
+
+const styleProps: Record<string, boolean> = {
+  variant: true,
+  size: true,
+  edge: true,
+  startIcon: true,
+  endIcon: true,
+  responsive: true,
+  color: true,
+} satisfies Record<keyof ButtonStyleProps, boolean>
+
+const shouldForwardProp = (prop: string) => !styleProps[prop]
+
+const DEFAULT_PROPS: Required<
+  Omit<ButtonStyleProps, "startIcon" | "endIcon" | "color">
+> = {
+  variant: "primary",
+  size: "medium",
+  edge: "rounded",
+  responsive: false,
+}
+
+const BORDER_WIDTHS = {
+  small: 1,
+  medium: 1,
+  large: 2,
+}
+
+const RESPONSIVE_SIZES: Record<ButtonSize, ButtonSize> = {
+  small: "small",
+  medium: "small",
+  large: "medium",
+}
+
+const sizeStyles = (
+  size: ButtonSize,
+  hasBorder: boolean,
+  theme: Theme,
+): Partial<ThemeOptions["typography"]>[] => {
+  const paddingAdjust = hasBorder ? BORDER_WIDTHS[size] : 0
+  return [
+    {
+      boxSizing: "border-box",
+      borderWidth: BORDER_WIDTHS[size],
+    },
+    size === "large" && {
+      padding: `${14 - paddingAdjust}px 24px`,
+      ...theme.typography.buttonLarge,
+    },
+    size === "medium" && {
+      padding: `${11 - paddingAdjust}px 16px`,
+      ...theme.typography.button,
+    },
+    size === "small" && {
+      padding: `${8 - paddingAdjust}px 12px`,
+      ...theme.typography.buttonSmall,
+    },
+  ]
+}
+
+const buildStyles = (props: ButtonStyleProps & { theme: Theme }) => {
+  const { size, variant, edge, theme, color, responsive } = {
+    ...DEFAULT_PROPS,
+    ...props,
+  }
+  const { colors } = theme.custom
+  const hasBorder = variant === "secondary"
+  return css([
+    {
+      color: theme.palette.text.primary,
+      textAlign: "center",
+      // display
+      display: "inline-flex",
+      justifyContent: "center",
+      alignItems: "center",
+      // transitions
+      transition: `background ${theme.transitions.duration.short}ms`,
+      // cursor
+      cursor: "pointer",
+      ":disabled": {
+        cursor: "default",
+      },
+      minWidth: "100px",
+    },
+    ...sizeStyles(size, hasBorder, theme),
+    // responsive
+    responsive && {
+      [theme.breakpoints.down("sm")]: sizeStyles(
+        RESPONSIVE_SIZES[size],
+        hasBorder,
+        theme,
+      ),
+    },
+    // variant
+    variant === "primary" && {
+      backgroundColor: colors.mitRed,
+      color: colors.white,
+      border: "none",
+      /* Shadow/04dp */
+      boxShadow:
+        "0px 2px 4px 0px rgba(37, 38, 43, 0.10), 0px 3px 8px 0px rgba(37, 38, 43, 0.12)",
+      ":hover:not(:disabled)": {
+        backgroundColor: colors.red,
+        boxShadow: "none",
+      },
+      ":disabled": {
+        backgroundColor: colors.silverGray,
+        boxShadow: "none",
+      },
+    },
+    hasBorder && {
+      backgroundColor: "transparent",
+      borderColor: "currentcolor",
+      borderStyle: "solid",
+    },
+    variant === "unstable_success" && {
+      backgroundColor: colors.darkGreen,
+      color: colors.white,
+      border: "none",
+      /* Shadow/04dp */
+      boxShadow:
+        "0px 2px 4px 0px rgba(37, 38, 43, 0.10), 0px 3px 8px 0px rgba(37, 38, 43, 0.12)",
+      ":hover:not(:disabled)": {
+        backgroundColor: colors.darkGreen,
+        boxShadow: "none",
+      },
+      ":disabled": {
+        backgroundColor: colors.silverGray,
+        boxShadow: "none",
+      },
+    },
+    hasBorder && {
+      backgroundColor: "transparent",
+      borderColor: "currentcolor",
+      borderStyle: "solid",
+    },
+    variant === "secondary" && {
+      color: colors.red,
+      ":hover:not(:disabled)": {
+        // brightRed at 0.06 alpha
+        backgroundColor: "rgba(255, 20, 35, 0.06)",
+      },
+      ":disabled": {
+        color: colors.silverGray,
+      },
+    },
+    variant === "text" && {
+      backgroundColor: "transparent",
+      borderStyle: "none",
+      color: colors.darkGray2,
+      ":hover:not(:disabled)": {
+        // darkGray1 at 6% alpha
+        backgroundColor: "rgba(64, 70, 76, 0.06)",
+      },
+      ":disabled": {
+        color: colors.silverGray,
+      },
+    },
+    variant === "unstable_noBorder" && {
+      backgroundColor: colors.white,
+      color: colors.darkGray2,
+      border: "none",
+      ":hover:not(:disabled)": {
+        // darkGray1 at 6% alpha
+        backgroundColor: "rgba(64, 70, 76, 0.06)",
+      },
+      ":disabled": {
+        color: colors.silverGray,
+      },
+    },
+    variant === "tertiary" && {
+      color: colors.darkGray2,
+      border: "none",
+      backgroundColor: colors.lightGray2,
+      ":hover:not(:disabled)": {
+        backgroundColor: colors.white,
+      },
+      ":disabled": {
+        backgroundColor: colors.lightGray2,
+        color: colors.silverGrayLight,
+      },
+    },
+    variant === "unstable_inverted" && {
+      backgroundColor: colors.white,
+      color: colors.mitRed,
+      borderColor: colors.mitRed,
+      borderStyle: "solid",
+    },
+    // edge
+    edge === "rounded" && {
+      borderRadius: "4px",
+    },
+    edge === "circular" && {
+      // Pill-shaped buttons... Overlapping border radius get clipped to pill.
+      borderRadius: "100vh",
+    },
+    // color
+    color === "secondary" && {
+      color: theme.custom.colors.silverGray,
+      borderColor: theme.custom.colors.silverGray,
+      ":hover:not(:disabled)": {
+        backgroundColor: theme.custom.colors.lightGray1,
+      },
+    },
+  ])
+}
+
+const ButtonStyled = styled("button", { shouldForwardProp })<ButtonStyleProps>(
+  buildStyles,
+)
+const LinkStyled = styled(LinkAdapter, {
+  shouldForwardProp,
+})<ButtonStyleProps>(buildStyles)
+
+const IconContainer = styled.span<{ side: "start" | "end"; size: ButtonSize }>(
+  ({ size, side }) => [
+    {
+      height: "1em",
+      display: "flex",
+      alignItems: "center",
+    },
+    side === "start" && {
+      /**
+       * The negative margin is to counteract the padding on the button itself.
+       * Without icons, the left space is 24/16/12 px.
+       * With icons, the left space is 20/12/8 px.
+       */
+      marginLeft: "-4px",
+      marginRight: "8px",
+    },
+    side === "end" && {
+      marginLeft: "8px",
+      marginRight: "-4px",
+    },
+    {
+      "& svg, & .MuiSvgIcon-root": {
+        width: "1em",
+        height: "1em",
+        fontSize: pxToRem(
+          {
+            small: 16,
+            medium: 20,
+            large: 24,
+          }[size],
+        ),
+      },
+    },
+  ],
+)
+
+const ButtonInner: React.FC<
+  ButtonStyleProps & { children?: React.ReactNode }
+> = (props) => {
+  const { children, size = DEFAULT_PROPS.size } = props
+  return (
+    <>
+      {props.startIcon ? (
+        <IconContainer size={size} side="start">
+          {props.startIcon}
+        </IconContainer>
+      ) : null}
+      {children}
+      {props.endIcon ? (
+        <IconContainer size={size} side="end">
+          {props.endIcon}
+        </IconContainer>
+      ) : null}
+    </>
+  )
+}
+
+type ButtonProps = ButtonStyleProps & React.ComponentProps<"button">
+
+/**
+ * Our standard button component.
+ *
+ * See also:
+ * - ButtonLink
+ * - ActionButton
+ */
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ children, ...props }, ref) => {
+    return (
+      <ButtonStyled ref={ref} type="button" {...props}>
+        <ButtonInner {...props}>{children}</ButtonInner>
+      </ButtonStyled>
+    )
+  },
+)
+
+type ButtonLinkProps = ButtonStyleProps &
+  React.ComponentProps<"a"> & {
+    Component?: React.ElementType
+  } & LinkAdapterPropsOverrides
+
+const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
+  ({ children, Component, ...props }: ButtonLinkProps, ref) => {
+    return (
+      <LinkStyled Component={Component} ref={ref} {...props}>
+        <ButtonInner {...props}>{children}</ButtonInner>
+      </LinkStyled>
+    )
+  },
+)
+
+ButtonLink.displayName = "ButtonLink"
+
+type ActionButtonStyleProps = Omit<ButtonStyleProps, "startIcon" | "endIcon">
+type ActionButtonProps = ActionButtonStyleProps & React.ComponentProps<"button">
+
+const actionStyles = (size: ButtonSize) => {
+  return {
+    minWidth: "auto",
+    padding: 0,
+    height: {
+      small: "32px",
+      medium: "40px",
+      large: "48px",
+    }[size],
+    width: {
+      small: "32px",
+      medium: "40px",
+      large: "48px",
+    }[size],
+    "& svg, & .MuiSvgIcon-root": {
+      width: "1em",
+      height: "1em",
+      fontSize: pxToRem(
+        {
+          small: 20,
+          medium: 24,
+          large: 32,
+        }[size],
+      ),
+    },
+  }
+}
+
+/**
+ * A button that should contain a remixicon icon and nothing else.
+ * For a variant that functions as a link, see ActionButtonLink.
+ */
+const ActionButton = styled(
+  React.forwardRef<HTMLButtonElement, ActionButtonProps>((props, ref) => (
+    <ButtonStyled ref={ref} type="button" {...props} />
+  )),
+)(({ size = DEFAULT_PROPS.size, responsive, theme }) => {
+  return [
+    actionStyles(size),
+    responsive && {
+      [theme.breakpoints.down("sm")]: actionStyles(RESPONSIVE_SIZES[size]),
+    },
+  ]
+})
+
+type ActionButtonLinkProps = ActionButtonStyleProps &
+  React.ComponentProps<"a"> & {
+    Component?: React.ElementType
+  } & LinkAdapterPropsOverrides
+
+const ActionButtonLink = ActionButton.withComponent(
+  ({ Component, ...props }: ButtonLinkProps) => {
+    return <LinkStyled Component={Component} {...props} />
+  },
+)
+ActionButtonLink.displayName = "ActionButtonLink"
+
+export { Button, ButtonLink, ActionButton, ActionButtonLink, DEFAULT_PROPS }
+
+export type {
+  ButtonProps,
+  ButtonLinkProps,
+  ActionButtonProps,
+  ActionButtonLinkProps,
+}

package/src/components/LinkAdapter/LinkAdapter.tsx

@@ -0,0 +1,38 @@
+import * as React from "react"
+import { useTheme } from "@emotion/react"
+import styled from "@emotion/styled"
+
+const PlainLink = styled.a({
+  color: "inherit",
+  textDecoration: "none",
+})
+
+/**
+ * LinkAdapterPropsOverrides can be used with module augmentation to provide
+ * extra props to ButtonLink.
+ *
+ * For example, in a NextJS App, you might set `next/link` as your default
+ * Link implementation, and use LinkAdapterPropsOverrides to provide
+ * `next/link`-specific props.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface LinkAdapterPropsOverrides {}
+type LinkAdapterProps = React.ComponentProps<"a"> & {
+  Component?: React.ElementType
+} & LinkAdapterPropsOverrides
+/**
+ * Overrideable link component.
+ * - If `Component` is provided, renders as `Component`
+ * - else, if `theme.custom.LinkAdapter` is provided, renders as `theme.custom.LinkAdapter`
+ * - else, renders as `a` tag
+ */
+const LinkAdapter = React.forwardRef<HTMLAnchorElement, LinkAdapterProps>(
+  ({ Component, ...props }, ref) => {
+    const theme = useTheme()
+    const LinkComponent = Component ?? theme.custom.LinkAdapter
+    return <PlainLink as={LinkComponent} ref={ref} {...props} />
+  },
+)
+
+export { LinkAdapter }
+export type { LinkAdapterPropsOverrides }

package/src/components/ThemeProvider/ThemeProvider.stories.tsx

@@ -0,0 +1,94 @@
+import * as React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { ThemeProvider, createTheme } from "./ThemeProvider"
+import { ButtonLink } from "../Button/Button"
+
+const CustomLinkAdapater = React.forwardRef<
+  HTMLAnchorElement,
+  React.ComponentProps<"a">
+>((props, ref) => (
+  // eslint-disable-next-line jsx-a11y/anchor-has-content, jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+  <a
+    ref={ref}
+    onClick={(e) => {
+      e.preventDefault()
+      alert(`Custom link to: ${e.currentTarget.href}. (Preventing Navigation.)`)
+    }}
+    data-custom="theme-default"
+    {...props}
+  />
+))
+const customTheme = createTheme({
+  custom: {
+    LinkAdapter: CustomLinkAdapater,
+  },
+})
+
+const meta: Meta<typeof ThemeProvider> = {
+  title: "smoot-design/ThemeProvider",
+  component: ThemeProvider,
+  argTypes: {
+    theme: {
+      options: ["Default", "Custom Link Adapter"],
+      mapping: {
+        Default: undefined,
+        "Custom Link Adapter": customTheme,
+      },
+    },
+    children: {
+      table: { disable: true },
+    },
+  },
+  tags: ["autodocs"],
+  id: "smoot-design/ThemeProvider",
+}
+
+type Story = StoryObj<typeof ThemeProvider>
+
+/**
+ * `ThemeProvider` must wrap all components from `smoot`-design, and allows
+ *  styling any component via [`styled`](https://emotion.sh/docs/styled).
+ *
+ * In general, most useful theme properties are exposed on `theme.custom`. (Root
+ * `theme` properties are used internally by MUI.) See typescript definitions
+ * for more information.
+ *
+ * ### Custom Link Adapter
+ * One particularly notable property is `theme.custom.LinkAdapter`. Some `smoot-design`
+ * components render links. These links are native anchor tags by default. In
+ * order to use these components with custom routing libraries (e.g. `react-router`
+ * or `next/link`), you can provide a custom link adapter. Link components wills
+ *
+ * As an example, `ButtonLink` will:
+ *   - use `Component` on `ButtonLink` if specified (`<ButtonLink Component={Link} />`)
+ *   - else, use `theme.custom.LinkAdapter` if specified,
+ *   - else, use `a` tag.
+ *
+ * If you provide a custom `LinkAdapter` and need **aditional** props, you can
+ * use [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to add the custom props to relevant
+ * components. For example, if using `next/link`
+ * ```
+ * // Add scroll prop to all components using LinkAdapter
+ * declare module "@mitodl/smoot-design" {
+ *   interface LinkAdapterPropsOverrides {
+ *     scroll?: boolean
+ *   }
+ * }
+ * ```
+ */
+export const LinkAdapterOverride: Story = {
+  args: {
+    theme: customTheme,
+  },
+  render: (args) => {
+    return (
+      <ThemeProvider theme={args.theme}>
+        <ButtonLink href="https://mit.edu">
+          {args.theme ? "Custom theme in use" : "Default theme in use"}
+        </ButtonLink>
+      </ThemeProvider>
+    )
+  },
+}
+
+export default meta