feat(square-card): add new square card component

packages/example/src/data/nav-items.yaml

@@ -74,6 +74,8 @@
       path: /components/PageDescription
     - title: ResourceCard
       path: /components/ResourceCard
+    - title: SquareCard
+      path: /components/SquareCard
     - title: Tabs
       path: /components/Tabs
     - title: Title

packages/example/src/pages/components/SquareCard.mdx

@@ -0,0 +1,114 @@
+---
+title: SquareCard
+description: Usage instructions for the SquareCard component
+---
+
+import { Tools } from '@carbon/pictograms-react';
+
+<PageDescription>
+
+The `<SquareCard>` component should generally be used inside of a
+`<Row className="square-card-group">` component. This allows us to
+properly space the columns components when they wrap on mobile.
+
+</PageDescription>
+
+## Example
+
+
+<Row className="square-card-group">
+<SquareCard
+  title="A small sentence can go here in conjunction with a pictogram"
+  href="/"
+  >
+  <Tools aria-label="Tools" className="my-custom-class" />
+</SquareCard>
+<SquareCard
+  title="A small sentence can go here with no pictogram"
+  href="/"
+  helperText="(Optional text)"
+  />
+<SquareCard
+  title="Short title"
+  href="/"
+  bodyText="A short body paragraph describing the card could go here."
+  />
+<SquareCard
+  title="Small title here"
+  smallTitle
+  href="/"
+  bodyText="A short body paragraph describing the card could go here."
+  disabled
+  >
+  <Tools aria-label="Tools" className="my-custom-class" />
+</SquareCard>
+<SquareCard
+  title="Small title here"
+  smallTitle
+  href="/"
+  bodyText="A short body paragraph describing the card could go here."
+  helperText="(Optional text)"
+  disabled
+  />
+</Row>
+
+## Code
+
+```mdx path=components/SquareCard/SquareCard.js src=https://github.com/carbon-design-system/gatsby-theme-carbon/tree/main/packages/gatsby-theme-carbon/src/components/SquareCard
+import { Tools } from '@carbon/pictograms-react';
+
+<Row className="square-card-group">
+  <SquareCard
+    title="A small sentence can go here in conjunction with a pictogram"
+    href="/"
+    >
+    <Tools aria-label="Tools" className="my-custom-class" />
+  </SquareCard>
+
+  <SquareCard
+    title="A small sentence can go here with no pictogram"
+    href="/"
+    helperText="(Optional text)"
+    />
+
+  <SquareCard
+    title="Short title"
+    href="/"
+    bodyText="A short body paragraph describing the card could go here."
+    />
+
+  <SquareCard
+    title="Small title here"
+    smallTitle
+    href="/"
+    bodyText="A short body paragraph describing the card could go here."
+    disabled
+    >
+    <Tools aria-label="Tools" className="my-custom-class" />
+  </SquareCard>
+
+  <SquareCard
+    title="Small title here"
+    smallTitle
+    href="/"
+    bodyText="A short body paragraph describing the card could go here."
+    helperText="(Optional text)"
+    disabled
+    />
+</Row>
+```
+
+### Props
+
+| property      | propType | required | default     | description                                                                                                      |
+| ------------- | -------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| children      | node     |          |             | Optional pictogram icon to add to bottom left corner cannot be combined with 'helperText'                        |
+| href          | string   |          |             | Set url for card                                                                                                 |
+| smallTitle    | bool     |          | `false`     | Set to true to display smaller title                                                                             |
+| title         | string   |          |             | Card title - default is `large`                                                                                  |
+| actionIcon    | string   |          | `ArrowRight`| Action icon, default is no 'ArrowRight', options are `Launch`, `ArrowRight`, `Download`, `Disabled`, `Email`     |
+| disabled      | bool     |          | `false`     | Set for disabled card                                                                                            |
+| className     | string   |          |             | Add custom class name                                                                                            |
+| helperText    | string   |          |             | Optional helper text that appears at the bottom left corner cannot be combined with 'children' text. This is only meant for a date or a category name              |
+| bodyText      | string   |          |             | Optional body text for card description                                                                          |
+| color         | string   |          | `light`     | Set to `dark` for dark background                                                                                |

packages/gatsby-theme-carbon/index.js

@@ -13,6 +13,7 @@ export { default as Aside } from './src/components/Aside';
 export { default as FeatureCard } from './src/components/FeatureCard';
 export { default as FourOhFour } from './src/components/FourOhFour';
 export { default as ImageCard } from './src/components/ImageCard';
+export { default as SquareCard } from './src/components/SquareCard';
 export { Tabs, Tab } from './src/components/Tabs';
 export { default as InlineNotification } from './src/components/InlineNotification';
 // Homepage Template Components

packages/gatsby-theme-carbon/package.json

@@ -25,6 +25,7 @@
     "@babel/core": "^7.14.6",
     "@carbon/elements": "^10.38.0",
     "@carbon/icons-react": "^10.35.0",
+    "@carbon/pictograms-react": "^11.14.0",
     "@carbon/themes": "^10.38.0",
     "@mdx-js/mdx": "^1.5.5",
     "@mdx-js/react": "^1.5.5",

