@a4ui/core 0.11.1 → 0.13.0

package/src/ui/ScrambleText.tsx

@@ -0,0 +1,95 @@
+// Text that "decodes" into place: characters scramble through random glyphs
+// before locking, left to right, into the final string — motion.dev's
+// scramble-text effect, reimplemented here with a plain setInterval (locking
+// one more character's worth of the string on each tick) rather than the
+// `motion` package, since the effect is character substitution, not a tween.
+import { createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ScrambleTextProps {
+  text: string
+  /** When to run: on mount, or on hover. @default 'mount' */
+  trigger?: 'mount' | 'hover'
+  /** Total scramble duration in ms. @default 800 */
+  duration?: number
+  class?: string
+}
+
+const GLYPHS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*<>-_'
+const TICK_MS = 30
+
+function randomGlyph(): string {
+  return GLYPHS[Math.floor(Math.random() * GLYPHS.length)] as string
+}
+
+/**
+ * Text that scrambles through random glyphs before "decoding" into the final
+ * string, left to right, over `duration` ms. Runs once on mount by default;
+ * pass `trigger="hover"` to (re)run it — cleanly restarting if it's still
+ * mid-scramble — on pointer hover instead. Renders the final text as-is, with
+ * no scramble, when the user prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <ScrambleText text="ACCESS GRANTED" trigger="hover" duration={600} />
+ * ```
+ */
+export function ScrambleText(props: ScrambleTextProps): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- one-time seed; scramble() re-reads props.text on each run
+  const [display, setDisplay] = createSignal(props.text)
+  let intervalId: ReturnType<typeof setInterval> | undefined
+
+  const stop = (): void => {
+    if (intervalId === undefined) return
+    clearInterval(intervalId)
+    intervalId = undefined
+  }
+
+  const scramble = (): void => {
+    const text = props.text
+    if (motionReduced()) {
+      setDisplay(text)
+      return
+    }
+
+    // Restart cleanly if a previous scramble (from a prior trigger) is still running.
+    stop()
+    const totalTicks = Math.max(1, Math.round((props.duration ?? 800) / TICK_MS))
+    let tick = 0
+
+    intervalId = setInterval(() => {
+      tick += 1
+
+      if (tick >= totalTicks) {
+        setDisplay(text)
+        stop()
+        return
+      }
+
+      const lockedCount = Math.floor((tick / totalTicks) * text.length)
+      setDisplay(
+        text
+          .split('')
+          .map((char, i) => (char === ' ' || i < lockedCount ? char : randomGlyph()))
+          .join(''),
+      )
+    }, TICK_MS)
+  }
+
+  onMount(() => {
+    if (props.trigger !== 'hover') scramble()
+  })
+  onCleanup(stop)
+
+  const handleMouseEnter = (): void => {
+    if (props.trigger === 'hover') scramble()
+  }
+
+  return (
+    <span class={cn('font-mono', props.class)} onMouseEnter={handleMouseEnter}>
+      {display()}
+    </span>
+  )
+}

package/src/ui/SegmentedControl.tsx

@@ -0,0 +1,61 @@
+// Single-choice segmented control on Kobalte's SegmentedControl primitive,
+// with an animated indicator sliding under the selected item.
+import { SegmentedControl as KSegmentedControl } from '@kobalte/core/segmented-control'
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single selectable choice within a {@link SegmentedControl}. */
+export interface SegmentedOption {
+  value: string
+  label: string
+}
+
+interface SegmentedControlProps {
+  value: string
+  onChange: (value: string) => void
+  options: SegmentedOption[]
+  class?: string
+}
+
+/**
+ * Single-choice segmented control with an animated indicator that slides
+ * under the selected item, built on Kobalte's `SegmentedControl` primitive.
+ * Use for a small, always-visible set of mutually exclusive options (e.g.
+ * view toggles) as a more compact alternative to {@link RadioGroup}.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   value={view()}
+ *   onChange={setView}
+ *   options={[
+ *     { value: 'list', label: 'List' },
+ *     { value: 'grid', label: 'Grid' },
+ *   ]}
+ * />
+ * ```
+ */
+export function SegmentedControl(props: SegmentedControlProps): JSX.Element {
+  return (
+    <KSegmentedControl
+      value={props.value}
+      onChange={props.onChange}
+      class={cn('relative inline-flex rounded-md border border-border bg-card p-1', props.class)}
+    >
+      <KSegmentedControl.Indicator class="absolute rounded-sm bg-primary shadow-sm transition-all" />
+      <For each={props.options}>
+        {(option) => (
+          <KSegmentedControl.Item
+            value={option.value}
+            class="relative z-10 flex cursor-pointer items-center px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors data-[selected]:text-primary-foreground"
+          >
+            <KSegmentedControl.ItemInput />
+            <KSegmentedControl.ItemLabel>{option.label}</KSegmentedControl.ItemLabel>
+          </KSegmentedControl.Item>
+        )}
+      </For>
+    </KSegmentedControl>
+  )
+}

