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.

thought: Ideally we'll be able to do something else here at some point 🤔

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

heymatthenry · 2024-12-17T16:46:08Z

Unfortunately, we're still hitting that issue in dev mode and it seems to be a Lit problem. From a Lit dev in their discord:

I believe there isn't compatibility between dev and prod mode so you'll need to force your environment to use one or the other consistently. Based on your setup, maybe try configuring your dev environment to build with prod settings?

This tracks with my own troubleshooting since, if you add the banner via a CDN like esm.sh, such that you're getting the production build, it works with a server in dev mode. SInce Vite 6's environments API now gives library authors finer-grained controls over environment settings, maybe there's something we can use there?

Useful for testing in other environments without having to run build on every change.

mejiaj · 2024-12-30T15:03:37Z

package.json

-    "build": "npm run clean && vite build && npm run manifest:build",
-    "clean": "node ./scripts/rmrf.js dist",
+    "build": "vite build && npm run manifest:build",
+    "build:watch": "vite build --watch",


Tip
Added for local development and testing. For example, when using npm link to test in Sandbox environment. You can run this without having to manually build every update.

praise: Nice. Thanks. I'd been doing this by hand a lot when npm linking

mejiaj · 2024-12-30T18:10:27Z

@heymatthenry I've done the the following:

Created a new blank vite environment [vite-sandbox] on uswds-sandbox.
Created a branch for testing the currentDirective._$initialize is not a function issue, that's [vite-sandbox-test-elements].
Opened a draft PR with findings/workarounds, USWDS-Sandbox - Test: Banner Elements.
- Can you test and confirm that this is working?

…a-banner-component

mejiaj · 2025-01-08T21:51:30Z

storybook/index.css

-  min-width: 320px;
-  min-height: 100vh;
-}
-


Note
Removed these styles because it was affecting our storybook previews. Screenshot below.

mejiaj · 2025-01-08T21:53:30Z

Ready for re-review. Resolved conflicts and added a comment on recent style change in da0454a

heymatthenry · 2025-01-14T17:22:02Z

src/core/fonts.css

+  font-weight: 700;
+  src: url("@uswds/uswds/fonts/public-sans/PublicSans-BoldItalic.woff2")
+    format("woff2");
+}


thought: These will all need to be in their own package sooner rather than later (but not today)

heymatthenry

Great work on this! Especially on de-Sass-ifying things!

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

mejiaj added 2 commits October 22, 2024 11:53

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

7a4628a

…a-banner-component

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

0e3de69

…a-banner-component

mejiaj requested a review from a team as a code owner December 3, 2024 17:46

mejiaj added 2 commits December 26, 2024 11:02

Resolve conflicts and regen generated files

81b7578

Add a script to build and watch for changes

47efcdb

Useful for testing in other environments without having to run build on every change.

mejiaj mentioned this pull request Dec 27, 2024

USWDS-Sandbox - Test: Banner Elements uswds/uswds-sandbox#170

Draft

mejiaj commented Dec 30, 2024

View reviewed changes

mejiaj added 3 commits January 8, 2025 15:47

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

101ff78

…a-banner-component

Remove global styles that were shrinking storybook previews

da0454a

Regenerate custom elements manifest

ec98109

mejiaj commented Jan 8, 2025

View reviewed changes

heymatthenry reviewed Jan 14, 2025

View reviewed changes

heymatthenry approved these changes Jan 14, 2025

View reviewed changes

heymatthenry merged commit ca3ffca into develop Jan 14, 2025
5 checks passed

heymatthenry deleted the jm/beta-banner-component branch January 14, 2025 17:23

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

heymatthenry Jan 14, 2025

mejiaj Oct 4, 2024 •

edited

Loading

mejiaj Oct 4, 2024

mejiaj Oct 4, 2024

mejiaj Oct 4, 2024

heymatthenry commented Dec 17, 2024

mejiaj Dec 30, 2024

heymatthenry Jan 14, 2025

mejiaj commented Dec 30, 2024

mejiaj Jan 8, 2025

mejiaj commented Jan 8, 2025

heymatthenry Jan 14, 2025

heymatthenry left a comment

USWDS - Web components: Beta 2 banner additions #65

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

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 Oct 4, 2024 • edited Loading

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

heymatthenry commented Dec 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mejiaj commented Dec 30, 2024

Choose a reason for hiding this comment

mejiaj commented Jan 8, 2025

Choose a reason for hiding this comment

heymatthenry left a comment

Choose a reason for hiding this comment

mejiaj commented Sep 4, 2024 •

edited

Loading

mejiaj Oct 4, 2024 •

edited

Loading