@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.5

package/src/Component/Translate/Translate.tsx

@@ -0,0 +1,213 @@
+import { JSX, KeyboardEvent, MouseEvent, useEffect, useId, useMemo, useRef } from "react"
+import { FocusScope, useFocusManager } from "react-aria"
+import classNames from "classnames"
+import { PopoverPlacementModifier } from "@pnx-mixtape/ids-shape"
+import Icon from "../../Atom/Icon/Icon"
+import { Icons } from "../../enums"
+import { GoogleTranslateWidget } from "../../Utility/utilities"
+import { TranslateLanguage } from "./languages"
+
+type TranslateItemsProps = {
+  languages: TranslateLanguage[]
+  onSelect: (code: string, event: MouseEvent<HTMLAnchorElement>) => void
+}
+
+const TranslateItems = ({ languages, onSelect }: TranslateItemsProps): JSX.Element => {
+  const focusManager = useFocusManager()
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLAnchorElement>): void => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        event.preventDefault()
+        focusManager?.focusNext({ wrap: true, tabbable: true })
+        break
+      case "ArrowUp":
+      case "ArrowLeft":
+        event.preventDefault()
+        focusManager?.focusPrevious({ wrap: true, tabbable: true })
+        break
+      default:
+        break
+    }
+  }
+
+  return (
+    <>
+      {languages.map(language => (
+        <a
+          key={language.code}
+          className="mx-translate__item"
+          href={`?hl=${language.code}`}
+          lang={language.code}
+          hrefLang={language.code}
+          role="menuitem"
+          data-language={language.code}
+          onClick={event => onSelect(language.code, event)}
+          onKeyDown={handleKeyDown}
+        >
+          {language.label}
+        </a>
+      ))}
+    </>
+  )
+}
+
+type TranslateProps = {
+  id?: string
+  label?: string
+  /** The language list — no built-in default, import `DEFAULT_LANGUAGES` from this component to opt into one. */
+  languages: TranslateLanguage[]
+  defaultLanguage?: string
+  /** Paths where translation is disallowed — the blocked notice shows instead. */
+  blockedPaths?: string[]
+  scriptUrl?: string
+  storageKey?: string
+  /**
+   * Updates the trigger's visible language code + `aria-label` to reflect the active language.
+   * On by default — pass `false` to keep the trigger static instead, which some sites prefer.
+   */
+  updateTriggerLabel?: boolean
+  /** Consumer-supplied copy shown once a non-default language is active — entirely opt-in, omit to never show a notice. */
+  noticeContent?: string
+  /** Consumer-supplied copy shown instead, on a blocked path. */
+  noticeBlockedContent?: string
+  /** Where to insert the notice. Defaults to the top of `<body>` if omitted — the notice doesn't have to live near this component, e.g. if the trigger is in the header. */
+  noticeAnchor?: string
+  /** Insertion position relative to `noticeAnchor`. Defaults to `afterend` when set, `afterbegin` otherwise. */
+  noticePosition?: InsertPosition
+  placement?: PopoverPlacementModifier
+  className?: string
+  /** Closes the menu after a language is chosen. */
+  closeOnSelect?: boolean
+  onOpen?: () => void
+  onClose?: () => void
+  onLanguageChange?: (code: string) => void
+}
+
+const Translate = ({
+  id,
+  label = "Language",
+  languages,
+  defaultLanguage = "en",
+  blockedPaths,
+  scriptUrl,
+  storageKey,
+  updateTriggerLabel = true,
+  noticeContent,
+  noticeBlockedContent,
+  noticeAnchor,
+  noticePosition,
+  placement = PopoverPlacementModifier.BOTTOM_START,
+  className,
+  closeOnSelect = true,
+  onOpen,
+  onClose,
+  onLanguageChange,
+}: TranslateProps): JSX.Element => {
+  const generatedId = useId()
+  const rootId = id ?? generatedId
+  const rootRef = useRef<HTMLDivElement>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const widgetRef = useRef<GoogleTranslateWidget | null>(null)
+  const polyfillRef = useRef<any>(null)
+
+  const triggerStyle = useMemo(() => ({ anchorName: `--${rootId}` }), [rootId])
+  const popoverStyle = useMemo(() => ({ positionAnchor: `--${rootId}` }), [rootId])
+
+  useEffect(() => {
+    if (!rootRef.current) return undefined
+    const widget = new GoogleTranslateWidget(rootRef.current, {
+      defaultLanguage,
+      blockedPaths,
+      scriptUrl,
+      storageKey,
+      updateTriggerLabel,
+      notice: noticeContent
+        ? {
+            content: noticeContent,
+            blockedContent: noticeBlockedContent,
+            anchorSelector: noticeAnchor,
+            position: noticePosition,
+          }
+        : undefined,
+      onLanguageChange,
+    })
+    widget.init()
+    widgetRef.current = widget
+    return () => widget.destroy()
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- only re-runs on mount/unmount; config changes apply on the next setLanguage call
+  }, [])
+
+  useEffect(() => {
+    const popover = popoverRef.current
+    if (!popover) return undefined
+
+    const polyfill = async (): Promise<void> => {
+      if (
+        !("anchorName" in document.documentElement.style) ||
+        !("popover" in HTMLElement.prototype)
+      ) {
+        const { default: Polyfills } = await import("../Popover/polyfills")
+        polyfillRef.current = new Polyfills(popover)
+      }
+    }
+    polyfill().catch(() => {})
+
+    const controller = new AbortController()
+    popover.addEventListener(
+      "toggle",
+      (event: Event) => {
+        const { newState } = event as ToggleEvent
+        if (newState === "open") onOpen?.()
+        else onClose?.()
+      },
+      { signal: controller.signal },
+    )
+
+    return () => {
+      controller.abort()
+      polyfillRef.current?.destroy()
+    }
+  }, [onOpen, onClose])
+
+  const handleSelect = (code: string, event: MouseEvent<HTMLAnchorElement>): void => {
+    event.preventDefault()
+    widgetRef.current?.setLanguage(code)
+    if (closeOnSelect) popoverRef.current?.hidePopover()
+  }
+
+  return (
+    <div ref={rootRef} className={classNames("mx-translate", className)}>
+      <button
+        type="button"
+        id={`${rootId}-target`}
+        className="mx-translate__trigger mx-popover__trigger notranslate"
+        popoverTarget={rootId}
+        style={triggerStyle}
+        data-label={label}
+        aria-label={label}
+      >
+        <Icon icon={Icons.GLOBE} />
+        <span className="mx-translate__code">{defaultLanguage.toUpperCase()}</span>
+      </button>
+      <div
+        ref={popoverRef}
+        id={rootId}
+        className="mx-popover mx-translate__menu notranslate"
+        aria-describedby={`${rootId}-target`}
+        aria-labelledby={`${rootId}-target`}
+        style={popoverStyle}
+        data-placement={placement}
+        popover=""
+        role="menu"
+      >
+        <FocusScope>
+          <TranslateItems languages={languages} onSelect={handleSelect} />
+        </FocusScope>
+      </div>
+    </div>
+  )
+}
+
+export default Translate