package/src/ui/Select.tsx

@@ -0,0 +1,55 @@
+// Controlled native <select>.
+import type { JSX, ParentProps } from 'solid-js'
+import { createEffect, splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+const SELECT_BASE =
+  'w-full rounded-md border border-input bg-background text-foreground px-3 py-2 text-sm outline-none transition-colors a4-field'
+
+interface SelectProps
+  extends ParentProps, Omit<JSX.SelectHTMLAttributes<HTMLSelectElement>, 'value' | 'onChange'> {
+  value: string
+  onChange: (value: string) => void
+  class?: string
+}
+
+/**
+ * Controlled native `<select>`, styled to match the design system. Pass
+ * `<option>` elements as children. Not a Kobalte primitive — for a
+ * non-native, fully custom dropdown consider building on Kobalte's `Select`
+ * directly.
+ *
+ * @example
+ * ```tsx
+ * <Select value={country()} onChange={setCountry}>
+ *   <option value="mx">Mexico</option>
+ *   <option value="us">United States</option>
+ * </Select>
+ * ```
+ */
+export function Select(props: SelectProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['value', 'onChange', 'class', 'children'])
+  let el!: HTMLSelectElement
+  // A native <select> silently drops its value when the matching <option> isn't
+  // in the DOM yet — e.g. options loaded async, or the value set (edit form)
+  // before the options mount. The declarative `value` below covers the common
+  // case; this effect re-applies it whenever EITHER the value or the option set
+  // changes, so edit forms reliably pre-select.
+  createEffect(() => {
+    const v = local.value ?? ''
+    void local.children // track option changes
+    if (el && el.value !== v) el.value = v
+  })
+  return (
+    <select
+      ref={el}
+      class={cn(SELECT_BASE, local.class)}
+      value={local.value}
+      onChange={(ev) => local.onChange(ev.currentTarget.value)}
+      {...rest}
+    >
+      {local.children}
+    </select>
+  )
+}

package/src/ui/Separator.tsx

@@ -0,0 +1,39 @@
+// Visual/semantic divider on Kobalte's Separator primitive.
+import { Separator as KSeparator } from '@kobalte/core/separator'
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface SeparatorProps {
+  /** Default: `'horizontal'`. */
+  orientation?: 'horizontal' | 'vertical'
+  class?: string
+}
+
+/**
+ * Visual/semantic divider, built on Kobalte's `Separator` primitive (renders
+ * with the correct ARIA role for the given orientation). Use to separate
+ * groups of content, e.g. inside a menu or between toolbar sections.
+ *
+ * @example
+ * ```tsx
+ * <Separator orientation="vertical" />
+ * ```
+ */
+export function Separator(props: SeparatorProps): JSX.Element {
+  const orientation = () => props.orientation ?? 'horizontal'
+  // Kobalte's Separator renders an <hr>, which carries default block margins and
+  // a zero height that defeat `self-stretch` on the vertical variant — reset both
+  // (border-0 m-0) and give vertical a fallback min-height so it shows even when
+  // its flex parent doesn't stretch it.
+  return (
+    <KSeparator
+      orientation={orientation()}
+      class={cn(
+        'shrink-0 border-0 bg-border m-0',
+        orientation() === 'vertical' ? 'w-px min-h-4 h-full self-stretch' : 'h-px w-full',
+        props.class,
+      )}
+    />
+  )
+}

package/src/ui/Skeleton.tsx

