Web-components: Create `usa-identifier` web component #21

amyleadem · 2024-06-17T15:31:52Z

Summary

Create an alpha version of the usa-identifier web component.

Related issue

Closes #26

Preview link

Identifier component (Storybook)

Related PRs

This is a cleaned up version of the "identifier playground" in PR #11.

Note

PR #11 explores alternative methods for implementing the identifier component, including a couple of options for an attribute-based implementation. There are a lot of files and options in there, so I created this second PR to minimize confusion as I focus on the declarative markup version of the component. Please add any comments about the identifier web component to this PR, not PR #11.

Task list

Match visuals from USWDS 3
Passes accessibility tests
Offer ability to create content in multiple languages
Incorporate Lit internationalization (on hold)
Add CSS parts to customizable elements
Create CSS variables for existing identifier settings
Improve formatting on code preview in Storybook
Draft unit tests
Demo css variables in storybook controls

web-components/src/components/usa-identifier/identifier.stories.js

mejiaj

Nice work so far! Added a few comments thinking about lessons learned in #12.

We don't have to follow that path, but we should consider what we can render by default in the component if users write <usa-identifier></usa-identifier>.

web-components/src/components/usa-identifier/identifier.stories.js

mejiaj · 2024-06-20T20:43:42Z

web-components/src/components/usa-identifier/index.js

