@bloom-housing/ui-components 6.0.1-alpha.1 → 6.0.1-alpha.2

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [6.0.1-alpha.2](https://github.com/bloom-housing/bloom/compare/@bloom-housing/ui-components@6.0.1-alpha.1...@bloom-housing/ui-components@6.0.1-alpha.2) (2022-09-29)
+
+
+* 2938/card component (#3043) ([7a4a148](https://github.com/bloom-housing/bloom/commit/7a4a14891b4c8057f27a9f95e87a00d1d7a58be8)), closes [#3043](https://github.com/bloom-housing/bloom/issues/3043)
+
+
+### BREAKING CHANGES
+
+* Renamed exported interfaces in ListingCard so as to not conflict with Card and other components
+
+* Fix code style issues with Prettier
+
+* feat: split HeadingGroup out to its own separate component
+
+* fix: simplify stories and styling for Card and HeadingGroup
+
+* remove: prototype "slotted" card component
+
+* test: fix the incorrect component name in Card
+
+Co-authored-by: Lint Action <lint-action@samuelmeuli.com>
+
+
+
+
+
 ## [6.0.1-alpha.1](https://github.com/bloom-housing/bloom/compare/@bloom-housing/ui-components@6.0.1-alpha.0...@bloom-housing/ui-components@6.0.1-alpha.1) (2022-09-28)
 
 

package/index.ts

@@ -10,6 +10,7 @@ export * from "./src/actions/Video"
 /* Blocks */
 export * from "./src/blocks/ActionBlock"
 export * from "./src/blocks/StatusItem"
+export * from "./src/blocks/Card"
 export * from "./src/blocks/DashBlock"
 export * from "./src/blocks/DashBlocks"
 export * from "./src/blocks/FormCard"
@@ -55,6 +56,7 @@ export * from "./src/headers/PageHeader"
 export * from "./src/headers/SiteHeader"
 export * from "./src/headers/StepHeader"
 export * from "./src/headers/Heading"
+export * from "./src/headers/HeadingGroup"
 
 /* Helpers */
 export * from "./src/helpers/capitalize"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloom-housing/ui-components",
-  "version": "6.0.1-alpha.1",
+  "version": "6.0.1-alpha.2",
   "author": "Sean Albert <sean.albert@exygy.com>",
   "description": "Shared user interface components for Bloom affordable housing system",
   "homepage": "https://github.com/bloom-housing/bloom/tree/master/shared/ui-components",
@@ -110,5 +110,5 @@
     "ts-jest": "^26.4.1",
     "typesafe-actions": "^5.1.0"
   },
-  "gitHead": "413ca224f8c49c4ae69e431cfabe26545fe54159"
+  "gitHead": "2a2bd0fb61d7643c31d4a200b96a78d401bd0590"
 }

package/src/blocks/Card.docs.mdx

