@sproutsocial/seeds-react-card 1.0.0

package/src/__tests__/Card.test.tsx

@@ -0,0 +1,264 @@
+import React from "react";
+import {
+  render,
+  screen,
+  waitFor,
+} from "@sproutsocial/seeds-react-testing-library";
+import { PointerEventsCheckLevel } from "@testing-library/user-event";
+import Card from "../";
+import Badge from "@sproutsocial/seeds-react-badge";
+import {
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardLink,
+} from "../subComponents";
+import { theme } from "@sproutsocial/seeds-react-theme";
+
+jest.mock("../utils");
+const mockCardClick = jest.fn();
+
+describe("A card is interactive", () => {
+  it("should be clickable", async () => {
+    const { user } = render(
+      <Card role="button" onClick={mockCardClick}>
+        Test
+      </Card>
+    );
+
+    const card = screen.getByRole("button");
+
+    await user.click(card);
+    expect(mockCardClick).toBeCalledTimes(1);
+  });
+
+  it("should function as a link", async () => {
+    const { user } = render(
+      <Card role="link" href="https://sproutsocial.com/">
+        Hello
+        <CardLink>Test</CardLink>
+      </Card>
+    );
+
+    const card = screen.getByText("Hello");
+    const link = screen.getByText("Test");
+
+    // listen to the child link to make sure that clicking the parent Card clicks the link programmatically
+    link.addEventListener("click", mockCardClick);
+
+    expect(card).toContainElement(link);
+    expect(link).toHaveAttribute("href", "https://sproutsocial.com/");
+
+    await user.click(card);
+    expect(mockCardClick).toBeCalled();
+  });
+
+  it("should function as a button", async () => {
+    const { user } = render(
+      <Card role="button" onClick={mockCardClick}>
+        Test
+      </Card>
+    );
+
+    const card = screen.getByRole("button");
+    expect(card).toHaveAttribute("role", "button");
+
+    await user.click(card);
+    expect(mockCardClick).toBeCalledTimes(1);
+  });
+
+  it("can be purely presentational", () => {
+    render(<Card role="presentation">Test</Card>);
+
+    const card = screen.getByRole("presentation");
+    expect(card).toHaveAttribute("role", "presentation");
+  });
+
+  it("can be disabled", async () => {
+    const { user } = render(
+      <Card role="button" onClick={mockCardClick} disabled={true}>
+        Test
+      </Card>
+    );
+
+    const card = screen.getByRole("button");
+
+    await user
+      .setup({
+        pointerEventsCheck: PointerEventsCheckLevel.Never,
+      })
+      .click(card);
+    expect(card).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("should have an adjustable hover state style", async () => {
+    const { user } = render(
+      <Card role="presentation" elevation="high">
+        Test
+      </Card>
+    );
+
+    const card = screen.getByRole("presentation");
+
+    // apparently, jest-dom can't do this with toHaveStyle
+    // https://github.com/testing-library/jest-dom/issues/59
+    //
+    // have to use toHaveStyleRule from jest-styled-comps
+    // https://github.com/styled-components/jest-styled-components#tohavestylerule
+    await user.hover(card);
+    expect(card).toHaveStyleRule("box-shadow", theme.shadows.high, {
+      modifier: ":hover",
+    });
+  });
+
+  it("can be focused", async () => {
+    const { user } = render(
+      <Card role="presentation">
+        Test
+        <button>child click test</button>
+      </Card>
+    );
+
+    const card = screen.getByRole("presentation");
+    const button = screen.getByRole("button");
+
+    expect(card).toHaveAttribute("tabindex", "0");
+
+    await user.tab();
+    expect(card).toHaveFocus();
+
+    await user.tab();
+    expect(button).toHaveFocus();
+
+    await user.tab({ shift: true });
+    expect(card).toHaveFocus();
+  });
+
+  it('handles onKeyDown "enter"', async () => {
+    const { rerender, debug, user } = render(
+      <Card role="button" onClick={mockCardClick}>
+        Test
+      </Card>
+    );
+
+    debug;
+
+    const cardAsButton = screen.getByRole("button");
+
+    await user.tab();
+    expect(cardAsButton).toHaveFocus();
+
+    await user.type(cardAsButton, "{enter}");
+    expect(mockCardClick).toBeCalledTimes(1);
+
+    rerender(
+      <Card role="link" href="https://sproutsocial.com/">
+        Hello
+        <CardLink>Test</CardLink>
+      </Card>
+    );
+
+    const cardAsLink = screen.getByText("Test");
+
+    await user.tab();
+    expect(cardAsLink).toHaveFocus();
+    expect(cardAsLink).toHaveAttribute("href", "https://sproutsocial.com/");
+  });
+
+  it("is selectable", async () => {
+    const TestCheckboxCard = () => {
+      const [selected, setSelected] = React.useState<boolean>(false);
+      return (
+        <Card
+          role="checkbox"
+          onClick={() => setSelected(!selected)}
+          selected={selected}
+        >
+          Test
+        </Card>
+      );
+    };
+
+    const { user } = render(<TestCheckboxCard />);
+
+    const card = screen.getByRole("checkbox");
+    await user.click(card);
+
+    await waitFor(() => expect(screen.getByRole("checkbox")).toBeChecked());
+    expect(card).toHaveStyle(
+      `border: ${theme.borderWidths[500]} solid ${theme.colors.container.border.selected}`
+    );
+  });
+
+  it("should support interactive children", async () => {
+    const mockChildClick = jest.fn((e) => e.stopPropagation());
+
+    const { user } = render(
+      <Card role="presentation" onClick={mockCardClick}>
+        Test
+        <button onClick={mockChildClick}>child click test</button>
+      </Card>
+    );
+
+    const card = screen.getByRole("presentation");
+    const cardChild = screen.getByText("child click test");
+
+    // Expect clicking the card to trigger the card's onClick but not the child's
+    await user.click(card);
+    expect(mockCardClick).toBeCalledTimes(1);
+    expect(mockChildClick).toBeCalledTimes(0);
+
+    // Expect clicking the interactive child NOT to trigger the card's onClick.
+    await user.click(cardChild);
+    expect(mockCardClick).toBeCalledTimes(1);
+    expect(mockChildClick).toBeCalledTimes(1);
+  });
+});
+
+describe("A Card supports composable layouts", () => {
+  it("should support children", () => {
+    render(
+      <Card role="presentation">
+        Hello, world!
+        <Badge>Cool Badge</Badge>
+      </Card>
+    );
+
+    const parent = screen.getByRole("presentation");
+    const child = screen.getByText("Cool Badge");
+
+    expect(parent).toContainElement(child);
+  });
+
+  it("should accept system props", () => {
+    render(
+      <Card role="presentation" p={300}>
+        Hello, world!
+      </Card>
+    );
+
+    const card = screen.getByRole("presentation");
+    expect(card).toHaveStyle(`padding: ${theme.space[300]}`);
+  });
+
+  it("adjusts it's styles dynamically when subcomponents are present", () => {
+    render(
+      <Card role="presentation">
+        <CardHeader>Card Header</CardHeader>
+        <CardContent>CardContent</CardContent>
+        <CardFooter>CardFooter</CardFooter>
+      </Card>
+    );
+
+    const card = screen.getByRole("presentation");
+    const cardSubcomponent = screen.getByText("CardFooter");
+
+    expect(cardSubcomponent).toBeInTheDocument();
+    // We have to wait for the new classes to be set once the state changes. Not sure how to do this better but a function seems to work.
+    () => expect(card).toHaveStyle("padding: 0px");
+  });
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+});

package/src/__tests__/CardTypes.typetest.tsx

@@ -0,0 +1,76 @@
+import * as React from "react";
+import Card from "..";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function CardTypes() {
+  return (
+    <>
+      <Card role="link" href="https://sproutsocial.com/">
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that href is required with role=link */}
+      <Card role="link">This is a card.</Card>
+      {/* @ts-expect-error - test that onClick is never allowed with role=link */}
+      <Card
+        role="link"
+        onClick={() => {
+          return;
+        }}
+      >
+        This is a card.
+      </Card>
+      <Card
+        role="button"
+        onClick={() => {
+          return;
+        }}
+      >
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that onClick is required with role=button */}
+      <Card role="button">This is a card.</Card>
+      <Card
+        role="checkbox"
+        selected={true}
+        onClick={() => {
+          return;
+        }}
+      >
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that select is required with role=checkbox */}
+      <Card
+        role="checkbox"
+        onClick={() => {
+          return;
+        }}
+      >
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that onClick is required with role=checkbox */}
+      <Card role="checkbox" selected={true}>
+        This is a card.
+      </Card>
+      <Card role="presentation">This is a card.</Card>
+      <Card
+        role="presentation"
+        onClick={() => {
+          return;
+        }}
+      >
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that href is never allowed with role=presentation */}
+      <Card role="presentation" href="">
+        This is a card.
+      </Card>
+      <Card role="presentation" disabled={true} selected={true}>
+        This is a card.
+      </Card>
+      {/* @ts-expect-error - test that consumer level transient props fail */}
+      <Card role="presentation" $disabled={true} $selected={true}>
+        This is a card.
+      </Card>
+    </>
+  );
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import Card from "./Card";
+
+export default Card;
+export { Card };
+export { CardHeader, CardContent, CardFooter, CardLink } from "./subComponents";
+export * from "./CardTypes";