@@ -0,0 +1,23 @@
+// Pulsing placeholder for loading content — plain div, no primitive.
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface SkeletonProps {
+  /** Size/shape the placeholder to match the content it stands in for, e.g. `"h-4 w-32 rounded-full"`. */
+  class?: string
+}
+
+/**
+ * Pulsing placeholder block for content that is still loading. Plain `div`,
+ * no Kobalte primitive — size it via `class` to match the shape of the real
+ * content (text line, avatar, card, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Skeleton class="h-4 w-48" />
+ * ```
+ */
+export function Skeleton(props: SkeletonProps): JSX.Element {
+  return <div class={cn('animate-pulse rounded-md bg-muted', props.class)} />
+}

package/src/ui/Slider.tsx

@@ -0,0 +1,57 @@
+// Single-value range slider on Kobalte's Slider primitive. Kobalte works in
+// arrays (multi-thumb); we wrap/unwrap the single value for a simpler API.
+import { Slider as KSlider } from '@kobalte/core/slider'
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface SliderProps {
+  value: number
+  onChange: (value: number) => void
+  /** Default: 0. */
+  min?: number
+  /** Default: 100. */
+  max?: number
+  /** Increment step. Default: 1. */
+  step?: number
+  /** Label shown above the track, paired with an auto-generated value label. */
+  label?: string
+  class?: string
+}
+
+/**
+ * Single-value range slider, built on Kobalte's `Slider` primitive (which
+ * natively supports multiple thumbs). This wrapper accepts and emits a plain
+ * `number` instead of an array, for a simpler single-thumb API.
+ *
+ * @example
+ * ```tsx
+ * <Slider label="Volume" value={volume()} onChange={setVolume} min={0} max={100} />
+ * ```
+ */
+export function Slider(props: SliderProps): JSX.Element {
+  return (
+    <KSlider
+      value={[props.value]}
+      onChange={(v) => props.onChange(v[0])}
+      minValue={props.min ?? 0}
+      maxValue={props.max ?? 100}
+      step={props.step ?? 1}
+      class={cn('flex flex-col gap-2', props.class)}
+    >
+      <Show when={props.label}>
+        <div class="flex items-center justify-between text-sm text-foreground">
+          <KSlider.Label>{props.label}</KSlider.Label>
+          <KSlider.ValueLabel class="text-muted-foreground" />
+        </div>
+      </Show>
+      <KSlider.Track class="relative h-1.5 w-full rounded-full bg-muted">
+        <KSlider.Fill class="absolute h-full rounded-full bg-primary" />
+        <KSlider.Thumb class="-top-1.5 block h-4 w-4 rounded-full bg-primary outline-none focus:ring-2 focus:ring-ring/40">
+          <KSlider.Input />
+        </KSlider.Thumb>
+      </KSlider.Track>
+    </KSlider>
+  )
+}

package/src/ui/Sortable.tsx