@@ -0,0 +1,60 @@
+import { Canvas, Story, ArgsTable } from "@storybook/addon-docs"
+import { Swatch } from "../prototypes/Swatch"
+import { Card } from "./Card"
+
+# Card
+
+<Canvas>
+  <Story id="blocks-card--text-content" />
+</Canvas>
+
+The 2nd-generation Card component is intended to serve as a flexible content container with a header, optional content sections, and a footer. Over time our intention is to "port" some other card types and content blocks in the system to use Card as their underlying structure.
+
+Styles within the Card node tree are intended to set up sensible defaults without requiring the consumer to configure bespoke styling as they author a card. For example, rule lines will be drawn automatically between the various subcomponents within a card, and margin/padding will be set according to top-level variables.
+
+You can author a Card using subcomponents simply by referencing them via a single Card import. For example, `<Card.Header>`, `<Card.Footer>` etc. In the case where you want to create a new type of card, you can import the subcomponents directly as `<CardHeader>`, `<CardFooter>`, etc. and place them in any container. It's still recommended you include the `.card` class on your custom container so you inherit a base set of CSS properties.
+
+Note that the `<Card.Footer>` subcomponent doesn't inherently add rules or padding so that you can use other components with self-contained styling such as `<ButtonGroup>`. However, you can add `<Card.Section>` within `<Card.Footer>` to add rules and padding.
+
+The `<Card.Header>` subcomponent will typically be paired with a child `<HeadingGroup>` for a title + subtitle grouping, but that's not a requirement.
+
+You can browse through the various stories for different examples of how you'd pattern a card with various subcomponents. Many of the visual aspects of a Card can be customized using the CSS variables listed below. For example, this "Detroit style" example:
+
+<Canvas>
+  <Story id="blocks-card--detroit-style" />
+</Canvas>
+
+## Card Properties
+
+<ArgsTable of={Card} />
+
+## Card.Header Properties
+
+<ArgsTable of={Card.Header} />
+
+## Card.Section Properties
+
+<ArgsTable of={Card.Section} />
+
+## Card.Footer Properties
+
+<ArgsTable of={Card.Footer} />
+
+## Theming Variables
+
+You can apply CSS variables to the `.card` selector to customize the appearance of both the component and various subcomponents.
+
+| Name                              | Type                                         | Description                                                                  | Default                  |
+| --------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------ |
+| `--background-color`              | <Swatch colorVar="--bloom-color-white" />    | Background color of the card                                                 | `--bloom-color-white`    |
+| `--border-radius`                 | Size                                         | Border radius of the card                                                    | `--bloom-rounded-lg`     |
+| `--border-width`                  | Size                                         | Border width of the card (and rules by default)                              | `--bloom-border-1`       |
+| `--border-color`                  | <Swatch colorVar="--bloom-color-gray-450" /> | Border color of the card (and rules by default)                              | `--bloom-color-gray-450` |
+| `--rule-width`                    | Size                                         | Width of the inset rules                                                     | `--border-width`         |
+| `--rule-color`                    | <Swatch colorVar="--bloom-color-gray-450" /> | Color of the inset rules                                                     | `--border-color`         |
+| `--content-padding-block`         | Size                                         | The space above and below content sections                                   | `--bloom-s8`             |
+| `--content-margin-inline-desktop` | Size                                         | The space to the left and right of content sections for desktop-size screens | `--bloom-s16`            |
+| `--content-margin-inline-mobile`  | Size                                         | The space to the left and right of content sections for mobile-size screens  | `--bloom-s4`             |
+| `--header-padding-block`          | Size                                         | The space above and below the header                                         | `--bloom-s8`             |
+| `--header-margin-inline-desktop`  | Size                                         | The space to the left and right of the header for desktop-size screens       | `--bloom-s16`            |
+| `--header-margin-inline-mobile`   | Size                                         | The space to the left and right of the header for mobile-size screens        | `--bloom-s4`             |

package/src/blocks/Card.scss

@@ -0,0 +1,65 @@
+.card {
+  /* Component Variables */
+  --background-color: var(--bloom-color-white);
+  --border-radius: var(--bloom-rounded-lg);
+  --border-width: var(--bloom-border-1);
+  --border-color: var(--bloom-color-gray-450);
+  --rule-width: var(--border-width);
+  --rule-color: var(--border-color);
+
+  --content-padding-block: var(--bloom-s8);
+  --content-margin-inline-desktop: var(--bloom-s16);
+  --content-margin-inline-mobile: var(--bloom-s4);
+  --content-margin-inline: var(--content-margin-inline-desktop);
+
+  --header-padding-block: var(--bloom-s8) var(--bloom-s3);
+  --header-margin-inline-desktop: var(--content-margin-inline-desktop);
+  --header-margin-inline-mobile: var(--content-margin-inline-mobile);
+  --header-margin-inline: var(--header-margin-inline-desktop);
+
+  @media (max-width: $screen-sm) {
+    --content-margin-inline: var(--content-margin-inline-mobile);
+    --header-margin-inline: var(--header-margin-inline-mobile);
+  }
+
+  /* Default Styles */
+  background-color: var(--background-color);
+  border: var(--border-width) solid var(--border-color);
+  overflow: hidden;
+  border-radius: var(--border-radius);
+  display: flex;
+  flex-direction: column;
+}
+
+.card__header {
+  padding-block: var(--header-padding-block);
+  margin-inline: var(--header-margin-inline);
+  border-bottom: var(--rule-width) solid var(--rule-color);
+
+  &.is-flex {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    gap: var(--bloom-s7);
+  }
+}
+
+.card__header + .card__footer {
+  margin-block-start: var(--content-padding-block);
+}
+
+.card > *:nth-child(n + 3),
+.card__footer > .card__section {
+  border-top: var(--rule-width) solid var(--rule-color);
+}
+
+.card__section {
+  padding-block: var(--content-padding-block);
+  margin-inline: var(--content-margin-inline);
+}
+
+/* Using the double-class specificity hack, proceed with caution: */
+.card__footer.card__footer,
+.card__footer.card__footer > :not(.card__section) + .card__section {
+  border-top: none;
+}