package/src/styles.tsx

@@ -0,0 +1,171 @@
+import styled from "styled-components";
+import {
+  border,
+  color,
+  flexbox,
+  grid,
+  layout,
+  position,
+  space,
+  typography,
+} from "styled-system";
+import { focusRing, disabled } from "@sproutsocial/seeds-react-mixins";
+import type {
+  TypeStyledCard,
+  TypeCardArea,
+  TypeStyledSelectedIcon,
+  TypeCardLink,
+} from "./CardTypes";
+import Icon from "@sproutsocial/seeds-react-icon";
+
+// TODO: Would be really cool to cherry pick specific props from style functions. For example,
+// removing the css prop 'color' from the color function or importing just the specific
+// props the component needs. It appears to be possible with some and not others.
+// https://github.com/styled-system/styled-system/issues/1569
+
+export const StyledCardContent = styled.div<TypeCardArea>`
+  display: flex;
+  flex-direction: column;
+  padding: ${({ theme }) => theme.space[400]};
+  box-sizing: border-box;
+
+  ${border}
+  ${color}
+  ${flexbox}
+  ${grid}
+  ${layout}
+  ${space}
+`;
+
+export const StyledCardHeader = styled(StyledCardContent)`
+  flex-direction: row;
+  border-bottom: ${({ theme }) => `${theme.borderWidths[500]} solid
+  ${theme.colors.container.border.base}`};
+  border-top-left-radius: ${({ theme }) => theme.radii.inner};
+  border-top-right-radius: ${({ theme }) => theme.radii.inner};
+
+  ${border}
+  ${color}
+  ${flexbox}
+  ${grid}
+  ${layout}
+  ${space}
+`;
+
+export const StyledCardFooter = styled(StyledCardContent)`
+  flex-direction: row;
+  border-top: ${({ theme }) => `${theme.borderWidths[500]} solid
+  ${theme.colors.container.border.base}`};
+  border-bottom-left-radius: ${({ theme }) => theme.radii.inner};
+  border-bottom-right-radius: ${({ theme }) => theme.radii.inner};
+
+  ${border}
+  ${color}
+  ${flexbox}
+  ${grid}
+  ${layout}
+  ${space}
+`;
+
+export const SelectedIconWrapper = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: absolute;
+  top: -8px;
+  right: -8px;
+`;
+
+export const StyledSelectedIcon = styled(Icon)<TypeStyledSelectedIcon>`
+  border-radius: 50%;
+  background: ${({ theme }) => theme.colors.container.background.base};
+  opacity: 0;
+  transition: opacity ${({ theme }) => theme.duration.medium};
+
+  ${({ $selected }) =>
+    $selected &&
+    `
+    opacity: 1;
+  `}
+`;
+
+export const StyledCardLink = styled.a<TypeCardLink>`
+  font-family: ${(p) => p.theme.fontFamily};
+  font-weight: ${(p) => p.theme.fontWeights.bold};
+  color: ${(p) => p.theme.colors.text.headline};
+  ${(p) => p.theme.typography[400]};
+
+  ${color}
+  ${typography}
+`;
+
+export const StyledCard = styled.div<TypeStyledCard>`
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  margin: 0;
+  background: ${({ theme }) => theme.colors.container.background.base};
+  border: ${({ theme }) => theme.borderWidths[500]} solid
+    ${({ theme }) => theme.colors.container.border.base};
+  padding: ${({ theme, $compositionalComponents }) =>
+    $compositionalComponents ? 0 : theme.space[400]};
+  border-radius: ${({ theme }) => theme.radii.outer};
+  transition: box-shadow ${({ theme }) => theme.duration.medium},
+    border ${({ theme }) => theme.duration.medium};
+
+  &[role="button"],
+  &[role="checkbox"] {
+    cursor: pointer;
+  }
+
+  ${({ $isRoleLink }) =>
+    $isRoleLink &&
+    `
+		cursor: pointer;
+	`}
+
+  &:hover {
+    box-shadow: ${({ theme, $elevation = "low" }) => theme.shadows[$elevation]};
+  }
+
+  &:focus-within {
+    ${({ $isRoleLink }) => ($isRoleLink ? focusRing : null)}
+    ${StyledCardLink}:focus {
+      border: none;
+      box-shadow: none;
+      outline: none;
+    }
+  }
+
+  &:focus {
+    ${focusRing}
+  }
+
+  ${({ $disabled }) =>
+    $disabled &&
+    `
+    ${disabled}
+  `}
+
+  ${({ $selected, theme }) =>
+    $selected &&
+    `
+    border: ${theme.borderWidths[500]} solid ${theme.colors.container.border.selected};  
+  `}
+
+  ${border}
+  ${color}
+  ${flexbox}
+  ${grid}
+  ${layout}
+  ${position}
+  ${space}
+`;
+
+export const StyledCardAffordance = styled(Icon)`
+  ${StyledCard}:hover & {
+    transform: translateX(${(p) => p.theme.space[200]});
+  }
+  transition: ${(p) => p.theme.duration.medium};
+`;

package/src/subComponents.tsx

@@ -0,0 +1,110 @@
+import React, { useContext } from "react";
+import { useChildContext, SubComponentContext } from "./utils";
+import type {
+  TypeCardLink,
+  TypeSharedCardSystemProps,
+  TypeStyledSelectedIcon,
+} from "./CardTypes";
+import {
+  StyledCardContent,
+  StyledCardHeader,
+  StyledCardFooter,
+  StyledSelectedIcon,
+  SelectedIconWrapper,
+  StyledCardAffordance,
+  StyledCardLink,
+} from "./styles";
+
+interface TypeSharedSubComponentProps extends TypeSharedCardSystemProps {
+  children?: React.ReactNode;
+}
+
+export const CardContent = ({
+  children,
+  ...rest
+}: TypeSharedSubComponentProps) => {
+  // TODO: It could be cool to possibly adjust the context to include an array of names of child components.
+  // Then, if CardHeader or CardFooter aren't used with CardContent throw an error.
+  useChildContext();
+  return <StyledCardContent {...rest}>{children}</StyledCardContent>;
+};
+
+export const CardHeader = ({
+  children,
+  ...rest
+}: TypeSharedSubComponentProps) => {
+  useChildContext();
+  return <StyledCardHeader {...rest}>{children}</StyledCardHeader>;
+};
+
+export const CardFooter = ({
+  children,
+  ...rest
+}: TypeSharedSubComponentProps) => {
+  useChildContext();
+  return <StyledCardFooter {...rest}>{children}</StyledCardFooter>;
+};
+
+interface TypeSelectedIconProps {
+  $selected?: TypeStyledSelectedIcon["$selected"];
+}
+
+export const SelectedIcon = ({ $selected }: TypeSelectedIconProps) => {
+  return (
+    <SelectedIconWrapper>
+      <StyledSelectedIcon
+        aria-hidden
+        color="icon.base"
+        name="circle-check-solid"
+        $selected={$selected}
+      />
+    </SelectedIconWrapper>
+  );
+};
+
+export const CardAffordance = ({ ...rest }) => {
+  return (
+    <StyledCardAffordance
+      {...rest}
+      size="mini"
+      name="arrow-right-solid"
+      // TODO: probably need to make this available to the top level for external links https://sprout.atlassian.net/browse/DS-2223
+      aria-hidden
+    />
+  );
+};
+
+export const CardLink = ({
+  affordance,
+  children,
+  external = false,
+  color,
+  ...rest
+}: React.PropsWithChildren<TypeCardLink>) => {
+  const { href, linkRef } = useContext(SubComponentContext);
+
+  // Because we are hijacking Card click event to directly click this link, we need to stop propagation to avoid a double click event.
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.stopPropagation();
+  };
+
+  return (
+    <StyledCardLink
+      {...rest}
+      target={external ? "_blank" : undefined}
+      rel={external ? "noreferrer" : undefined}
+      href={href}
+      onClick={handleClick}
+      ref={linkRef}
+      // TODO: fix this type since `color` should be valid here. TS can't resolve the correct type.
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      color={color}
+    >
+      <>
+        {children}
+        {affordance ? <CardAffordance ml={300} /> : null}
+      </>
+    </StyledCardLink>
+  );
+};

package/src/utils.ts

@@ -0,0 +1,61 @@
+import { createContext, useContext, useEffect } from "react";
+import { assertIsElement } from "@sproutsocial/seeds-react-utilities";
+import type { TypeCardProps, TypeCardContext } from "./CardTypes";
+
+export const SubComponentContext = createContext<TypeCardContext>({
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  setHasSubComponent: () => {},
+  href: "",
+  linkRef: null,
+});
+
+export function useChildContext() {
+  const { setHasSubComponent } = useContext(SubComponentContext);
+  useEffect(() => {
+    setHasSubComponent && setHasSubComponent(true);
+  }, [setHasSubComponent]);
+}
+
+interface navigateToParams extends Pick<TypeCardProps, "href"> {
+  e: React.MouseEvent | React.KeyboardEvent;
+  ref: React.RefObject<HTMLDivElement>;
+}
+
+export const navigateTo = ({ e, href, ref }: navigateToParams) => {
+  const { target } = e;
+
+  // asserts that target is an element so `contains` accepts it
+  assertIsElement(target);
+
+  if (ref.current?.contains(target)) {
+    if (
+      target.getAttribute("onclick") !== null ||
+      target.getAttribute("href") !== null
+    ) {
+      e.stopPropagation();
+      return;
+    }
+  }
+
+  window.open(href, "_blank")?.focus();
+};
+
+interface onKeyDownParams
+  extends Pick<TypeCardProps, "href" | "onClick" | "role"> {
+  e: React.KeyboardEvent;
+  ref: React.RefObject<HTMLDivElement>;
+}
+
+export const onKeyDown = ({ e, href, onClick, ref, role }: onKeyDownParams) => {
+  if (e?.key === "Enter") {
+    if (role === "link") {
+      return navigateTo({ e, href, ref });
+    }
+
+    if (role === "presentation") {
+      return;
+    }
+
+    return onClick?.(e);
+  }
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@sproutsocial/seeds-tsconfig/bundler/dom/library-monorepo",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "module": "esnext"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}