USWDS - Web components: Beta 2 banner additions #65

mejiaj · 2024-09-04T19:19:27Z

Summary

Improvements to Banner. Added JSDocs and component is now configurable via CSS custom properties.

Related issue

Closes #39.

Preview link

Preview link:

Banner preview →

Problem statement

Banner was missing:

a11y checklist requirements
theme settings
JSDoc comments
Unit tests

Additionally, the HTTPS lock icon was using unsafe SVG.

Solution

Added all the items above and swapped the SVG icon for a background image.

Major changes

Global CSS properties

Shared global properties created in a new core directory. They contain global token values and theme settings. They're meant to be attached at :root level and leaves :host for component-level settings.

.
├── components
└── core
    ├── colors.css
    ├── fonts.css
    └── index.css

Core stylesheets also added as an export in package.json.

  "exports": {
    "./core/*": "./src/core/*"
  },

Example

:root {
  // Atom/molecule
  --font-stack-source-sans-pro: "Source Sans Pro", "Helvetica Neue", "Helvetica",
    "Roboto", "Arial", sans-serif;
  --font-stack-public-sans: "Public Sans Web", -apple-system, BlinkMacSystemFont,
    "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji",
    "Segoe UI Emoji", "Segoe UI Symbol";

  // System token
  --usa-font-sans: var(--font-stack-source-sans-pro);
  
  // Theme token
  --usa-font-ui: var(--usa-font-sans);
}

Component properties

Caution

Missing the theme setting theme-banner-max-width because media queries don't allow custom props as a value. Potential solutions: SASS, PostCSS custom media queries, or Lightning CSS each requires additional dependencies for everyone.

Property	Default value	Fallback value	Description
--theme-banner-background-color	`--usa-base-lightest`	`#f0f0f0`	Sets banner background color.
--theme-banner-font-family	`--usa-font-ui`	`system-ui, sans-serif`	Sets banner font family.
--theme-banner-link-color	`--theme-link-color`	`#005ea2`	Sets the default link color.
--theme-banner-link-hover-color	`--theme-link-hover-color`	`#1a4480`	Sets the default link color.

Link settings and names match those defined in USA Link component.

Lock icon replaced

The icon is added via CSS on a class. This allows users to not worry about pasting in a big block of SVG markup. Especially useful when adding custom content via slots.

Before	After

Following pattern set by @aduth in uswds/uswds#5829.

Testing and review

Visit Banner preview
Verify there aren't regressions in functionality.
Unit tests pass.
Theme settings can be overridden.

Dependency updates

Dependency name	Previous version	New version
@chromatic-com/storybook	1.6.1	1.8.0
@rollup/rollup-linux-x64-gnu	4.20.0	4.21.2
@storybook/addon-a11y	8.2.7	8.2.9
@storybook/addon-essentials	8.2.7	8.2.9
@storybook/addon-links	8.2.7	8.2.9
@storybook/blocks	8.2.7	8.2.9
@storybook/manager-api	8.2.7	8.2.9
@storybook/test	8.2.7	8.2.9
@storybook/theming	8.2.7	8.2.9
@storybook/web-components	8.2.7	8.2.9
@storybook/web-components-vite	8.2.7	8.2.9
@uswds/uswds	3.8.1	3.8.2
axe-playwright	2.0.1	~~2.0.2~~ 2.0.3
eslint	9.8.0	9.9.1
shadow-dom-testing-library	1.11.2	1.11.3
storybook	8.2.7	8.2.9
vite	5.3.5	~~5.4.3~~ 5.4.8
@vitest/eslint-plugin	-	1.1.4

Following pattern from uswds/uswds#5829.

src/components/usa-banner/index.js

Following plugin guidance[^1] to avoid ESLint errors in unit tests [^1]: https://github.com/vitest-dev/eslint-plugin-vitest

Improve defaults, disable unused controls, and improve content.

…a-banner-component

mejiaj · 2024-10-04T16:22:01Z

package.json

@@ -57,8 +58,9 @@
    "@storybook/theming": "^8.2.9",
    "@storybook/web-components": "^8.2.9",
    "@storybook/web-components-vite": "^8.2.9",
+    "@vitest/eslint-plugin": "^1.1.4",


Helps get rid of errors when writing unit tests.

Before After

Looked into this while doing some POAM for this repo. Good addition 👍

mejiaj · 2024-10-04T17:01:03Z

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

@@ -4,58 +4,59 @@ import { html, nothing } from "lit";

 import { userEvent, expect, waitFor } from "@storybook/test";
 import { within } from "shadow-dom-testing-library";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";


Tip
Helps render custom slotted content in HTTPS body because it includes HTML.

mejiaj · 2024-10-04T18:15:28Z

src/core/colors.css

Tip
Will look into @property now that it has baseline support.

mejiaj · 2024-10-04T18:17:30Z