@@ -0,0 +1,174 @@
+// Generic drag-to-reorder list. Dragging is pointer-events based (mouse +
+// touch, no HTML5 drag/drop, no external lib): a grip handle starts the drag,
+// a floating clone follows the pointer through a Portal, and the grabbed
+// row's slot collapses into a dashed placeholder until it's dropped.
+import { createEffect, createSignal, For, Show, type JSX } from 'solid-js'
+import { Portal } from 'solid-js/web'
+import { GripVertical } from 'lucide-solid'
+
+import { cn } from '../lib/cn'
+
+export interface SortableProps<T> {
+  /** The items to render, in current order. */
+  items: T[]
+  /** Stable unique key for an item (used for drag tracking + list keying). */
+  itemKey: (item: T) => string
+  /** Render an item's content (the grip handle is added automatically to its left). */
+  children: (item: T) => JSX.Element
+  /** Called with the new order after a drop. */
+  onReorder: (items: T[]) => void
+  /** Disable dragging. */
+  disabled?: boolean
+  class?: string
+}
+
+interface Drag {
+  key: string
+  y: number
+  offset: number
+  height: number
+  width: number
+  left: number
+}
+
+/**
+ * Vertical list whose rows reorder by dragging a grip handle. Pointer-events
+ * driven (works with mouse and touch): the grabbed row leaves behind a dashed
+ * placeholder while a floating clone follows the pointer, and other rows shift
+ * live as the pointer crosses their midpoint. `onReorder` fires once on drop
+ * with the final order.
+ *
+ * @example
+ * ```tsx
+ * <Sortable
+ *   items={fields()}
+ *   itemKey={(f) => f.id}
+ *   onReorder={setFields}
+ * >
+ *   {(field) => <span>{field.label}</span>}
+ * </Sortable>
+ * ```
+ */
+export function Sortable<T>(props: SortableProps<T>): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- seed once; a createEffect below keeps it in sync
+  const [local, setLocal] = createSignal<T[]>(props.items)
+  const [drag, setDrag] = createSignal<Drag | null>(null)
+  let listRef: HTMLDivElement | undefined
+
+  createEffect(() => {
+    const next = props.items
+    if (!drag()) setLocal(next)
+  })
+
+  const onDragMove = (e: PointerEvent) => {
+    const d = drag()
+    if (!d || !listRef) return
+    setDrag({ ...d, y: e.clientY })
+    const rows = Array.from(listRef.querySelectorAll<HTMLElement>('[data-sortable-item]'))
+    let target = rows.length - 1
+    for (let i = 0; i < rows.length; i++) {
+      const r = rows[i].getBoundingClientRect()
+      if (e.clientY < r.top + r.height / 2) {
+        target = i
+        break
+      }
+    }
+    const cur = local()
+    const from = cur.findIndex((it) => props.itemKey(it) === d.key)
+    if (from === -1 || from === target) return
+    const next = cur.slice()
+    const [moved] = next.splice(from, 1)
+    next.splice(target, 0, moved)
+    setLocal(next)
+  }
+
+  const onDragStart = (e: PointerEvent, key: string) => {
+    if (props.disabled) return
+    e.preventDefault()
+    const row = (e.currentTarget as HTMLElement).closest('[data-sortable-item]') as HTMLElement | null
+    if (!row) return
+    const r = row.getBoundingClientRect()
+    setDrag({ key, y: e.clientY, offset: e.clientY - r.top, height: r.height, width: r.width, left: r.left })
+
+    const move = (ev: PointerEvent) => onDragMove(ev)
+    const up = () => {
+      window.removeEventListener('pointermove', move)
+      window.removeEventListener('pointerup', up)
+      const order = local()
+      const had = drag() !== null
+      setDrag(null)
+      if (had) props.onReorder(order)
+    }
+    window.addEventListener('pointermove', move)
+    window.addEventListener('pointerup', up)
+  }
+
+  const draggedItem = () => {
+    const d = drag()
+    if (!d) return undefined
+    return local().find((it) => props.itemKey(it) === d.key)
+  }
+
+  return (
+    <div ref={listRef} class={cn('flex flex-col gap-2', drag() && 'select-none', props.class)}>
+      <For each={local()} fallback={null}>
+        {(item) => {
+          const key = props.itemKey(item)
+          const isDragged = () => drag()?.key === key
+          return (
+            <Show
+              when={!isDragged()}
+              fallback={
+                <div
+                  data-sortable-item
+                  class="rounded-lg border-2 border-dashed border-primary/40 bg-primary/5"
+                  style={{ height: `${drag()?.height ?? 0}px` }}
+                />
+              }
+            >
+              <div
+                data-sortable-item
+                class="flex items-center gap-2 rounded-lg border border-border bg-card p-2"
+              >
+                <button
+                  type="button"
+                  onPointerDown={(e) => onDragStart(e, key)}
+                  style={{ 'touch-action': 'none' }}
+                  class="cursor-grab active:cursor-grabbing text-muted-foreground shrink-0"
+                  aria-label="Drag to reorder"
+                  disabled={props.disabled}
+                >
+                  <GripVertical class="h-4 w-4" />
+                </button>
+                <div class="min-w-0 flex-1">{props.children(item)}</div>
+              </div>
+            </Show>
+          )
+        }}
+      </For>
+      <Show when={drag()}>
+        {(d) => (
+          <Portal>
+            <div
+              class="fixed shadow-2xl flex items-center gap-2 rounded-lg border border-border bg-card p-2"
+              style={{
+                left: `${d().left}px`,
+                top: `${d().y - d().offset}px`,
+                width: `${d().width}px`,
+                'pointer-events': 'none',
+                'z-index': 70,
+              }}
+            >
+              <span class="text-muted-foreground shrink-0">
+                <GripVertical class="h-4 w-4" />
+              </span>
+              <div class="min-w-0 flex-1">
+                <Show when={draggedItem()}>{(item) => props.children(item())}</Show>
+              </div>
+            </div>
+          </Portal>
+        )}
+      </Show>
+    </div>
+  )
+}

