@a4ui/core 0.11.1 → 0.13.0

package/src/ui/FileUpload.tsx

@@ -0,0 +1,198 @@
+// Advanced file uploader: a drop zone plus a list of files with per-file
+// progress, error/retry, preview thumbnail, and remove. Purely presentational
+// and controlled — the consumer owns `files` and the actual upload; this
+// component only emits `onAdd`/`onRemove`/`onRetry` events.
+import { Check, File as FileIcon, X } from 'lucide-solid'
+import { For, type JSX, Show, createSignal } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { Progress } from './Progress'
+
+/** A single file entry rendered by {@link FileUpload}. The consumer owns this state. */
+export interface UploadFile {
+  id: string
+  name: string
+  /** File size in bytes. */
+  size: number
+  /** Upload progress, 0-100. */
+  progress: number
+  status: 'pending' | 'uploading' | 'done' | 'error'
+  /** Optional preview/thumbnail URL (e.g. an object URL for an image). */
+  url?: string
+  /** Error message when `status === 'error'`. */
+  error?: string
+}
+
+export interface FileUploadProps {
+  files: UploadFile[]
+  /** Called with the newly chosen File[] (from drop or the file dialog). */
+  onAdd: (files: File[]) => void
+  onRemove?: (id: string) => void
+  onRetry?: (id: string) => void
+  /** `accept` attribute for the hidden input, e.g. ".png,.jpg,application/pdf". */
+  accept?: string
+  /** Allow choosing/dropping more than one file at a time. Default: `true`. */
+  multiple?: boolean
+  /** Helper text shown inside the drop zone. */
+  hint?: string
+  disabled?: boolean
+  class?: string
+}
+
+/** Format a byte count as a short human-readable string, e.g. `1.4 MB`. */
+function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return '0 B'
+  if (n < 1024) return `${n} B`
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let value = n / 1024
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  return `${value.toFixed(1)} ${units[unit]}`
+}
+
+/**
+ * Advanced, controlled file uploader: a click-or-drag drop zone plus a list of
+ * files showing per-file progress, error/retry, a preview thumbnail, and a
+ * remove action. This component owns no file state — the consumer supplies
+ * `files` and performs the actual upload, updating `files` as progress comes in.
+ *
+ * @example
+ * ```tsx
+ * const [files, setFiles] = createSignal<UploadFile[]>([])
+ *
+ * <FileUpload
+ *   files={files()}
+ *   accept="image/*"
+ *   onAdd={(added) => {
+ *     const entries = added.map((f) => ({ id: crypto.randomUUID(), name: f.name, size: f.size, progress: 0, status: 'pending' as const }))
+ *     setFiles((prev) => [...prev, ...entries])
+ *     entries.forEach((entry, i) => upload(added[i], entry.id, setFiles))
+ *   }}
+ *   onRemove={(id) => setFiles((prev) => prev.filter((f) => f.id !== id))}
+ *   onRetry={(id) => retryUpload(id, setFiles)}
+ * />
+ * ```
+ */
+export function FileUpload(props: FileUploadProps): JSX.Element {
+  const [dragOver, setDragOver] = createSignal(false)
+  let input: HTMLInputElement | undefined
+
+  const emit = (list: FileList | null | undefined) => {
+    if (props.disabled || !list) return
+    const files = Array.from(list)
+    if (files.length) props.onAdd(files)
+  }
+
+  return (
+    <div class={cn('flex flex-col gap-4', props.class)}>
+      <button
+        type="button"
+        disabled={props.disabled}
+        onClick={() => !props.disabled && input?.click()}
+        onDragOver={(e) => {
+          if (props.disabled) return
+          e.preventDefault()
+          setDragOver(true)
+        }}
+        onDragLeave={(e) => {
+          e.preventDefault()
+          setDragOver(false)
+        }}
+        onDrop={(e) => {
+          e.preventDefault()
+          setDragOver(false)
+          emit(e.dataTransfer?.files)
+        }}
+        class="flex w-full flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed border-input p-6 text-center transition-colors"
+        classList={{
+          'border-primary bg-primary/5': dragOver(),
+          'hover:border-primary hover:bg-primary/5': !dragOver() && !props.disabled,
+          'cursor-not-allowed opacity-60': props.disabled,
+        }}
+      >
+        <FileIcon class="h-8 w-8 text-muted-foreground" />
+        <p class="text-sm font-medium text-foreground">
+          {props.hint ?? 'Drag files here or click to browse'}
+        </p>
+        <input
+          ref={input}
+          type="file"
+          class="hidden"
+          accept={props.accept}
+          multiple={props.multiple ?? true}
+          disabled={props.disabled}
+          onChange={(e) => {
+            emit(e.currentTarget.files)
+            e.currentTarget.value = '' // allow re-selecting the same file
+          }}
+        />
+      </button>
+
+      <Show when={props.files.length > 0}>
+        <ul class="flex flex-col gap-2">
+          <For each={props.files}>
+            {(file) => (
+              <li class="flex items-center gap-3 rounded-lg border border-border bg-glass p-3">
+                <Show
+                  when={file.url}
+                  fallback={
+                    <div class="flex h-10 w-10 shrink-0 items-center justify-center rounded bg-muted">
+                      <FileIcon class="h-5 w-5 text-muted-foreground" />
+                    </div>
+                  }
+                >
+                  <img src={file.url} alt="" class="h-10 w-10 shrink-0 rounded object-cover" />
+                </Show>
+
+                <div class="flex min-w-0 flex-1 flex-col gap-1">
+                  <div class="flex items-baseline gap-2">
+                    <span class="truncate text-sm font-medium text-foreground">{file.name}</span>
+                    <span class="shrink-0 text-xs text-muted-foreground">{formatBytes(file.size)}</span>
+                  </div>
+
+                  <Show when={file.status === 'uploading'}>
+                    <Progress value={file.progress} />
+                  </Show>
+
+                  <Show when={file.status === 'error'}>
+                    <div class="flex items-center gap-2">
+                      <span class="text-xs text-destructive">{file.error ?? 'Upload failed'}</span>
+                      <Show when={props.onRetry}>
+                        <Button
+                          variant="outline"
+                          class="h-6 px-2 py-0 text-xs"
+                          onClick={() => props.onRetry?.(file.id)}
+                        >
+                          Retry
+                        </Button>
+                      </Show>
+                    </div>
+                  </Show>
+                </div>
+
+                <Show when={file.status === 'done'}>
+                  <Check class="h-5 w-5 shrink-0 text-primary" aria-label="Upload complete" />
+                </Show>
+
+                <Show when={props.onRemove}>
+                  <button
+                    type="button"
+                    aria-label="Remove file"
+                    onClick={() => props.onRemove?.(file.id)}
+                    class="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus:outline-none focus:ring-2 focus:ring-ring"
+                  >
+                    <X class="h-4 w-4" />
+                  </button>
+                </Show>
+              </li>
+            )}
+          </For>
+        </ul>
+      </Show>
+    </div>
+  )
+}

