@a4ui/core 0.37.0 → 0.38.0

package/src/ui/DateRangePicker.tsx

@@ -9,6 +9,7 @@ import type { JSX } from 'solid-js'
 import { createEffect, createMemo, createSignal, onCleanup, Show } from 'solid-js'
 import { Portal } from 'solid-js/web'
 
+import { createAnchorReflow } from '../lib/anchored'
 import { cn } from '../lib/cn'
 import { CalendarCore } from './internal/CalendarCore'
 
@@ -116,17 +117,25 @@ export function DateRangePicker(props: DateRangePickerProps): JSX.Element {
 
   // Wire/tear-down the global listeners strictly around the open state. Scroll/
   // resize close the popover (its fixed position would otherwise drift).
+  // Follow the trigger rather than closing. The panel is `fixed` at the
+  // trigger's rect, so a scroll makes that rect stale — it does not make the
+  // panel unwanted. Closing on any captured scroll made this unusable on a
+  // scrolling page: clicking a trigger below the fold scrolls it into view,
+  // and that scroll arrived right after the panel opened and shut it in the
+  // same gesture. See `createAnchorReflow`.
+  const reflow = createAnchorReflow({ anchor: () => btnRef, place, close })
+
   const toggleListeners = (isOpen: boolean) => {
     if (isOpen) {
       document.addEventListener('mousedown', onDocPointer)
       document.addEventListener('keydown', onKey)
-      window.addEventListener('scroll', close, true)
-      window.addEventListener('resize', close)
+      window.addEventListener('scroll', reflow, true)
+      window.addEventListener('resize', reflow)
     } else {
       document.removeEventListener('mousedown', onDocPointer)
       document.removeEventListener('keydown', onKey)
-      window.removeEventListener('scroll', close, true)
-      window.removeEventListener('resize', close)
+      window.removeEventListener('scroll', reflow, true)
+      window.removeEventListener('resize', reflow)
     }
   }
   // Reactively attach when open flips; always clean up on unmount.
@@ -184,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>
+  )
+}

package/src/ui/FeatureGrid.tsx

@@ -0,0 +1,77 @@
+// FeatureGrid — a heading plus a responsive grid of feature cards (icon, title,
+// short text).
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Card } from './Card'
+import { SectionHeading } from './internal/sectionKit'
+
+/** One feature rendered by {@link FeatureGrid}. */
+export interface FeatureItem {
+  title: string
+  text: string
+  /** Optional icon node, shown in a tinted tile above the title. */
+  icon?: JSX.Element
+}
+
+export interface FeatureGridProps {
+  title?: string
+  subtitle?: string
+  items: FeatureItem[]
+  /** Columns on wide screens (one column on phones). Defaults to `3`. */
+  columns?: 2 | 3 | 4
+  /** Anchor id for in-page navigation. */
+  id?: string
+  class?: string
+}
+
+const COLS: Record<2 | 3 | 4, string> = {
+  2: 'sm:grid-cols-2',
+  3: 'sm:grid-cols-2 lg:grid-cols-3',
+  4: 'sm:grid-cols-2 lg:grid-cols-4',
+}
+
+/**
+ * Section listing a product's features: an optional heading and a responsive
+ * grid of glass cards, each with an optional icon, a title and a short text.
+ *
+ * @example
+ * ```tsx
+ * <FeatureGrid
+ *   title="Why teams switch"
+ *   items={[
+ *     { title: 'Fast', text: 'Pages load in under a second.' },
+ *     { title: 'Accessible', text: 'Keyboard and screen-reader friendly.' },
+ *     { title: 'Themeable', text: 'Swap palettes without touching CSS.' },
+ *   ]}
+ * />
+ * ```
+ */
+export function FeatureGrid(props: FeatureGridProps): JSX.Element {
+  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} />
+      <ul class={cn('grid gap-6', COLS[props.columns ?? 3])}>
+        <For each={props.items}>
+          {(item) => (
+            <li class="flex">
+              <Card glass class="flex w-full flex-col gap-3 p-6">
+                <Show when={item.icon}>
+                  <div class="grid h-11 w-11 place-items-center rounded-lg bg-primary/15 text-primary [&_svg]:h-5 [&_svg]:w-5">
+                    {item.icon}
+                  </div>
+                </Show>
+                <h3 class="text-lg font-semibold text-foreground">{item.title}</h3>
+                <p class="text-sm leading-relaxed text-muted-foreground">{item.text}</p>
+              </Card>
+            </li>
+          )}
+        </For>
+      </ul>
+    </section>
+  )
+}