package/src/ui/SpeedDial.tsx

@@ -0,0 +1,85 @@
+// Floating action button that fans a stack of actions upward when open.
+import { Plus } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** A single action in a {@link SpeedDial} — an icon button with an accessible label. */
+export interface SpeedDialAction {
+  icon: JSX.Element
+  label: string
+  onClick: () => void
+}
+
+export interface SpeedDialProps {
+  actions: SpeedDialAction[]
+  /** Icon for the main FAB. Defaults to a `Plus` that rotates to an ✕ when open. */
+  icon?: JSX.Element
+  class?: string
+}
+
+/**
+ * A fixed floating action button (FAB) pinned to the bottom-right. Clicking the
+ * main circular button toggles an open state; while open, `actions` fan out
+ * upward as a vertical stack of smaller circular buttons. Selecting an action
+ * runs its `onClick` and closes the dial. Theme-agnostic — colors come from
+ * semantic tokens only.
+ *
+ * @example
+ * ```tsx
+ * <SpeedDial actions={[
+ *   { icon: <Share class="h-5 w-5" />, label: 'Share', onClick: () => share() },
+ *   { icon: <Copy class="h-5 w-5" />, label: 'Copy', onClick: () => copy() },
+ * ]} />
+ * ```
+ */
+export function SpeedDial(props: SpeedDialProps): JSX.Element {
+  const [open, setOpen] = createSignal(false)
+
+  return (
+    <div class={cn('fixed bottom-6 right-6 z-40 flex flex-col items-center gap-3', props.class)}>
+      <Show when={open()}>
+        <div class="flex flex-col items-center gap-3">
+          <For each={props.actions}>
+            {(action, i) => (
+              <button
+                ref={(el) => {
+                  // Fan out with a staggered spring as the dial opens.
+                  if (!motionReduced())
+                    animate(
+                      el,
+                      { opacity: [0, 1], y: [12, 0], scale: [0.8, 1] },
+                      { type: 'spring', stiffness: 500, damping: 24, delay: i() * 0.05 },
+                    )
+                }}
+                type="button"
+                aria-label={action.label}
+                title={action.label}
+                onClick={() => {
+                  action.onClick()
+                  setOpen(false)
+                }}
+                class="flex h-11 w-11 items-center justify-center rounded-full border border-border bg-card text-foreground shadow hover:bg-muted focus:outline-none focus:ring-2 focus:ring-ring"
+              >
+                {action.icon}
+              </button>
+            )}
+          </For>
+        </div>
+      </Show>
+      <button
+        type="button"
+        aria-label={open() ? 'Close actions' : 'Open actions'}
+        aria-expanded={open()}
+        onClick={() => setOpen((v) => !v)}
+        class="flex h-14 w-14 items-center justify-center rounded-full bg-primary text-primary-foreground shadow-lg transition-transform duration-150 active:scale-[0.97] focus:outline-none focus:ring-2 focus:ring-ring"
+      >
+        <span class={cn('inline-flex transition-transform duration-150', open() && 'rotate-45')}>
+          {props.icon ?? <Plus class="h-6 w-6" />}
+        </span>
+      </button>
+    </div>
+  )
+}

package/src/ui/Spinner.tsx

@@ -0,0 +1,33 @@
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface SpinnerProps {
+  class?: string
+  /** Accessible label announced to screen readers via `aria-label`. Default: `'Loading'`. */
+  label?: string
+}
+
+/**
+ * Small spinning loading indicator (inline SVG, no primitive). Use for
+ * indeterminate loading states such as button/inline busy states.
+ *
+ * @example
+ * ```tsx
+ * <Spinner label="Saving" />
+ * ```
+ */
+export function Spinner(props: SpinnerProps): JSX.Element {
+  return (
+    <svg
+      class={cn('h-5 w-5 animate-spin text-muted-foreground', props.class)}
+      viewBox="0 0 24 24"
+      fill="none"
+      role="status"
+      aria-label={props.label ?? 'Loading'}
+    >
+      <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
+      <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+    </svg>
+  )
+}