package/src/ui/FillText.tsx

@@ -0,0 +1,63 @@
+// FillText — text with a color "fill" band sweeping left-to-right on loop,
+// for loading states. The sweep is a background-position animation clipped
+// to the glyphs via `background-clip: text`, driven by Motion's `animate`.
+// Falls back to plain static text under reduced motion.
+import { onCleanup, onMount, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface FillTextProps {
+  text: string
+  /** Seconds per sweep. @default 1.6 */
+  duration?: number
+  class?: string
+}
+
+/**
+ * Renders `text` with a bright gradient band that sweeps across the glyphs
+ * repeatedly, useful as a lightweight loading indicator. Respects
+ * `prefers-reduced-motion` by rendering plain muted text instead of animating.
+ *
+ * @example
+ * ```tsx
+ * <FillText text="Loading results…" />
+ * ```
+ */
+export function FillText(props: FillTextProps): JSX.Element {
+  let el!: HTMLSpanElement
+  let controls: { stop: () => void } | undefined
+
+  onMount(() => {
+    if (motionReduced()) return
+
+    controls = animate(
+      el,
+      { backgroundPosition: ['200% 0%', '-200% 0%'] },
+      { duration: props.duration ?? 1.6, ease: 'linear', repeat: Infinity },
+    )
+
+    onCleanup(() => controls?.stop())
+  })
+
+  return (
+    <span role="status" class={cn('font-medium', props.class)}>
+      <Show when={!motionReduced()} fallback={<span class="text-muted-foreground">{props.text}</span>}>
+        <span
+          ref={el}
+          style={{
+            background:
+              'linear-gradient(90deg, hsl(var(--muted-foreground)) 0%, hsl(var(--muted-foreground)) 40%, hsl(var(--foreground)) 50%, hsl(var(--muted-foreground)) 60%, hsl(var(--muted-foreground)) 100%)',
+            'background-size': '200% 100%',
+            '-webkit-background-clip': 'text',
+            'background-clip': 'text',
+            '-webkit-text-fill-color': 'transparent',
+            color: 'transparent',
+          }}
+        >
+          {props.text}
+        </span>
+      </Show>
+    </span>
+  )
+}

package/src/ui/FloatingActionButton.tsx

@@ -0,0 +1,48 @@
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** Screen corner a {@link FloatingActionButton} anchors to. Defaults to `'bottom-right'`. */
+export type FloatingActionButtonPosition = 'bottom-right' | 'bottom-left'
+
+const POSITION_CLASSES: Record<FloatingActionButtonPosition, string> = {
+  'bottom-right': 'bottom-6 right-6',
+  'bottom-left': 'bottom-6 left-6',
+}
+
+// brightness-110 on hover keeps the tint theme-agnostic — it lifts whatever
+// primary color the active theme resolves to, no per-variant color needed.
+const FAB_BASE =
+  'fixed z-40 grid h-14 w-14 place-items-center rounded-full bg-primary text-primary-foreground shadow-lg transition hover:brightness-110'
+
+export interface FloatingActionButtonProps {
+  /** Icon rendered centered inside the button. */
+  icon: JSX.Element
+  /** Accessible label; surfaced via `aria-label`. */
+  label: string
+  onClick?: () => void
+  /** Screen corner to anchor to. Defaults to `'bottom-right'`. */
+  position?: FloatingActionButtonPosition
+  class?: string
+}
+
+/**
+ * A fixed circular primary action button pinned to a screen corner.
+ *
+ * @example
+ * ```tsx
+ * <FloatingActionButton icon={<PlusIcon />} label="New item" onClick={() => create()} />
+ * ```
+ */
+export function FloatingActionButton(props: FloatingActionButtonProps): JSX.Element {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      onClick={() => props.onClick?.()}
+      class={cn(FAB_BASE, POSITION_CLASSES[props.position ?? 'bottom-right'], props.class)}
+    >
+      {props.icon}
+    </button>
+  )
+}