package/src/ui/Field.tsx

@@ -0,0 +1,374 @@
+// Field — composable form-field layout: FieldSet/FieldLegend/FieldGroup for
+// structure, Field for one labelled control. A per-field context hands out one
+// control id and collects description/error ids, so the label's `for`, the
+// control's `aria-describedby`, `aria-errormessage` and `aria-invalid` are
+// wired automatically. The control is discovered in the DOM after mount (first
+// input/textarea/select/combobox/switch inside the field), so plain, Kobalte
+// and InputGroup controls all work with no render-prop.
+//
+// Layout note: Tailwind 3.4 (the preset's version) has no built-in `@container`
+// variants, so `orientation="responsive"` and FieldGroup use viewport
+// breakpoints (`sm:`), not container queries.
+import type { JSX, ParentProps } from 'solid-js'
+import {
+  createContext,
+  createEffect,
+  createSignal,
+  createUniqueId,
+  For,
+  onCleanup,
+  onMount,
+  Show,
+  splitProps,
+  useContext,
+} from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** Layout direction of a {@link Field}. */
+export type FieldOrientation = 'vertical' | 'horizontal' | 'responsive'
+
+interface FieldContextValue {
+  /** Id of the control (adopted from the control if it already has one). */
+  controlId: () => string
+  registerDescription: (id: string) => () => void
+  registerError: (id: string) => () => void
+}
+
+const FieldContext = createContext<FieldContextValue>()
+
+const CONTROL_SELECTOR =
+  '[data-field-control], input:not([type="hidden"]), textarea, select, [role="combobox"], [role="switch"], [role="checkbox"]'
+
+// Add an id to a signal-held list; returns the remover.
+function register(setter: (fn: (prev: string[]) => string[]) => void, id: string): () => void {
+  setter((prev) => [...prev, id])
+  return () => setter((prev) => prev.filter((x) => x !== id))
+}
+
+const ORIENTATION_CLASSES: Record<FieldOrientation, string> = {
+  vertical: 'flex-col',
+  horizontal: 'flex-row items-center justify-between gap-3',
+  responsive: 'flex-col sm:flex-row sm:items-center sm:justify-between sm:gap-3',
+}
+
+export interface FieldSetProps extends ParentProps, JSX.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  class?: string
+}
+
+/**
+ * Semantic `<fieldset>` that groups related fields. Pair with {@link FieldLegend}.
+ *
+ * @example
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Profile</FieldLegend>
+ *   <FieldGroup>...</FieldGroup>
+ * </FieldSet>
+ * ```
+ */
+export function FieldSet(props: FieldSetProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <fieldset class={cn('m-0 flex min-w-0 flex-col gap-4 border-0 p-0', local.class)} {...rest}>
+      {local.children}
+    </fieldset>
+  )
+}
+
+export interface FieldLegendProps extends ParentProps, JSX.HTMLAttributes<HTMLLegendElement> {
+  /** `legend` is a section heading; `label` is the smaller label size. Defaults to `legend`. */
+  variant?: 'legend' | 'label'
+  class?: string
+}
+
+/**
+ * Caption of a {@link FieldSet}.
+ *
+ * @example
+ * ```tsx
+ * <FieldLegend variant="label">Notifications</FieldLegend>
+ * ```
+ */
+export function FieldLegend(props: FieldLegendProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'variant', 'children'])
+  return (
+    <legend
+      data-variant={local.variant ?? 'legend'}
+      class={cn(
+        'mb-1 font-semibold text-foreground',
+        local.variant === 'label' ? 'text-sm' : 'text-base',
+        local.class,
+      )}
+      {...rest}
+    >
+      {local.children}
+    </legend>
+  )
+}
+
+export interface FieldGroupProps extends ParentProps, JSX.HTMLAttributes<HTMLDivElement> {
+  class?: string
+}
+
+/**
+ * Vertical stack of {@link Field}s with consistent spacing.
+ *
+ * @example
+ * ```tsx
+ * <FieldGroup><Field>...</Field><Field>...</Field></FieldGroup>
+ * ```
+ */
+export function FieldGroup(props: FieldGroupProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <div data-slot="field-group" class={cn('flex w-full flex-col gap-5', local.class)} {...rest}>
+      {local.children}
+    </div>
+  )
+}
+
+export interface FieldProps extends ParentProps, JSX.HTMLAttributes<HTMLDivElement> {
+  /** `vertical` (default), `horizontal`, or `responsive` (stacked below `sm`, a row above). */
+  orientation?: FieldOrientation
+  /** Marks the field invalid: sets `data-invalid` and `aria-invalid` on the control. */
+  invalid?: boolean
+  class?: string
+}
+
+/**
+ * One labelled form field. Provides the id context used by {@link FieldLabel},
+ * {@link FieldDescription} and {@link FieldError}, and wires the control inside
+ * it (`id`, `aria-describedby`, `aria-errormessage`, `aria-invalid`).
+ *
+ * @example
+ * ```tsx
+ * <Field invalid={!!error()}>
+ *   <FieldLabel>Email</FieldLabel>
+ *   <Input value={email()} onInput={setEmail} />
+ *   <FieldDescription>We never share it.</FieldDescription>
+ *   <FieldError>{error()}</FieldError>
+ * </Field>
+ * ```
+ */
+export function Field(props: FieldProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'orientation', 'invalid', 'children'])
+  const uid = createUniqueId()
+  const [controlId, setControlId] = createSignal(`${uid}-control`)
+  const [descIds, setDescIds] = createSignal<string[]>([])
+  const [errIds, setErrIds] = createSignal<string[]>([])
+  let root!: HTMLDivElement
+
+  const ctx: FieldContextValue = {
+    controlId,
+    registerDescription: (id) => register(setDescIds, id),
+    registerError: (id) => register(setErrIds, id),
+  }
+
+  // The control is found in the DOM (any input-like element), so it may appear
+  // after mount (e.g. inside a <Show>). A MutationObserver re-runs the wiring.
+  const [control, setControl] = createSignal<HTMLElement | null>(null)
+  const findControl = (): HTMLElement | null => root.querySelector<HTMLElement>(CONTROL_SELECTOR)
+  const syncControl = (): void => {
+    const el = findControl()
+    if (el && !el.id) el.id = controlId()
+    if (el) setControlId(el.id)
+    setControl(el)
+  }
+
+  onMount(() => {
+    syncControl()
+    const observer = new MutationObserver(syncControl)
+    observer.observe(root, { childList: true, subtree: true })
+    onCleanup(() => observer.disconnect())
+  })
+
+  // Re-apply ARIA wiring whenever the control, descriptions, errors or invalid change.
+  createEffect(() => {
+    const desc = descIds()
+    const err = errIds()
+    const invalid = !!local.invalid
+    const el = control()
+    if (!el) return
+    const ids = [...desc, ...err]
+    if (ids.length) el.setAttribute('aria-describedby', ids.join(' '))
+    else el.removeAttribute('aria-describedby')
+    if (invalid) el.setAttribute('aria-invalid', 'true')
+    else el.removeAttribute('aria-invalid')
+    if (invalid && err.length) el.setAttribute('aria-errormessage', err.join(' '))
+    else el.removeAttribute('aria-errormessage')
+  })
+
+  return (
+    <FieldContext.Provider value={ctx}>
+      <div
+        ref={root}
+        role="group"
+        data-slot="field"
+        data-orientation={local.orientation ?? 'vertical'}
+        data-invalid={local.invalid ? '' : undefined}
+        class={cn(
+          'group/field flex w-full gap-2',
+          ORIENTATION_CLASSES[local.orientation ?? 'vertical'],
+          local.class,
+        )}
+        {...rest}
+      >
+        {local.children}
+      </div>
+    </FieldContext.Provider>
+  )
+}
+
+/**
+ * Wrapper for a title + description block next to a control, e.g. the text half
+ * of a horizontal switch row.
+ *
+ * @example
+ * ```tsx
+ * <FieldContent><FieldTitle>Alerts</FieldTitle><FieldDescription>Email me.</FieldDescription></FieldContent>
+ * ```
+ */
+export function FieldContent(props: ParentProps<{ class?: string }>): JSX.Element {
+  return <div class={cn('flex flex-1 flex-col gap-1', props.class)}>{props.children}</div>
+}
+
+export interface FieldLabelProps extends ParentProps, JSX.LabelHTMLAttributes<HTMLLabelElement> {
+  class?: string
+}
+
+/**
+ * `<label>` bound to the enclosing {@link Field}'s control through `for`.
+ *
+ * @example
+ * ```tsx
+ * <FieldLabel>Full name</FieldLabel>
+ * ```
+ */
+export function FieldLabel(props: FieldLabelProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children', 'for'])
+  const ctx = useContext(FieldContext)
+  return (
+    <label
+      for={local.for ?? ctx?.controlId()}
+      class={cn(
+        'text-sm font-medium leading-none text-foreground group-data-[invalid]/field:text-destructive',
+        local.class,
+      )}
+      {...rest}
+    >
+      {local.children}
+    </label>
+  )
+}
+
+/**
+ * Non-label title text for a field (use where a `<label>` would be wrong).
+ *
+ * @example
+ * ```tsx
+ * <FieldTitle>Two-factor authentication</FieldTitle>
+ * ```
+ */
+export function FieldTitle(props: ParentProps<{ class?: string }>): JSX.Element {
+  return (
+    <div class={cn('text-sm font-medium leading-none text-foreground', props.class)}>{props.children}</div>
+  )
+}
+
+/**
+ * Helper text, linked to the control through `aria-describedby`.
+ *
+ * @example
+ * ```tsx
+ * <FieldDescription>Use 8 or more characters.</FieldDescription>
+ * ```
+ */
+export function FieldDescription(props: ParentProps<{ class?: string; id?: string }>): JSX.Element {
+  const ctx = useContext(FieldContext)
+  // eslint-disable-next-line solid/reactivity -- id is stable for the element's lifetime
+  const id = props.id ?? createUniqueId()
+  if (ctx) onCleanup(ctx.registerDescription(id))
+  return (
+    <p id={id} class={cn('text-xs text-muted-foreground', props.class)}>
+      {props.children}
+    </p>
+  )
+}
+
+export interface FieldSeparatorProps {
+  /** Optional text shown in the middle of the rule. */
+  children?: JSX.Element
+  class?: string
+}
+
+/**
+ * Horizontal rule between fields, optionally with text in the middle.
+ *
+ * @example
+ * ```tsx
+ * <FieldSeparator>or continue with</FieldSeparator>
+ * ```
+ */
+export function FieldSeparator(props: FieldSeparatorProps): JSX.Element {
+  return (
+    <div
+      role="separator"
+      data-slot="field-separator"
+      class={cn('relative flex items-center gap-3 text-xs text-muted-foreground', props.class)}
+    >
+      <span class="h-px flex-1 bg-border" />
+      <Show when={props.children}>
+        <span>{props.children}</span>
+        <span class="h-px flex-1 bg-border" />
+      </Show>
+    </div>
+  )
+}
+
+export interface FieldErrorProps {
+  /** Error messages; entries may be strings or `{ message }` objects (e.g. schema issues). */
+  errors?: Array<string | { message?: string } | undefined>
+  /** Custom content, used when `errors` is not given. */
+  children?: JSX.Element
+  class?: string
+}
+
+/**
+ * Validation message(s) for a field. Renders nothing when empty, a single line
+ * for one message and a list for several. `role="alert"` is set only while
+ * something is shown, so assistive tech announces it when it appears.
+ *
+ * @example
+ * ```tsx
+ * <FieldError errors={['Too short', 'Needs a number']} />
+ * ```
+ */
+export function FieldError(props: FieldErrorProps): JSX.Element {
+  const ctx = useContext(FieldContext)
+  const id = createUniqueId()
+  const messages = (): string[] => {
+    const out: string[] = []
+    for (const e of props.errors ?? []) {
+      const m = typeof e === 'string' ? e : e?.message
+      if (m) out.push(m)
+    }
+    return out
+  }
+  const visible = (): boolean => messages().length > 0 || !!props.children
+  createEffect(() => {
+    if (!ctx || !visible()) return
+    onCleanup(ctx.registerError(id))
+  })
+  return (
+    <Show when={visible()}>
+      <div id={id} role="alert" data-slot="field-error" class={cn('text-xs text-destructive', props.class)}>
+        <Show when={messages().length > 1} fallback={<>{messages()[0] ?? props.children}</>}>
+          <ul class="ml-4 list-disc space-y-0.5">
+            <For each={messages()}>{(m) => <li>{m}</li>}</For>
+          </ul>
+        </Show>
+      </div>
+    </Show>
+  )
+}