@a4ui/core 0.11.1 → 0.12.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/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/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>
+  )
+}

package/src/ui/Image.tsx

@@ -0,0 +1,66 @@
+// Content image with an optional click-to-zoom lightbox, built on Kobalte's
+// Dialog primitive. The thumbnail lazy-loads; when `preview` is on it becomes a
+// button that opens a dimmed, backdrop-blurred overlay with an enlarged copy of
+// the image and a corner close button (focus trap/portal handled by Kobalte).
+import { Dialog } from '@kobalte/core/dialog'
+import { X } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface ImageProps {
+  src: string
+  alt: string
+  class?: string
+  /** When true, clicking the image opens a zoomable lightbox. @default true */
+  preview?: boolean
+}
+
+/**
+ * Lazy-loaded content image. Unless `preview` is disabled, the thumbnail is a
+ * zoom-in button that opens a centered lightbox (dimmed overlay + close button)
+ * on Kobalte's `Dialog` primitive.
+ *
+ * @example
+ * ```tsx
+ * <Image src="/photo.jpg" alt="A scenic view" />
+ * <Image src="/logo.svg" alt="Logo" preview={false} />
+ * ```
+ */
+export function Image(props: ImageProps): JSX.Element {
+  const [open, setOpen] = createSignal(false)
+  const preview = () => props.preview !== false
+
+  const img = (
+    <img src={props.src} alt={props.alt} loading="lazy" class={cn('rounded-lg object-cover', props.class)} />
+  )
+
+  return (
+    <Show when={preview()} fallback={img}>
+      <button type="button" class="cursor-zoom-in" aria-label={props.alt} onClick={() => setOpen(true)}>
+        {img}
+      </button>
+      <Dialog open={open()} onOpenChange={setOpen}>
+        <Dialog.Portal>
+          <Dialog.Overlay class="fixed inset-0 z-40 bg-background/80 backdrop-blur-sm" />
+          <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+            <Dialog.Content role="dialog" class="relative">
+              <img
+                src={props.src}
+                alt={props.alt}
+                class="max-h-[85vh] max-w-[90vw] rounded-lg object-contain"
+              />
+              <Dialog.CloseButton
+                class="absolute right-2 top-2 grid h-8 w-8 place-items-center rounded-lg bg-background/70 text-foreground transition hover:bg-muted"
+                aria-label="Close"
+              >
+                <X class="h-5 w-5" />
+              </Dialog.CloseButton>
+            </Dialog.Content>
+          </div>
+        </Dialog.Portal>
+      </Dialog>
+    </Show>
+  )
+}

package/src/ui/Input.tsx

@@ -0,0 +1,38 @@
+// `disabled` is wired onto the <input> element (not just styled).
+import type { JSX } from 'solid-js'
+import { splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+const INPUT_BASE =
+  'w-full rounded-md border border-input bg-background text-foreground placeholder:text-muted-foreground px-3 py-2 text-sm outline-none transition-colors a4-field disabled:cursor-not-allowed disabled:opacity-50'
+
+interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onInput'> {
+  value: string
+  /** Called with the raw string value on every input event (controlled). */
+  onInput: (value: string) => void
+  class?: string
+}
+
+/**
+ * Themed text input with a value/onInput controlled-string API (instead of raw
+ * DOM events). All other native `<input>` attributes pass through, so `type`,
+ * `disabled`, `placeholder`, etc. work as usual.
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = createSignal('')
+ * <Input value={name()} onInput={setName} placeholder="Full name" />
+ * ```
+ */
+export function Input(props: InputProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['value', 'onInput', 'class'])
+  return (
+    <input
+      class={cn(INPUT_BASE, local.class)}
+      value={local.value}
+      onInput={(ev) => local.onInput(ev.currentTarget.value)}
+      {...rest}
+    />
+  )
+}

package/src/ui/Kbd.tsx

@@ -0,0 +1,25 @@
+// Kbd — keyboard key indicator. Renders a single keycap for documenting
+// shortcuts; compose several side by side for chords (e.g. ⌘ + K). Purely
+// presentational and theme-agnostic — colors come from semantic tokens.
+import type { JSX, ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface KbdProps extends ParentProps {
+  class?: string
+}
+
+const KBD_BASE =
+  'inline-flex min-w-[1.5rem] items-center justify-center rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-xs text-muted-foreground shadow-sm'
+
+/**
+ * Keycap-styled indicator for a keyboard key or shortcut token.
+ *
+ * @example
+ * ```tsx
+ * <Kbd>⌘</Kbd><Kbd>K</Kbd>
+ * ```
+ */
+export function Kbd(props: KbdProps): JSX.Element {
+  return <kbd class={cn(KBD_BASE, props.class)}>{props.children}</kbd>
+}

package/src/ui/List.tsx

@@ -0,0 +1,71 @@
+// Vertical list primitive (plain HTML + Tailwind, no headless dep). Renders a
+// semantic <ul> of rows, each with an optional leading avatar, a title +
+// optional description column, and an optional trailing meta/actions slot.
+import { For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single row in a {@link List}. */
+export interface ListItem {
+  title: string
+  description?: string
+  avatar?: JSX.Element
+  meta?: JSX.Element
+  actions?: JSX.Element
+}
+
+interface ListProps {
+  items: ListItem[]
+  class?: string
+}
+
+export type { ListProps }
+
+/**
+ * Vertical list of rows inside a rounded, bordered container with divider
+ * lines between items. Each item shows an optional leading `avatar`, a
+ * `title` with optional `description`, and an optional trailing `meta` /
+ * `actions` slot.
+ *
+ * @example
+ * ```tsx
+ * <List
+ *   items={[
+ *     {
+ *       title: 'Alfredo Rivera',
+ *       description: 'Owner',
+ *       avatar: <Avatar name="Alfredo" />,
+ *       meta: <span>2h ago</span>,
+ *       actions: <Button size="sm">Edit</Button>,
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export function List(props: ListProps): JSX.Element {
+  return (
+    <ul class={cn('divide-y divide-border rounded-lg border border-border', props.class)}>
+      <For each={props.items}>
+        {(item) => (
+          <li class="flex items-center gap-3 px-4 py-3">
+            <Show when={item.avatar}>
+              <div class="shrink-0">{item.avatar}</div>
+            </Show>
+            <div class="min-w-0 flex-1">
+              <p class="text-sm font-medium text-foreground">{item.title}</p>
+              <Show when={item.description}>
+                <p class="text-xs text-muted-foreground">{item.description}</p>
+              </Show>
+            </div>
+            <Show when={item.meta}>
+              <div class="text-xs text-muted-foreground">{item.meta}</div>
+            </Show>
+            <Show when={item.actions}>
+              <div class="shrink-0">{item.actions}</div>
+            </Show>
+          </li>
+        )}
+      </For>
+    </ul>
+  )
+}