package/src/ui/Form.tsx

@@ -0,0 +1,108 @@
+// Accessible form-field primitives. `FormField` provisions a shared,
+// auto-generated id via context so `FormLabel`, `FormControl`,
+// `FormDescription`, and `FormError` can associate themselves (`for`,
+// `aria-describedby`, element ids) without the consumer wiring ids by hand.
+import type { JSX } from 'solid-js'
+import { createContext, createUniqueId, Show, useContext } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface FormFieldContextValue {
+  id: string
+  describedBy: string
+}
+
+const FormFieldContext = createContext<FormFieldContextValue>()
+
+function useFormFieldContext(): FormFieldContextValue {
+  const ctx = useContext(FormFieldContext)
+  return ctx ?? { id: '', describedBy: '' }
+}
+
+export interface FormFieldProps {
+  /** Optional explicit id; otherwise auto-generated. */
+  id?: string
+  children: JSX.Element
+  class?: string
+}
+
+/**
+ * Container/provider that gives `FormLabel`, `FormControl`,
+ * `FormDescription`, and `FormError` a shared field id so they wire up
+ * `for`/`id`/`aria-describedby` automatically.
+ *
+ * Pairs well with a schema validator (Valibot/Zod): the consumer computes
+ * the error string and passes it to `FormError`.
+ *
+ * @example
+ * ```tsx
+ * <FormField>
+ *   <FormLabel>Email</FormLabel>
+ *   <FormControl>
+ *     {(fieldProps) => <input type="email" {...fieldProps} />}
+ *   </FormControl>
+ *   <FormDescription>We'll never share your email.</FormDescription>
+ *   <FormError>{errors().email}</FormError>
+ * </FormField>
+ * ```
+ */
+export function FormField(props: FormFieldProps): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- id is stable for a field's lifetime
+  const id = props.id ?? createUniqueId()
+  const value: FormFieldContextValue = {
+    id,
+    describedBy: `${id}-desc ${id}-error`,
+  }
+  return (
+    <FormFieldContext.Provider value={value}>
+      <div class={cn('space-y-1.5', props.class)}>{props.children}</div>
+    </FormFieldContext.Provider>
+  )
+}
+
+/** Label associated with the enclosing `FormField`'s control via `for`. */
+export function FormLabel(props: { children: JSX.Element; class?: string }): JSX.Element {
+  const ctx = useFormFieldContext()
+  return (
+    <label for={ctx.id} class={cn('text-sm font-medium text-foreground', props.class)}>
+      {props.children}
+    </label>
+  )
+}
+
+/**
+ * Render-prop bridge that hands the enclosing `FormField`'s `id` and
+ * `aria-describedby` to the caller's control, to be spread onto the actual
+ * input/select/textarea element.
+ */
+export function FormControl(props: {
+  children: (fieldProps: { id: string; 'aria-describedby': string }) => JSX.Element
+}): JSX.Element {
+  const ctx = useFormFieldContext()
+  return <>{props.children({ id: ctx.id, 'aria-describedby': ctx.describedBy })}</>
+}
+
+/** Helper text for the enclosing `FormField`, linked via `aria-describedby`. */
+export function FormDescription(props: { children: JSX.Element; class?: string }): JSX.Element {
+  const ctx = useFormFieldContext()
+  return (
+    <p id={`${ctx.id}-desc`} class={cn('text-xs text-muted-foreground', props.class)}>
+      {props.children}
+    </p>
+  )
+}
+
+/**
+ * Error text for the enclosing `FormField`, linked via `aria-describedby`.
+ * Renders nothing when there is no error to show.
+ */
+export function FormError(props: { children?: JSX.Element; class?: string }): JSX.Element {
+  const ctx = useFormFieldContext()
+  return (
+    <Show when={props.children}>
+      <p id={`${ctx.id}-error`} role="alert" class={cn('text-xs text-destructive', props.class)}>
+        {props.children}
+      </p>
+    </Show>
+  )
+}