+import uswdsCoreStyle from "@uswds/uswds/scss/uswds-core?inline";
+import usaIdentifierStyle from "@uswds/uswds/scss/usa-identifier?inline";
+
+export class UsaIdentifier extends LitElement {


Lit recommends using component props as input. Source →

We should leverage reactive props if we're able to for defaults / configurable settings.

mejiaj · 2024-06-20T20:49:00Z

web-components/src/components/usa-identifier/identifier.stories.js

+      <a slot="logo" href="${primary_agency.url}">
+        <img src="${logo1}" alt="${primary_agency.name} logo" />
+      </a>`: null}


Seeing slot here, I'd expect to see <slot> elements in the component template.

Example

 <slot name="logo"></slot>  <span slot="logo"> <img src="logo-1.svg" /> <img src="logo-2.svg" /> <img src="logo-3.svg" /> </span>

web-components/src/components/usa-identifier/index.js

…s/uswds-next into al/add-identifier-storybook

…/add-identifier-storybook

- Prevents axe-core error for invalid attribute

…/add-identifier-storybook

…now)

- This should fix color contrast errors in playwright

…/add-identifier-storybook

amyleadem · 2024-08-21T14:15:38Z

package.json

@@ -45,6 +45,7 @@
    "@storybook/addon-a11y": "^8.2.7",
    "@storybook/addon-essentials": "^8.2.7",
    "@storybook/addon-links": "^8.2.7",
+    "@storybook/addon-mdx-gfm": "^8.1.11",


Note
Added this dependency to enable markdown tables in the readme.mdx file ¹. If we move forward without the docs tables, we can remove this dependency.

Footnotes

https://storybook.js.org/docs/writing-docs/mdx#markdown-tables-arent-rendering-correctly ↩

amyleadem · 2024-08-21T14:16:12Z

.storybook/main.js

+    {
+      name: '@storybook/addon-docs',
+      options: {
+        mdxPluginOptions: {
+          mdxCompileOptions: {
+            remarkPlugins: [remarkGfm],
+          },
+        },
+      },
+    },


Note
Added this code to enable markdown tables in the readme.mdx file ¹. If we move forward without the docs tables, we can remove this.

Footnotes

https://storybook.js.org/docs/writing-docs/mdx#markdown-tables-arent-rendering-correctly ↩

amyleadem · 2024-08-21T14:33:02Z

src/components/usa-identifier/_readme.mdx

Note
I manually added content to the tables on this page to demonstrate ideas for possible content in the storybook docs. In the future, we should explore ways to automatically generate this content from the JSDocs in index.js.

amyleadem · 2024-08-21T15:39:00Z

@mahoneycm @mejiaj @heymatthenry @thisisdano

I just tagged you all for review on this PR. There is a lot here, so I'm proposing that before we dive into review of the structure of the .js and .css files, it would be good to first get feedback on the light DOM structure, the customization options, and the visuals and accessibility of the rendered component.

I just don't want us spending time diving too deep into the JS or CSS then decide we want to restructure it all in favor of a different light DOM setup, for example.

Let me know if you have any questions or comments!

mejiaj

Reviewing based on request for feedback on: structure, customization options, and visuals/accessibility of component.

I used our implementation of Identifier from USWDS-Site as a reference.

Structure

Listed a few ways I tried to create my own Identifier component.

Minimal markup

Note: Leaving out the required links intentionally to see what's generated.

Input

<usa-identifier>
  <div slot="logo">
    <a href="#">
      <img
        src="https://designsystem.digital.gov/img/gsa-logo.svg"
        alt="GSA logo"
      />
    </a>
  </div>
  <p slot="domain">designsystem.digital.gov</p>

  <div slot="agency-primary">
    <a href="#" agency-shortname="GSA">General Services Administration</a>
  </div>
</usa-identifier>

Ouput
The output is pretty good and it looks exactly how I'd expect.

Quibble: There's no indication that I'm missing required link URLs.

A working version

Input

<usa-identifier
  urlAbout="https://www.gsa.gov/about-us"
  urlAccessibility="https://www.gsa.gov/website-information/accessibility-statement"
  urlFOIA="https://www.gsa.gov/reference/freedom-of-information-act-foia"
  urlNoFEAR="https://www.gsa.gov/reference/civil-rights-programs/notification-and-federal-employee-antidiscrimination-and-retaliation-act-of-2002"
  urlOIG="https://www.gsaig.gov/"
  urlPerformance="https://www.gsa.gov/reference/reports/budget-performance"
  urlPrivacy="https://www.gsa.gov/website-information/website-policies"
>
  <div slot="logo">
    <a href="#">
      <img
        src="https://designsystem.digital.gov/img/gsa-logo.svg"
        alt="GSA logo"
      />
    </a>
  </div>
  <p slot="domain">designsystem.digital.gov</p>

  <div slot="agency-primary">
    <a href="#" agency-shortname="GSA">General Services Administration</a>
  </div>
</usa-identifier>

Output
Visually, nothing changed — which is good.

Customizing strings

Input

Not sure if I did it right, but the visual output looks similar to what I'd expect.

<usa-identifier
  urlAbout="https://www.gsa.gov/about-us"
  urlAccessibility="https://www.gsa.gov/website-information/accessibility-statement"
  urlFOIA="https://www.gsa.gov/reference/freedom-of-information-act-foia"
  urlNoFEAR="https://www.gsa.gov/reference/civil-rights-programs/notification-and-federal-employee-antidiscrimination-and-retaliation-act-of-2002"
  urlOIG="https://www.gsaig.gov/"
  urlPerformance="https://www.gsa.gov/reference/reports/budget-performance"
  urlPrivacy="https://www.gsa.gov/website-information/website-policies"
  textAbout="Sobre vote.gov"
  textAccessibility="Acessibilidade"
  textFOIA="Pedidos de FOIA (em inglês)"
  textPerformance="TK (em inglês)"
  textOIG="TK (em inglês)"
  textPrivacy="Política de privacidade (em inglês)"
>
  <div slot="logo">
    <a href="#">
      <img
        src="https://designsystem.digital.gov/img/gsa-logo.svg"
        alt="GSA logo"
      />
    </a>
  </div>
  <span slot="agency-intro">
    Uma página web oficial da Administração dos Serviços Gerais (em
    inglês)
  </span>
  <p slot="domain">designsystem.digital.gov</p>

  <div slot="agency-primary">
    <a href="#" agency-shortname="GSA">General Services Administration</a>
  </div>

  <!-- ! Docs say anchor, but demo uses div with an anchor. -->
  <!-- <a slot="usagov">Você procura informação e serviços do governo dos EUA? Visite USA.gov (em inglês)</a> -->

  <div slot="usagov">
    Você procura informação e serviços do governo dos EUA? Visite USA.gov
    (em inglês) <a href="https://www.usa.gov/">Visitez USA.gov</a>
  </div>
</usa-identifier>

Output

I had to reference the documentation a lot.

My version is missing translated strings for aria labels. I'm not sure how to set those (except for 1st item), but capturing findings below.

Aria label	Description
`usa-identifier`	This exists, but I forgot to change — maybe cue for us highlight in guidance.
`Agency description`	In the stable implementation this is set on `usa-identifier__identity`.
`Important links`	In stable this is set on `usa-identifier__section--required-links`.

Recommendations

Reduce # of props. This would improve readability. It's also consistent with components from landscape analysis and with patterns in existing component. For example, a single prop to set urlAbout and textAbout or move that to markup.
Allow aria labels to be set on description and important links. This could be on inner identifier markup.
Prototype slots with the same name. This can help simplify the markup because they'll be placed one after the other. The user doesn't have to worry about grouping or setting containers.

Example

This is a rough example for discussion.

Before

      <usa-identifier
        urlAbout="https://www.gsa.gov/about-us"
        urlAccessibility="https://www.gsa.gov/website-information/accessibility-statement"
        urlFOIA="https://www.gsa.gov/reference/freedom-of-information-act-foia"
        urlNoFEAR="https://www.gsa.gov/reference/civil-rights-programs/notification-and-federal-employee-antidiscrimination-and-retaliation-act-of-2002"
        urlOIG="https://www.gsaig.gov/"
        urlPerformance="https://www.gsa.gov/reference/reports/budget-performance"
        urlPrivacy="https://www.gsa.gov/website-information/website-policies"
        textAbout="Sobre vote.gov"
        textAccessibility="Acessibilidade"
        textFOIA="Pedidos de FOIA (em inglês)"
        textPerformance="TK (em inglês)"
        textOIG="TK (em inglês)"
        textPrivacy="Política de privacidade (em inglês)"
      >
        <div slot="logo">
          <a href="#">
            <img
              src="https://designsystem.digital.gov/img/gsa-logo.svg"
              alt="GSA logo"
            />
          </a>
        </div>
        <span slot="agency-intro">
          Uma página web oficial da Administração dos Serviços Gerais (em
          inglês)
        </span>
        <p slot="domain">designsystem.digital.gov</p>

        <div slot="agency-primary">
          <a href="#" agency-shortname="GSA">General Services Administration</a>
        </div>

        <!-- ! Docs say anchor, but demo uses div with an anchor. -->
        <!-- <a slot="usagov">Você procura informação e serviços do governo dos EUA? Visite USA.gov (em inglês)</a> -->

        <div slot="usagov">
          Você procura informação e serviços do governo dos EUA? Visite USA.gov
          (em inglês) <a href="https://www.usa.gov/">Visitez USA.gov</a>
        </div>
      </usa-identifier>

After

<usa-identifier>
  <a href="#" slot="logo">
    <img
      src="https://designsystem.digital.gov/img/gsa-logo.svg"
      alt="GSA logo"
    />
  </a>
  <!-- User would add this markup to customize. -->
  <p slot="agency-disclaimer" aria-label="descrição">
    Uma página web oficial da Administração dos Serviços Gerais (em inglês)
    <a href="">&lt;Parent agency&gt;</a>
  </p>

  <nav class="usa-identifier__section--required-links" aria-label="Importante">
    <a href="#">Sobre GSA<a>
    <a href="#">Acessibilidade</a>
    <a href="#">Pedidos de FOIA (em inglês)</a>
    <a href="#">Performance (em inglês)</a>
    <a href="#">OIG (em inglês)</a>
    <a href="#">Política de privacidade (em inglês)</a>
  </nav>

  <div slot="usagov">
    Você procura informação e serviços do governo dos EUA? Visite USA.gov
    (em inglês) <a href="https://www.usa.gov/">Visitez USA.gov</a>
  </div>
</usa-identifier>

Customization

I was able to successfully override using CSS Custom Properties via usa-identifier selector in devtools.

Add identifier component in storybook

44495b4

amyleadem mentioned this pull request Jun 17, 2024

[Playground] Add identifier component #11

Draft

amyleadem commented Jun 17, 2024

View reviewed changes

web-components/src/components/usa-identifier/identifier.stories.js Outdated Show resolved Hide resolved

amyleadem and others added 2 commits June 18, 2024 12:42

Comment out "an official" wrapper to prevent storybook error

299b123

Use latest vite config to fix SCSS import errors

973de11

amyleadem marked this pull request as ready for review June 20, 2024 16:08

mejiaj requested changes Jun 20, 2024

View reviewed changes

amyleadem added 9 commits June 21, 2024 07:39

Add css preprocessor to vite config

e25ca97

Merge branch 'al/add-identifier-storybook' of https://github.com/uswd…

ec9bd87

…s/uswds-next into al/add-identifier-storybook

Create indiv link objects in storybook; rename stories

26b0497

Add starter tests to identifier.spec.js

dfdc3c9

Update test for logos

0603ca8

Add lang data and control; add default usagov

b2264c8

Add custom content usagov; move lang data to json

5fd129e

Create default link; add taxpayer attribute

21c5c23

Consolidate aria-labels; rename controls

0ae101e

amyleadem marked this pull request as draft June 26, 2024 23:48

amyleadem added 13 commits June 28, 2024 09:05

Use map for required links

5187659

Use kebab case for slot names

3e35676

Add default content in masthead

701aea8

Update taxpayer prop name

5870445

Merge branch 'develop' of https://github.com/uswds/uswds-next into al…

36aebe9

…/add-identifier-storybook

Clean up code

11146d5

Add styles for second logo

2300129

Replace aria-label prop with label

972e137

- Prevents axe-core error for invalid attribute

Add custom docs

3295148

Install remark-gfm

20f6be0

Add font-face for source sans

a29a5fc

Add system and theme css vars files

311c8b4

Add css custom props; format css

aea6026

amyleadem added 10 commits August 12, 2024 16:35

Replace logo slots with usa-link

f20b3b8

Merge branch 'develop' of https://github.com/uswds/uswds-next into al…

bc8e74a

…/add-identifier-storybook

Run prettier

622c0f9

Remove identifier.spec.js

7e1f4a7

Use props for req'd links urls; remove custom translation story (for …

a4c3508

…now)

Add custom link text props; fix taxpayer_custom control

a72ef76

Clean up storybook controls and jsdocs

7c43d59

Remove usa-link import

2096376

Run prettier

89d281e

Alphabetize props in docs

1d023af

amyleadem marked this pull request as ready for review August 14, 2024 20:27

amyleadem added 9 commits August 16, 2024 14:45

Add explicit color styles for disclaimer and usagov

c7a2ade

- This should fix color contrast errors in playwright

Merge branch 'develop' of https://github.com/uswds/uswds-next into al…

79f63e5

…/add-identifier-storybook

Add --usa-theme-identifier-text-color & set to white

61a01d9

Run prettier

f64f2ee

Run prettier

0c5dc99

Merge branch 'develop' of https://github.com/uswds/uswds-next into al…

37ba970

…/add-identifier-storybook

Add CSS var controls; rename text color vars

089fe47

Add basic unit tests

5876e4b

Run prettier

8c67e36

amyleadem commented Aug 21, 2024

View reviewed changes

amyleadem requested review from mahoneycm, heymatthenry and thisisdano August 21, 2024 15:27

amyleadem requested a review from mejiaj August 21, 2024 15:42

mejiaj reviewed Sep 12, 2024

View reviewed changes

amyleadem changed the title ~~USWDS-Next: Create usa-identifier web component~~ Web-components: Create usa-identifier web component Sep 13, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Web-components: Create `usa-identifier` web component #21

Web-components: Create `usa-identifier` web component #21

amyleadem commented Jun 17, 2024 •

edited

Loading

mejiaj left a comment

mejiaj Jun 20, 2024

mejiaj Jun 20, 2024

amyleadem Aug 21, 2024

amyleadem Aug 21, 2024

amyleadem Aug 21, 2024

amyleadem commented Aug 21, 2024

mejiaj left a comment •

edited

Loading

Web-components: Create usa-identifier web component #21

Are you sure you want to change the base?

Web-components: Create usa-identifier web component #21

Conversation

amyleadem commented Jun 17, 2024 • edited Loading

Summary

Related issue

Preview link

Related PRs

Task list

mejiaj left a comment

Choose a reason for hiding this comment

mejiaj Jun 20, 2024

Choose a reason for hiding this comment

mejiaj Jun 20, 2024

Choose a reason for hiding this comment

amyleadem Aug 21, 2024

Choose a reason for hiding this comment

Footnotes

amyleadem Aug 21, 2024

Choose a reason for hiding this comment

Footnotes

amyleadem Aug 21, 2024

Choose a reason for hiding this comment

amyleadem commented Aug 21, 2024

mejiaj left a comment • edited Loading

Choose a reason for hiding this comment

Structure

Minimal markup

A working version

Customizing strings

Recommendations

Customization

Web-components: Create `usa-identifier` web component #21

Web-components: Create `usa-identifier` web component #21

amyleadem commented Jun 17, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading