@a4ui/core 0.37.1 → 0.38.0

package/src/ui/ChatMarker.tsx

@@ -0,0 +1,58 @@
+// ChatMarker — an inline system note inside a conversation ("Nova joined",
+// "Yesterday", "Conversation archived").
+import { Show, type JSX, type ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export type ChatMarkerVariant = 'default' | 'border' | 'separator'
+
+interface ChatMarkerProps extends ParentProps {
+  /** `default`: muted text. `border`: bordered pill. `separator`: text between two lines. @default 'default' */
+  variant?: ChatMarkerVariant
+  /** Optional leading icon; decorative (`aria-hidden`). */
+  icon?: JSX.Element
+  class?: string
+}
+
+export type { ChatMarkerProps }
+
+/**
+ * Inline system note in a thread, e.g. a date divider or a status change.
+ *
+ * @example
+ * ```tsx
+ * <ChatMarker variant="separator">Yesterday</ChatMarker>
+ * <ChatMarker variant="border" icon={<UserPlus />}>Nova joined</ChatMarker>
+ * ```
+ */
+export function ChatMarker(props: ChatMarkerProps): JSX.Element {
+  const variant = (): ChatMarkerVariant => props.variant ?? 'default'
+  const label = (): JSX.Element => (
+    <span
+      class={cn(
+        'inline-flex items-center gap-1.5 text-xs text-muted-foreground [&>span>svg]:h-3.5 [&>span>svg]:w-3.5',
+        variant() === 'border' && 'rounded-full border border-border bg-muted/40 px-3 py-1',
+      )}
+    >
+      <Show when={props.icon}>
+        <span aria-hidden="true" class="inline-flex">
+          {props.icon}
+        </span>
+      </Show>
+      {props.children}
+    </span>
+  )
+  return (
+    <div
+      data-slot="chat-marker"
+      data-variant={variant()}
+      class={cn('flex w-full items-center justify-center gap-3 py-1', props.class)}
+    >
+      <Show when={variant() === 'separator'} fallback={label()}>
+        <span aria-hidden="true" class="h-px flex-1 bg-border" />
+        {label()}
+        <span aria-hidden="true" class="h-px flex-1 bg-border" />
+      </Show>
+    </div>
+  )
+}

package/src/ui/ChatThread.tsx

@@ -1,59 +1,151 @@
 // ChatThread — layout shell for AI/conversation UIs: a centered, scrollable
-// reading column that stacks chat messages. Purely a container: it has no
-// idea what a "message" looks like, so any element can be stacked inside it.
-import { createEffect, onMount, type JSX } from 'solid-js'
+// reading column that stacks chat messages. It has no idea what a "message"
+// looks like, but it owns the scroll behaviour of a conversation: it follows
+// new output only while the reader is at the bottom, keeps the view steady when
+// older messages are prepended, and offers a "Jump to latest" button.
+import { ArrowDown } from 'lucide-solid'
+import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
 import { motionReduced } from '../lib/motion'
 
+/** Imperative handle handed out through {@link ChatThreadProps.apiRef}. */
+export interface ChatThreadApi {
+  /** Scroll the element carrying `data-message-id={id}` to the top of the view. Throws if there is none. */
+  scrollToMessage: (id: string, options?: { behavior?: ScrollBehavior }) => void
+  /** Scroll to the newest content and re-pin the thread to the bottom. */
+  scrollToEnd: (options?: { behavior?: ScrollBehavior }) => void
+}
+
 export interface ChatThreadProps {
   children: JSX.Element
   /** Max width of the reading column, in px. Defaults to `768`. */
   maxWidth?: number
-  /** Auto-scroll to the newest message on mount and whenever children change. Defaults to `true`. */
+  /**
+   * Follow new content (appended messages and streamed text) to the bottom,
+   * but only while the reader is already at the bottom. Defaults to `true`.
+   */
   stickToBottom?: boolean
+  /** Receives the imperative API once on mount. */
+  apiRef?: (api: ChatThreadApi) => void
+  /** Label of the button shown when new content arrives off-screen. Defaults to `'Jump to latest'`. */
+  jumpLabel?: string
   class?: string
 }
 
+/** Within this many px of the end counts as "at the bottom". */
+const PIN_THRESHOLD = 24
+
 /**
- * Scrollable, centered reading column that stacks chat messages. Layout-only:
- * it renders whatever is passed as `children`, so pair it with your own
- * message bubbles/components.
+ * Scrollable, centered reading column that stacks chat messages. Give message
+ * elements a `data-message-id` (`<Message id="…">` does) to target them with
+ * `apiRef`'s `scrollToMessage`.
+ *
+ * - Appended or streamed content scrolls into view only while the reader is
+ *   pinned to the bottom; otherwise the view stays put and a **Jump to latest**
+ *   button appears.
+ * - Prepending older messages keeps the visible messages where they were.
  *
  * @example
  * ```tsx
- * <ChatThread maxWidth={640}>
- *   <div>Hi! Ask me anything about your itinerary.</div>
- *   <div>What's the weather like in Rivertown this weekend?</div>
- *   <div>Sunny and mild, 18–22°C, light breeze on Saturday.</div>
+ * let api!: ChatThreadApi
+ * <ChatThread maxWidth={640} apiRef={(a) => (api = a)} class="h-96">
+ *   <Message id="m1" role="user">What changed in v2?</Message>
+ *   <Message id="m2" role="assistant">Three things…</Message>
  * </ChatThread>
+ * // later: api.scrollToMessage('m1')
  * ```
  */
 export function ChatThread(props: ChatThreadProps): JSX.Element {
-  let scrollEl: HTMLDivElement | undefined
+  let scrollEl!: HTMLDivElement
+  const [showJump, setShowJump] = createSignal(false)
+  let pinned = true
+  // Snapshot taken after every change, to detect prepends and measure deltas.
+  let lastScrollHeight = 0
+  let lastFirst: Element | null = null
 
-  const scrollToBottom = () => {
-    if (!scrollEl) return
-    scrollEl.scrollTo({ top: scrollEl.scrollHeight, behavior: motionReduced() ? 'auto' : 'smooth' })
+  const behavior = (b?: ScrollBehavior): ScrollBehavior => b ?? (motionReduced() ? 'auto' : 'smooth')
+  const distanceFromEnd = (): number => scrollEl.scrollHeight - scrollEl.scrollTop - scrollEl.clientHeight
+  const firstMessage = (): Element | null => scrollEl.firstElementChild
+  const snapshot = (): void => {
+    lastScrollHeight = scrollEl.scrollHeight
+    lastFirst = firstMessage()
   }
 
-  onMount(() => {
-    if (props.stickToBottom ?? true) scrollToBottom()
-  })
+  const scrollToEnd = (options?: { behavior?: ScrollBehavior }): void => {
+    pinned = true
+    setShowJump(false)
+    scrollEl.scrollTo({ top: scrollEl.scrollHeight, behavior: behavior(options?.behavior) })
+  }
 
-  createEffect(() => {
-    // Track children so newly appended messages pull the thread down.
-    void props.children
-    if (props.stickToBottom ?? true) queueMicrotask(scrollToBottom)
+  const scrollToMessage = (id: string, options?: { behavior?: ScrollBehavior }): void => {
+    const target = scrollEl.querySelector<HTMLElement>(`[data-message-id="${CSS.escape(id)}"]`)
+    if (!target) throw new Error(`ChatThread.scrollToMessage: no element with data-message-id="${id}"`)
+    const top = target.getBoundingClientRect().top - scrollEl.getBoundingClientRect().top + scrollEl.scrollTop
+    scrollEl.scrollTo({ top: Math.max(0, top - 8), behavior: behavior(options?.behavior) })
+  }
+
+  const onScroll = (): void => {
+    pinned = distanceFromEnd() <= PIN_THRESHOLD
+    if (pinned) setShowJump(false)
+  }
+
+  const onContentChange = (): void => {
+    const first = firstMessage()
+    const prepended = lastFirst !== null && first !== lastFirst && scrollEl.contains(lastFirst)
+    if (prepended) {
+      // Older messages were inserted above: shift by the height they added so
+      // what the reader was looking at does not move.
+      scrollEl.scrollTop += scrollEl.scrollHeight - lastScrollHeight
+    } else if (scrollEl.scrollHeight !== lastScrollHeight) {
+      if (pinned && (props.stickToBottom ?? true)) {
+        scrollEl.scrollTop = scrollEl.scrollHeight
+      } else if (!pinned) {
+        setShowJump(true)
+      }
+    }
+    snapshot()
+  }
+
+  onMount(() => {
+    props.apiRef?.({ scrollToMessage, scrollToEnd })
+    if (props.stickToBottom ?? true) scrollEl.scrollTop = scrollEl.scrollHeight
+    pinned = distanceFromEnd() <= PIN_THRESHOLD
+    snapshot()
+    const observer = new MutationObserver(onContentChange)
+    observer.observe(scrollEl, { childList: true, subtree: true, characterData: true })
+    onCleanup(() => observer.disconnect())
   })
 
   return (
     <div
       ref={scrollEl}
-      class={cn('mx-auto flex w-full flex-col gap-4 overflow-y-auto', props.class)}
+      onScroll={onScroll}
+      tabIndex={0}
+      // Scroll anchoring would double-apply the prepend correction above.
+      class={cn(
+        'mx-auto flex w-full flex-col gap-4 overflow-y-auto outline-none [overflow-anchor:none] focus-visible:ring-2 focus-visible:ring-ring',
+        props.class,
+      )}
       style={{ 'max-width': `${props.maxWidth ?? 768}px` }}
     >
       {props.children}
+      <Show when={showJump()}>
+        {/* Zero-height sticky row so the button floats over the bottom edge without adding scroll height. */}
+        <div
+          data-slot="chat-jump"
+          class="pointer-events-none sticky bottom-3 -mt-4 flex h-0 shrink-0 justify-center"
+        >
+          <button
+            type="button"
+            onClick={() => scrollToEnd()}
+            class="pointer-events-auto absolute bottom-0 inline-flex items-center gap-1.5 rounded-full border border-border bg-card px-3 py-1.5 text-xs font-medium text-card-foreground shadow-lg transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            <ArrowDown class="h-3.5 w-3.5" aria-hidden="true" />
+            {props.jumpLabel ?? 'Jump to latest'}
+          </button>
+        </div>
+      </Show>
     </div>
   )
 }

package/src/ui/ContactSection.tsx

@@ -0,0 +1,199 @@
+// ContactSection — a contact form plus the business's direct contact details.
+// The form posts natively to `action` (a URL or a `mailto:` link); there is no
+// backend in the component.
+import { Mail, MapPin, Phone } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, createUniqueId, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { Card } from './Card'
+import { Input } from './Input'
+import { SectionHeading } from './internal/sectionKit'
+import { Label } from './Label'
+import { Textarea } from './Textarea'
+
+/** A field {@link ContactSection} can render. */
+export type ContactField = 'name' | 'email' | 'phone' | 'subject' | 'message'
+
+/** Submitted values, keyed by field. Only the rendered fields are present. */
+export type ContactValues = Partial<Record<ContactField, string>>
+
+export interface ContactSectionProps {
+  title?: string
+  subtitle?: string
+  /** Fields to render, in order. Defaults to `['name', 'email', 'message']`. */
+  fields?: ContactField[]
+  /** Override field and contact-detail labels, e.g. for another language. */
+  labels?: Partial<Record<ContactField | 'address', string>>
+  /** Submit button text. Defaults to `'Send message'`. */
+  submitLabel?: string
+  /**
+   * Where the form posts (`method="post"`): an endpoint URL, or a `mailto:` link
+   * (sent as plain text). Omit it to handle submission yourself with `onSubmit`.
+   */
+  action?: string
+  /** Called with the values when the form submits and there is no `action`. */
+  onSubmit?: (values: ContactValues) => void
+  /** Email shown (and linked) beside the form. */
+  email?: string
+  /** Phone number shown (and linked) beside the form. */
+  phone?: string
+  /** Postal address shown beside the form. */
+  address?: string
+  /** Anchor id for in-page navigation. */
+  id?: string
+  class?: string
+}
+
+const DEFAULT_FIELDS: ContactField[] = ['name', 'email', 'message']
+const DEFAULT_LABELS: Record<ContactField | 'address', string> = {
+  name: 'Name',
+  email: 'Email',
+  phone: 'Phone',
+  subject: 'Subject',
+  message: 'Message',
+  address: 'Address',
+}
+const INPUT_TYPE: Record<Exclude<ContactField, 'message'>, string> = {
+  name: 'text',
+  email: 'email',
+  phone: 'tel',
+  subject: 'text',
+}
+const AUTOCOMPLETE: Partial<Record<ContactField, string>> = { name: 'name', email: 'email', phone: 'tel' }
+const REQUIRED: ReadonlySet<ContactField> = new Set(['name', 'email', 'message'])
+
+/**
+ * Contact section: a form (any of name, email, phone, subject, message) beside
+ * the business's email, phone and address. With `action` the form posts
+ * natively to that URL or `mailto:` link; without it, `onSubmit` receives the
+ * values. Name, email and message are required.
+ *
+ * @example
+ * ```tsx
+ * <ContactSection
+ *   title="Talk to us"
+ *   fields={['name', 'email', 'subject', 'message']}
+ *   action="https://formspree.io/f/your-id"
+ *   email="hello@example.com"
+ *   phone="+52 55 1234 5678"
+ * />
+ * ```
+ */
+export function ContactSection(props: ContactSectionProps): JSX.Element {
+  const uid = createUniqueId()
+  const fields = () => props.fields ?? DEFAULT_FIELDS
+  const [values, setValues] = createSignal<ContactValues>({})
+  const label = (field: ContactField | 'address') => props.labels?.[field] ?? DEFAULT_LABELS[field]
+  const hasDetails = () => Boolean(props.email || props.phone || props.address)
+  const isMailto = () => props.action?.startsWith('mailto:') === true
+
+  const handleSubmit = (event: SubmitEvent) => {
+    if (props.action !== undefined) return
+    event.preventDefault()
+    const out: ContactValues = {}
+    for (const field of fields()) out[field] = values()[field] ?? ''
+    props.onSubmit?.(out)
+  }
+
+  return (
+    <section
+      id={props.id}
+      class={cn('mx-auto flex w-full max-w-6xl flex-col gap-12 px-5 py-20', props.class)}
+    >
+      <SectionHeading title={props.title} subtitle={props.subtitle} />
+      <div class={cn('grid gap-8', hasDetails() && 'lg:grid-cols-[2fr_1fr]')}>
+        <Card glass class={cn('p-6 sm:p-8', !hasDetails() && 'mx-auto w-full max-w-2xl')}>
+          <form
+            action={props.action}
+            method="post"
+            enctype={isMailto() ? 'text/plain' : undefined}
+            class="grid gap-5 sm:grid-cols-2"
+            onSubmit={handleSubmit}
+          >
+            <For each={fields()}>
+              {(field) => {
+                const id = `${uid}-${field}`
+                const wide = field === 'message' || field === 'subject'
+                const common = {
+                  id,
+                  name: field,
+                  required: REQUIRED.has(field),
+                  onInput: (value: string) => setValues((prev) => ({ ...prev, [field]: value })),
+                }
+                return (
+                  <div class={cn('flex flex-col gap-2', wide && 'sm:col-span-2')}>
+                    <Label for={id} required={REQUIRED.has(field)}>
+                      {label(field)}
+                    </Label>
+                    <Show
+                      when={field !== 'message'}
+                      fallback={<Textarea {...common} rows={5} value={values()[field] ?? ''} />}
+                    >
+                      <Input
+                        {...common}
+                        value={values()[field] ?? ''}
+                        type={INPUT_TYPE[field as Exclude<ContactField, 'message'>]}
+                        autocomplete={AUTOCOMPLETE[field]}
+                      />
+                    </Show>
+                  </div>
+                )
+              }}
+            </For>
+            <div class="sm:col-span-2">
+              <Button type="submit" ripple class="w-full px-5 py-2.5 text-base sm:w-auto">
+                {props.submitLabel ?? 'Send message'}
+              </Button>
+            </div>
+          </form>
+        </Card>
+
+        <Show when={hasDetails()}>
+          <ul class="flex flex-col gap-4">
+            <Show when={props.email}>
+              {(email) => (
+                <Detail icon={<Mail />} label={label('email')}>
+                  <a href={`mailto:${email()}`} class="break-all hover:text-primary">
+                    {email()}
+                  </a>
+                </Detail>
+              )}
+            </Show>
+            <Show when={props.phone}>
+              {(phone) => (
+                <Detail icon={<Phone />} label={label('phone')}>
+                  <a href={`tel:${phone().replace(/[^\d+]/g, '')}`} class="hover:text-primary">
+                    {phone()}
+                  </a>
+                </Detail>
+              )}
+            </Show>
+            <Show when={props.address}>
+              {(address) => (
+                <Detail icon={<MapPin />} label={label('address')}>
+                  <span class="whitespace-pre-line">{address()}</span>
+                </Detail>
+              )}
+            </Show>
+          </ul>
+        </Show>
+      </div>
+    </section>
+  )
+}
+
+function Detail(props: { icon: JSX.Element; label: string; children: JSX.Element }): JSX.Element {
+  return (
+    <li class="card flex items-start gap-4 rounded-xl p-5">
+      <span class="grid h-10 w-10 shrink-0 place-items-center rounded-lg bg-primary/15 text-primary [&_svg]:h-5 [&_svg]:w-5">
+        {props.icon}
+      </span>
+      <div class="min-w-0">
+        <p class="text-xs font-medium uppercase tracking-wide text-muted-foreground">{props.label}</p>
+        <p class="mt-1 text-sm text-foreground">{props.children}</p>
+      </div>
+    </li>
+  )
+}

package/src/ui/CtaBanner.tsx

@@ -0,0 +1,62 @@
+// CtaBanner — a closing call-to-action band: headline, one line of support and
+// one or two buttons on a tinted glass panel.
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { SectionHeading, type SectionLink } from './internal/sectionKit'
+
+export interface CtaBannerProps {
+  title: string
+  subtitle?: string
+  /** Main call-to-action (filled button). */
+  primary: SectionLink
+  /** Secondary call-to-action (outline button). */
+  secondary?: SectionLink
+  /** Anchor id for in-page navigation. */
+  id?: string
+  class?: string
+}
+
+/**
+ * Call-to-action band that closes a page or splits long ones: a headline, an
+ * optional line of support and one or two buttons on a glass panel tinted with
+ * the theme's primary color.
+ *
+ * @example
+ * ```tsx
+ * <CtaBanner
+ *   title="Ready to launch?"
+ *   subtitle="Start free, upgrade when you grow."
+ *   primary={{ label: 'Create account', href: '/signup' }}
+ * />
+ * ```
+ */
+export function CtaBanner(props: CtaBannerProps): JSX.Element {
+  return (
+    <section id={props.id} class={cn('mx-auto w-full max-w-6xl px-5 py-16', props.class)}>
+      <div class="card glow-edge relative isolate overflow-hidden rounded-2xl px-6 py-14 sm:px-12">
+        <div
+          aria-hidden="true"
+          class="absolute inset-0 -z-10 bg-gradient-to-br from-primary/25 via-transparent to-accent/20"
+        />
+        <div class="flex flex-col items-center gap-8 text-center">
+          <SectionHeading title={props.title} subtitle={props.subtitle} />
+          <div class="flex flex-wrap justify-center gap-3">
+            <Button href={props.primary.href} ripple class="px-5 py-2.5 text-base">
+              {props.primary.label}
+            </Button>
+            <Show when={props.secondary}>
+              {(link) => (
+                <Button href={link().href} variant="outline" class="px-5 py-2.5 text-base">
+                  {link().label}
+                </Button>
+              )}
+            </Show>
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/ui/DateField.tsx

@@ -167,8 +167,9 @@ export function DateField(props: DateFieldProps): JSX.Element {
         <Portal>
           <div
             ref={popRef}
+            data-a4-floating
             style={{ position: 'fixed', top: `${pos().top}px`, left: `${pos().left}px` }}
-            class="z-50 w-72 rounded-lg border border-border bg-card p-3 text-card-foreground shadow-lg"
+            class="pointer-events-auto z-50 w-72 rounded-lg border border-border bg-card p-3 text-card-foreground shadow-lg"
           >
             <CalendarCore
               selected={selected() ?? undefined}

package/src/ui/DateRangePicker.tsx

@@ -193,8 +193,9 @@ export function DateRangePicker(props: DateRangePickerProps): JSX.Element {
         <Portal>
           <div
             ref={popRef}
+            data-a4-floating
             style={{ position: 'fixed', top: `${pos().top}px`, left: `${pos().left}px` }}
-            class="z-50 w-72 rounded-lg border border-border bg-card p-3 text-card-foreground shadow-lg"
+            class="pointer-events-auto z-50 w-72 rounded-lg border border-border bg-card p-3 text-card-foreground shadow-lg"
           >
             <CalendarCore
               rangeStart={startDate() ?? undefined}

package/src/ui/Drawer.tsx

@@ -1,4 +1,4 @@
-// Right-anchored slide-over on Kobalte's Dialog primitive (focus trap +
+// Edge-anchored slide-over (right by default; `side` picks left/top/bottom) on Kobalte's Dialog primitive (focus trap +
 // presence for free, like Modal). The drawer-content class drives the
 // slide-in/out keyframes in styles.css off Kobalte's data-expanded/data-closed.
 // Pass a `title` for the sticky glass header, or omit it and render your own
@@ -20,10 +20,39 @@ interface DrawerProps extends ParentProps {
   class?: string
   /** Accessible label for the close button. @default 'Close' */
   closeLabel?: string
+  /** Edge the panel is anchored to and slides in from. @default 'right' */
+  side?: DrawerSide
 }
 
+export type DrawerSide = 'right' | 'left' | 'top' | 'bottom'
+
+const SIDE: Record<DrawerSide, { wrap: string; panel: string; offscreen: string }> = {
+  right: {
+    wrap: 'justify-end',
+    panel: 'h-full w-full max-w-[520px] border-l',
+    offscreen: 'translateX(100%)',
+  },
+  left: {
+    wrap: 'justify-start',
+    panel: 'h-full w-full max-w-[520px] border-r',
+    offscreen: 'translateX(-100%)',
+  },
+  top: {
+    wrap: 'flex-col justify-start',
+    panel: 'max-h-[85vh] w-full rounded-b-2xl border-b',
+    offscreen: 'translateY(-100%)',
+  },
+  bottom: {
+    wrap: 'flex-col justify-end',
+    panel: 'max-h-[85vh] w-full rounded-t-2xl border-t',
+    offscreen: 'translateY(100%)',
+  },
+}
+
+export type { DrawerProps }
+
 /**
- * Right-anchored slide-over panel built on Kobalte's `Dialog` (focus trap, portal,
+ * Edge-anchored slide-over panel (right by default, or `side="left" | "top" | "bottom"`) built on Kobalte's `Dialog` (focus trap, portal,
  * and open/close presence handled for you). Use for create/edit forms or detail
  * panels that need more room than a centered `Modal`.
  *
@@ -36,14 +65,18 @@ interface DrawerProps extends ParentProps {
  * ```
  */
 export function Drawer(props: DrawerProps): JSX.Element {
+  const side = (): (typeof SIDE)[DrawerSide] => SIDE[props.side ?? 'right']
   return (
     <Dialog open={props.open} onOpenChange={props.onOpenChange}>
       <Dialog.Portal>
         <Dialog.Overlay class="modal-overlay fixed inset-0 z-40 bg-black/50 backdrop-blur-[2px]" />
-        <div class="fixed inset-0 z-50 flex justify-end">
+        <div class={cn('fixed inset-0 z-50 flex', side().wrap)}>
           <Dialog.Content
+            data-side={props.side ?? 'right'}
+            style={{ '--drawer-offscreen': side().offscreen }}
             class={cn(
-              'drawer-content flex h-full w-full max-w-[520px] flex-col overflow-y-auto border-l border-border bg-glass shadow-2xl',
+              'drawer-content flex flex-col overflow-y-auto border-border bg-glass shadow-2xl',
+              side().panel,
               props.class,
             )}
           >

package/src/ui/Faq.tsx

@@ -0,0 +1,57 @@
+// Faq — frequently asked questions as an accordion under a heading.
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Accordion } from './Accordion'
+import { SectionHeading } from './internal/sectionKit'
+
+/** One question/answer pair rendered by {@link Faq}. */
+export interface FaqItem {
+  question: string
+  answer: string
+}
+
+export interface FaqProps {
+  title?: string
+  subtitle?: string
+  items: FaqItem[]
+  /** Allow several answers open at once. Defaults to `false`. */
+  multiple?: boolean
+  /** Anchor id for in-page navigation. */
+  id?: string
+  class?: string
+}
+
+/**
+ * Frequently-asked-questions section: an optional heading over an
+ * {@link Accordion} of questions on a glass panel; each answer expands in place.
+ *
+ * @example
+ * ```tsx
+ * <Faq
+ *   title="Questions"
+ *   items={[{ question: 'Can I cancel anytime?', answer: 'Yes, from your account settings.' }]}
+ * />
+ * ```
+ */
+export function Faq(props: FaqProps): JSX.Element {
+  return (
+    <section
+      id={props.id}
+      class={cn('mx-auto flex w-full max-w-3xl flex-col gap-10 px-5 py-20', props.class)}
+    >
+      <SectionHeading title={props.title} subtitle={props.subtitle} />
+      <div class="card rounded-xl px-5 sm:px-6 [&_button]:py-4 [&_button]:text-left [&_button]:text-base">
+        <Accordion
+          multiple={props.multiple}
+          class="[&>*:last-child]:border-b-0"
+          items={props.items.map((item, index) => ({
+            value: `faq-${index}`,
+            title: item.question,
+            content: item.answer,
+          }))}
+        />
+      </div>
+    </section>
+  )
+}