packages/gatsby-theme-carbon/src/components/MDXProvider/defaultComponents.js

@@ -30,6 +30,7 @@ import Title from '../Title';
 import { MiniCard, CardGroup } from '../MiniCard';
 import Sup from '../markdown/Sup';
 import Abbr from '../markdown/Abbr';
+import SquareCard from '../SquareCard';
 
 const components = {
   wrapper: function Wrapper({ children, ...props }) {
@@ -81,6 +82,7 @@ const components = {
   Title,
   MiniCard,
   CardGroup,
+  SquareCard,
 };
 
 export default components;

packages/gatsby-theme-carbon/src/components/SquareCard/SquareCard.js

@@ -0,0 +1,175 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import cx from 'classnames';
+import { Link, withPrefix } from 'gatsby';
+import {
+  Launch20,
+  Download20,
+  ArrowRight20,
+  Error20,
+  Email20,
+} from '@carbon/icons-react';
+import { settings } from 'carbon-components';
+import { Column } from '../Grid';
+import * as styles from './SquareCard.module.scss';
+
+const { prefix } = settings;
+
+export default class SquareCard extends React.Component {
+  render() {
+    const {
+      children,
+      href,
+      title,
+      smallTitle,
+      disabled,
+      bodyText,
+      helperText,
+      className,
+      actionIcon,
+      color,
+      ...rest
+    } = this.props;
+
+    let isLink;
+    if (href !== undefined) {
+      isLink = href.charAt(0) === '/';
+    }
+
+    const SquareCardClassNames = cx(className, styles.squareCard, {
+      [styles.disabled]: disabled,
+      [styles.darkMode]: color === 'dark',
+    });
+
+    const SquareCardTitleClassNames = cx(className, styles.title, {
+      [styles.titleSmall]: smallTitle,
+    });
+
+    const carbonTileclassNames = cx(
+      [`${prefix}--tile`],
+      [`${prefix}--tile--clickable`]
+    );
+
+    const aspectRatioClassNames = cx(
+      `${prefix}--aspect-ratio`,
+      `${prefix}--aspect-ratio--1x1`
+    );
+
+    const cardContent = (
+      <>
+        <h2 className={SquareCardTitleClassNames}>{title}</h2>
+        {bodyText ? <p className={styles.body}>{bodyText}</p> : null}
+        {helperText ? <p className={styles.helperText}>{helperText}</p> : null}
+        {children ? <div className={styles.helperIcon}>{children}</div> : null}
+        <div className={styles.actionIcon}>
+          {actionIcon === 'arrowRight' && !disabled ? (
+            <ArrowRight20 aria-label="Open resource" />
+          ) : null}
+          {actionIcon === 'launch' && !disabled ? (
+            <Launch20 aria-label="Open resource" />
+          ) : null}
+          {actionIcon === 'download' && !disabled ? (
+            <Download20 aria-label="Download" />
+          ) : null}
+          {actionIcon === 'email' && !disabled ? (
+            <Email20 aria-label="Email" />
+          ) : null}
+          {actionIcon === 'disabled' || disabled === true ? (
+            <Error20 aria-label="disabled" />
+          ) : null}
+        </div>
+      </>
+    );
+
+    let cardContainer;
+    if (disabled === true) {
+      cardContainer = <div className={carbonTileclassNames}>{cardContent}</div>;
+    } else if (isLink === true) {
+      cardContainer = (
+        <Link to={href} className={carbonTileclassNames} {...rest}>
+          {cardContent}
+        </Link>
+      );
+    } else {
+      cardContainer = (
+        <a href={href} className={carbonTileclassNames} {...rest}>
+          {cardContent}
+        </a>
+      );
+    }
+
+    return (
+      <Column
+        colMd={4}
+        colLg={4}
+        noGutterSm
+        className={SquareCardClassNames}
+        {...rest}>
+        <div className={aspectRatioClassNames}>
+          <div className={`${prefix}--aspect-ratio--object`}>
+            {cardContainer}
+          </div>
+        </div>
+      </Column>
+    );
+  }
+}
+
+SquareCard.propTypes = {
+  /**
+   * Use to set a pictogram
+   */
+  children: PropTypes.node,
+
+  /**
+   * Set url for card
+   */
+  href: PropTypes.string,
+
+  /**
+   * Large heading
+   */
+  title: PropTypes.string,
+
+  /**
+   * Use to enable the smaller heading
+   */
+  smallTitle: PropTypes.bool,
+
+  /**
+   * Action icon, default is Arrow Right, options are Launch, ArrowRight, Download, Error
+   */
+  actionIcon: PropTypes.string,
+
+  /**
+   * Use for disabled card
+   */
+  disabled: PropTypes.bool,
+
+  /**
+   * Body text
+   */
+  bodyText: PropTypes.string,
+
+  /**
+   * Helper text
+   */
+  helperText: PropTypes.string,
+
+  /**
+   * set to "dark" for dark background card
+   */
+  color: PropTypes.string,
+
+  /**
+   * Specify a custom class
+   */
+  className: PropTypes.string,
+};
+
+SquareCard.defaultProps = {
+  color: 'light',
+  disabled: false,
+  smallTitle: false,
+  actionIcon: 'arrowRight',
+};