package/src/blocks/Card.tsx

@@ -0,0 +1,74 @@
+import React from "react"
+import "./Card.scss"
+
+export interface CardHeaderProps {
+  /** An additional element(s) you can add to the side of the main child element(s) */
+  suffix?: React.ReactNode
+  /** Additional class name */
+  className?: string
+  children: React.ReactNode
+}
+
+const CardHeader = (props: CardHeaderProps) => {
+  const classNames = ["card__header"]
+  if (props.suffix) classNames.push("is-flex")
+  if (props.className) classNames.push(props.className)
+
+  return (
+    <header className={classNames.join(" ")}>
+      {props.children}
+      {props.suffix}
+    </header>
+  )
+}
+
+export interface CardSectionProps {
+  /**
+   * Whether to center the text within the section
+   * @default false
+   */
+  centered?: boolean
+  /** Additional class name */
+  className?: string
+  children: React.ReactNode
+}
+
+const CardSection = (props: CardSectionProps) => {
+  const classNames = ["card__section"]
+  if (props.centered) classNames.push("text-center")
+  if (props.className) classNames.push(props.className)
+
+  return <div className={classNames.join(" ")}>{props.children}</div>
+}
+
+export interface CardFooterProps {
+  /** Additional class name */
+  className?: string
+  children: React.ReactNode
+}
+
+const CardFooter = (props: CardFooterProps) => {
+  const classNames = ["card__footer"]
+  if (props.className) classNames.push(props.className)
+
+  return <footer className={classNames.join(" ")}>{props.children}</footer>
+}
+
+export interface CardProps {
+  /** Additional class name */
+  className?: string
+  children: React.ReactNode
+}
+
+const Card = (props: CardProps) => {
+  const classNames = ["card"]
+  if (props.className) classNames.push(props.className)
+
+  return <article className={classNames.join(" ")}>{props.children}</article>
+}
+
+Card.Header = CardHeader
+Card.Section = CardSection
+Card.Footer = CardFooter
+
+export { Card as default, Card, CardHeader, CardSection, CardFooter }

package/src/headers/Heading.tsx

@@ -22,10 +22,11 @@ const HeaderStyleMap = {
 const Heading = (props: HeadingProps) => {
   const priority = props.priority && props.priority >= 1 && props.priority <= 6 ? props.priority : 1
   const Tag = `h${priority}` as keyof JSX.IntrinsicElements
-  const classNames = `${props.style && HeaderStyleMap[props.style]} ${
-    props.className && props.className
-  }`
-  return <Tag className={classNames}>{props.children}</Tag>
+  const classNames = []
+  if (props.style) classNames.push(HeaderStyleMap[props.style])
+  if (props.className) classNames.push(props.className)
+
+  return <Tag className={classNames.join(" ")}>{props.children}</Tag>
 }
 
 export { Heading as default, Heading }

package/src/headers/HeadingGroup.docs.mdx

@@ -0,0 +1,25 @@
+import { Canvas, Story, ArgsTable } from "@storybook/addon-docs"
+import { HeadingGroup } from "./HeadingGroup"
+
+# Heading Group
+
+<Canvas>
+  <Story id="headers-heading-group--with-content" />
+</Canvas>
+
+The HeadingGroup component provides a heading tag (h1-h6) combined with a paragraph tag as a subheading in an aria-minded fashion. Good for use in Card header components and other headers.
+
+## Heading Group Properties
+
+<ArgsTable of={HeadingGroup} />
+
+## Theming Variables
+
+You can apply CSS variables to the `.heading-group` selector to customize the appearance of the component.
+
+| Name                  | Type  | Description                                         | Default      |
+| --------------------- | ----- | --------------------------------------------------- | ------------ |
+| `--heading-margin`    | Size  | Vertical space added around the top heading, if any | `0rem`       |
+| `--subheading-margin` | Size  | The space between the heading and subheading        | `--bloom-s3` |
+| `--heading-color`     | Color | Override to set a specific heading text color       | `inherit`    |
+| `--subheading-color`  | Color | Override to set a specific subheading text color    | `inherit`    |

package/src/headers/HeadingGroup.scss

@@ -0,0 +1,23 @@
+.heading-group {
+  /* Component Variables */
+  --heading-margin: 0rem;
+  --subheading-margin: var(--bloom-s3);
+  --heading-color: inherit;
+  --subheading-color: inherit;
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    margin-block: var(--heading-margin);
+    color: var(--heading-color);
+  }
+
+  p {
+    margin-block: var(--subheading-margin);
+    font-size: var(--bloom-font-size-base);
+    color: var(--subheading-color);
+  }
+}