package/src/Component/Translate/__snapshots__/Translate.stories.ts.snap

@@ -0,0 +1,18 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Translate 1`] = `
+"
+<mx-translate class="mx-translate" closeonclick="" data-default-language="en" data-update-trigger-label="true" data-notice-content="Our website uses an automatic service to translate content. These translations should be used as a guide only.">
+  <button id="unique-0" type="button" class="mx-button mx-button--light mx-button--small mx-translate__trigger mx-popover__trigger notranslate" popovertarget="translate" style="anchor-name: --translate" data-label="Language" aria-label="Language: English">
+    
+<span class="mx-icon mx-icon--globe"></span>
+    <span class="mx-translate__code">EN</span>
+  </button>
+  <div class="mx-popover mx-translate__menu notranslate" id="translate" aria-describedby="unique-0" aria-labelledby="unique-0" style="position-anchor: --translate" data-placement="bottom-start" popover="" role="menu">
+          <a class="mx-translate__item" href="?hl=en" lang="en" hreflang="en" role="menuitem" data-language="en" aria-current="true">English</a>
+          <a class="mx-translate__item" href="?hl=fr" lang="fr" hreflang="fr" role="menuitem" data-language="fr">Français</a>
+          <a class="mx-translate__item" href="?hl=es" lang="es" hreflang="es" role="menuitem" data-language="es">Español</a>
+      </div>
+</mx-translate>
+"
+`;

package/src/Component/Translate/__snapshots__/Translate.stories.tsx.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Translate 1`] = `"<div class="mx-translate"><button type="button" id="translate-target" class="mx-translate__trigger mx-popover__trigger notranslate" popovertarget="translate" data-label="Language" aria-label="Language: English" style="anchor-name: --translate;"><span class="mx-icon mx-icon--globe"></span><span class="mx-translate__code">EN</span></button><div id="translate" class="mx-popover mx-translate__menu notranslate" aria-describedby="translate-target" aria-labelledby="translate-target" data-placement="bottom-start" popover="" role="menu" style="position-anchor: --translate;"><span data-focus-scope-start="true" hidden=""></span><a class="mx-translate__item" href="?hl=en" lang="en" hreflang="en" role="menuitem" data-language="en" aria-current="true">English</a><a class="mx-translate__item" href="?hl=fr" lang="fr" hreflang="fr" role="menuitem" data-language="fr">Français</a><a class="mx-translate__item" href="?hl=es" lang="es" hreflang="es" role="menuitem" data-language="es">Español</a><span data-focus-scope-end="true" hidden=""></span></div></div>"`;