package/src/ui/Highlight.tsx

@@ -0,0 +1,53 @@
+// Highlight — renders text with every case-insensitive occurrence of a query
+// wrapped in a <mark>. Design-system primitive: no business vocabulary, no
+// hardcoded colors — the mark uses semantic tokens so it tracks the theme.
+import { For, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface HighlightProps {
+  /** Full text to render. */
+  text: string
+  /** Substring to highlight; every case-insensitive occurrence is marked. */
+  query: string
+  class?: string
+}
+
+/** Escape regex metacharacters so an arbitrary query matches literally. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Highlights every case-insensitive occurrence of `query` within `text`.
+ * When `query` is empty the text renders unchanged.
+ *
+ * @example
+ * ```tsx
+ * <Highlight text="Sonora Precision" query="prec" />
+ * ```
+ */
+export function Highlight(props: HighlightProps): JSX.Element {
+  const segments = (): { text: string; match: boolean }[] => {
+    if (!props.query) return [{ text: props.text, match: false }]
+    const re = new RegExp(`(${escapeRegExp(props.query)})`, 'gi')
+    const q = props.query.toLowerCase()
+    return props.text
+      .split(re)
+      .filter((part) => part !== '')
+      .map((part) => ({ text: part, match: part.toLowerCase() === q }))
+  }
+  return (
+    <span class={cn(props.class)}>
+      <For each={segments()}>
+        {(segment) =>
+          segment.match ? (
+            <mark class="rounded bg-primary/30 px-0.5 text-foreground">{segment.text}</mark>
+          ) : (
+            segment.text
+          )
+        }
+      </For>
+    </span>
+  )
+}

package/src/ui/HoldToConfirm.tsx

@@ -0,0 +1,141 @@
+// A destructive/important-action button that requires a press-and-HOLD (not a
+// single click) to confirm — the fill sweeping across the button doubles as a
+// "how much longer" progress affordance, guarding against accidental taps.
+import type { JSX } from 'solid-js'
+import { createSignal, onCleanup } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface HoldToConfirmProps {
+  onConfirm: () => void
+  /** Button label. @default 'Hold to confirm' */
+  label?: string
+  /** How long to hold, in ms. @default 1200 */
+  holdMs?: number
+  disabled?: boolean
+  class?: string
+}
+
+/**
+ * Press-and-hold button for destructive/important actions: `onConfirm` only
+ * fires once the pointer (or Space/Enter) has been held down for `holdMs`.
+ * A fill layer sweeps left-to-right as visual progress; releasing early stops
+ * and resets it. Under reduced motion the hold is still required (gated by a
+ * plain timer instead of the tracked animation), but the fill jumps instead
+ * of sweeping and the success flourish is skipped.
+ *
+ * @example
+ * ```tsx
+ * <HoldToConfirm label="Hold to delete" holdMs={1500} onConfirm={() => deleteItem(id)} />
+ * ```
+ */
+export function HoldToConfirm(props: HoldToConfirmProps): JSX.Element {
+  const [holding, setHolding] = createSignal(false)
+
+  let buttonEl: HTMLButtonElement | undefined
+  let fillEl: HTMLSpanElement | undefined
+  let controls: ReturnType<typeof animate> | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let active = false
+
+  const holdMs = () => props.holdMs ?? 1200
+
+  const resetFill = (durationSec: number) => {
+    if (!fillEl) return
+    if (motionReduced()) {
+      fillEl.style.transform = 'scaleX(0)'
+      return
+    }
+    animate(fillEl, { scaleX: 0 }, { duration: durationSec, ease: 'easeOut' })
+  }
+
+  const succeed = () => {
+    active = false
+    setHolding(false)
+    props.onConfirm()
+    if (!motionReduced() && buttonEl) {
+      animate(buttonEl, { scale: [1, 1.04, 1] }, { duration: 0.3, ease: 'easeOut' })
+    }
+    resetFill(0.2)
+  }
+
+  const cancel = () => {
+    if (!active) return
+    active = false
+    setHolding(false)
+    controls?.stop()
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+    resetFill(0.15)
+  }
+
+  const start = (event: PointerEvent | KeyboardEvent) => {
+    if (props.disabled || active) return
+    event.preventDefault()
+    active = true
+    setHolding(true)
+
+    if (motionReduced()) {
+      if (fillEl) fillEl.style.transform = 'scaleX(1)'
+      timer = setTimeout(() => {
+        if (active) succeed()
+      }, holdMs())
+      return
+    }
+
+    if (!fillEl) return
+    controls = animate(fillEl, { scaleX: [0, 1] }, { duration: holdMs() / 1000, ease: 'linear' })
+    controls.finished
+      // eslint-disable-next-line solid/reactivity -- promise callback, not a tracked scope; setHolding runs fine here
+      .then(() => {
+        if (active) succeed()
+      })
+      .catch(() => {})
+  }
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== ' ' && event.key !== 'Enter') return
+    if (event.repeat) return
+    start(event)
+  }
+
+  const onKeyUp = (event: KeyboardEvent) => {
+    if (event.key !== ' ' && event.key !== 'Enter') return
+    cancel()
+  }
+
+  onCleanup(() => {
+    controls?.stop()
+    if (timer !== undefined) clearTimeout(timer)
+  })
+
+  return (
+    <button
+      ref={buttonEl}
+      type="button"
+      disabled={props.disabled}
+      aria-label={props.label ?? 'Hold to confirm'}
+      aria-busy={holding()}
+      class={cn(
+        'relative overflow-hidden rounded-lg border border-border bg-card px-4 py-2 text-sm font-medium disabled:pointer-events-none disabled:opacity-50',
+        props.class,
+      )}
+      onPointerDown={start}
+      onPointerUp={cancel}
+      onPointerLeave={cancel}
+      onKeyDown={onKeyDown}
+      onKeyUp={onKeyUp}
+    >
+      <span
+        aria-hidden="true"
+        ref={fillEl}
+        class="absolute inset-0 origin-left bg-primary/25"
+        style={{ transform: 'scaleX(0)' }}
+      />
+      <span class="relative z-10">{props.label ?? 'Hold to confirm'}</span>
+    </button>
+  )
+}

