@ogds/elements 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/components/ogds-alert/ogds-alert.stories.ts

@@ -0,0 +1,75 @@
+import "./index.ts";
+import { html, nothing } from "lit";
+
+const meta = {
+  title: "Components/Alert",
+  component: "ogds-alert",
+  tags: ["experimental"],
+  render: ({
+    heading,
+    type,
+    body,
+    noIcon,
+  }: {
+    heading: string;
+    type: string;
+    body: string;
+    noIcon: boolean;
+  }) => {
+    return html`
+      <ogds-alert type="${type}" ?no-icon="${noIcon}">
+        ${heading ? html`<h3 slot="heading">${heading}</h3>` : nothing}
+        <p slot="body" .innerHTML=${body}></p>
+      </ogds-alert>
+    `;
+  },
+};
+
+export default meta;
+
+export const InformationalAlert = {
+  args: {
+    heading: "Informational Alert",
+    type: "info",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+  },
+};
+
+export const WarningAlert = {
+  args: {
+    heading: "Warning Alert",
+    type: "warning",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+  },
+};
+
+export const SuccessAlert = {
+  args: {
+    heading: "Success Alert",
+    type: "success",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+  },
+};
+
+export const ErrorAlert = {
+  args: {
+    heading: "Error Alert",
+    type: "error",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+  },
+};
+
+export const SlimAlert = {
+  args: {
+    type: "info",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+  },
+};
+
+export const AlertWithNoIcon = {
+  args: {
+    type: "info",
+    body: `Lorem ipsum dolor sit amet, <a href="#">consectetur adipiscing elit</a>, sed do eiusmod.`,
+    noIcon: "true",
+  },
+};

package/src/components/{usa-banner → ogds-banner}/docs.mdx

@@ -55,7 +55,7 @@ Listed below are additional variations of the component.
 
 ### 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
+This version of `ogds-banner` (i.e. using web components) first became available as `usa-banner` in [USWDS v3.13.0](https://github.com/uswds/uswds/releases/tag/v3.13.0) and is part of the `@uswds/uswds-elements` package. This is a direct port/fork of that component.
 
 ### When to use the default banner
 
@@ -97,12 +97,3 @@ Some `.gov` websites don’t represent the federal level of the U.S. government.
 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 → ogds-banner}/index.ts

@@ -5,7 +5,7 @@ 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 styles from "./ogds-banner.css";
 
 import usFlagSmall from "@uswds/uswds/img/us_flag_small.png";
 import iconDotGov from "@uswds/uswds/img/icon-dot-gov.svg";
@@ -15,7 +15,7 @@ import iconExpandMore from "../../shared/icons/expand_more.svg";
 import iconExpandLess from "../../shared/icons/expand_less.svg";
 import { defineCustomElement } from "../../utils";
 
