USWDS-Next - Alpha: Create `usa-card` component #13

mahoneycm · 2024-06-04T20:36:14Z

Summary

Created an alpha version of a usa-card web component

Related issue

Closes #16

Requirements notes

Variants

Name	Description
Default	Card component with a heading, text content, and a button
Card w/ Media	A card variant featuring media.
Media with header first	A card variant featuring media, displaying the header first.
Inset Media	Indents the media element so it doesn’t extend to the edge of the card.
Exdent Media	Extends the media element out over the card border.
Flag	Display in a horizontal (“flag”) orientation at a specified width ($theme-card-flag-min-width).
Flag Media Right Inset	Display in a horizontal (“flag”) orientation with media inset and on the right side.

Accessibility

See related accessibility tests

Attributes & Props

Attribute	Element	Description
`header-first`	`<usa-card>`	Enables header first variant when added to custom element tag
`inset`	`<img>`	Indents the media element so it doesn’t extend to the edge of the card.
`exdent`	`<usa-card>`	When added to the custom element, it applies `exdent` styles to the header, body, and footer divs
	Component slots	Can be added to individual card slots to add `exdent` styles to specific card elements
`layout`	`<usa-card>`	Can take `flag

heymatthenry

Thanks for this! Couple of suggestions in there about supporting theming better and adding some documentation, but a really solid start!

heymatthenry · 2024-07-10T14:33:01Z

src/components/usa-card-group/index.js

@@ -0,0 +1,24 @@
+import { LitElement, html, unsafeCSS } from "lit";
+import usaCardStyle from "@uswds/uswds/scss/usa-card?inline";
+


suggestion: Could you please add some JSDoc comments to explain the props/attributes for this component? If you end up adding any style hooks, add those in too. Take a look at the supported metadata for custom element manifests to see what's available.

heymatthenry · 2024-07-10T14:46:21Z

src/components/usa-card/usa-card.scss.js

+      box-sizing: border-box;
+    }
+
+    [slot="card-heading"] {


suggestion: Consider using a part here for styling since this seems like a good place to support theming.

heymatthenry · 2024-07-10T14:52:42Z

src/components/usa-card/usa-card.scss.js

@@ -0,0 +1,23 @@
+import uswdsCoreStyle from "@uswds/uswds/scss/uswds-core?inline";
+import usaCardStyle from "@uswds/uswds/scss/usa-card?inline";


suggestion: Consider adding some CSS variable versions of design tokens to support theming here.

heymatthenry · 2024-07-10T14:53:23Z

src/components/usa-card/usa-card.scss.js

@@ -0,0 +1,23 @@
+import uswdsCoreStyle from "@uswds/uswds/scss/uswds-core?inline";
+import usaCardStyle from "@uswds/uswds/scss/usa-card?inline";
+import usaButtonStyle from "@uswds/uswds/scss/usa-button?inline";


suggestion: Same suggestion re: CSS variables for card theming.

mejiaj

Thanks for starting this. Added comments to better follow lit standards and improve clarity.

What I tested

Code passes npm run prettier:js
Creating custom card elements without errors
Card element follows lit standards and best practices

mejiaj · 2024-07-08T19:08:07Z

src/components/usa-card/card.stories.js

+import "./index";
+import "../usa-card-group/index";
+
+import { html, nothing} from "lit";


polish: Can we fix the spacing in braces?

mejiaj · 2024-07-08T19:16:54Z

src/components/usa-card/card.stories.js

+  args: {
+    title: "",
+    media: "https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg",
+    content: "Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.",


question: Does this mean I can't pass in custom markup to the card body?

mejiaj · 2024-07-08T19:20:23Z

src/components/usa-card/card.stories.js

+    title: "",
+    media: "https://designsystem.digital.gov/img/introducing-uswds-2-0/built-to-grow--alt.jpg",
+    content: "Lorem ipsum dolor sit amet consectetur adipisicing elit. Facilis earum tenetur quo cupiditate, eaque qui officia recusandae.",
+    buttonText: "Visit Florida Keys",


issue (non-blocking): Currently there's no way for users to pass their own CTA.

For example, if I wanted to pass a button instead of anchor. Or if I wanted to set a custom href.

mejiaj · 2024-07-10T15:19:34Z

src/components/usa-card/index.js

+  }
+}
+
+window.customElements.define("usa-card", UsaCard);


Suggested change

window.customElements.define("usa-card", UsaCard);

customElements.define("usa-card", UsaCard);

mejiaj · 2024-07-10T15:37:41Z

src/components/usa-card-group/index.js

+  }
+}
+
+window.customElements.define("usa-card-group", UsaCardGroup);


Suggested change

window.customElements.define("usa-card-group", UsaCardGroup);

customElements.define("usa-card-group", UsaCardGroup);

mejiaj · 2024-07-10T15:45:46Z

src/components/usa-card/index.js

+  cardTemplate() {
+    const classes = {
+      "usa-card": true,
+      "usa-card--header-first": this.headerFirst,
+      "usa-card--flag": this.layout === "flag" || this.layout === "flag-alt",
+      "usa-card--media-right": this.layout == "flag-alt",
+    }
+    return html`
+        <div class="${classMap(classes)}">
+          <div class="usa-card__container">
+            ${this.headerTemplate()}
+            ${this.mediaTemplate()}
+            ${this.bodyTemplate()}
+            ${this.footerTemplate()}
+          </div>
+        </div>
+    `
+  }


issue: This function seems redundant and could instead be moved to the render().

mejiaj · 2024-07-10T15:50:25Z

src/components/usa-card/index.js

+    }
+
+    const classes = {
+      "usa-card__media": true,


issue: Let's move static classes, like usa-card__media to the element and reserve class maps for dynamic.

Example

const classes = { - "usa-card__media": true, } + <div class="usa-card__media ${classMap(classes)}">

mejiaj · 2024-07-10T15:59:20Z

src/components/usa-card/index.js

+      "usa-card__media--inset": this.media.hasAttribute("inset") && !this.media.hasAttribute("exdent"),
+      "usa-card__media--exdent": this.exdent || this.media.hasAttribute("exdent") && !this.media.hasAttribute("indent"),


thought: Just an idea. A new attribute placement="extend | indent | none" might be useful here.

Possible alternative names: padding, position, spacing.

mejiaj · 2024-07-10T16:24:35Z

src/components/usa-card/index.js

+    this.headerContent = [...this.header.children];
+    this.media = this.querySelector("[slot='card-media']")
+    this.body = this.querySelector("[slot='card-body']");
+    this.bodyContent = [...this.body.children];


issue: If not defined I get an error.

Error

VM784 index.js:26 Uncaught TypeError: Cannot read properties of null (reading 'children') at new UsaCard (VM784 index.js:26:38) at TemplateInstance._clone (VM740 chunk-MPCHNED3.js:354:80) at _ChildPart._commitTemplateResult (VM740 chunk-MPCHNED3.js:590:33) at _ChildPart._$setValue (VM740 chunk-MPCHNED3.js:486:12) at render (VM740 chunk-MPCHNED3.js:934:8) at renderToCanvas (VM728 @storybook_web-components_dist_entry-preview__mjs.js:48:5) at StoryRender.renderToScreen (VM713 runtime.js:147:9014) at VM713 runtime.js:144:3305 at StoryRender.runPhase (VM713 runtime.js:144:943) at StoryRender.render (VM713 runtime.js:144:3238)

Sample markup

<usa-card> <div slot="card-header"> <h1>My title</h1> </div> Hello </usa-card>

mejiaj · 2024-07-10T16:26:56Z

src/components/usa-card/index.js

+    this.footer = this.querySelector("[slot='card-footer']");
+    this.footerContent = [...this.footer.children];


issue: If not defined I get an error.

Error

index.js:28 Uncaught TypeError: Cannot read properties of null (reading 'children') at new UsaCard (index.js:28:42) at TemplateInstance._clone (chunk-MPCHNED3.js?v=1f2e655f:354:80) at _ChildPart._commitTemplateResult (chunk-MPCHNED3.js?v=1f2e655f:590:33) at _ChildPart._$setValue (chunk-MPCHNED3.js?v=1f2e655f:486:12) at render (chunk-MPCHNED3.js?v=1f2e655f:934:8) at sourceDecorator (@storybook_web-components_dist_entry-preview-docs__mjs.js?v=1f2e655f:162:108) at hookified (runtime.js:97:10605) at runtime.js:113:3361 at runtime.js:113:4023 at runtime.js:97:11408

Sample markup

<usa-card> <div slot="card-body"> <h1>My title</h1> Hello from card body. </div> </usa-card>

amyleadem and others added 12 commits May 24, 2024 15:49

Add identifier component

c4f8c72

Add scaffolding to elements

3d348a9

Add attribute-based identifier

dae3bb9

Replace inline classes with slot names

eb8c394

Clean up code

78ff480

Check for existence of slot elements before manipulating

0bb3b3a

Generate logo wrapper; clean up code and comments

f346baf

Add examples of diff logo counts

d732d9d

Create card component

cb1fcb7

Remove identifier to isolate component

2bf476c

Switch to slot approach

80b74a5

Add component markup

16ffebb

mahoneycm changed the title ~~Add usa-link component~~ [Playground] - Add usa-card component Jun 5, 2024

mahoneycm marked this pull request as draft June 7, 2024 18:14

mahoneycm added 5 commits June 7, 2024 14:20

Add usa-card group component

e588cd8

Add flag variant

8b88b43

Remove console.log

d0b9832

Add all variant classes

698f559

Add all variants to index.html

104f0a3

mahoneycm mentioned this pull request Jun 11, 2024

Add usa-link component #8

Merged

mahoneycm added 10 commits June 11, 2024 15:50

Update properties to use reactive props syntax

fb9d0f8

Co-authored-by: James Mejia <[email protected]>

e264fed

Add card variants to storybook

f977c70

Remove unused variants

833036a

testing conditional image

0dc2b0a

Add conditional header first logic

ed9e4eb

Remove unused setClasses function

873193d

Revise variant approach

f89956b

Use new variant attributes

80b53fd

Fix exdent check

51f8461

mahoneycm added 2 commits June 14, 2024 17:12

Fix indent example in index.html

cb347f6

Update storybook controls

ef16691

Base automatically changed from jm-lit-banner to mh/lit-banner June 18, 2024 14:09

mahoneycm added 9 commits June 26, 2024 14:22

Remove unused functions, update attributes to kebab case

97b3626

Normalize storybook controls, add card group example

1c6fb6c

Add flag variants to card group

bfe9ccc

Add expanded control panel to display descriptions

008dc99

Set heading styles via card-heading slot

42393e6

Abstract styles to usa-card.scss.js

1e190c9

Merge branch 'develop' of github.com:uswds/uswds-next into cm/lit-card

ff84c5f

Move components to src/components

434007d

Fix card group html display

8808009

mahoneycm changed the title ~~[Playground] - Add usa-card component~~ USWDS-Next - Alpha: Create usa-card component Jul 3, 2024

Add story description for flag media right

93a482a

mahoneycm changed the base branch from mh/lit-banner to develop July 3, 2024 19:43

mahoneycm marked this pull request as ready for review July 3, 2024 20:41

mahoneycm requested review from heymatthenry, mejiaj and amyleadem July 3, 2024 20:42

heymatthenry requested changes Jul 10, 2024

View reviewed changes

mejiaj requested changes Jul 10, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS-Next - Alpha: Create `usa-card` component #13

USWDS-Next - Alpha: Create `usa-card` component #13

mahoneycm commented Jun 4, 2024 •

edited

Loading

heymatthenry left a comment

heymatthenry Jul 10, 2024

heymatthenry Jul 10, 2024

heymatthenry Jul 10, 2024

heymatthenry Jul 10, 2024

mejiaj left a comment

mejiaj Jul 8, 2024

mejiaj Jul 8, 2024

mejiaj Jul 8, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

mejiaj Jul 10, 2024

		@@ -0,0 +1,24 @@
		import { LitElement, html, unsafeCSS } from "lit";
		import usaCardStyle from "@uswds/uswds/scss/usa-card?inline";

		@@ -0,0 +1,23 @@
		import uswdsCoreStyle from "@uswds/uswds/scss/uswds-core?inline";
		import usaCardStyle from "@uswds/uswds/scss/usa-card?inline";

	window.customElements.define("usa-card", UsaCard);
	customElements.define("usa-card", UsaCard);

	window.customElements.define("usa-card-group", UsaCardGroup);
	customElements.define("usa-card-group", UsaCardGroup);

		"usa-card__media--inset": this.media.hasAttribute("inset") && !this.media.hasAttribute("exdent"),
		"usa-card__media--exdent": this.exdent \|\| this.media.hasAttribute("exdent") && !this.media.hasAttribute("indent"),

		this.footer = this.querySelector("[slot='card-footer']");
		this.footerContent = [...this.footer.children];

USWDS-Next - Alpha: Create usa-card component #13

Are you sure you want to change the base?

USWDS-Next - Alpha: Create usa-card component #13

Conversation

mahoneycm commented Jun 4, 2024 • edited Loading

Summary

Related issue

Requirements notes

Variants

Accessibility

Attributes & Props

heymatthenry left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mejiaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

USWDS-Next - Alpha: Create `usa-card` component #13

USWDS-Next - Alpha: Create `usa-card` component #13

mahoneycm commented Jun 4, 2024 •

edited

Loading