package/src/ui/HoverCard.tsx

@@ -0,0 +1,42 @@
+// Hover-triggered floating panel on Kobalte's HoverCard primitive.
+import { HoverCard as KHoverCard } from '@kobalte/core/hover-card'
+import type { JSX, ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface HoverCardProps extends ParentProps {
+  /** Content that opens the card on hover/focus. */
+  trigger: JSX.Element
+  class?: string
+}
+
+/**
+ * Floating panel that appears on hover (or focus) of a trigger element, built on
+ * Kobalte's `HoverCard` primitive. Good for previews/tooltips with richer content
+ * than a plain `title` attribute — e.g. a user avatar preview card.
+ *
+ * @example
+ * ```tsx
+ * <HoverCard trigger={<Avatar src={user.avatar} />}>
+ *   <p>{user.name}</p>
+ * </HoverCard>
+ * ```
+ */
+export function HoverCard(props: HoverCardProps): JSX.Element {
+  return (
+    <KHoverCard>
+      <KHoverCard.Trigger class="inline-flex">{props.trigger}</KHoverCard.Trigger>
+      <KHoverCard.Portal>
+        <KHoverCard.Content
+          class={cn(
+            'bg-glass z-50 rounded-lg border border-border p-4 text-card-foreground shadow-lg',
+            props.class,
+          )}
+        >
+          <KHoverCard.Arrow />
+          {props.children}
+        </KHoverCard.Content>
+      </KHoverCard.Portal>
+    </KHoverCard>
+  )
+}