@a4ui/core 0.11.1 → 0.13.0

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

package/src/ui/LoadingDots.tsx

@@ -0,0 +1,75 @@
+// Three dots bouncing in a staggered wave — a lightweight indeterminate
+// loading indicator. The bounce is pure CSS (keyframes injected once into the
+// document head) so there's no per-frame JS cost; reduced motion swaps the
+// bounce for a gentle opacity pulse.
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface LoadingDotsProps {
+  /** Dot diameter in px. @default 8 */
+  size?: number
+  /** Optional accessible label. @default 'Loading' */
+  label?: string
+  class?: string
+}
+
+const STYLE_ID = 'a4ui-loading-dots-style'
+
+function ensureStyleInjected(): void {
+  if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+@keyframes a4-dot-bounce {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-60%); }
+}
+@keyframes a4-dot-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.35; }
+}
+`
+  document.head.appendChild(style)
+}
+
+/**
+ * Three dots bouncing in a staggered wave — an inline, indeterminate loading
+ * indicator. Dots use `bg-current`, so color/size follow the ancestor's text
+ * color; diameter is set via `size`. Falls back to a gentle opacity pulse
+ * under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <LoadingDots label="Loading results" class="text-primary" />
+ * ```
+ */
+export function LoadingDots(props: LoadingDotsProps): JSX.Element {
+  ensureStyleInjected()
+
+  const size = () => props.size ?? 8
+  const animationName = () => (motionReduced() ? 'a4-dot-pulse' : 'a4-dot-bounce')
+
+  const dotStyle = (delayMs: number): JSX.CSSProperties => ({
+    width: `${size()}px`,
+    height: `${size()}px`,
+    'animation-name': animationName(),
+    'animation-duration': '0.6s',
+    'animation-iteration-count': 'infinite',
+    'animation-timing-function': 'ease-in-out',
+    'animation-delay': `${delayMs}ms`,
+  })
+
+  return (
+    <span
+      role="status"
+      aria-label={props.label ?? 'Loading'}
+      class={cn('inline-flex items-center gap-1 text-current', props.class)}
+    >
+      <span class="rounded-full bg-current" style={dotStyle(0)} />
+      <span class="rounded-full bg-current" style={dotStyle(120)} />
+      <span class="rounded-full bg-current" style={dotStyle(240)} />
+    </span>
+  )
+}

package/src/ui/Marquee.tsx

