@a4ui/core 0.37.1 → 0.38.0

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>
+  )
+}

package/src/ui/Hero.tsx

@@ -0,0 +1,146 @@
+// Hero — the opening section of a landing page: headline, supporting text, up
+// to two calls-to-action, and an optional image, on a plain, aurora or photo
+// background.
+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'
+
+/** Arrangement of a {@link Hero}: text centered, or text beside the image. */
+export type HeroLayout = 'center' | 'split'
+/** Backdrop of a {@link Hero}. `'image'` uses `image` as a full-bleed photo. */
+export type HeroBackground = 'none' | 'aurora' | 'image'
+
+export interface HeroProps {
+  /** Small label above the title, e.g. a category or announcement. */
+  eyebrow?: string
+  /** Main headline, rendered as the page `<h1>`. */
+  title: string
+  /** Supporting paragraph under the title. */
+  subtitle?: string
+  /** Main call-to-action (filled button). */
+  primary?: SectionLink
+  /** Secondary call-to-action (outline button). */
+  secondary?: SectionLink
+  /** Image URL. Shown beside the text in `split` layout, under it in `center`, or behind it with `background="image"`. */
+  image?: string
+  /** Alt text of `image`. Defaults to empty (decorative). */
+  imageAlt?: string
+  /** Defaults to `'center'`. */
+  layout?: HeroLayout
+  /** Defaults to `'aurora'`. */
+  background?: HeroBackground
+  /** Anchor id for in-page navigation. */
+  id?: string
+  class?: string
+}
+
+/**
+ * Opening section of a landing page: eyebrow, headline, subtitle and up to two
+ * call-to-action links, with an optional image. `layout="split"` puts the image
+ * beside the text on wide screens (stacked on phones); `background` picks a
+ * theme-tinted aurora glow, a full-bleed photo with a legibility scrim, or
+ * nothing.
+ *
+ * @example
+ * ```tsx
+ * <Hero
+ *   eyebrow="New"
+ *   title="Ship your site this week"
+ *   subtitle="Everything you need to launch, nothing you don't."
+ *   primary={{ label: 'Get started', href: '/signup' }}
+ *   secondary={{ label: 'See pricing', href: '#pricing' }}
+ * />
+ * ```
+ */
+export function Hero(props: HeroProps): JSX.Element {
+  const layout = () => props.layout ?? 'center'
+  const background = () => props.background ?? 'aurora'
+  const photoBackdrop = () => background() === 'image' && props.image !== undefined
+  const showInlineImage = () => props.image !== undefined && !photoBackdrop()
+
+  const actions = (
+    <Show when={props.primary || props.secondary}>
+      <div class={cn('flex flex-wrap gap-3', layout() === 'center' && 'justify-center')}>
+        <Show when={props.primary}>
+          {(link) => (
+            <Button href={link().href} ripple class="px-5 py-2.5 text-base">
+              {link().label}
+            </Button>
+          )}
+        </Show>
+        <Show when={props.secondary}>
+          {(link) => (
+            <Button href={link().href} variant="outline" class="px-5 py-2.5 text-base">
+              {link().label}
+            </Button>
+          )}
+        </Show>
+      </div>
+    </Show>
+  )
+
+  return (
+    <section
+      id={props.id}
+      class={cn('relative isolate overflow-hidden', photoBackdrop() && 'text-white', props.class)}
+    >
+      <Show when={background() === 'aurora'}>
+        <div aria-hidden="true" class="pointer-events-none absolute inset-0 -z-10">
+          <div class="aurora-drift absolute -left-[10%] -top-[30%] h-[28rem] w-[28rem] rounded-full bg-primary/30 blur-3xl" />
+          <div class="aurora-drift absolute -right-[10%] top-[10%] h-[24rem] w-[24rem] rounded-full bg-accent/25 blur-3xl [animation-delay:-9s]" />
+        </div>
+      </Show>
+      <Show when={photoBackdrop()}>
+        <img
+          src={props.image}
+          alt={props.imageAlt ?? ''}
+          class="absolute inset-0 -z-20 h-full w-full object-cover"
+        />
+        <div
+          aria-hidden="true"
+          class="absolute inset-0 -z-10 bg-gradient-to-b from-black/70 via-black/55 to-black/75"
+        />
+      </Show>
+
+      <div
+        class={cn(
+          'mx-auto grid w-full max-w-6xl gap-10 px-5 py-20 sm:py-28',
+          layout() === 'split' && showInlineImage() && 'items-center md:grid-cols-2',
+        )}
+      >
+        <div
+          class={cn(
+            'flex flex-col gap-8',
+            layout() === 'center' ? 'items-center text-center' : 'items-start',
+          )}
+        >
+          <SectionHeading
+            level={1}
+            align={layout() === 'center' ? 'center' : 'left'}
+            eyebrow={props.eyebrow}
+            title={props.title}
+            subtitle={props.subtitle}
+            class={cn(
+              layout() === 'center' && 'max-w-3xl',
+              photoBackdrop() && '[&_h1]:text-white [&_p]:text-white/85',
+            )}
+          />
+          {actions}
+        </div>
+        <Show when={showInlineImage()}>
+          <img
+            src={props.image}
+            alt={props.imageAlt ?? ''}
+            class={cn(
+              'card w-full rounded-2xl object-cover shadow-xl',
+              layout() === 'center' ? 'mx-auto aspect-[16/9] max-w-4xl' : 'aspect-[4/3]',
+            )}
+          />
+        </Show>
+      </div>
+    </section>
+  )
+}