@smicolon/fasla-ui 0.6.0 → 0.8.0

package/registry/blocks/contact-us-form-with-faq/ContactUsFormWithFaq.tsx

@@ -0,0 +1,383 @@
+"use client"
+
+import * as React from "react"
+import { ChevronDown, LifeBuoy, Send } from "lucide-react"
+import { cn } from "../../../src/lib/utils"
+import { Badge } from "../../ui/badge/badge"
+import {
+  CONTACT_US_TEXTAREA_88,
+  ContactUsField,
+  ContactUsForm,
+  ContactUsHeader,
+  ContactUsSection,
+  ContactUsSubmit,
+  contactUsFormMessages,
+  prefersReducedMotion,
+  splitCopy,
+  useContactUsForm,
+  useReveal,
+  type ContactUsFieldDef,
+  type ContactUsFormBlockProps,
+  type ContactUsFormMessages,
+  type ContactUsLocale,
+  type ContactUsOption,
+} from "../contact-us/contact-us"
+
+/*
+ * Figma: `Contact Us` (42334:293941), Type=Form with FAQ.
+ *
+ * Left (the start side, 744px on Desktop): an eyebrow in capitals, an h2
+ * (36px; 30px on Tablet; 24px on Mobile), a line, then Name and Email side by
+ * side, a Topic select, a Message textarea (its group 88px tall), a "Send me a
+ * copy" checkbox and a Solid Primary "Send message" Button with a send icon.
+ * Right: the FAQ sidebar, 440px, `muted` with 10px corners and 24px of
+ * padding: the label BEFORE YOU WRITE, a bordered `card` of five question rows
+ * (a chevron after each) and a "Still stuck?" help link with a life-buoy icon.
+ * In Arabic the two swap sides and the chevrons sit at the start of each row,
+ * because the page's `dir` flips both.
+ *
+ * Tablet: the sidebar drops below the form at full width and stops being
+ * sticky; Name and Email stay side by side. Mobile: Name and Email stack, and
+ * the FAQ moves ABOVE the send button, inside the form's column, so it is read
+ * before sending. That is ONE element: the form's `<form>` is `display:
+ * contents`, so the header, the fields, the actions and the FAQ are all items
+ * of one grid, and `order` puts the FAQ where each size wants it.
+ *
+ * Real: the form validates on the client and calls `onSubmit(values)` with
+ * name, email, topic, message and copy (a boolean). Email is required (it
+ * shows the word "Required"); name, topic, message and the copy box are not.
+ * Each FAQ row is a disclosure: a button with `aria-expanded` that opens its
+ * answer (rows open independently). The sidebar is `position: sticky` on
+ * Desktop, CSS only. The smart nudge reads the message as it is typed and the
+ * topic as it is picked, matches them against each FAQ's `keywords` and
+ * highlights the rows that fit, with a "Might this help?" chip; it never
+ * blocks sending.
+ *
+ * Static: Figma draws no answers, no open row and no chip; the answers and the
+ * chip's look (Badge, Soft Primary, sm) are ours.
+ *
+ * Motion: once, when the block is in view, the header and fields rise and the
+ * sidebar slides 16px in from the end side. A row opens by a grid-template-rows
+ * transition 0fr to 1fr over 260ms and the chevron turns 180 degrees over the
+ * same 260ms. A nudged row's `muted` background fades in over 260ms and its chip
+ * fades in over 260ms. Reduced motion: opening and closing are instant, no
+ * background tween, the chip appears without a fade.
+ *
+ * Content limits: heading up to 24 characters, line up to 90, question up to 40,
+ * answer up to 180, up to 5 questions, 5 topics, 6 keywords a question.
+ */
+
+export interface ContactUsFaq {
+  question: string
+  answer: string
+  /** Words that, found in the message or the topic, nudge this question. Lower case. */
+  keywords: string[]
+}
+
+export interface ContactUsFormWithFaqCopy extends ContactUsFormMessages {
+  /** The small line above the heading. */
+  eyebrow: string
+  /** The h2. */
+  heading: string
+  /** The line under it. */
+  description: string
+  name: string
+  namePlaceholder: string
+  email: string
+  emailPlaceholder: string
+  topic: string
+  topicPlaceholder: string
+  /** The topic choices. A topic's label also feeds the nudge. */
+  topics: ContactUsOption[]
+  message: string
+  messagePlaceholder: string
+  /** The checkbox: send the visitor a copy. */
+  copyMe: string
+  submit: string
+  /** The sidebar's label. */
+  sidebarLabel: string
+  /** The questions, in order. */
+  faqs: ContactUsFaq[]
+  /** The help link's text. */
+  helpLabel: string
+  /** The chip on a nudged question. */
+  nudge: string
+}
+
+const COPY: Record<ContactUsLocale, ContactUsFormWithFaqCopy> = {
+  en: {
+    ...contactUsFormMessages.en,
+    eyebrow: "SEND A MESSAGE",
+    heading: "Ask us anything",
+    description: "Before you write, the answers on the right solve most questions in under a minute.",
+    name: "Name",
+    namePlaceholder: "Sara Al Mansouri",
+    email: "Email",
+    emailPlaceholder: "sara@company.com",
+    topic: "Topic",
+    topicPlaceholder: "Choose a topic",
+    topics: [
+      { value: "general", label: "General question" },
+      { value: "billing", label: "Billing and invoices" },
+      { value: "education", label: "Education licence" },
+      { value: "bug", label: "Report a bug" },
+      { value: "other", label: "Something else" },
+    ],
+    message: "Message",
+    messagePlaceholder: "What can we help with?",
+    copyMe: "Send me a copy of this message.",
+    submit: "Send message",
+    sidebarLabel: "BEFORE YOU WRITE",
+    faqs: [
+      {
+        question: "How long does a reply take?",
+        answer: "We answer within one working day, and usually within a few hours between 09:00 and 18:00 Gulf time, Sunday to Thursday.",
+        keywords: ["reply", "response", "how long", "wait", "slow", "urgent", "hours"],
+      },
+      {
+        question: "Can I get an invoice in AED?",
+        answer: "Yes. We invoice in AED or USD. Tell us which, and your company's tax details, and the billing team will send it.",
+        keywords: ["invoice", "aed", "billing", "payment", "vat", "tax", "receipt", "price", "pricing"],
+      },
+      {
+        question: "Do you offer an education licence?",
+        answer: "We do. Schools, universities and students use Fasla at a reduced rate. Send us the name of your institution and we will confirm the discount.",
+        keywords: ["education", "student", "university", "school", "licence", "license", "discount", "academic"],
+      },
+      {
+        question: "Where do I report a bug?",
+        answer: "Describe what happened, the steps to repeat it and a screenshot in the message here, or use the report link in the help centre.",
+        keywords: ["bug", "error", "broken", "crash", "issue", "problem", "not working", "fix"],
+      },
+      {
+        question: "Can I book a call instead?",
+        answer: "Of course. Pick a time that suits you on our booking page and we will send a calendar invite with the meeting link.",
+        keywords: ["call", "book", "meeting", "schedule", "demo", "talk", "phone"],
+      },
+    ],
+    helpLabel: "Still stuck? Visit the help centre",
+    nudge: "Might this help?",
+  },
+  ar: {
+    ...contactUsFormMessages.ar,
+    eyebrow: "أرسل رسالة",
+    heading: "اسألنا عن أي شيء",
+    description: "قبل أن تكتب، الإجابات المجاورة تحلّ معظم الأسئلة خلال أقل من دقيقة.",
+    name: "الاسم",
+    namePlaceholder: "سارة المنصوري",
+    email: "البريد الإلكتروني",
+    emailPlaceholder: "sara@company.com",
+    topic: "الموضوع",
+    topicPlaceholder: "اختر موضوعًا",
+    topics: [
+      { value: "general", label: "سؤال عام" },
+      { value: "billing", label: "الفواتير والدفع" },
+      { value: "education", label: "الترخيص التعليمي" },
+      { value: "bug", label: "الإبلاغ عن خلل" },
+      { value: "other", label: "شيء آخر" },
+    ],
+    message: "الرسالة",
+    messagePlaceholder: "بماذا يمكننا مساعدتك؟",
+    copyMe: "أرسل لي نسخة من هذه الرسالة.",
+    submit: "إرسال الرسالة",
+    sidebarLabel: "قبل أن تكتب",
+    faqs: [
+      {
+        question: "كم يستغرق الردّ؟",
+        answer: "نرد خلال يوم عمل واحد، وغالبًا خلال ساعات قليلة بين 09:00 و18:00 بتوقيت الخليج، من الأحد إلى الخميس.",
+        keywords: ["رد", "الرد", "ردّ", "كم يستغرق", "انتظار", "عاجل", "ساعات", "reply"],
+      },
+      {
+        question: "هل يمكنني الحصول على فاتورة بالدرهم؟",
+        answer: "نعم. نصدر الفواتير بالدرهم أو بالدولار. أخبرنا بالعملة وببيانات شركتك الضريبية وسيرسلها فريق الفواتير.",
+        keywords: ["فاتور", "درهم", "الدفع", "دفع", "ضريب", "إيصال", "سعر", "أسعار", "aed"],
+      },
+      {
+        question: "هل تقدّمون ترخيصًا تعليميًا؟",
+        answer: "نعم. تستخدم المدارس والجامعات والطلاب فاصلة بسعر مخفّض. أرسل لنا اسم مؤسستك وسنؤكد لك الخصم.",
+        keywords: ["تعليم", "طالب", "طلاب", "جامعة", "مدرسة", "ترخيص", "خصم", "أكاديمي"],
+      },
+      {
+        question: "أين أبلّغ عن خلل؟",
+        answer: "اشرح ما حدث وخطوات تكراره وأرفق وصفًا للشاشة في الرسالة هنا، أو استخدم رابط الإبلاغ في مركز المساعدة.",
+        keywords: ["خلل", "خطأ", "عطل", "مشكلة", "لا يعمل", "تعطل", "إبلاغ", "أبلغ"],
+      },
+      {
+        question: "هل يمكنني حجز مكالمة بدلًا من ذلك؟",
+        answer: "بالطبع. اختر الوقت المناسب لك في صفحة الحجز وسنرسل لك دعوة التقويم مع رابط الاجتماع.",
+        keywords: ["مكالم", "حجز", "احجز", "اجتماع", "موعد", "عرض", "اتصال", "هاتف"],
+      },
+    ],
+    helpLabel: "ما زلت عالقًا؟ زر مركز المساعدة",
+    nudge: "هل يفيدك هذا؟",
+  },
+}
+
+export interface ContactUsFormWithFaqProps extends ContactUsFormBlockProps, Partial<ContactUsFormWithFaqCopy> {
+  /** Where the help link goes. */
+  helpHref?: string
+}
+
+/** The questions whose keywords appear in what the visitor has typed or picked. */
+export function matchContactUsFaqs(faqs: readonly ContactUsFaq[], ...texts: string[]) {
+  const haystack = texts.join(" ").toLowerCase()
+  if (haystack.trim().length < 3) return new Set<number>()
+  const found = new Set<number>()
+  faqs.forEach((faq, index) => {
+    if (faq.keywords.some((word) => word.trim() !== "" && haystack.includes(word.toLowerCase()))) found.add(index)
+  })
+  return found
+}
+
+const STANDARD = "ease-[cubic-bezier(0.2,0,0,1)]"
+
+function NudgeChip({ children }: { children: React.ReactNode }) {
+  const ref = React.useRef<HTMLSpanElement>(null)
+  React.useEffect(() => {
+    const node = ref.current
+    if (!node || prefersReducedMotion() || typeof node.animate !== "function") return
+    node.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 260, easing: "cubic-bezier(0.2, 0, 0, 1)" })
+  }, [])
+  return (
+    <span ref={ref} className="shrink-0">
+      <Badge variant="soft" tone="primary" size="sm">
+        {children}
+      </Badge>
+    </span>
+  )
+}
+
+function FaqRow({ faq, nudged, nudge, last }: { faq: ContactUsFaq; nudged: boolean; nudge: string; last: boolean }) {
+  const [open, setOpen] = React.useState(false)
+  const id = React.useId()
+  return (
+    <div className={cn(!last && "border-b border-border")}>
+      <h3 className="m-0">
+        <button
+          type="button"
+          id={`${id}-q`}
+          aria-expanded={open}
+          aria-controls={`${id}-a`}
+          onClick={() => setOpen((value) => !value)}
+          className={cn(
+            "flex w-full cursor-pointer items-center gap-3 px-5 py-4 text-start text-sm font-medium text-foreground outline-none rtl:leading-6 focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-ring/50",
+            "motion-safe:transition-colors motion-safe:duration-[260ms]",
+            STANDARD,
+            nudged ? "bg-muted" : "bg-transparent"
+          )}
+        >
+          <span className="min-w-0 flex-1">{faq.question}</span>
+          {nudged ? <NudgeChip>{nudge}</NudgeChip> : null}
+          <ChevronDown
+            aria-hidden
+            size={16}
+            strokeWidth={1.5}
+            className={cn("shrink-0 text-muted-foreground motion-safe:transition-transform motion-safe:duration-[260ms]", STANDARD, open && "rotate-180")}
+          />
+        </button>
+      </h3>
+      <div
+        id={`${id}-a`}
+        role="region"
+        aria-labelledby={`${id}-q`}
+        className={cn(
+          "grid motion-safe:transition-[grid-template-rows,visibility] motion-safe:duration-[260ms]",
+          STANDARD,
+          open ? "visible grid-rows-[1fr]" : "invisible grid-rows-[0fr]"
+        )}
+      >
+        <div className="overflow-hidden">
+          <p className="px-5 pb-4 text-sm text-muted-foreground rtl:leading-6">{faq.answer}</p>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export function ContactUsFormWithFaq({ locale = "en", ...given }: ContactUsFormWithFaqProps) {
+  const { copy, rest } = splitCopy(COPY[locale], given)
+  const { onSubmit, disabled, helpHref = "/help", className, ...html } = rest
+  const headingId = React.useId()
+  const reveal = useReveal<HTMLDivElement>()
+
+  const f = {
+    name: { name: "name", kind: "text", label: copy.name, placeholder: copy.namePlaceholder, autoComplete: "name" },
+    email: { name: "email", kind: "email", label: copy.email, placeholder: copy.emailPlaceholder, autoComplete: "email", required: true },
+    topic: { name: "topic", kind: "select", label: copy.topic, placeholder: copy.topicPlaceholder, options: copy.topics },
+    message: { name: "message", kind: "textarea", label: copy.message, placeholder: copy.messagePlaceholder, groupClassName: CONTACT_US_TEXTAREA_88 },
+    copy: { name: "copy", kind: "checkbox", label: copy.copyMe, size: "sm" },
+  } satisfies Record<string, ContactUsFieldDef>
+  const form = useContactUsForm({ fields: Object.values(f), messages: copy, onSubmit, disabled })
+
+  // The smart nudge: what is typed and what is picked, against each FAQ's keywords.
+  const topicValue = typeof form.values.topic === "string" ? form.values.topic : ""
+  const topicLabel = copy.topics.find((option) => option.value === topicValue)?.label ?? ""
+  const typed = typeof form.values.message === "string" ? form.values.message : ""
+  const nudged = React.useMemo(() => matchContactUsFaqs(copy.faqs, typed, topicLabel, topicValue), [copy.faqs, typed, topicLabel, topicValue])
+
+  return (
+    <ContactUsSection labelledBy={headingId} gap="none" className={className} {...html}>
+      <div ref={reveal} className="grid grid-cols-1 gap-x-16 gap-y-5 [@container(min-width:64rem)]:grid-cols-[minmax(0,1fr)_27.5rem]">
+        <ContactUsHeader
+          headingId={headingId}
+          eyebrow={copy.eyebrow}
+          heading={copy.heading}
+          description={copy.description}
+          data-reveal="rise"
+          className="order-1 mb-1 min-w-0 gap-6"
+          eyebrowClassName="text-sm font-semibold text-foreground rtl:leading-6"
+          headingClassName="text-2xl leading-8 rtl:leading-10 [@container(min-width:40rem)]:text-3xl [@container(min-width:40rem)]:leading-[2.75rem] [@container(min-width:40rem)]:rtl:leading-[3.75rem] [@container(min-width:64rem)]:text-4xl"
+          descriptionClassName="rtl:leading-7"
+        />
+        {/* The form's own box vanishes, so the fields, the actions and the FAQ share one grid. */}
+        <ContactUsForm form={form} className="contents [&>[role=alert]]:order-4 [&>[role=status]]:order-2">
+          <div data-reveal="rise" className="order-2 flex min-w-0 flex-col gap-5">
+            <div className="grid grid-cols-1 gap-4 [@container(min-width:40rem)]:grid-cols-2">
+              <ContactUsField field={f.name} />
+              <ContactUsField field={f.email} />
+            </div>
+            <ContactUsField field={f.topic} />
+            <ContactUsField field={f.message} />
+          </div>
+          <div className="order-4 flex min-w-0 flex-col gap-3 [@container(min-width:40rem)]:flex-row [@container(min-width:40rem)]:items-center [@container(min-width:40rem)]:justify-between">
+            <ContactUsField field={f.copy} />
+            <ContactUsSubmit size="md" className="w-full [@container(min-width:40rem)]:w-auto">
+              {copy.submit}
+              <Send aria-hidden className="rtl:-scale-x-100" />
+            </ContactUsSubmit>
+          </div>
+        </ContactUsForm>
+        <aside
+          data-reveal="slide"
+          data-reveal-from="end"
+          aria-label={copy.sidebarLabel}
+          className={cn(
+            "order-3 flex min-w-0 flex-col gap-5 rounded-[10px] bg-muted p-6",
+            "[@container(min-width:40rem)]:order-5 [@container(min-width:40rem)]:mt-11",
+            "[@container(min-width:64rem)]:sticky [@container(min-width:64rem)]:top-24 [@container(min-width:64rem)]:col-start-2 [@container(min-width:64rem)]:row-span-3 [@container(min-width:64rem)]:row-start-1 [@container(min-width:64rem)]:mt-0 [@container(min-width:64rem)]:self-start"
+          )}
+        >
+          <p className="text-xs font-semibold text-muted-foreground rtl:leading-5">{copy.sidebarLabel}</p>
+          <div className="overflow-hidden rounded-lg border border-border bg-card">
+            {copy.faqs.map((faq, index) => (
+              <FaqRow key={faq.question} faq={faq} nudged={nudged.has(index)} nudge={copy.nudge} last={index === copy.faqs.length - 1} />
+            ))}
+          </div>
+          <a
+            href={helpHref}
+            className="flex items-center gap-2 rounded-sm text-sm font-medium text-foreground outline-none rtl:leading-6 hover:underline focus-visible:ring-[3px] focus-visible:ring-ring/50"
+          >
+            <LifeBuoy aria-hidden size={16} strokeWidth={1.5} className="shrink-0 text-muted-foreground" />
+            {copy.helpLabel}
+          </a>
+        </aside>
+      </div>
+    </ContactUsSection>
+  )
+}
+
+/**
+ * The default copy, English and Arabic, as `locale` picks it. Spread it to
+ * change a few strings and keep the rest.
+ */
+export const contactUsFormWithFaqCopy = COPY

package/registry/blocks/contact-us-form-with-faq/index.ts

@@ -0,0 +1,7 @@
+export {
+  ContactUsFormWithFaq,
+  contactUsFormWithFaqCopy,
+  matchContactUsFaqs,
+  type ContactUsFaq,
+  type ContactUsFormWithFaqProps,
+} from "./ContactUsFormWithFaq"

package/registry/blocks/contact-us-form-with-faq.test.tsx

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from "vitest"
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { ContactUsFormWithFaq, contactUsFormWithFaqCopy, matchContactUsFaqs } from "./contact-us-form-with-faq"
+
+// jsdom has no layout: Figma's sizes and the container-query layouts were
+// measured in a browser. These assert the contract around them.
+
+const strings = (value: unknown): string[] =>
+  typeof value === "string" ? [value] : value && typeof value === "object" ? Object.values(value).flatMap(strings) : []
+const submit = (container: HTMLElement) => fireEvent.submit(container.querySelector("form")!)
+const rowButtons = () => screen.getAllByRole("button", { expanded: false }).filter((b) => b.closest("h3"))
+
+describe("Form with FAQ", () => {
+  it.each(["en", "ar"] as const)("is a labelled section with an h2 and a form, in %s", (locale) => {
+    const { container } = render(<ContactUsFormWithFaq locale={locale} />)
+    const section = container.querySelector("section")!
+    const label = document.getElementById(section.getAttribute("aria-labelledby")!)
+    expect(label?.tagName).toBe("H2")
+    expect(label?.textContent).toBe(contactUsFormWithFaqCopy[locale].heading)
+    expect(container.querySelector("form")).toBeTruthy()
+  })
+
+  it("has Arabic copy for every English key, five questions each with an answer and keywords", () => {
+    const { en, ar } = contactUsFormWithFaqCopy
+    expect(Object.keys(ar).sort()).toEqual(Object.keys(en).sort())
+    for (const copy of [en, ar]) {
+      expect(copy.faqs).toHaveLength(5)
+      for (const faq of copy.faqs) {
+        expect(faq.answer.length).toBeGreaterThan(20)
+        expect(faq.keywords.length).toBeGreaterThan(0)
+      }
+    }
+    expect(ar.topics.map((t) => t.value)).toEqual(en.topics.map((t) => t.value))
+  })
+
+  it("writes Arabic without a middle dot, a dash outside digits, an Arabic-Indic digit or a percent sign", () => {
+    const arabic = strings(contactUsFormWithFaqCopy.ar).join("\n")
+    expect(arabic).not.toMatch(/[·—]|(?<!\d\s)–|–(?!\s\d)/)
+    expect(arabic).not.toMatch(/[٠-٩%٪]/)
+  })
+
+  it("asks only for the email, and sends nothing while it is empty", () => {
+    const onSubmit = vi.fn()
+    const { container } = render(<ContactUsFormWithFaq onSubmit={onSubmit} />)
+    submit(container)
+    expect(onSubmit).not.toHaveBeenCalled()
+    expect(container.querySelectorAll("[data-contact-field][data-invalid]")).toHaveLength(1)
+    expect(screen.getByPlaceholderText("sara@company.com").getAttribute("aria-invalid")).toBe("true")
+    for (const optional of ["Sara Al Mansouri", "What can we help with?"]) expect(screen.getByPlaceholderText(optional).getAttribute("aria-required")).toBeNull()
+  })
+
+  it.each([["en", "Required"], ["ar", "مطلوب"]] as const)("shows the word %s once, in the atom's Top Right label slot, and no asterisk", (locale, word) => {
+    const { container } = render(<ContactUsFormWithFaq locale={locale} />)
+    const words = screen.getAllByText(word)
+    expect(words).toHaveLength(1)
+    expect(words[0]!.getAttribute("data-slot")).toMatch(/label-end$/)
+    expect(container.textContent).not.toContain("*")
+  })
+
+  it("holds the message group to 88px", () => {
+    render(<ContactUsFormWithFaq />)
+    expect(screen.getByPlaceholderText("What can we help with?").closest("[data-slot=textarea-field]")?.className).toContain("min-h-[88px]")
+  })
+
+  it("sends every field by name, then thanks the reader", async () => {
+    const onSubmit = vi.fn().mockResolvedValue(undefined)
+    const { container } = render(<ContactUsFormWithFaq onSubmit={onSubmit} />)
+    fireEvent.change(screen.getByPlaceholderText("Sara Al Mansouri"), { target: { value: "Sara" } })
+    fireEvent.change(screen.getByPlaceholderText("sara@company.com"), { target: { value: "sara@company.com" } })
+    fireEvent.change(screen.getByPlaceholderText("What can we help with?"), { target: { value: "  Hello  " } })
+    fireEvent.click(screen.getByLabelText("Send me a copy of this message."))
+    submit(container)
+    await waitFor(() => expect(screen.getByRole("status")).toBeTruthy())
+    expect(onSubmit.mock.calls[0]![0]).toEqual({ name: "Sara", email: "sara@company.com", topic: "", message: "Hello", copy: true })
+  })
+
+  it("shows the send error in Arabic too, when onSubmit rejects", async () => {
+    const onSubmit = vi.fn().mockRejectedValue(new Error("no"))
+    const { container } = render(<ContactUsFormWithFaq locale="ar" onSubmit={onSubmit} />)
+    fireEvent.change(screen.getByPlaceholderText("sara@company.com"), { target: { value: "sara@company.com" } })
+    submit(container)
+    await waitFor(() => expect(screen.getByRole("alert").textContent).toBe(contactUsFormWithFaqCopy.ar.error))
+  })
+
+  it("makes each FAQ row a disclosure: a button with aria-expanded that opens its answer region", async () => {
+    const user = userEvent.setup()
+    render(<ContactUsFormWithFaq />)
+    expect(rowButtons()).toHaveLength(5)
+    const first = screen.getByRole("button", { name: /How long does a reply take/ })
+    expect(first.getAttribute("aria-expanded")).toBe("false")
+    const panel = document.getElementById(first.getAttribute("aria-controls")!)!
+    expect(panel.getAttribute("role")).toBe("region")
+    expect(panel.getAttribute("aria-labelledby")).toBe(first.id)
+    expect(panel.className).toContain("grid-rows-[0fr]")
+    expect(panel.className).toContain("duration-[260ms]")
+    await user.click(first)
+    expect(first.getAttribute("aria-expanded")).toBe("true")
+    expect(panel.className).toContain("grid-rows-[1fr]")
+    expect(first.querySelector("svg")!.getAttribute("class")).toContain("rotate-180")
+    await user.click(first)
+    expect(first.getAttribute("aria-expanded")).toBe("false")
+  })
+
+  it("is sticky with CSS only on Desktop, in one FAQ element placed by grid order", () => {
+    const { container } = render(<ContactUsFormWithFaq />)
+    const aside = container.querySelector("aside")!
+    expect(container.querySelectorAll("aside")).toHaveLength(1)
+    expect(aside.className).toContain("[@container(min-width:64rem)]:sticky")
+    expect(aside.className).toContain("[@container(min-width:64rem)]:top-24")
+    // Mobile: above the send button (order 3 before 4). Tablet: below the form (order 5).
+    expect(aside.className).toContain("order-3")
+    expect(aside.className).toContain("[@container(min-width:40rem)]:order-5")
+    expect(container.querySelector("form")!.className).toContain("contents")
+    expect(container.querySelector("button[type=submit]")!.closest(".order-4")).toBeTruthy()
+  })
+
+  it("points the help link where helpHref says", () => {
+    render(<ContactUsFormWithFaq helpHref="/support" />)
+    expect(screen.getByRole("link", { name: /Still stuck/ }).getAttribute("href")).toBe("/support")
+  })
+
+  it("nudges the rows the message matches, with a chip, and never blocks sending", async () => {
+    const onSubmit = vi.fn().mockResolvedValue(undefined)
+    const { container } = render(<ContactUsFormWithFaq onSubmit={onSubmit} />)
+    expect(screen.queryByText("Might this help?")).toBeNull()
+    fireEvent.change(screen.getByPlaceholderText("What can we help with?"), { target: { value: "I need an invoice for last month" } })
+    const chips = screen.getAllByText("Might this help?")
+    expect(chips).toHaveLength(1)
+    const row = chips[0]!.closest("button")!
+    expect(row.textContent).toContain("invoice in AED")
+    expect(row.className).toContain("bg-muted")
+    expect(row.className).toContain("duration-[260ms]")
+    fireEvent.change(screen.getByPlaceholderText("What can we help with?"), { target: { value: "" } })
+    expect(screen.queryByText("Might this help?")).toBeNull()
+    // Sending still works while a row is nudged.
+    fireEvent.change(screen.getByPlaceholderText("What can we help with?"), { target: { value: "invoice" } })
+    fireEvent.change(screen.getByPlaceholderText("sara@company.com"), { target: { value: "sara@company.com" } })
+    submit(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+  })
+
+  it("nudges from the topic too, and in Arabic from Arabic words", async () => {
+    const user = userEvent.setup()
+    const { unmount } = render(<ContactUsFormWithFaq />)
+    await user.click(screen.getByRole("combobox"))
+    await user.click(await screen.findByRole("option", { name: "Report a bug" }))
+    expect(within(screen.getAllByText("Might this help?")[0]!.closest("button")!).getByText(/report a bug/i)).toBeTruthy()
+    unmount()
+    render(<ContactUsFormWithFaq locale="ar" />)
+    fireEvent.change(screen.getByPlaceholderText("بماذا يمكننا مساعدتك؟"), { target: { value: "أريد فاتورة" } })
+    expect(screen.getAllByText("هل يفيدك هذا؟")).toHaveLength(1)
+  })
+
+  it("matches keywords case-insensitively and ignores very short input", () => {
+    const { faqs } = contactUsFormWithFaqCopy.en
+    expect([...matchContactUsFaqs(faqs, "BUG")]).toEqual([3])
+    expect(matchContactUsFaqs(faqs, "a").size).toBe(0)
+    expect(matchContactUsFaqs(faqs, "hello there").size).toBe(0)
+  })
+})