package/src/Component/Translate/languages.ts

@@ -0,0 +1,39 @@
+export type TranslateLanguage = {
+  code: string
+  label: string
+}
+
+/**
+ * A representative set of languages Google's Website Translator supports, in each language's
+ * own name. Not bundled into `Translate` by default — import and pass this explicitly (or your
+ * own list) via the `languages` prop.
+ */
+export const DEFAULT_LANGUAGES: TranslateLanguage[] = [
+  { code: "en", label: "English" },
+  { code: "ar", label: "العربية" },
+  { code: "zh-CN", label: "中文 (简体)" },
+  { code: "zh-TW", label: "中文 (繁體)" },
+  { code: "nl", label: "Nederlands" },
+  { code: "fr", label: "Français" },
+  { code: "de", label: "Deutsch" },
+  { code: "el", label: "Ελληνικά" },
+  { code: "hi", label: "हिन्दी" },
+  { code: "id", label: "Bahasa Indonesia" },
+  { code: "it", label: "Italiano" },
+  { code: "ja", label: "日本語" },
+  { code: "ko", label: "한국어" },
+  { code: "ms", label: "Bahasa Melayu" },
+  { code: "fa", label: "فارسی" },
+  { code: "pl", label: "Polski" },
+  { code: "pt", label: "Português" },
+  { code: "ru", label: "Русский" },
+  { code: "es", label: "Español" },
+  { code: "sw", label: "Kiswahili" },
+  { code: "sv", label: "Svenska" },
+  { code: "tl", label: "Tagalog" },
+  { code: "th", label: "ไทย" },
+  { code: "tr", label: "Türkçe" },
+  { code: "uk", label: "Українська" },
+  { code: "ur", label: "اردو" },
+  { code: "vi", label: "Tiếng Việt" },
+]

package/src/Component/Translate/translate.css