package/src/headers/HeadingGroup.tsx

@@ -0,0 +1,31 @@
+import React from "react"
+import { Heading } from "./Heading"
+import "./HeadingGroup.scss"
+
+export interface HeadingGroupProps {
+  /** A string or element to display in an `h2` tag (overridable via `headingPriority`) */
+  heading: React.ReactNode
+  /** A string or element to display in an `p` tag (using `aria-roledescription="subtitle"`) */
+  subheading: React.ReactNode
+  /**
+   * The heading level (1 through 6)
+   * @default 2
+   */
+  headingPriority?: number
+  /** Additional class name for the whole group */
+  className?: string
+}
+
+const HeadingGroup = (props: HeadingGroupProps) => {
+  const classNames = ["heading-group"]
+  if (props.className) classNames.push(props.className)
+
+  return (
+    <hgroup className={classNames.join(" ")} role="group">
+      <Heading priority={props.headingPriority ?? 2}>{props.heading}</Heading>
+      <p aria-roledescription="subtitle">{props.subheading}</p>
+    </hgroup>
+  )
+}
+
+export { HeadingGroup as default, HeadingGroup }

package/src/page_components/listing/ListingCard.tsx

@@ -12,7 +12,7 @@ import { NavigationContext } from "../../config/NavigationContext"
 
 interface ListingCardTableProps extends StandardTableProps, StackedTableProps {}
 
-export interface CardHeader {
+export interface ListingCardHeader {
   content: string | React.ReactNode
   href?: string
   customClass?: string
@@ -20,17 +20,17 @@ export interface CardHeader {
   isPillType?: boolean
 }
 
-export interface FooterButton {
+export interface ListingFooterButton {
   href: string
   text: string
   ariaHidden?: boolean
 }
 
 export interface ListingCardContentProps {
-  contentHeader?: CardHeader
-  contentSubheader?: CardHeader
-  tableHeader?: CardHeader
-  tableSubheader?: CardHeader
+  contentHeader?: ListingCardHeader
+  contentSubheader?: ListingCardHeader
+  tableHeader?: ListingCardHeader
+  tableSubheader?: ListingCardHeader
 }
 export interface ListingCardProps {
   /** A list of tags to be rendered below the content header, a Tag component is rendered for each */
@@ -40,7 +40,7 @@ export interface ListingCardProps {
   /** An object containing fields that render optional headers above the content section's table */
   contentProps?: ListingCardContentProps
   /** A list of buttons to render in the footer of the content section */
-  footerButtons?: FooterButton[]
+  footerButtons?: ListingFooterButton[]
   /** A class name applied to the footer container of the content section */
   footerContainerClass?: string
   /** Custom content rendered below the content table */
@@ -74,7 +74,7 @@ const ListingCard = (props: ListingCardProps) => {
   const { LinkComponent } = useContext(NavigationContext)
 
   const getHeader = (
-    header: CardHeader | undefined,
+    header: ListingCardHeader | undefined,
     priority: number,
     styleType?: HeaderType,
     customClass?: string