@ogds/elements 1.0.0-alpha.6

package/src/components/ogds-accordion/docs.mdx

@@ -0,0 +1,90 @@
+import { Meta, Title, Primary, Stories } from "@storybook/addon-docs/blocks";
+
+<Meta isTemplate />
+
+<Title />
+
+Accordions show and hide sections of related content on a page.
+
+---
+
+## Default
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+## Guidance
+
+### When to use the accordion component
+
+_To organize related content._ Accordions can help reduce page length when there are multiple sections of content that users may not need to read in full.
+
+_To let users get to relevant content faster._ Accordions keep a page focused by allowing users to choose what they read rather than having to scroll past large amounts of content.
+
+### When to consider something else
+
+_If users need most or all of the content._ If users are likely to need most of the content on a page, showing it all at once may be more helpful than hiding it behind an accordion.
+
+_For critical information._ Avoid using accordions to hide important content that all users should see, as users may miss it.
+
+### Usability guidance
+
+_Use clear, descriptive labels._ The summary text should clearly describe the content within. Users should be able to decide whether to expand a section based on the label alone.
+
+_Use icons to reinforce state._ Add the `with-icon` class to provide a visual indicator of open and closed state. Use `with-icon right` to align the icon to the trailing edge of the summary, or `with-icon plus` to use plus/minus icons instead of chevrons.
+
+_Use `bordered` for visual separation._ Add the `bordered` class when the accordion needs stronger visual separation from surrounding content.
+
+#### Built-in `<details>` element functionality
+
+Because the component uses `<details>` elements, you can use all of the built-in functionality that element supports, including:
+
+1. **Exclusive accordion behavior with the `name` attribute.** By default, a user can open multiple accordion panels at once. In some use cases, only allowing one panel to be open at one time may be a better experience. To acheive this behavior, just add a `name="myAccordion"` ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details#name)) to each `<details>` that needs to be exclusive (the value of the attribute does not matter as long as it is shared across each of the details elements):
+
+```html
+<ogds-accordion>
+  <details name="anExclusiveAccordion">
+    <summary>Foo</summary>
+  </details>
+  <details name="anExclusiveAccordion">
+    <summary>Bar</summary>
+  </details>
+  <!-- and so on...  -->
+</ogds-accordion>
+```
+
+2. **Make panel `open` by default.** Any `<details>` with an `open` attribute ([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details#open)) on it will be open when the page loads (be careful when using this with the `name` attribute described above).
+
+### Accessibility guidance
+
+The accordion uses the native `<details>` and `<summary>` HTML elements, which provide built-in keyboard interaction and screen reader support without requiring additional JavaScript.
+
+#### ARIA Support
+
+Depending on the kind of content in the accordion, you may want to add some ARIA to provide a better experience for assistive technology users. Headings and lists in particular, can be important landmarks for screen readers. The `<ogds-accordion>` component provides an easy way to add ARIA that may be helpful depending on your content:
+
+1. **Heading semantics.** The USWDS accordion uses heading elements inside the buttons that toggle the sections. If you want to follow this pattern, you can add a `heading-level=<Number>` attribute to the opening `<ogds-accordion>` tag, and it will automatically set the correct ARIA attributes on each of the child `<summary>` tags to set the heading at the level you tell it. As always, it is important to use the right heading level to preserve the document outline. Even if you are not using the web component version of the component, you can achieve this same effect by including a heading element inside the summary tag, though this may require a little extra CSS to keep the visual appearance consistent.
+2. **List semantics.** If the content in the accordion makes more sense as a list, adding a `use-list-semantics` attribute to the `<ogds-accordion>` tag will add the correct ARIA.
+
+### Web component usage
+
+The stories above show how to use the accordion web component. This component uses all light DOM (no shadow DOM). That means that it's up to you to add the required markup inside the `<ogds-accordion>` tag. As shown, it only needs at least one `details` element.
+
+### CSS-only usage
+
+The accordion component can be used without JavaScript by applying the styles in `ogds-accordion.css` directly to your page. If using the icon variants, you must set the following custom properties to point to your own icon assets:
+
+```css
+ogds-accordion,
+.ogds-accordion {
+  --ogds-accordion-icon-closed: url("/path/to/your/icon-closed.svg");
+  --ogds-accordion-icon-open: url("/path/to/your/icon-open.svg");
+}
+```
+
+Even if you are not using the web component JavaScript, the CSS will work on a `<ogds-accordion>` tag. However, if you'd prefer to stick with built-in elements, all of the above will also work on a `<div class="ogds-accordion">`.

package/src/components/ogds-accordion/index.ts

@@ -0,0 +1,132 @@
+import { LitElement, nothing } from "lit";
+
+import styles from "./ogds-accordion.css";
+import iconChevronDown from "../../shared/icons/expand_more.svg";
+import iconChevronUp from "../../shared/icons/expand_less.svg";
+import iconPlus from "../../shared/icons/add.svg";
+import iconMinus from "../../shared/icons/remove.svg";
+
+import { adoptTokenStyles } from "../../core/token-styles";
+import { defineCustomElement } from "../../utils";
+import { property } from "lit/decorators.js";
+
+/**
+ * @summary The ogds-accordion component.
+ *
+ * Apply these classes to `<ogds-accordion>` to enable variants:
+ * - `bordered` — adds a border to expanded content
+ * - `with-icon` — shows a chevron icon on each summary
+ * - `with-icon plus` — uses plus/minus icons instead of chevrons
+ * - `with-icon right` — aligns the icon to the right
+ *
+ * @cssprop --ogds-accordion-border - Border used in the bordered variant.
+ * @cssprop --ogds-accordion-content-padding - Padding for the expanded content area.
+ * @cssprop --ogds-accordion-icon-closed - Icon shown when a panel is closed. Defaults to a chevron pointing down. CSS-only users must set this to a url() value pointing to their own icon asset.
+ * @cssprop --ogds-accordion-icon-open - Icon shown when a panel is open. Defaults to a chevron pointing up. CSS-only users must set this to a url() value pointing to their own icon asset.
+ * @attribute {boolean} use-list-semantics - Adds `role="list"` to the component and `role="listitem"` to each `<details>` child, conveying the accordion as a list to assistive technologies. Mutually exclusive with `heading-level`.
+ * @attribute {number} heading-level - Sets a heading level for each accordion panel by adding `role="heading"` and the corresponding `aria-level` to each `<summary>` element. Has no effect when set to `0` (the default). Mutually exclusive with `use-list-semantics`.
+ *
+ * @slot - The default (only) slot for the <ogds-accordion> expects one or more plain HTML <details> elements.
+ * @element ogds-accordion
+ */
+export class OgdsAccordion extends LitElement {
+  /** @ignore */
+  private static _sheet: CSSStyleSheet | null = null;
+
+  @property({ type: Boolean, attribute: "use-list-semantics" })
+  useListSemantics = false;
+
+  @property({ type: Number, attribute: "heading-level" })
+  headingLevel = 0;
+
+  declare detailsChildren: HTMLCollectionOf<HTMLDetailsElement> | undefined;
+  declare childRoles: Map<HTMLDetailsElement, Set<string>>;
+
+  override createRenderRoot() {
+    return this;
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    adoptTokenStyles();
+    if (!OgdsAccordion._sheet) {
+      OgdsAccordion._sheet = new CSSStyleSheet();
+      OgdsAccordion._sheet.replaceSync(
+        `ogds-accordion, .ogds-accordion {
+          --icon-chevron-pointing-down: url("${iconChevronDown}");
+          --icon-chevron-pointing-up: url("${iconChevronUp}");
+          --icon-plus: url("${iconPlus}");
+          --icon-minus: url("${iconMinus}");
+        }\n` + styles.cssText,
+      );
+      document.adoptedStyleSheets = [
+        ...document.adoptedStyleSheets,
+        OgdsAccordion._sheet,
+      ];
+    }
+    this.detailsChildren = this.getDetailsChildren();
+    this.childRoles = new Map(
+      Array.from(this.detailsChildren ?? []).map((el) => [el, new Set()]),
+    );
+  }
+
+  override firstUpdated() {
+    if (this.useListSemantics && this.headingLevel !== 0) {
+      console.warn(
+        "<ogds-accordion>: use-list-semantics and heading-level are mutually exclusive. " +
+          "Screen readers cannot reliably announce both list position and heading level " +
+          "on the same element. Remove one attribute.",
+      );
+      return;
+    }
+    this.addListSemantics();
+    this.addHeadingSemantics();
+    this.applyChildRoles();
+  }
+
+  getDetailsChildren() {
+    const detailsEls = this.getElementsByTagName("details");
+    if (detailsEls.length > 0) {
+      return detailsEls;
+    } else {
+      console.error(
+        "<ogds-accordion>: This component expects to have at least one details element as a child",
+      );
+    }
+  }
+
+  addListSemantics() {
+    if (this.useListSemantics && this.detailsChildren) {
+      Array.from(this.detailsChildren).forEach((el) =>
+        this.childRoles.get(el)?.add("listitem"),
+      );
+      this.setAttribute("role", "list");
+    }
+  }
+
+  addHeadingSemantics() {
+    const headingLevel = this.headingLevel;
+
+    if (headingLevel !== 0 && this.detailsChildren) {
+      Array.from(this.detailsChildren).forEach((el) => {
+        const summary = el.querySelector("summary");
+        if (summary) {
+          summary.setAttribute("role", "heading");
+          summary.setAttribute("aria-level", String(headingLevel));
+        }
+      });
+    }
+  }
+
+  applyChildRoles() {
+    this.childRoles.forEach((roles, el) => {
+      if (roles.size > 0) el.setAttribute("role", Array.from(roles).join(" "));
+    });
+  }
+
+  render() {
+    return nothing;
+  }
+}
+
+defineCustomElement("ogds-accordion", OgdsAccordion);

package/src/components/ogds-accordion/ogds-accordion.css

@@ -0,0 +1,99 @@
+@layer ogds.components;
+
+@layer ogds.components {
+  .ogds-accordion,
+  ogds-accordion {
+    --ogds-accordion-border: 0.25rem solid var(--ogds-theme-color-base-lightest);
+    --ogds-accordion-content-padding: 1rem 1.25rem calc(1rem - 0.25rem);
+    --ogds-accordion-icon-closed: var(--icon-chevron-pointing-down);
+    --ogds-accordion-icon-open: var(--icon-chevron-pointing-up);
+
+    &.plus {
+      --ogds-accordion-icon-closed: var(--icon-plus);
+      --ogds-accordion-icon-open: var(--icon-minus);
+    }
+
+    --accordion-icon: var(--ogds-accordion-icon-closed);
+
+    details {
+      color: var(--ogds-theme-color-base-ink);
+      margin-block-end: 0.5rem;
+      margin-block-start: 0.5rem;
+
+      &[open] {
+        --accordion-icon: var(--ogds-accordion-icon-open);
+      }
+    }
+
+    summary {
+      background-color: var(--ogds-theme-color-base-lightest);
+      font-weight: 700;
+      padding: 1rem 1.25rem;
+
+      &:hover {
+        background-color: var(--ogds-color-gray-10);
+      }
+
+      /* TODO: extract this out */
+      &:focus {
+        outline: 0.25rem solid #2491ff;
+      }
+    }
+
+    &.with-icon {
+      summary {
+        align-items: center;
+        display: flex;
+
+        &::marker,
+        &::-webkit-details-marker {
+          display: none;
+        }
+
+        &::before {
+          background-color: currentColor;
+          content: "";
+          display: block;
+          flex-shrink: 0;
+          height: 1.25rem;
+          mask-image: var(--accordion-icon);
+          mask-position: center;
+          mask-repeat: no-repeat;
+          mask-size: contain;
+          width: 1.5rem;
+        }
+      }
+    }
+
+    &.with-icon.right {
+      summary::before {
+        margin-inline-start: auto;
+        order: 2;
+      }
+    }
+
+    @supports selector(::details-content) {
+      details[open]::details-content {
+        padding: var(--ogds-accordion-content-padding);
+      }
+
+      &.bordered details[open]::details-content {
+        border-block-end: var(--ogds-accordion-border);
+        border-inline-end: var(--ogds-accordion-border);
+        border-inline-start: var(--ogds-accordion-border);
+      }
+    }
+
+    @supports not selector(::details-content) {
+      .details-content {
+        padding: var(--ogds-accordion-content-padding);
+      }
+
+      &.bordered .details-content {
+        border-block-end: var(--ogds-accordion-border);
+        border-inline-end: var(--ogds-accordion-border);
+        border-inline-start: var(--ogds-accordion-border);
+      }
+    }
+  }
+}

package/src/components/ogds-accordion/ogds-accordion.spec.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("./ogds-accordion.css", () => ({ default: { cssText: "" } }));
+vi.mock("../../shared/icons/expand_more.svg", () => ({ default: "" }));
+vi.mock("../../shared/icons/expand_less.svg", () => ({ default: "" }));
+vi.mock("../../shared/icons/add.svg", () => ({ default: "" }));
+vi.mock("../../shared/icons/remove.svg", () => ({ default: "" }));
+vi.mock("../../core/token-styles", () => ({ adoptTokenStyles: vi.fn() }));
+
+import { OgdsAccordion } from "./index";
+
+function mount(html: string): OgdsAccordion {
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const el = container.firstElementChild as OgdsAccordion;
+  document.body.appendChild(el);
+  return el;
+}
+
+beforeEach(() => {
+  document.adoptedStyleSheets = [];
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("getDetailsChildren", () => {
+  it("returns the details children when present", async () => {
+    const el = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+        <details><summary>Two</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(el.detailsChildren).toBeDefined();
+    expect(el.detailsChildren?.length).toBe(2);
+  });
+
+  it("logs a console error when no details children are present", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mount(`<ogds-accordion></ogds-accordion>`);
+    await el.updateComplete;
+    expect(errorSpy).toHaveBeenCalledWith(
+      "<ogds-accordion>: This component expects to have at least one details element as a child",
+    );
+    errorSpy.mockRestore();
+  });
+});
+
+describe("addListSemantics", () => {
+  it("adds role=list to the component when use-list-semantics is set", async () => {
+    const el = mount(`
+      <ogds-accordion use-list-semantics>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(el.getAttribute("role")).toBe("list");
+  });
+
+  it("adds role=listitem to each details child when use-list-semantics is set", async () => {
+    const el = mount(`
+      <ogds-accordion use-list-semantics>
+        <details><summary>One</summary></details>
+        <details><summary>Two</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    el.querySelectorAll("details").forEach((d) => {
+      expect(d.getAttribute("role")).toContain("listitem");
+    });
+  });
+
+  it("does not add role=list when use-list-semantics is not set", async () => {
+    const el = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(el.getAttribute("role")).toBeNull();
+  });
+
+  it("does not add role=listitem to children when use-list-semantics is not set", async () => {
+    const el = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(el.querySelector("details")?.getAttribute("role")).toBeNull();
+  });
+});
+
+describe("addHeadingSemantics", () => {
+  it("adds role=heading and aria-level to each summary when heading-level is set", async () => {
+    const el = mount(`
+      <ogds-accordion heading-level="2">
+        <details><summary>One</summary></details>
+        <details><summary>Two</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    el.querySelectorAll("summary").forEach((s) => {
+      expect(s.getAttribute("role")).toBe("heading");
+      expect(s.getAttribute("aria-level")).toBe("2");
+    });
+  });
+
+  it("does not add heading role when heading-level is not set", async () => {
+    const el = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(el.querySelector("details")?.getAttribute("role")).toBeNull();
+  });
+});
+
+describe("stylesheet adoption", () => {
+  beforeEach(() => {
+    (OgdsAccordion as any)._sheet = null;
+    document.adoptedStyleSheets = [];
+  });
+
+  it("adds a stylesheet to document.adoptedStyleSheets on first mount", async () => {
+    const el = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(document.adoptedStyleSheets).toHaveLength(1);
+  });
+
+  it("does not add the stylesheet more than once when multiple accordions are mounted", async () => {
+    const el1 = mount(`
+      <ogds-accordion>
+        <details><summary>One</summary></details>
+      </ogds-accordion>
+    `);
+    const el2 = mount(`
+      <ogds-accordion>
+        <details><summary>Two</summary></details>
+      </ogds-accordion>
+    `);
+    await Promise.all([el1.updateComplete, el2.updateComplete]);
+    expect(document.adoptedStyleSheets).toHaveLength(1);
+  });
+});
+
+describe("use-list-semantics and heading-level used together", () => {
+  it("warns and applies neither when both attributes are present", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const el = mount(`
+      <ogds-accordion use-list-semantics heading-level="3">
+        <details><summary>One</summary></details>
+        <details><summary>Two</summary></details>
+      </ogds-accordion>
+    `);
+    await el.updateComplete;
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(el.getAttribute("role")).toBeNull();
+    el.querySelectorAll("details").forEach((d) => {
+      expect(d.getAttribute("role")).toBeNull();
+    });
+    el.querySelectorAll("summary").forEach((s) => {
+      expect(s.getAttribute("role")).toBeNull();
+    });
+    warnSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,77 @@
+import { html } from "lit";
+import "./index";
+import ComponentDocs from "./docs.mdx";
+
+const items = html`
+  <details>
+    <summary>First Amendment</summary>
+    <p>
+      Congress shall make no law respecting an establishment of religion, or
+      prohibiting the free exercise thereof; or abridging the freedom of speech,
+      or of the press; or the right of the people peaceably to assemble, and to
+      petition the Government for a redress of grievances.
+    </p>
+  </details>
+  <details>
+    <summary>Second Amendment</summary>
+    <p>
+      A well regulated Militia, being necessary to the security of a free State,
+      the right of the people to keep and bear Arms, shall not be infringed.
+    </p>
+  </details>
+  <details>
+    <summary>Third Amendment</summary>
+    <p>
+      No Soldier shall, in time of peace be quartered in any house, without the
+      consent of the Owner, nor in time of war, but in a manner to be prescribed
+      by law.
+    </p>
+  </details>
+`;
+
+export default {
+  title: "Components/Accordion",
+  component: "ogds-accordion",
+  tags: ["alpha"],
+  parameters: {
+    docs: {
+      page: ComponentDocs,
+    },
+  },
+};
+
+export const Default = {
+  render: () => html`<ogds-accordion>${items}</ogds-accordion>`,
+};
+
+export const Bordered = {
+  render: () =>
+    html`<ogds-accordion class="bordered">${items}</ogds-accordion>`,
+};
+
+export const WithChevronIcons = {
+  render: () =>
+    html`<ogds-accordion class="with-icon">${items}</ogds-accordion>`,
+};
+
+export const WithChevronIconsRight = {
+  render: () =>
+    html`<ogds-accordion class="with-icon right">${items}</ogds-accordion>`,
+};
+
+export const WithChevronIconsBordered = {
+  render: () =>
+    html`<ogds-accordion class="with-icon bordered">${items}</ogds-accordion>`,
+};
+
+export const WithPlusIcons = {
+  render: () =>
+    html`<ogds-accordion class="with-icon plus">${items}</ogds-accordion>`,
+};
+
+export const WithPlusIconsBordered = {
+  render: () =>
+    html`<ogds-accordion class="with-icon plus bordered"
+      >${items}</ogds-accordion
+    >`,
+};

package/src/components/ogds-accordion-toggle/index.ts

@@ -0,0 +1,80 @@
+import { LitElement, html } from "lit";
+import { adoptTokenStyles } from "../../core/token-styles";
+import { defineCustomElement } from "../../utils";
+
+import { property, state } from "lit/decorators.js";
+
+/**
+ * @summary A button that expands or collapses all panels in an associated `<ogds-accordion>`.
+ *
+ * @attribute {string} controls - The `id` of the `<ogds-accordion>` to control. Required.
+ * @attribute {string} expand-label - Button label when all panels are collapsed. Defaults to "Expand All".
+ * @attribute {string} collapse-label - Button label when one or more panels are open. Defaults to "Collapse All".
+ *
+ * @csspart button - The toggle button.
+ *
+ * @element ogds-accordion-toggle
+ */
+export class OgdsAccordionToggle extends LitElement {
+  @property({ type: String, attribute: "controls" })
+  controls = "";
+
+  @property({ type: String, attribute: "expand-label" })
+  expandLabel = "Expand All";
+
+  @property({ type: String, attribute: "collapse-label" })
+  collapseLabel = "Collapse All";
+
+  @state()
+  private _anyOpen = false;
+
+  override connectedCallback() {
+    super.connectedCallback();
+
+    if (this.controls == "") {
+      console.error(
+        "<ogds-accordion-toggle>: Component must have a controls attribute with the ID" +
+          "of an <ogds-accordion> component",
+      );
+      return;
+    }
+    this._anyOpen = this.checkOpen();
+    adoptTokenStyles();
+  }
+
+  checkOpen() {
+    const accordionEl = document.getElementById(this.controls);
+    const openDetails = accordionEl?.querySelector("details[open]");
+    return !!openDetails;
+  }
+
+  toggleAll() {
+    const accordionEl = document.getElementById(this.controls);
+    if (!accordionEl) {
+      console.error(
+        "<ogds-accordion-toggle>: Unable to get an accordion component with the ID" +
+          " specfied in the controls attribute",
+      );
+      return;
+    }
+
+    const detailsEls = Array.from(accordionEl.getElementsByTagName("details"));
+    const anyOpen = detailsEls.some((d) => d.hasAttribute("open"));
+    if (!anyOpen) {
+      detailsEls.forEach((d) => d.toggleAttribute("open", true));
+    } else {
+      detailsEls.forEach((d) => d.toggleAttribute("open", false));
+    }
+    this._anyOpen = !anyOpen;
+  }
+
+  protected override render(): unknown {
+    return html`
+      <button @click="${this.toggleAll}" part="button">
+        ${this._anyOpen ? this.collapseLabel : this.expandLabel}
+      </button>
+    `;
+  }
+}
+
+defineCustomElement("ogds-accordion-toggle", OgdsAccordionToggle);