@@ -0,0 +1,62 @@
+/**
+ * Translate
+ *
+ * Composes DropMenu/Popover — import their CSS alongside this file.
+ */
+
+@layer design-system.defaults {
+  mx-translate {
+    display: inline-block;
+  }
+}
+
+@layer design-system.components {
+  .mx-translate {
+    position: relative;
+  }
+
+  .mx-translate__trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-xxs);
+  }
+
+  .mx-translate__code {
+    text-transform: uppercase;
+    font-size: var(--font-size-xs);
+  }
+
+  /* @public --translate-menu-max-block-size, --translate-popover-padding */
+  .mx-translate__menu {
+    --popover-padding: var(--translate-popover-padding, 0px);
+
+    max-block-size: var(--translate-menu-max-block-size, 60vh);
+    overflow-y: auto;
+  }
+
+  .mx-translate__item {
+    display: block;
+    padding-block: var(--vertical-padding, var(--spacing-xxs));
+    padding-inline: var(--horizontal-padding, var(--spacing-m));
+    text-decoration: none;
+
+    &[aria-current="true"] {
+      font-weight: var(--font-weight-bold);
+      text-decoration: underline;
+    }
+  }
+}
+
+/* Stop Google giving us top padding */
+body {
+  inset-block-start: 0 !important;
+  min-block-size: 0 !important;
+}
+
+/* Hide Google elements */
+/* stylelint-disable selector-id-pattern */
+.skiptranslate,
+#googleTranslateElement,
+#goog-gt-tt {
+  display: none !important;
+}

package/src/Component/Translate/translate.entry.js

@@ -0,0 +1 @@
+import "./Elements/Translate"

package/src/Component/Translate/translate.twig

@@ -0,0 +1,44 @@
+{% set attributes = (attributes ?? create_attribute()).addClass('mx-translate') %}
+{% set id = id|default('translate') %}
+{% set label = label|default('Language') %}
+{% set defaultLanguage = defaultLanguage|default('en') %}
+{% set updateTriggerLabel = updateTriggerLabel|default(true) %}
+
+<mx-translate{{ attributes }} closeonclick
+    data-default-language="{{ defaultLanguage }}"
+    {%- if blockedPaths %} data-blocked-paths="{{ blockedPaths|join(',') }}"{% endif -%}
+    {%- if scriptUrl %} data-script-url="{{ scriptUrl }}"{% endif -%}
+    {%- if storageKey %} data-storage-key="{{ storageKey }}"{% endif -%}
+    data-update-trigger-label="{{ updateTriggerLabel ? 'true' : 'false' }}"
+    {%- if noticeContent %} data-notice-content="{{ noticeContent }}"{% endif -%}
+    {%- if noticeBlockedContent %} data-notice-blocked-content="{{ noticeBlockedContent }}"{% endif -%}
+    {%- if noticeAnchor %} data-notice-anchor="{{ noticeAnchor }}"{% endif -%}
+    {%- if noticePosition %} data-notice-position="{{ noticePosition }}"{% endif -%}
+>
+  <button
+      id="{{ id }}-target"
+      type="button"
+      class="mx-button mx-button--light mx-button--small mx-translate__trigger mx-popover__trigger notranslate"
+      popovertarget="{{ id }}"
+      style="anchor-name: --{{ id }}"
+      data-label="{{ label }}"
+      aria-label="{{ label }}"
+  >
+    {% include '@mixtape/Atom/Icon/icon.twig' with { icon: 'globe' } only %}
+    <span class="mx-translate__code">{{ defaultLanguage|upper }}</span>
+  </button>
+  <div
+      class="mx-popover mx-translate__menu notranslate"
+      id="{{ id }}"
+      aria-describedby="{{ id }}-target"
+      aria-labelledby="{{ id }}-target"
+      style="position-anchor: --{{ id }}"
+      data-placement="{{ placement|default('bottom-start') }}"
+      popover
+      role="menu"
+  >
+    {% for language in languages %}
+      <a class="mx-translate__item" href="?hl={{ language.code }}" lang="{{ language.code }}" hreflang="{{ language.code }}" role="menuitem" data-language="{{ language.code }}">{{ language.label }}</a>
+    {% endfor %}
+  </div>
+</mx-translate>

package/src/Form/Autocomplete/Autocomplete.stories.tsx

