@ogds/elements 1.0.0-alpha.6

package/src/components/usa-banner/docs.mdx

@@ -0,0 +1,108 @@
+import {
+  Meta,
+  Title,
+  Primary,
+  Controls,
+  Stories,
+} from "@storybook/addon-docs/blocks";
+import { SiteNote } from "../../../.storybook/blocks/SiteNote.jsx";
+
+<Meta isTemplate />
+
+<Title />
+
+Banners identify official websites of government organizations in the United States. They also help visitors understand whether a website is official and secure.
+
+## About the banner component
+
+<SiteNote>
+  <strong>Note:</strong> Banners and identifiers are core components. We
+  recommend using both core components on most sites. Together, they are the
+  most recognizable and standardized design elements of a government site.
+</SiteNote>
+
+You should use the banner to identify your site as an official government site.
+
+The banner explains how to identify an official `.gov` or `.mil` domain and that these sites have secure HTTPS connections. Using the banner component is the best way to assure visitors that they’re connected to an official site.
+
+Most government sites should use the banner, but some should not use the banner. Do NOT use the banner on non-government domains such as a `.com` or `.org`.
+
+[//]: # "If you are unable to update to USWDS 2.8.0 (described on GitHub) or higher but still want to include the new language in your banner, we recommend editing your content to the language outlined in the component preview."
+
+---
+
+## Default
+
+This is the default banner as it appears when no additional properties or slots are passed to the component.
+
+<Primary />
+
+## Inputs
+
+The component accepts the following inputs (props). You can change the values below to see how the component changes.
+
+<Controls />
+
+---
+
+## Variations
+
+Listed below are additional variations of the component.
+
+<Stories />
+
+## Guidance
+
+### About
+
+This version of `usa-banner` (i.e. using web components) became available in [USWDS v3.13.0](https://github.com/uswds/uswds/releases/tag/v3.13.0). It is now part of the `@uswds/uswds-elements` package
+
+### When to use the default banner
+
+_To identify as an official government site._ Most government sites should use the banner, though non-federal government sites will need to change the text to be more accurate.
+
+### When to consider something else
+
+_If you don’t use a .gov/.mil domain and HTTPS._ The Design System’s banner text identifies `.gov` and `.mil` domains and HTTPS as indicators that a website is an official government website. Use this banner only if your site uses both the proper top-level domain (TLD) and HTTPS.
+
+_Any time it would be misleading._ The banner should be used to reduce confusion. Avoid using the banner on any site meant only for testing or otherwise not meant to be identified as an official government website.
+
+### Usability guidance
+
+_Use the provided text without customization._ The banner is most effective as an identifier and a learning tool when its message is consistent across government sites. With only a few exceptions (described in our Implementation guidance), sites should use the top-level domain (TLD)-appropriate text provided, unaltered. Use the Spanish version of the banner for Spanish-language websites.
+
+_Use the version appropriate to your website’s top-level domain (TLD)._ If your project uses a .mil top-level domain, use the .mil banner text.
+Show the banner on every page. Use the banner at the top of every page of a site. It can be confusing or misleading if it appears on some pages and not others.
+
+_Avoid distraction._ The banner should appear on every page of your site. Choose background colors that fit with your site theme, and avoid color combinations that draw excessive attention to the banner.
+
+_Keep the text up to date._ Use the most current version of the banner.
+
+### Accessibility guidance
+
+The component provides default labels for English and Spanish when `lang="en"` or `lang="es"` is passed to the component. If no `lang` attribute is passed, the English label will be used.
+
+If the default labels are not appropriate, you can pass a custom label to the component, which will be used instead and rendered as an `aria-label` attribute inside the banner.
+
+For example, if you were providing a French version of the banner, you should also add a label in French to distinguish the banner header from the main header.
+
+```html
+<usa-banner label="Un site Web officiel du gouvernement américain">
+  <!-- rest of the banner markup -->
+</usa-banner>
+```
+
+Some `.gov` websites don’t represent the federal level of the U.S. government. These sites should adapt the An official website of the United States government and Official websites use `.gov` sections to use more accurate language specific to the site.
+
+Some `.mil` websites don’t belong to an official U.S. Department of War organization. These sites should adapt the Official websites use `.mil` section to use more technically accurate language: “A .mil website operates under the approval of the U.S. Department of War.”
+
+The banner should directly follow the `skipnav` component.
+
+<SiteNote>
+  <strong>Note:</strong> As this is the first Web Component shipping in USWDS,
+  we are still working on the best way to document its usage. We want to hear
+  from users about challenges with adding this component to your projects.
+  Please let us know what works, what doesn’t, and what additional documentation
+  might be helpful in this [discussion
+  thread](https://github.com/uswds/uswds/discussions/6477).
+</SiteNote>

package/src/components/usa-banner/index.ts

@@ -0,0 +1,290 @@
+import { LitElement, html, css, unsafeCSS } from "lit";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { classMap } from "lit/directives/class-map.js";
+
+import colorTokens from "@ogds/tokens/styles/css/colors.css";
+import spacingTokens from "@ogds/tokens/styles/css/spacing.css";
+import breakpointTokens from "@ogds/tokens/styles/css/breakpoints.css";
+import styles from "./usa-banner.css";
+
+import usFlagSmall from "@uswds/uswds/img/us_flag_small.png";
+import iconDotGov from "@uswds/uswds/img/icon-dot-gov.svg";
+import iconHttps from "@uswds/uswds/img/icon-https.svg";
+import iconClose from "../../shared/icons/close.svg";
+import iconExpandMore from "../../shared/icons/expand_more.svg";
+import iconExpandLess from "../../shared/icons/expand_less.svg";
+import { defineCustomElement } from "../../utils";
+
+interface UsaBannerTranslations {
+  banner: {
+    label: string;
+    text: string;
+    action: string;
+  };
+  domain: {
+    heading: string;
+    text1: string;
+    text2: string;
+  };
+  https: {
+    heading1: string;
+    heading2: string;
+    text1: string;
+    text2: string;
+    text3: string;
+  };
+}
+
+type SupportedLanguage = "en" | "es";
+
+const USA_BANNER_TRANSLATIONS: Record<
+  SupportedLanguage,
+  UsaBannerTranslations
+> = {
+  en: {
+    banner: {
+      label: "Official website of the United States government",
+      text: "An official website of the United States government",
+      action: "Here’s how you know",
+    },
+    domain: {
+      heading: "Official websites use",
+      text1: "A",
+      text2:
+        "website belongs to an official government organization in the United States.",
+    },
+    https: {
+      heading1: "Secure",
+      heading2: "websites use HTTPS",
+      text1: "A <strong>lock</strong>",
+      text2:
+        "or <strong>https://</strong> means you’ve safely connected to the",
+      text3:
+        "website. Share sensitive information only on official, secure websites.",
+    },
+  },
+  es: {
+    banner: {
+      label: "Un sitio oficial del Gobierno de Estados Unidos",
+      text: "Un sitio oficial del Gobierno de Estados Unidos",
+      action: "Así es como usted puede verificarlo",
+    },
+    domain: {
+      heading: "Los sitios web oficiales usan",
+      text1: "Un sitio web",
+      text2:
+        "pertenece a una organización oficial del Gobierno de Estados Unidos.",
+    },
+    https: {
+      heading1: "Los sitios web seguros",
+      heading2: "usan HTTPS",
+      text1: "Un <strong>candado</strong>",
+      text2:
+        "o <strong>https://</strong> significa que usted se conectó de forma segura a un sitio web",
+      text3:
+        "Comparta información sensible sólo en sitios web oficiales y seguros.",
+    },
+  },
+};
+
+/**
+ * @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 --ogds-banner-background-color - Sets banner background color.
+ * @cssprop --ogds-banner-button-close-background-color - Sets the background color for the close control on smaller viewports.
+ * @cssprop --ogds-banner-focus-outline-color - Sets banner focus outline color.
+ * @cssprop --ogds-banner-font-family - Sets banner font family.
+ * @cssprop --ogds-banner-icon-gov-color - Sets the color for the official government domain icon in the expanded state of the banner.
+ * @cssprop --ogds-banner-icon-https-color - Sets the color for the https icon in the expanded state of the banner.
+ * @cssprop --ogds-banner-link-color - Sets the default link color.
+ * @cssprop --ogds-banner-link-hover-color - Sets the default link color.
+ * @cssprop --ogds-banner-text-color - Sets the default text 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.
+ *
+ * @element usa-banner
+ */
+export class UsaBanner extends LitElement {
+  static properties = {
+    flagSrc: { type: String },
+    lang: { type: String, reflect: true },
+    isOpen: { state: true },
+    label: { type: String },
+    tld: { type: String, reflect: true },
+  };
+
+  // Property declarations
+  flagSrc!: string;
+  lang!: "en" | "es";
+  isOpen!: boolean;
+  label!: string;
+  tld!: "gov" | "mil";
+
+  toggle() {
+    this.isOpen = !this.isOpen;
+    const contentElement = this.shadowRoot?.querySelector(".content");
+    if (contentElement) {
+      contentElement.toggleAttribute("hidden");
+    }
+  }
+
+  constructor() {
+    super();
+    this.flagSrc = usFlagSmall;
+    this.lang = "en";
+    this.isOpen = false;
+    this.tld = "gov";
+  }
+
+  // Get English or Spanish strings. Default to English if an unknown `lang` is passed.
+  // Ex: <usa-banner lang="zy"></usa-banner>
+  protected get _bannerText() {
+    return USA_BANNER_TRANSLATIONS[this.lang] || USA_BANNER_TRANSLATIONS["en"];
+  }
+
+  // Get the action text and use for both mobile & desktop buttons.
+  protected get _actionText() {
+    const bannerActionText = this.querySelector('[slot="banner-action"]');
+
+    return bannerActionText?.textContent;
+  }
+
+  domainTemplate(tld: string) {
+    const { domain } = this._bannerText;
+
+    return html`
+      <div class="icon-gov">
+        <p>
+          <strong>
+            <slot name="domain-heading"> ${domain.heading} .${tld} </slot>
+          </strong>
+          <br />
+          <slot name="domain-text">
+            ${domain.text1} <strong>.${tld}</strong> ${domain.text2}
+          </slot>
+        </p>
+      </div>
+    `;
+  }
+
+  lockIcon() {
+    return html`
+      <span
+        class="icon-lock"
+        role="img"
+        aria-label="Locked padlock icon"
+      ></span>
+    `;
+  }
+
+  httpsTemplate(tld: string) {
+    const { https } = this._bannerText;
+
+    return html`
+      <div class="icon-https">
+        <p>
+          <strong>
+            <slot name="https-heading">
+              ${https.heading1} .${tld} ${https.heading2}
+            </slot> </strong
+          ><br />
+          <slot name="https-text">
+            ${unsafeHTML(https.text1)} (${this.lockIcon()})
+            ${unsafeHTML(https.text2)} .${tld} ${https.text3}
+          </slot>
+        </p>
+      </div>
+    `;
+  }
+
+  static styles = [
+    css`
+      :host {
+        /** Icons */
+        --ogds-icon-close: url("${unsafeCSS(iconClose)}");
+        --ogds-icon-expand-less: url("${unsafeCSS(iconExpandLess)}");
+        --ogds-icon-expand-more: url("${unsafeCSS(iconExpandMore)}");
+        --ogds-icon-gov: url("${unsafeCSS(iconDotGov)}");
+        --ogds-icon-https: url("${unsafeCSS(iconHttps)}");
+      }
+    `,
+    breakpointTokens,
+    colorTokens,
+    spacingTokens,
+    styles,
+  ];
+
+  render() {
+    const classes = { ["expanded"]: this.isOpen };
+    // ? Is there a better way to fallback to a default value is passed value doesn't match?
+    // Example: User passes `tld="zzz"` --> uses "gov" domain instead of `zzz`.
+    const tld = this.tld === "mil" ? "mil" : "gov";
+    const { banner } = this._bannerText;
+
+    return html`
+      <section aria-label=${this.label || banner.label}>
+        <div class="usa-accordion">
+          <header class="${classMap(classes)}">
+            <div class="inner">
+              <div class="grid-col-auto">
+                <img
+                  aria-hidden="true"
+                  class="header-flag"
+                  src=${this.flagSrc}
+                  alt=""
+                />
+              </div>
+              <div
+                class="grid-col-fill tablet:grid-col-auto"
+                aria-hidden="true"
+              >
+                <p class="header-text">
+                  <slot name="banner-text">${banner.text}</slot>
+                </p>
+                <!-- 
+                  Since the header-action text below is underlined, the slot and p 
+                  need to be on the same line to avoid one extra space of underline 
+                  before the expand icon.
+                -->
+                <!-- prettier-ignore -->
+                <p class="header-action"><slot name="banner-action">${banner.action}</slot></p>
+              </div>
+              <button
+                type="button"
+                class="usa-accordion__button"
+                aria-expanded="${this.isOpen}"
+                aria-controls="gov-banner-default"
+                @click="${this.toggle}"
+              >
+                <span class="button-text">
+                  ${this._actionText || banner.action}
+                </span>
+              </button>
+            </div>
+          </header>
+          <div class="content usa-accordion__content" hidden>
+            <div class="grid-row grid-gap-lg">
+              <div class="guidance tablet:grid-col-6">
+                ${this.domainTemplate(tld)}
+              </div>
+              <div class="guidance tablet:grid-col-6">
+                ${this.httpsTemplate(tld)}
+              </div>
+            </div>
+          </div>
+        </div>
+      </section>
+    `;
+  }
+}
+
+defineCustomElement("usa-banner", UsaBanner);