@a4ui/core 0.11.1 → 0.12.0

package/src/ui/RingProgress.tsx

@@ -0,0 +1,75 @@
+// Circular (radial) progress ring rendered as an SVG with a centered label.
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface RingProgressProps {
+  value: number
+  /** Outer diameter of the ring in px. @default 96 */
+  size?: number
+  /** Stroke width of the track and arc in px. @default 8 */
+  thickness?: number
+  /** Content centered over the ring. Defaults to the rounded percent. */
+  label?: JSX.Element
+  class?: string
+}
+
+/**
+ * Circular progress indicator drawn with two concentric SVG circles: a muted
+ * track and a primary arc whose length is derived from `value` (0–100). Use for
+ * compact, radial completion feedback where a linear bar would be too wide.
+ *
+ * @example
+ * ```tsx
+ * <RingProgress value={72} />
+ * <RingProgress value={40} size={128} thickness={12} label={<span>4/10</span>} />
+ * ```
+ */
+export function RingProgress(props: RingProgressProps): JSX.Element {
+  const size = () => props.size ?? 96
+  const thickness = () => props.thickness ?? 8
+  const clamped = () => Math.min(100, Math.max(0, props.value))
+  const radius = () => (size() - thickness()) / 2
+  const circumference = () => 2 * Math.PI * radius()
+  const offset = () => circumference() * (1 - clamped() / 100)
+
+  return (
+    <div
+      role="progressbar"
+      aria-valuenow={clamped()}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      class={cn('relative inline-flex items-center justify-center', props.class)}
+      style={{ width: `${size()}px`, height: `${size()}px` }}
+    >
+      <svg width={size()} height={size()} viewBox={`0 0 ${size()} ${size()}`} class="-rotate-90">
+        <circle
+          cx={size() / 2}
+          cy={size() / 2}
+          r={radius()}
+          fill="none"
+          stroke="hsl(var(--muted))"
+          stroke-width={thickness()}
+        />
+        <circle
+          cx={size() / 2}
+          cy={size() / 2}
+          r={radius()}
+          fill="none"
+          stroke="hsl(var(--primary))"
+          stroke-width={thickness()}
+          stroke-linecap="round"
+          stroke-dasharray={String(circumference())}
+          stroke-dashoffset={String(offset())}
+          class="transition-all"
+        />
+      </svg>
+      <div class="absolute inset-0 flex items-center justify-center text-sm font-medium text-foreground">
+        <Show when={props.label} fallback={`${Math.round(clamped())}%`}>
+          {props.label}
+        </Show>
+      </div>
+    </div>
+  )
+}

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,75 @@
+// 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'
+
+/** 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) => (
+              <button
+                type="button"
+                aria-label={action.label}
+                title={action.label}
+                onClick={() => {
+                  action.onClick()
+                  setOpen(false)
+                }}
+                class="flex h-11 w-11 translate-y-0 items-center justify-center rounded-full border border-border bg-card text-foreground opacity-100 shadow transition-[opacity,transform] duration-150 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>
+  )
+}