storybook/welcome.mdx

 <ColorPalette>
  <ColorItem
    title="Base"
    subtitle="Grayscale colors"
    colors={{
-      White: "#FFFFFF",
-      "Longer custom text": "#F3F3F3",
-      Black: "#000",
+      "--usa-base-lightest": "#F0F0F0",
+    }}
+  />
+</ColorPalette>
+
+## Global
+
+<ColorPalette>
+  <ColorItem
+    title="Link"
+    subtitle="Link colors"
+    colors={{
+      "--usa-theme-link-color": "#005EA2",
+      "--usa-theme-link-hover-color": "#1A4480",


Tip
Starting to document the shared properties here.

mejiaj · 2024-10-04T18:18:14Z

storybook/welcome.mdx

+
+- Variants
+- Properties
+- CSS Custom Properties


Tip
We'll need to remove this if we continue with custom elements manifest.

mejiaj · 2024-10-04T18:26:27Z

src/components/usa-banner/index.js

+ * @summary The usa-banner component.
+ *
+ * @attribute {string} lang - The element's language.
+ * @attribute {string} label - The custom aria label users can override.
+ * @attribute {string} tld - The top level domain for the site.
+ *
+ * @cssprop --theme-banner-background-color - Sets banner background color.
+ * @cssprop --theme-banner-font-family - Sets banner font family.
+ * @cssprop --theme-banner-link-color - Sets the default link color.
+ * @cssprop --theme-banner-link-hover-color - Sets the default link color.
+ *
+ * @slot banner-text - The text for official government website text.
+ * @slot banner-action - Action text label "Here's how you know."
+ * @slot domain-heading - Heading text for the domain section.
+ * @slot domain-text - Body text for domain section.
+ * @slot https-heading - Heading for HTTPs section.
+ * @slot https-text - Body text for HTTPs section.
+ *
+ * @tagname usa-banner


Note
StorybookJS docs are generated from this. There's currently an issue for hiding internal props. A small downside, but still benefits us in not having to re-write these in Story Docs.

Example

…a-banner-component

mejiaj added 12 commits September 4, 2024 11:19

Create global stylesheets for shared CSS vars

0fd8c4a

Create and document Banner settings

193708b

Move lock icon from markup to CSS

ca79783

Following pattern from uswds/uswds#5829.

Reflect lang attribute

d9167dd

Remove redundant story

6f95fef

Update dependencies

fc1f243

Remove test exclamation

521a121

Remove commented code

c6c9553

Fix hover color

b837937

Add quotes to background images

370d1f0

Add core stylesheets to exports

d11629f

Add colors and minimum story requirements to docs

b52ceef

aduth reviewed Sep 6, 2024

View reviewed changes

src/components/usa-banner/index.js Show resolved Hide resolved

mejiaj added 10 commits September 30, 2024 09:48

Add eslint plugin for vitest

36de343

Following plugin guidance[^1] to avoid ESLint errors in unit tests [^1]: https://github.com/vitest-dev/eslint-plugin-vitest

Separate lock icon to improve HTTPS text readability

2c7f43b

Improve custom content story

ac0024d

Improve defaults, disable unused controls, and improve content.

Create unit tests

14524a9

Update deps; add patch updates to axe playwright and vite

c44331a

Merge branch 'develop' of github.com:uswds/web-components into jm/bet…

2eab5b5

…a-banner-component

Regen custom elements manifest

7c25830

Add font declarations to font stylesheet

4430699

Run custom element manifest task in parallel with start command

0bc0f39

Fix name TLD comment

72887f4

mejiaj commented Oct 4, 2024

View reviewed changes

src/core/colors.css Outdated

Copy link

Collaborator Author

mejiaj Oct 4, 2024 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tip
Will look into @property now that it has baseline support.

Remove duplicate fallback properties

a599f72

mejiaj commented Oct 4, 2024

View reviewed changes

mejiaj changed the title ~~USWDS - Web components: Beta banner additions~~ USWDS - Web components: Beta 2 banner additions Oct 4, 2024

mejiaj marked this pull request as ready for review October 4, 2024 18:19

mejiaj requested review from heymatthenry and amyleadem October 4, 2024 18:20

mejiaj commented Oct 4, 2024

View reviewed changes

mejiaj requested review from mahoneycm and removed request for amyleadem October 8, 2024 18:23

Merge branch 'develop' of github.com:uswds/web-components into jm/bet…

7a4628a

…a-banner-component

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS - Web components: Beta 2 banner additions #65

USWDS - Web components: Beta 2 banner additions #65

mejiaj commented Sep 4, 2024 •

edited

Loading

mejiaj Oct 4, 2024

mahoneycm Oct 16, 2024

mejiaj Oct 4, 2024

mejiaj Oct 4, 2024 •

edited

Loading

mejiaj Oct 4, 2024

mejiaj Oct 4, 2024

mejiaj Oct 4, 2024

USWDS - Web components: Beta 2 banner additions #65

Are you sure you want to change the base?

USWDS - Web components: Beta 2 banner additions #65

Conversation

mejiaj commented Sep 4, 2024 • edited Loading

Summary

Related issue

Preview link

Problem statement

Solution

Major changes

Global CSS properties

Component properties

Lock icon replaced

Testing and review

Dependency updates

mejiaj Oct 4, 2024

Choose a reason for hiding this comment

mahoneycm Oct 16, 2024

Choose a reason for hiding this comment

mejiaj Oct 4, 2024

Choose a reason for hiding this comment

mejiaj Oct 4, 2024 • edited Loading

Choose a reason for hiding this comment

mejiaj Oct 4, 2024

Choose a reason for hiding this comment

mejiaj Oct 4, 2024

Choose a reason for hiding this comment

mejiaj Oct 4, 2024

Choose a reason for hiding this comment

mejiaj commented Sep 4, 2024 •

edited

Loading

mejiaj Oct 4, 2024 •

edited

Loading