@@ -0,0 +1,48 @@
+// Infinite horizontal scroller that loops its children seamlessly.
+import type { JSX, ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+interface MarqueeProps extends ParentProps {
+  /** Seconds for one full loop of the track. Lower is faster. Defaults to `20`. */
+  speed?: number
+  /** Pause the scroll while the pointer hovers the strip. Defaults to `true`. */
+  pauseOnHover?: boolean
+  class?: string
+}
+
+/**
+ * A horizontally scrolling strip that loops its children seamlessly. The
+ * children are rendered twice inside a flex track; when the first copy has
+ * scrolled fully out of view the second copy sits exactly where the first
+ * began, so the animation restarts with no visible seam. Honors reduced
+ * motion (the track sits still) and, by default, pauses on hover.
+ *
+ * @example
+ * ```tsx
+ * <Marquee speed={30}>
+ *   <span class="mx-4">A4ui</span>
+ *   <span class="mx-4">SolidJS</span>
+ *   <span class="mx-4">Tailwind</span>
+ * </Marquee>
+ * ```
+ */
+export function Marquee(props: MarqueeProps): JSX.Element {
+  const pauseOnHover = () => props.pauseOnHover ?? true
+
+  return (
+    <div class={cn('overflow-hidden', props.class)}>
+      <style>{'@keyframes marquee{from{transform:translateX(0)}to{transform:translateX(-50%)}}'}</style>
+      <div
+        class={cn('flex w-max shrink-0', pauseOnHover() && 'hover:[animation-play-state:paused]')}
+        style={motionReduced() ? undefined : { animation: `marquee ${props.speed ?? 20}s linear infinite` }}
+      >
+        <div class="flex shrink-0">{props.children}</div>
+        <div class="flex shrink-0" aria-hidden="true">
+          {props.children}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/ui/Mentions.tsx

@@ -0,0 +1,170 @@
+// Multi-line text field with @mention autocomplete over a native <textarea>.
+import type { JSX } from 'solid-js'
+import { For, Show, createSignal } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface MentionOption {
+  value: string
+  label: string
+}
+
+export interface MentionsProps {
+  value: string
+  /** Called with the new string value on every input (not the raw DOM event). */
+  onChange: (value: string) => void
+  /** Options offered while typing an `@mention`. */
+  options: MentionOption[]
+  placeholder?: string
+  class?: string
+}
+
+const TEXTAREA_BASE =
+  'w-full min-h-[80px] resize-y 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'
+
+/** Match an active `@query` immediately before the caret. */
+const MENTION_RE = /@(\w*)$/
+
+/**
+ * Controlled multi-line text field that shows an autocomplete dropdown while
+ * the user types an `@mention`. On each input, the text before the caret is
+ * checked for a trailing `@query`; matching {@link MentionOption}s (by `label`
+ * or `value`, case-insensitive) are offered in a panel. Selecting one replaces
+ * the `@query` with `@{label} `. Arrow keys move the highlight, Enter accepts,
+ * Escape dismisses.
+ *
+ * @example
+ * ```tsx
+ * const [body, setBody] = createSignal('')
+ * <Mentions
+ *   value={body()}
+ *   onChange={setBody}
+ *   options={[
+ *     { value: 'ada', label: 'Ada Lovelace' },
+ *     { value: 'alan', label: 'Alan Turing' },
+ *   ]}
+ *   placeholder="Write a note, use @ to mention someone"
+ * />
+ * ```
+ */
+export function Mentions(props: MentionsProps): JSX.Element {
+  let ref: HTMLTextAreaElement | undefined
+  const [open, setOpen] = createSignal(false)
+  const [query, setQuery] = createSignal('')
+  const [caret, setCaret] = createSignal(0)
+  const [highlighted, setHighlighted] = createSignal(0)
+
+  const filtered = (): MentionOption[] => {
+    const q = query().toLowerCase()
+    return props.options.filter((o) => o.label.toLowerCase().includes(q) || o.value.toLowerCase().includes(q))
+  }
+
+  const close = () => {
+    setOpen(false)
+    setQuery('')
+  }
+
+  const sync = (el: HTMLTextAreaElement) => {
+    const pos = el.selectionStart ?? el.value.length
+    setCaret(pos)
+    const before = el.value.slice(0, pos)
+    const match = before.match(MENTION_RE)
+    if (match) {
+      setQuery(match[1])
+      setOpen(true)
+      setHighlighted(0)
+    } else {
+      close()
+    }
+  }
+
+  const select = (option: MentionOption) => {
+    const el = ref
+    const full = props.value
+    const pos = el ? (el.selectionStart ?? caret()) : caret()
+    const before = full.slice(0, pos)
+    const after = full.slice(pos)
+    const start = before.lastIndexOf('@')
+    if (start === -1) {
+      close()
+      return
+    }
+    const insert = `@${option.label} `
+    const next = full.slice(0, start) + insert + after
+    props.onChange(next)
+    close()
+    if (el) {
+      const nextCaret = start + insert.length
+      queueMicrotask(() => {
+        el.focus()
+        el.setSelectionRange(nextCaret, nextCaret)
+        setCaret(nextCaret)
+      })
+    }
+  }
+
+  const onKeyDown = (ev: KeyboardEvent) => {
+    if (!open()) return
+    const items = filtered()
+    if (items.length === 0) return
+    switch (ev.key) {
+      case 'ArrowDown':
+        ev.preventDefault()
+        setHighlighted((i) => (i + 1) % items.length)
+        break
+      case 'ArrowUp':
+        ev.preventDefault()
+        setHighlighted((i) => (i - 1 + items.length) % items.length)
+        break
+      case 'Enter':
+        ev.preventDefault()
+        select(items[Math.min(highlighted(), items.length - 1)])
+        break
+      case 'Escape':
+        ev.preventDefault()
+        close()
+        break
+    }
+  }
+
+  return (
+    <div class={cn('relative', props.class)}>
+      <textarea
+        ref={ref}
+        class={TEXTAREA_BASE}
+        value={props.value}
+        placeholder={props.placeholder}
+        onInput={(ev) => {
+          props.onChange(ev.currentTarget.value)
+          sync(ev.currentTarget)
+        }}
+        onClick={(ev) => sync(ev.currentTarget)}
+        onKeyUp={(ev) => sync(ev.currentTarget)}
+        onKeyDown={onKeyDown}
+        onBlur={() => close()}
+      />
+      <Show when={open() && filtered().length > 0}>
+        <div class="absolute z-50 mt-1 max-h-48 w-56 overflow-y-auto rounded-md border border-border bg-card p-1 shadow-md">
+          <For each={filtered()}>
+            {(option, i) => (
+              <button
+                type="button"
+                class={cn(
+                  'w-full rounded px-2 py-1.5 text-left text-sm hover:bg-muted',
+                  i() === highlighted() && 'bg-muted',
+                )}
+                onMouseDown={(ev) => {
+                  ev.preventDefault()
+                  select(option)
+                }}
+                onMouseEnter={() => setHighlighted(i())}
+              >
+                {option.label}
+              </button>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  )
+}

package/src/ui/Meter.tsx

@@ -0,0 +1,57 @@
+// Static measurement gauge on Kobalte's Meter primitive (e.g. disk usage).
+import { Meter as KMeter } from '@kobalte/core/meter'
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface MeterProps {
+  value: number
+  /** @default 100 */
+  max?: number
+  /** Label shown above the track, paired with an auto-formatted value label. */
+  label?: string
+  class?: string
+}
+
+/**
+ * Static measurement gauge (e.g. disk/quota usage) on Kobalte's `Meter` primitive.
+ * Unlike a progress bar, a meter represents a fixed measurement against a range,
+ * not an in-flight operation.
+ *
+ * @example
+ * ```tsx
+ * <Meter value={72} max={100} label="Storage used" />
+ * ```
+ */
+export function Meter(props: MeterProps): JSX.Element {
+  // Kobalte's Meter.Fill has no intrinsic width — we set it ourselves from the
+  // value as a fraction of the range, clamped to 0–100%. (Without this the bar
+  // ignored `max`, so e.g. value 38 of max 50 read "76%" but filled only ~38%.)
+  const percent = () => {
+    const max = props.max ?? 100
+    if (max <= 0) return 0
+    return Math.max(0, Math.min(100, (props.value / max) * 100))
+  }
+  return (
+    <KMeter
+      value={props.value}
+      minValue={0}
+      maxValue={props.max ?? 100}
+      class={cn('flex flex-col gap-1.5', props.class)}
+    >
+      <Show when={props.label}>
+        <div class="flex items-center justify-between text-sm text-foreground">
+          <KMeter.Label>{props.label}</KMeter.Label>
+          <KMeter.ValueLabel class="text-muted-foreground" />
+        </div>
+      </Show>
+      <KMeter.Track class="h-2 overflow-hidden rounded-full bg-muted">
+        <KMeter.Fill
+          class="h-full rounded-full bg-primary transition-all duration-500"
+          style={{ width: `${percent()}%` }}
+        />
+      </KMeter.Track>
+    </KMeter>
+  )
+}

package/src/ui/Modal.tsx

@@ -0,0 +1,106 @@
+// Dialog on Kobalte's Dialog primitive. Two shapes via `variant`:
+//   - 'drawer' (default): right-anchored slide-over — create/edit forms, detail
+//     panels (more vertical room, less jarring than a centered pop).
+//   - 'center': the classic centered modal — short confirmations (destructive
+//     yes/no) where a full-height drawer would be overkill.
+// The .drawer-content / .modal-content classes drive the slide/scale keyframes
+// (styles.css) off Kobalte's data-expanded/data-closed presence tracking.
+import { Dialog } from '@kobalte/core/dialog'
+import { X } from 'lucide-solid'
+import type { JSX, ParentProps } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface ModalProps extends ParentProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Header title; omitting it hides the whole header bar. */
+  title?: string
+  /**
+   * `'drawer'` (default): right-anchored slide-over, more room, less jarring —
+   * use for forms/detail panels. `'center'`: classic centered modal — use for
+   * short confirmations (e.g. destructive yes/no).
+   * @default 'drawer'
+   */
+  variant?: 'drawer' | 'center'
+  class?: string
+  /** Accessible label for the close button. @default 'Close' */
+  closeLabel?: string
+}
+
+/**
+ * Dialog on Kobalte's `Dialog` primitive (focus trap, portal, presence handled
+ * for you), rendered as either a slide-over drawer or a centered modal depending
+ * on `variant`.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Modal open={open()} onOpenChange={setOpen} variant="center" title="Delete item?">
+ *   <p>This action cannot be undone.</p>
+ * </Modal>
+ * ```
+ */
+export function Modal(props: ModalProps): JSX.Element {
+  const isCenter = () => props.variant === 'center'
+  return (
+    <Dialog open={props.open} onOpenChange={props.onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay class="modal-overlay fixed inset-0 z-40 bg-background/80 backdrop-blur-sm" />
+        <Show
+          when={isCenter()}
+          fallback={
+            <div class="fixed inset-0 z-50 flex justify-end">
+              <Dialog.Content
+                class={cn(
+                  'drawer-content bg-glass flex h-full w-full max-w-[520px] flex-col overflow-y-auto border-l border-border text-card-foreground shadow-2xl',
+                  props.class,
+                )}
+              >
+                <Show when={props.title}>
+                  <div class="sticky top-0 z-10 flex items-center justify-between border-b border-border bg-background/85 px-6 py-4 backdrop-blur">
+                    <Dialog.Title class="text-lg font-semibold leading-none tracking-tight">
+                      {props.title}
+                    </Dialog.Title>
+                    <Dialog.CloseButton
+                      class="grid h-8 w-8 place-items-center rounded-lg text-muted-foreground transition hover:bg-muted hover:text-foreground"
+                      aria-label={props.closeLabel ?? 'Close'}
+                    >
+                      <X class="h-5 w-5" />
+                    </Dialog.CloseButton>
+                  </div>
+                </Show>
+                <div class="p-6 pt-4">{props.children}</div>
+              </Dialog.Content>
+            </div>
+          }
+        >
+          <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+            <Dialog.Content
+              class={cn(
+                'modal-content w-full max-w-lg rounded-xl border border-border bg-card text-card-foreground shadow-sm',
+                props.class,
+              )}
+            >
+              <Show when={props.title}>
+                <div class="flex items-center justify-between border-b border-border p-6 pb-4">
+                  <Dialog.Title class="text-lg font-semibold leading-none tracking-tight">
+                    {props.title}
+                  </Dialog.Title>
+                  <Dialog.CloseButton
+                    class="text-muted-foreground hover:text-foreground"
+                    aria-label={props.closeLabel ?? 'Close'}
+                  >
+                    ✕
+                  </Dialog.CloseButton>
+                </div>
+              </Show>
+              <div class="p-6 pt-4">{props.children}</div>
+            </Dialog.Content>
+          </div>
+        </Show>
+      </Dialog.Portal>
+    </Dialog>
+  )
+}