@@ -204,7 +204,7 @@ export const Pending: StoryObj<typeof meta> = {
  * `docs/Testing.md`'s Automated Screen Reader Testing section.
  */
 export const ScreenReaderAnnouncements: StoryObj<typeof meta> = {
-  play: async ({ canvas, userEvent }) => {
+  play: async ({ canvas, canvasElement, userEvent }) => {
     const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
 
     // "lu" matches exactly two fruits: Blueberry, then Plum.
@@ -229,5 +229,6 @@ export const ScreenReaderAnnouncements: StoryObj<typeof meta> = {
 
     await userEvent.clear(input)
     await expect(input).toHaveAttribute("aria-expanded", "false")
+    await userEvent.click(canvasElement)
   },
 }

package/src/Form/FeedbackForm/Elements/FeedbackForm.ts

@@ -0,0 +1,122 @@
+/**
+ * FeedbackForm
+ * @file Reveals a comment field once a rating is chosen, and dispatches a
+ * cancelable `mx-feedback-form-submit` event on submit so any backend can be
+ * wired up by the consumer — this component never performs a fetch/AJAX call
+ * itself. If the consuming app calls `preventDefault()` on that event, the
+ * native form submission is also cancelled, handing full control to the
+ * consumer; otherwise the browser submits normally via the form's
+ * `action`/`method`.
+ */
+
+import { validators } from "../../../Utility/utilities"
+
+export type FeedbackFormSubmitEvent = CustomEvent<{
+  rating: string | null
+  comment: string
+  form: HTMLFormElement
+}>
+
+export default class FeedbackForm extends HTMLElement {
+  internals_: ElementInternals
+  controller: AbortController
+  revealed: boolean
+
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+    this.controller = new AbortController()
+    this.revealed = false
+  }
+
+  static get observedAttributes(): string[] {
+    return ["pending"]
+  }
+
+  connectedCallback(): void {
+    const { signal } = this.controller
+
+    // Only gate the reveal behind a checked rating once JS is confirmed
+    // running — see feedback-form.css.
+    this.classList.add("is-enhanced")
+
+    // Validation is driven by this component's own status message instead of
+    // the browser's native validation bubble.
+    this.form?.setAttribute("novalidate", "")
+
+    this.querySelectorAll('input[type="radio"]').forEach(radio => {
+      radio.addEventListener("change", this.handleRatingChange, { signal })
+    })
+
+    this.form?.addEventListener("submit", this.handleSubmit, { signal })
+  }
+
+  disconnectedCallback(): void {
+    this.controller.abort()
+  }
+
+  attributeChangedCallback(name: string): void {
+    if (name !== "pending") return
+    const isPending = this.hasAttribute("pending")
+    this.internals_.states[isPending ? "add" : "delete"]("pending")
+    this.submitButton?.toggleAttribute("disabled", isPending)
+    this.submitButton?.setAttribute("aria-busy", String(isPending))
+  }
+
+  handleRatingChange = (): void => {
+    if (this.revealed) return
+    this.revealed = true
+    this.comment?.focus()
+  }
+
+  handleSubmit = (event: SubmitEvent): void => {
+    const comment = this.comment
+
+    if (comment?.required && !validators.notEmpty(comment.value)) {
+      event.preventDefault()
+      comment.setAttribute("aria-invalid", "true")
+      this.status?.removeAttribute("hidden")
+      comment.focus()
+      return
+    }
+
+    comment?.removeAttribute("aria-invalid")
+    this.status?.setAttribute("hidden", "")
+
+    const rating =
+      this.querySelector<HTMLInputElement>('input[type="radio"]:checked')?.value ?? null
+    const submitEvent: FeedbackFormSubmitEvent = new CustomEvent("mx-feedback-form-submit", {
+      bubbles: true,
+      cancelable: true,
+      detail: { rating, comment: comment?.value ?? "", form: this.form as HTMLFormElement },
+    })
+    const shouldProceed = this.dispatchEvent(submitEvent)
+    if (!shouldProceed) event.preventDefault()
+  }
+
+  get form(): HTMLFormElement | null {
+    return this.querySelector("form")
+  }
+
+  get comment(): HTMLTextAreaElement | null {
+    return this.querySelector(".mx-feedback-form__reveal textarea")
+  }
+
+  get status(): HTMLElement | null {
+    return this.querySelector('.mx-feedback-form__reveal [role="alert"]')
+  }
+
+  get submitButton(): HTMLButtonElement | null {
+    return this.querySelector(".mx-form-actions button")
+  }
+}
+
+if (!customElements.get("mx-feedback-form")) {
+  customElements.define("mx-feedback-form", FeedbackForm)
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "mx-feedback-form": FeedbackForm
+  }
+}

package/src/Form/FeedbackForm/FeedbackForm.stories.ts

@@ -0,0 +1,99 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./feedback-form.twig"
+import "./feedback-form.css"
+import "./Elements/FeedbackForm"
+
+type FeedbackFormArgs = {
+  id?: string
+  name?: string
+  question?: string
+  yesLabel?: string
+  noLabel?: string
+  secondaryText?: string
+  secondaryLinkText?: string
+  secondaryLinkHref?: string
+  commentLabel?: string
+  commentName?: string
+  commentPlaceholder?: string
+  commentRequired?: boolean
+  requiredErrorMessage?: string
+  submitLabel?: string
+  action?: string
+  method?: string
+  errorMessage?: string
+}
+
+/**
+ * A yes/no "was this page useful?" control that reveals a free-text comment field once a
+ * rating is chosen. It requires the `FeedbackForm` custom element javascript.
+ *
+ * This component never submits anywhere itself — it dispatches a cancelable
+ * `mx-feedback-form-submit` event with the chosen rating/comment before the form submits, so any
+ * backend can be wired up by the consumer.
+ */
+const meta: Meta<FeedbackFormArgs> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "feedback",
+    secondaryText: "Your rating will help us improve the website.",
+  },
+}
+
+export default meta
+type Story = StoryObj<FeedbackFormArgs>
+
+export const FeedbackForm: Story = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const wrapper = canvasElement.querySelector("mx-feedback-form") as HTMLElement
+    const comment = canvas.getByLabelText("How can we make it better?") as HTMLTextAreaElement
+
+    await step("Comment field is hidden until a rating is chosen", async () => {
+      await expect(comment).not.toBeVisible()
+    })
+
+    await step("Choosing a rating reveals and focuses the comment field", async () => {
+      await userEvent.click(canvas.getByRole("radio", { name: "Yes" }))
+      await waitFor(() => expect(comment).toBeVisible())
+      await expect(comment).toHaveFocus()
+    })
+
+    await step(
+      "Submitting dispatches mx-feedback-form-submit with the rating and comment",
+      async () => {
+        let detail: { rating: string | null; comment: string } | undefined
+        wrapper.addEventListener("mx-feedback-form-submit", (event: Event) => {
+          event.preventDefault()
+          detail = (event as CustomEvent<typeof detail>).detail
+        })
+        await userEvent.type(comment, "More examples would help.")
+        await userEvent.click(canvas.getByRole("button", { name: "Submit" }))
+        await waitFor(() =>
+          expect(detail).toEqual(
+            expect.objectContaining({ rating: "yes", comment: "More examples would help." }),
+          ),
+        )
+      },
+    )
+  },
+}
+
+/** With `commentRequired`, an empty comment blocks submission and shows an inline error. */
+export const RequiredComment: Story = {
+  args: {
+    id: "feedback-required",
+    commentRequired: true,
+  },
+  play: async ({ canvas, userEvent, step }) => {
+    await step("Reveal the comment field", async () => {
+      await userEvent.click(canvas.getByRole("radio", { name: "No" }))
+      await waitFor(() => expect(canvas.getByLabelText("How can we make it better?")).toBeVisible())
+    })
+
+    await step("Submitting an empty required comment shows the error", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "Submit" }))
+      await waitFor(() => expect(canvas.getByRole("alert")).toBeVisible())
+    })
+  },
+}