@sproutsocial/seeds-react-card 1.0.0

package/src/Card.stories.tsx

@@ -0,0 +1,389 @@
+import React, { useState, useEffect } from "react";
+import { Avatar } from "@sproutsocial/seeds-react-avatar";
+import { Banner } from "@sproutsocial/seeds-react-banner";
+import { Box } from "@sproutsocial/seeds-react-box";
+import { Card } from "./";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { Link } from "@sproutsocial/seeds-react-link";
+import { PartnerLogo } from "@sproutsocial/seeds-react-partner-logo";
+import type { EnumIllustrationNames } from "@sproutsocial/seeds-illustrations";
+import { SpotIllustration } from "@sproutsocial/seeds-react-spot-illustration";
+import { Text } from "@sproutsocial/seeds-react-text";
+import styled from "styled-components";
+import { CardHeader, CardContent, CardFooter, CardLink } from "./subComponents";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta<typeof Card> = {
+  title: "Components/Card",
+  component: Card,
+  argTypes: {
+    elevation: {
+      options: ["low", "medium", "high", undefined],
+      control: { type: "select" },
+    },
+    disabled: {
+      control: "boolean",
+    },
+    selected: {
+      control: "boolean",
+    },
+  },
+  args: {
+    elevation: undefined,
+    disabled: false,
+    selected: false,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Card>;
+
+export const AsLink: Story = {
+  render: (args) => (
+    <Card width={1 / 4} {...args}>
+      <Box display="flex" justifyContent="center" alignItems="center" my={400}>
+        <SpotIllustration
+          height="200px"
+          name="calendar-reporting"
+          aria-hidden
+        />
+      </Box>
+      <Text.SmallByline>Reporting</Text.SmallByline>
+      <CardLink external affordance>
+        Visit calendar report
+      </CardLink>
+    </Card>
+  ),
+  args: {
+    role: "link",
+    href: "https://seeds.sproutsocial.com/",
+  },
+};
+
+export const AsButton: Story = {
+  render: () => {
+    const [message, setMessage] = useState(false);
+
+    const _onClick = () => {
+      setMessage(true);
+    };
+
+    useEffect(() => {
+      const showMessage = setTimeout(() => {
+        setMessage(false);
+      }, 4000);
+
+      return function cleanup() {
+        clearTimeout(showMessage);
+      };
+    }, [message]);
+
+    return (
+      <>
+        {message ? (
+          <Box mb={400}>
+            <Banner text="Your click was successful." />
+          </Box>
+        ) : (
+          <Box mb={400}>
+            <Banner
+              type="warning"
+              text={
+                <Box
+                  width={1}
+                  display="flex"
+                  alignItems="center"
+                  justifyContent="space-between"
+                >
+                  <Text>
+                    Avoid nesting interactive content inside a Card with
+                    role='button'
+                  </Text>
+                  <Text>
+                    <Link href="https://html.spec.whatwg.org/multipage/dom.html#interactive-content">
+                      Learn more
+                      <Icon
+                        ml={200}
+                        size="mini"
+                        name="arrow-right-up-solid"
+                        role={undefined}
+                        svgProps={{
+                          role: "img",
+                          "aria-label": "opens in a new tab",
+                        }}
+                      />
+                    </Link>
+                  </Text>
+                </Box>
+              }
+            />
+          </Box>
+        )}
+        <Card role="button" onClick={_onClick} width={1 / 4}>
+          <Box mx="auto" mb={400}>
+            <PartnerLogo py={450} partnerName="facebook" size="jumbo" />
+          </Box>
+          <Text.SmallByline>Profile connect</Text.SmallByline>
+          <Text.Headline mb={300}>Facebook</Text.Headline>
+          <Text.BodyCopy>Click to connect your facebook account.</Text.BodyCopy>
+        </Card>
+      </>
+    );
+  },
+};
+
+export const AsPresentation: Story = {
+  render: (args) => (
+    <Card width={1 / 4} {...args}>
+      <Text.SmallByline>Analytics</Text.SmallByline>
+      <Text.Headline mb={300}>Google Analytics</Text.Headline>
+      <Box mx="auto" my={400}>
+        <PartnerLogo py={450} partnerName="google-analytics" size="jumbo" />
+      </Box>
+      <Text.BodyCopy mb={400}>
+        Learn more about how we track analytics.
+      </Text.BodyCopy>
+      <Link fontSize={300} href="https://google.com/" external>
+        Visit google
+        <Icon
+          mb={100}
+          ml={300}
+          size="mini"
+          name="arrow-right-outline"
+          role={undefined}
+          svgProps={{ role: "img", "aria-label": "opens in a new tab" }}
+        />
+      </Link>
+    </Card>
+  ),
+  args: {
+    role: "presentation",
+  },
+};
+
+export const AsButtonDisabled: Story = {
+  render: () => {
+    const [message, setMessage] = useState(false);
+
+    const _onClick = () => {
+      setMessage(true);
+    };
+
+    useEffect(() => {
+      const showMessage = setTimeout(() => {
+        setMessage(false);
+      }, 4000);
+
+      return function cleanup() {
+        clearTimeout(showMessage);
+      };
+    }, [message]);
+
+    return (
+      <>
+        {message ? (
+          <Box mb={400}>
+            <Banner text="Your click was successful." />
+          </Box>
+        ) : (
+          <Box mb={400}>
+            <Banner
+              type="warning"
+              text={
+                <Box
+                  width={1}
+                  display="flex"
+                  alignItems="center"
+                  justifyContent="space-between"
+                >
+                  <Text>
+                    Avoid nesting interactive content inside a Card with
+                    role='button'
+                  </Text>
+                  <Text>
+                    <Link href="https://html.spec.whatwg.org/multipage/dom.html#interactive-content">
+                      Learn more
+                      <Icon
+                        ml={200}
+                        size="mini"
+                        name="arrow-right-up-solid"
+                        role={undefined}
+                        svgProps={{
+                          role: "img",
+                          "aria-label": "opens in a new tab",
+                        }}
+                      />
+                    </Link>
+                  </Text>
+                </Box>
+              }
+            />
+          </Box>
+        )}
+        <Card role="button" disabled={true} onClick={_onClick} width={1 / 4}>
+          <Box mx="auto" mb={400}>
+            <SpotIllustration height="200px" name="coffee-cup" />
+          </Box>
+          <Text.SmallByline>SEEDS WEB</Text.SmallByline>
+          <Text.Headline mb={300}>Card component</Text.Headline>
+          <Text.BodyCopy>
+            The card component is a styled primitive container.
+          </Text.BodyCopy>
+        </Card>
+      </>
+    );
+  },
+};
+
+export const ConfigurableShadow: Story = {
+  render: (args) => (
+    <Card width={1 / 4} {...args}>
+      <Text.SmallByline>SEEDS WEB</Text.SmallByline>
+      <Text.Headline mb={300}>Card component</Text.Headline>
+      <Box mx="auto" my={400}>
+        <SpotIllustration height="200px" name="coffee-cup" />
+      </Box>
+      <Text.BodyCopy mb={400}>
+        The card component is a styled primitive container.
+      </Text.BodyCopy>
+      <Link fontSize={300} href="https://google.com/" external>
+        Use now
+        <Icon
+          mb={100}
+          ml={300}
+          size="mini"
+          name="arrow-right-up-solid"
+          role={undefined}
+          svgProps={{ role: "img", "aria-label": "opens in a new tab" }}
+        />
+      </Link>
+    </Card>
+  ),
+  args: {
+    role: "presentation",
+    elevation: "high",
+  },
+};
+
+export const SelectableComposition: Story = {
+  render: () => {
+    const [selected, setSelected] = useState(false);
+    const toggle = () => setSelected(!selected);
+
+    return (
+      <Card role="checkbox" selected={selected} onClick={toggle} width={1 / 3}>
+        <CardContent my={450} mx="auto">
+          <PartnerLogo partnerName="tiktok" size="jumbo" />
+        </CardContent>
+        <CardFooter flexDirection="column">
+          <Text.SmallSubHeadline>TikTok</Text.SmallSubHeadline>
+          <Text.SmallBodyCopy>
+            Select TikTok to start sharing content today.
+          </Text.SmallBodyCopy>
+        </CardFooter>
+      </Card>
+    );
+  },
+};
+
+export const CompositionUtilities: Story = {
+  render: () => (
+    <Card role="presentation">
+      <CardHeader>
+        <Avatar appearance="leaf" size="24px" name="Card Header" />
+        <Text.SubHeadline ml={300}>This is a card header</Text.SubHeadline>
+      </CardHeader>
+      <CardContent>
+        <Text.SmallBodyCopy as="p">
+          We can use the CardContent component to render cool content as seen
+          here:
+        </Text.SmallBodyCopy>
+        <Text.SmallBodyCopy as="p">
+          "Hi, Nard Dawg. I'm Lou Peachum!"
+        </Text.SmallBodyCopy>
+      </CardContent>
+      <CardFooter>
+        <Link external href="https://google.com">
+          Action in CardFooter
+          <Icon
+            ml={200}
+            size="mini"
+            name="arrow-right-up-solid"
+            role={undefined}
+            svgProps={{ role: "img", "aria-label": "opens in a new tab" }}
+          />
+        </Link>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+export const Cards: Story = {
+  render: () => {
+    const cards: {
+      subhead: string;
+      reportName: string;
+      image: EnumIllustrationNames;
+      href: string;
+    }[] = [
+      {
+        subhead: "Reporting",
+        reportName: "Profile performance",
+        image: "reporting",
+        href: "https://app.sproutsocial.com/reports/group_report",
+      },
+      {
+        subhead: "Reporting",
+        reportName: "Post performance",
+        image: "reporting-folder",
+        href: "https://app.sproutsocial.com/reports/post_performance",
+      },
+      {
+        subhead: "Reporting",
+        reportName: "Tag performance",
+        image: "analytics-offering",
+        href: "https://app.sproutsocial.com/reports/tag_performance",
+      },
+      {
+        subhead: "Reporting",
+        reportName: "Paid performance",
+        image: "listening-tour",
+        href: "https://app.sproutsocial.com/reports/cross_network_campaign_performance",
+      },
+    ];
+
+    const StyledList = styled.ul`
+      list-style: none;
+      display: flex;
+      flex-wrap: wrap;
+    `;
+
+    return (
+      <StyledList>
+        {cards.map((card) => (
+          <li key={card.href}>
+            <Card role="link" href={card.href} width="275px" mr={400} mb={400}>
+              <Box
+                display="flex"
+                justifyContent="center"
+                alignItems="center"
+                my={400}
+              >
+                <SpotIllustration
+                  height="200px"
+                  name={card.image}
+                  aria-hidden
+                />
+              </Box>
+              <Text.SmallByline>{card.subhead}</Text.SmallByline>
+              <CardLink external affordance>
+                Visit {card.reportName} report
+              </CardLink>
+            </Card>
+          </li>
+        ))}
+      </StyledList>
+    );
+  },
+};

package/src/Card.tsx

@@ -0,0 +1,73 @@
+import React, { useRef, useState } from "react";
+import { StyledCard } from "./styles";
+import type { TypeCardProps, TypeCardContext } from "./CardTypes";
+import { SubComponentContext, onKeyDown } from "./utils";
+import { SelectedIcon } from "./subComponents";
+
+/**
+ * @link https://seeds.sproutsocial.com/components/card/
+ *
+ * Avoid nesting interactive content inside a Card with role='button'.
+ *
+ * Interactive content: "a", "audio", "button", "embed", "iframe", "img", "input", "label", "select", "textarea", "video"
+ * @see https://html.spec.whatwg.org/multipage/dom.html#interactive-content
+ *
+ * @example
+ * <Card role="button" onClick={_onClick}>
+ *  <Button>Click me</Button>
+ * </Card>
+ */
+
+const Card = ({
+  children,
+  disabled = false,
+  elevation,
+  href,
+  onClick,
+  role = "presentation",
+  selected,
+  ...rest
+}: TypeCardProps) => {
+  const [hasSubComponent, setHasSubComponent] = useState<boolean>(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const linkRef = useRef<HTMLAnchorElement>(null);
+  const isRoleLink = role === "link";
+  const checkedConditions = role === "checkbox" ? selected : undefined;
+
+  const cardContext: TypeCardContext = {
+    setHasSubComponent: setHasSubComponent,
+    href: href,
+    linkRef: linkRef,
+  };
+
+  const handleClickConditions: React.MouseEventHandler = (e) =>
+    isRoleLink ? linkRef.current?.click() : onClick?.(e);
+
+  const handleKeyDown: React.KeyboardEventHandler<HTMLDivElement> = (e) =>
+    onKeyDown({ e, href, onClick, ref: containerRef, role });
+
+  return (
+    <StyledCard
+      tabIndex={isRoleLink ? -1 : 0}
+      role={isRoleLink ? undefined : role}
+      onClick={handleClickConditions}
+      onKeyDown={handleKeyDown}
+      $elevation={elevation}
+      ref={containerRef}
+      $selected={selected}
+      aria-checked={checkedConditions}
+      $disabled={disabled}
+      aria-disabled={disabled && disabled}
+      $compositionalComponents={hasSubComponent}
+      $isRoleLink={isRoleLink}
+      {...rest}
+    >
+      <SelectedIcon $selected={selected} />
+      <SubComponentContext.Provider value={cardContext}>
+        {children}
+      </SubComponentContext.Provider>
+    </StyledCard>
+  );
+};
+
+export default Card;

package/src/CardTypes.ts

@@ -0,0 +1,104 @@
+import type { TypeIconProps } from "@sproutsocial/seeds-react-icon";
+import * as React from "react";
+import type { TypeStyledComponentsCommonProps } from "@sproutsocial/seeds-react-system-props";
+import type {
+  TypeBorderSystemProps,
+  TypeColorSystemProps,
+  TypeFlexboxSystemProps,
+  TypeGridSystemProps,
+  TypeLayoutSystemProps,
+  TypePositionSystemProps,
+  TypeSpaceSystemProps,
+  TypeTypographySystemProps,
+} from "@sproutsocial/seeds-react-system-props";
+
+export interface TypeSharedCardSystemProps
+  extends Omit<React.ComponentPropsWithoutRef<"div">, "color">,
+    TypeStyledComponentsCommonProps,
+    TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypePositionSystemProps,
+    TypeSpaceSystemProps {}
+
+// consumer facing props that affect the styles of the component. We need to define these first so the user doesn't see our transient naming conventions.
+export interface TypeCardStyleProps {
+  elevation?: "low" | "medium" | "high";
+  disabled?: boolean;
+  compositionalComponents?: boolean;
+  selected?: boolean;
+  isRoleLink?: boolean;
+}
+
+// Since we only want to manage the style props in one place(above), we'll use this generic to prepend the properties of TypeCardStyleProps with $.
+export type TypeStyleTransientProps<T> = {
+  [K in Extract<keyof T, string> as `$${K}`]: T[K];
+};
+
+export type TypeCardStyleTransientProps =
+  TypeStyleTransientProps<TypeCardStyleProps>;
+
+export interface TypeStyledCard
+  extends TypeSharedCardSystemProps,
+    TypeCardStyleTransientProps {}
+
+export interface TypeCardStyles
+  extends TypeSharedCardSystemProps,
+    Omit<TypeCardStyleProps, "compositionalComponents"> {}
+
+type TypeOnClick = (event: React.MouseEvent | React.KeyboardEvent) => void;
+
+export type TypeCardConditions =
+  | {
+      role: "link";
+      href: string;
+      onClick?: never;
+    }
+  | {
+      role: "button";
+      href?: never;
+      onClick: TypeOnClick;
+    }
+  | {
+      role: "checkbox";
+      href?: never;
+      onClick: TypeOnClick;
+      selected: boolean;
+    }
+  | {
+      role: "presentation";
+      href?: never;
+      /**
+       * **Warning:**
+       * `role='presentation'` is outside of the accessiblity tree. Using an `onClick` that performs a user action should likely be used
+       * with `role='button'` instead.
+       */
+      onClick?: TypeOnClick;
+    };
+
+export type TypeCardProps = TypeCardConditions &
+  React.PropsWithChildren<TypeCardStyles>;
+
+export interface TypeCardArea extends TypeSharedCardSystemProps {
+  $divider?: "top" | "bottom";
+}
+
+export interface TypeStyledSelectedIcon extends TypeIconProps {
+  $selected?: TypeCardStyleTransientProps["$selected"];
+}
+
+export interface TypeCardContext {
+  setHasSubComponent?: React.Dispatch<React.SetStateAction<boolean>>;
+  href?: string;
+  linkRef: React.RefObject<HTMLAnchorElement> | null;
+}
+
+export interface TypeCardLink
+  extends Omit<React.ComponentPropsWithoutRef<"a">, "color">,
+    TypeColorSystemProps,
+    TypeTypographySystemProps {
+  affordance?: boolean;
+  external?: boolean;
+}