-interface UsaBannerTranslations {
+interface OgdsBannerTranslations {
   banner: {
     label: string;
     text: string;
@@ -37,9 +37,9 @@ interface UsaBannerTranslations {
 
 type SupportedLanguage = "en" | "es";
 
-const USA_BANNER_TRANSLATIONS: Record<
+const OGDS_BANNER_TRANSLATIONS: Record<
   SupportedLanguage,
-  UsaBannerTranslations
+  OgdsBannerTranslations
 > = {
   en: {
     banner: {
@@ -60,20 +60,20 @@ const USA_BANNER_TRANSLATIONS: Record<
       text2:
         "or <strong>https://</strong> means you’ve safely connected to the",
       text3:
-        "website. Share sensitive information only on official, secure websites.",
+        " 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",
+      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.",
+        "pertenece a una organización oficial del gobierno de Estados Unidos.",
     },
     https: {
       heading1: "Los sitios web seguros",
@@ -82,13 +82,13 @@ const USA_BANNER_TRANSLATIONS: Record<
       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.",
+        ". Comparta información sensible solo en sitios web oficiales y seguros.",
     },
   },
 };
 
 /**
- * @summary The usa-banner component.
+ * @summary The ogds-banner component.
  *
  * @attribute {string} lang - The element's language.
  * @attribute {string} label - The custom aria label users can override.
@@ -111,9 +111,9 @@ const USA_BANNER_TRANSLATIONS: Record<
  * @slot https-heading - Heading for HTTPs section.
  * @slot https-text - Body text for HTTPs section.
  *
- * @element usa-banner
+ * @element ogds-banner
  */
-export class UsaBanner extends LitElement {
+export class OgdsBanner extends LitElement {
   static properties = {
     flagSrc: { type: String },
     lang: { type: String, reflect: true },
@@ -148,7 +148,9 @@ export class UsaBanner extends LitElement {
   // 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"];
+    return (
+      OGDS_BANNER_TRANSLATIONS[this.lang] || OGDS_BANNER_TRANSLATIONS["en"]
+    );
   }
 
   // Get the action text and use for both mobile & desktop buttons.
@@ -199,7 +201,7 @@ export class UsaBanner extends LitElement {
           ><br />
           <slot name="https-text">
             ${unsafeHTML(https.text1)} (${this.lockIcon()})
-            ${unsafeHTML(https.text2)} .${tld} ${https.text3}
+            ${unsafeHTML(https.text2)} .${tld}${https.text3}
           </slot>
         </p>
       </div>
@@ -287,4 +289,4 @@ export class UsaBanner extends LitElement {
   }
 }
 
-defineCustomElement("usa-banner", UsaBanner);
+defineCustomElement("ogds-banner", OgdsBanner);

package/src/components/{usa-banner/usa-banner.spec.ts → ogds-banner/ogds-banner.spec.ts}

@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, it } from "vitest";
 import "./index.js";
 
 function getInsideBanner(): ShadowRoot {
-  const banner = document.body.querySelector("usa-banner");
+  const banner = document.body.querySelector("ogds-banner");
   if (!banner) {
     throw new Error("USA Banner element not found");
   }
@@ -23,7 +23,7 @@ function getBannerButton(): HTMLButtonElement {
 
 describe("USA Banner component", async () => {
   beforeEach(async () => {
-    document.body.innerHTML = "<usa-banner></usa-banner>";
+    document.body.innerHTML = "<ogds-banner></ogds-banner>";
   });
 
   it("renders correctly", () => {
@@ -53,19 +53,19 @@ describe("USA Banner component", async () => {
 
 describe("Spanish variant", async () => {
   beforeEach(async () => {
-    document.body.innerHTML = `<usa-banner lang="es"></usa-banner>`;
+    document.body.innerHTML = `<ogds-banner lang="es"></ogds-banner>`;
   });
 
   it("renders correctly", () => {
     expect(getInsideBanner().textContent).toContain(
-      "Un sitio oficial del Gobierno de Estados Unidos",
+      "Un sitio oficial del gobierno de Estados Unidos",
     );
   });
 });
 
 describe("MIL variant", async () => {
   beforeEach(async () => {
-    document.body.innerHTML = `<usa-banner tld="mil"></usa-banner>`;
+    document.body.innerHTML = `<ogds-banner tld="mil"></ogds-banner>`;
   });
 
   it("renders correctly", () => {

package/src/components/{usa-banner/usa-banner.stories.ts → ogds-banner/ogds-banner.stories.ts}

@@ -5,7 +5,7 @@ import { within } from "shadow-dom-testing-library";
 import { getStorybookHelpers } from "@wc-toolkit/storybook-helpers";
 import type { Args, ArgTypes } from "storybook/internal/csf";
 
-const { argTypes, args, template } = getStorybookHelpers("usa-banner");
+const { argTypes, args, template } = getStorybookHelpers("ogds-banner");
 
 const filteredArgTypes = (argTypes: ArgTypes) => {
   const filtered: ArgTypes = {};
@@ -30,7 +30,7 @@ const filteredArgTypes = (argTypes: ArgTypes) => {
 
 export default {
   title: "Components/Banner",
-  component: "usa-banner",
+  component: "ogds-banner",
   tags: ["beta"],
   args: {
     ...args,

package/src/components/task-list/docs.mdx

@@ -0,0 +1,23 @@
+import { Meta, Title, Primary, Stories } from "@storybook/addon-docs/blocks";
+
+<Meta isTemplate />
+
+<Title />
+
+A Task List displays user tasks, their status (e.g. "not started", "completed", "in progress"), and an actionable link for each task.
+
+---
+
+## Default
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+## Guidance
+
+The Task List is used primarily for lengthy or complex workflows (non-sequential), e.g. registration, rather than simple, short steps.

package/src/components/task-list/index.ts

@@ -0,0 +1,65 @@
+import { LitElement, html, unsafeCSS } from "lit";
+
+import styles from "./ogds-task-list.css";
+import { adoptTokenStyles } from "../../core/token-styles";
+
+import { property } from "lit/decorators.js";
+
+/**
+ * @summary The ogds-task-list component. For now, this is intended for non-sequential task lists (order doesn't matter).
+ * @element ogds-task-list
+ */
+
+interface TaskStep {
+  title: string;
+  description: string;
+  status: StepStatus;
+  url?: string;
+}
+
+type StepStatus = "not-started" | "in-progress" | "completed";
+
+export class OgdsTaskList extends LitElement {
+  /** @ignore */
+
+  @property({ type: Array })
+  steps: TaskStep[] = [];
+
+  static styles = unsafeCSS(styles);
+
+  override connectedCallback() {
+    super.connectedCallback();
+    adoptTokenStyles();
+  }
+
+  renderAction(step: TaskStep) {
+    switch (step.status) {
+      case "in-progress":
+        return html`<a href=${step.url}>Continue</a>`;
+      case "completed":
+        return html`
+          <span class="completed">Completed</span><a href=${step.url}>Edit</a>
+        `;
+      default:
+        return html`<a href=${step.url}>Start </a>`;
+    }
+  }
+
+  render() {
+    return html`
+      <ul>
+        ${this.steps.map(
+          (step) => html`
+            <li class="step" data-status=${step.status}>
+              <h2 class="heading">${step.title}</h2>
+              <div class="description">${step.description}</div>
+              <div class="action">${this.renderAction(step)}</div>
+            </li>
+          `,
+        )}
+      </ul>
+    `;
+  }
+}
+
+customElements.define("ogds-task-list", OgdsTaskList);

package/src/components/task-list/ogds-task-list.css

@@ -0,0 +1,34 @@
+:host {
+  display: block;
+}
+
+ul {
+  list-style: none;
+  padding-left: 1.5rem;
+}
+
+li {
+  border-block-end: 2px solid var(--ogds-theme-color-base-lightest);
+  margin-block-end: 2rem;
+  padding-block-end: 1.25rem;
+}
+
+.heading {
+  margin-block-end: 0.25rem;
+}
+
+.description {
+  color: var(--ogds-theme-color-base);
+  margin-block-end: 0.5rem;
+}
+
+.action {
+  display: flex;
+  flex-direction: column;
+}
+
+.completed {
+  align-items: center;
+  display: inline-flex;
+  gap: 0.4rem;
+}

package/src/components/task-list/ogds-task-list.stories.ts

@@ -0,0 +1,46 @@
+import { html } from "lit";
+import "./index";
+import ComponentDocs from "./docs.mdx";
+
+export default {
+  title: "Components/TaskList",
+  component: "ogds-task-list",
+  tags: ["experimental"],
+  parameters: {
+    docs: {
+      page: ComponentDocs,
+    },
+  },
+};
+
+const exampleSteps = [
+  {
+    title: "Tell us about you",
+    description:
+      " Confirm the legal entity structure, your employer details, and your EIN. ",
+    status: "in-progress",
+    url: "",
+  },
+  {
+    title: "Set up your employer profile",
+    description: "Click the link we sent to your inbox.",
+    status: "completed",
+    url: "",
+  },
+  {
+    title: "Enter the employer’s address",
+    description: "Tell us more about yourself.",
+    status: "completed",
+    url: "",
+  },
+  {
+    title: "Submit your Maryland Resident Agent details",
+    description: "Review and submit profile details.",
+    status: "not-started",
+    url: "",
+  },
+];
+
+export const Default = {
+  render: () => html`<ogds-task-list .steps=${exampleSteps}></ogds-task-list>`,
+};

package/src/core/token-styles.ts

@@ -2,6 +2,7 @@ import colorTokens from "@ogds/tokens/styles/css/colors.css";
 import spacingTokens from "@ogds/tokens/styles/css/spacing.css";
 import typographyTokens from "@ogds/tokens/styles/css/typography.css";
 import themeColorTokens from "@ogds/tokens/styles/css/theme-color.css";
+import themeComponentTokens from "@ogds/tokens/styles/css/theme-components.css";
 import themeSpacingTokens from "@ogds/tokens/styles/css/theme-spacing.css";
 import themeTypographyTokens from "@ogds/tokens/styles/css/theme-typography.css";
 
@@ -12,6 +13,7 @@ sheet.replaceSync(
     spacingTokens,
     typographyTokens,
     themeColorTokens,
+    themeComponentTokens,
     themeSpacingTokens,
     themeTypographyTokens,
   ]

package/src/declaration.d.ts

@@ -1,5 +1,10 @@
 /// <reference types="vite/client" />
 
+declare module "*.mdx" {
+  const content: unknown;
+  export default content;
+}
+
 import type { CSSResultGroup } from "lit";
 
 // Asset imports

package/storybook/contributing.mdx

@@ -1,115 +1,6 @@
 import { Meta, Markdown } from "@storybook/addon-docs/blocks";
 import Contributing from "../CONTRIBUTING.md?raw";
 
-<Meta title="Documentation/Contributing" />
+<Meta title="Documentation/Contributing Code" />
 
 <Markdown>{Contributing}</Markdown>
-
-## Overview
-
-This information is for USWDS Core team members contribute to the USWDS Elements project.
-
-## Project setup
-
-It is helpful to have [nvm installed](https://github.com/nvm-sh/nvm) and use the correct version of Node.js. From the project root, run the following command:
-
-```bash
-npm install
-```
-
-### Installing Playwright (for E2E testing)
-
-If you plan to run or write end-to-end tests, please see the [Playwright documentation](https://playwright.dev/docs/intro) for installation instructions and the [README.md file in the `e2e` directory](https://github.com/uswds/uswds-elements/tree/develop/e2e).
-
-## Development Workflow
-
-The development workflow uses [Storybook](https://storybook.js.org/) and [custom elements manifest](https://github.com/webcomponents/custom-elements-manifest) to generate a custom elements manifest and watch for changes to the custom elements manifest. Storybook handles documentation of component usage, styling, and properties.
-
-### Running StorybookJS
-
-Start the development server with Storybook and custom elements manifest watch process:
-
-```bash
-npm run start
-```
-
-This runs Storybook on port 8008 at `http://localhost:8008`.
-
----
-
-### Creating stories
-
-Stories should document the following component features:
-
-- Variants (e.g. default, primary, secondary, etc.)
-- Properties
-- CSS Custom Properties
-
-### Story File Structure
-
-Stories and functional tests should be created alongside components:
-
-```
-src/components/usa-example/
-  ├── docs.mdx
-  ├── index.ts
-  ├── usa-example.css
-  ├── usa-example.spec.ts
-  └── usa-example.stories.ts
-```
-
-## Project Structure
-
-- **`src/components/`** - Web Component implementations
-- **`src/core/`** - Core utilities and base classes
-- **`src/shared/`** - Static asset files like fonts and icons
-- **`e2e/`** - Playwright end-to-end tests
-- **`storybook/`** - Storybook documentation files
-- **`.storybook/`** - Storybook configuration
-- **`tokens/`** - Design token definitions (Style Dictionary)
-- **`internals/`** - Internal build scripts and utilities
-- **`config/`** - Config files for project tooling and testing
-
-## Component Development Checklist
-
-When creating a new component:
-
-- Create component files in `src/components/[component-name]/`
-- Add JSDoc comments to component files documenting the component's API
-- Write component implementation (TypeScript + Lit)
-- Create component styles in an external CSS file and import it into the component
-- Export component from `index.ts`
-- Add component to for package exports `src/components/index.js`
-- Create Storybook stories documenting all variants and props
-- Write unit tests with Vitest
-- Write E2E tests with Playwright (including visual regression tests)
-- Build the custom elements manifest to keep it synced with JSDoc comments
-- Test accessibility with Storybook's a11y addon
-
----
-
-## Pre-commit Hooks
-
-This project uses [Husky](https://typicode.github.io/husky/) for Git hooks. Hooks are automatically set up when you run `npm install` via the `prepare` script.
-
-## Publishing and Releases
-
-The package is published as `@uswds/elements` on npm. The current version can be found in `package.json`
-
-Component maturity levels:
-
-- **Pre-alpha**: Experimental, API may change significantly
-- **Alpha**: Core functionality stable, refinements expected
-- **Beta**: Feature complete, undergoing final testing
-- **Stable**: Production ready
-
-Check the README for current component status.
-
-## Additional Resources
-
-- [USWDS Design System](https://designsystem.digital.gov)
-- [Web Components MDN Guide](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-- [Lit Documentation](https://lit.dev)
-- [Storybook Documentation](https://storybook.js.org)
-- [Playwright Documentation](https://playwright.dev)
-- [E2E Testing Guide](https://github.com/uswds/uswds-elements/tree/develop/e2e) (detailed testing documentation)

package/storybook/framework-guidance.mdx

@@ -11,24 +11,24 @@ import VueExample from "../examples/with-vue/src/App.vue?raw";
 
 # Framework-specific Guidance
 
-We've made every effort to make using USWDS Elements in your project as easy as possible. Since many projects use modern front-end libraries and frameworks, we've included an [examples directory](https://github.com/uswds/uswds-elements/tree/develop/examples) in this repository that shows how to import and use USWDS Elements with a variety of popular front-end technologies. The goal is to provide an experience that involves minimal configuration to get up and running with your framework or library of choice.
+We've made every effort to make using OGDS Elements in your project as easy as possible. Since many projects use modern front-end libraries and frameworks, we've included an [examples directory](https://github.com/open-government-design-system/ogds-elements/tree/develop/examples) in this repository that shows how to import and use OGDS Elements with a variety of popular front-end technologies. The goal is to provide an experience that involves minimal configuration to get up and running with your framework or library of choice.
 
 In all cases, install the project from the npm package registry.
 
 ```bash
-$ npm install @uswds/elements
+$ npm install @ogds/elements
 ```
 
 ## Examples
 
 ### HTML
 
-To use a specific element directly in an HTML page, use the code snippet below. This example also applies if you're using USWDS Elements in a CMS that has its own templating engine (e.g. Drupal, WordPress, etc.).
+To use a specific element directly in an HTML page, use the code snippet below. This example also applies if you're using OGDS Elements in a CMS that has its own templating engine (e.g. Drupal, WordPress, etc.).
 
 ```html
 <!-- importing directly into an HTML page -->
 <script type="module">
-  import { UsaBanner } from "@uswds/elements";
+  import { OgdsBanner } from "@ogds/elements";
 </script>
 <usa-banner></usa-banner>
 ```
@@ -41,7 +41,7 @@ This is a minimal example of implementation in [Astro](https://astro.build/). Th
 
 ### React
 
-This is a minimal example of implementation in [React](https://react.dev/). Do note that USWDS Elements includes a wrapper for React components, and the `import` path is different from the other frameworks in this document.
+This is a minimal example of implementation in [React](https://react.dev/). Do note that OGDS Elements includes a wrapper for React components, and the `import` path is different from the other frameworks in this document.
 
 <Source code={ReactExample} language="jsx" />
 

package/storybook/readme.mdx

@@ -1,6 +1,6 @@
 import { Meta, Markdown } from "@storybook/addon-docs/blocks";
 import Readme from "../README.md?raw";
 
-<Meta title="README" />
+<Meta title="OGDS Elements (README)" />
 
 <Markdown>{Readme}</Markdown>