@a4ui/core 0.11.1 → 0.13.0

package/src/ui/CalendarHeatmap.tsx

@@ -0,0 +1,180 @@
+// GitHub-contributions-style activity grid: the last `weeks` weeks rendered as
+// columns of 7 Sun→Sat day-cells, each shaded into one of 5 intensity buckets by
+// its count. Plain Solid + theme tokens (works in light/dark) — level 0 is
+// `bg-muted`, levels 1–4 are `bg-primary` at rising opacity via a static class
+// map (never computed classes). Native `title` gives a hover tooltip per day.
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single day's activity count, keyed by an ISO `YYYY-MM-DD` date. */
+export interface HeatmapValue {
+  date: string
+  count: number
+}
+
+export interface CalendarHeatmapProps {
+  /** Activity counts to plot; dates outside the visible range are ignored. */
+  values: HeatmapValue[]
+  /** Number of week-columns to show, ending on today. Default 26. */
+  weeks?: number
+  class?: string
+}
+
+// Level 0 uses the neutral muted token; levels 1–4 tint the primary token at
+// increasing opacity. Kept as a literal map so Tailwind can see every class.
+const LEVEL_CLASSES = ['bg-muted', 'bg-primary/25', 'bg-primary/45', 'bg-primary/70', 'bg-primary'] as const
+
+// Layout constants (px): cell size + inter-cell gap → column/row pitch. Month
+// labels are absolutely positioned by column pitch; weekday labels by row pitch.
+const CELL = 11
+const GAP = 4
+const PITCH = CELL + GAP
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] as const
+// Weekday labels: only Mon/Wed/Fri are shown (rows 1/3/5, Sun=0), GitHub-style.
+const WEEKDAYS = ['', 'Mon', '', 'Wed', '', 'Fri', ''] as const
+
+/** Bucket a raw count into an intensity level 0..4. */
+function levelFor(count: number): number {
+  if (count <= 0) return 0
+  if (count <= 2) return 1
+  if (count <= 5) return 2
+  if (count <= 9) return 3
+  return 4
+}
+
+/** Local-time `YYYY-MM-DD` key for a Date. */
+function isoKey(d: Date): string {
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+/**
+ * GitHub-contributions-style heatmap: a grid of the last `weeks` weeks ending
+ * today, laid out as columns (one per week) of 7 vertically-stacked day-cells
+ * (Sun→Sat). Each cell is shaded by its count into 5 intensity levels and shows
+ * a native tooltip like "3 on 2026-07-10". A "Less … More" legend sits below.
+ * Theme-agnostic (semantic tokens only).
+ *
+ * @example
+ * ```tsx
+ * <CalendarHeatmap values={[{ date: '2026-07-10', count: 3 }]} weeks={26} />
+ * ```
+ */
+export function CalendarHeatmap(props: CalendarHeatmapProps): JSX.Element {
+  const weeks = () => props.weeks ?? 26
+
+  // date -> count lookup from the provided values.
+  const counts = () => {
+    const map = new Map<string, number>()
+    for (const v of props.values) map.set(v.date, (map.get(v.date) ?? 0) + v.count)
+    return map
+  }
+
+  // Build `weeks` columns ending on the week that contains today. The grid ends
+  // on the Saturday of the current week; column 0 is the earliest week.
+  const columns = () => {
+    const lookup = counts()
+    const today = new Date()
+    // Start of the current week (Sunday), then step back to the first column.
+    const currentSunday = new Date(today.getFullYear(), today.getMonth(), today.getDate() - today.getDay())
+    const cols: { date: Date; count: number; level: number; key: string }[][] = []
+    for (let w = 0; w < weeks(); w++) {
+      const weekOffset = (weeks() - 1 - w) * 7
+      const col: { date: Date; count: number; level: number; key: string }[] = []
+      for (let d = 0; d < 7; d++) {
+        const date = new Date(
+          currentSunday.getFullYear(),
+          currentSunday.getMonth(),
+          currentSunday.getDate() - weekOffset + d,
+        )
+        const key = isoKey(date)
+        const count = lookup.get(key) ?? 0
+        col.push({ date, count, level: levelFor(count), key })
+      }
+      cols.push(col)
+    }
+    return cols
+  }
+
+  // A month label at each column where a new month begins (top/Sunday cell).
+  const monthLabels = () => {
+    const cols = columns()
+    const labels: { index: number; label: string }[] = []
+    let prevMonth = -1
+    cols.forEach((col, i) => {
+      const month = col[0].date.getMonth()
+      if (month !== prevMonth) {
+        labels.push({ index: i, label: MONTHS[month] })
+        prevMonth = month
+      }
+    })
+    return labels
+  }
+
+  // Width reserved for the weekday label gutter (left of the grid).
+  const gutter = 28
+
+  return (
+    <div class={cn('inline-flex flex-col gap-2', props.class)}>
+      {/* Month labels, positioned by column so they sit over the right week. */}
+      <div class="relative h-4 text-[9px] text-muted-foreground" style={{ 'margin-left': `${gutter}px` }}>
+        <For each={monthLabels()}>
+          {(m) => (
+            <span class="absolute top-0 whitespace-nowrap" style={{ left: `${m.index * PITCH}px` }}>
+              {m.label}
+            </span>
+          )}
+        </For>
+      </div>
+
+      <div class="flex" style={{ gap: `${GAP}px` }}>
+        {/* Weekday gutter (Mon/Wed/Fri), aligned to the day rows. */}
+        <div
+          class="flex flex-col justify-between pr-1 text-right text-[9px] leading-none text-muted-foreground"
+          style={{ gap: `${GAP}px`, width: `${gutter}px` }}
+        >
+          <For each={WEEKDAYS}>
+            {(day) => (
+              <span class="flex items-center justify-end" style={{ height: `${CELL}px` }}>
+                {day}
+              </span>
+            )}
+          </For>
+        </div>
+
+        <For each={columns()}>
+          {(col) => (
+            <div class="flex flex-col" style={{ gap: `${GAP}px` }}>
+              <For each={col}>
+                {(cell) => (
+                  <div
+                    title={`${cell.count} on ${cell.key}`}
+                    class={cn('rounded-sm', LEVEL_CLASSES[cell.level])}
+                    style={{ height: `${CELL}px`, width: `${CELL}px` }}
+                  />
+                )}
+              </For>
+            </div>
+          )}
+        </For>
+      </div>
+
+      <div
+        class="flex items-center gap-1 text-xs text-muted-foreground"
+        style={{ 'margin-left': `${gutter}px` }}
+      >
+        <span>Less</span>
+        <For each={LEVEL_CLASSES}>
+          {(levelClass) => (
+            <div class={cn('rounded-sm', levelClass)} style={{ height: `${CELL}px`, width: `${CELL}px` }} />
+          )}
+        </For>
+        <span>More</span>
+      </div>
+    </div>
+  )
+}

package/src/ui/Card.tsx

@@ -0,0 +1,84 @@
+// Card + 4 sub-parts (no CardFooter/CardDescription — add if needed).
+import type { JSX, ParentProps } from 'solid-js'
+import { splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface DivProps extends ParentProps {
+  class?: string
+}
+
+interface CardProps extends DivProps {
+  /** Frosted "space glass" surface (`.card`) instead of the opaque default. */
+  glass?: boolean
+  /**
+   * Cursor-following edge glow (only meaningful with `glass`). Defaults to ON
+   * for glass cards so the look is uniform; pass `glow={false}` to opt out.
+   */
+  glow?: boolean
+}
+
+/**
+ * Container surface for grouping related content, with an optional frosted
+ * "space glass" look. Compose with {@link CardHeader}, {@link CardTitle}, and
+ * {@link CardContent}.
+ *
+ * @example
+ * ```tsx
+ * <Card glass>
+ *   <CardHeader>
+ *     <CardTitle>Usage</CardTitle>
+ *   </CardHeader>
+ *   <CardContent>1,204 requests today</CardContent>
+ * </Card>
+ * ```
+ */
+export function Card(props: CardProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children', 'glass', 'glow'])
+  // Glow defaults to the card's glass state when not explicitly set.
+  const showGlow = () => (local.glow ?? local.glass) === true
+  return (
+    <div
+      class={cn(
+        local.glass
+          ? 'card rounded-xl text-card-foreground'
+          : 'rounded-xl border border-border bg-card text-card-foreground shadow-sm',
+        showGlow() && 'glow-edge',
+        local.class,
+      )}
+      {...rest}
+    >
+      {local.children}
+    </div>
+  )
+}
+
+/** Header region of a {@link Card}; typically wraps a {@link CardTitle}. */
+export function CardHeader(props: DivProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <div class={cn('flex flex-col space-y-1.5 p-6', local.class)} {...rest}>
+      {local.children}
+    </div>
+  )
+}
+
+/** Heading text (rendered as an `<h2>`) for a {@link Card}. */
+export function CardTitle(props: DivProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <h2 class={cn('text-lg font-semibold leading-none tracking-tight', local.class)} {...rest}>
+      {local.children}
+    </h2>
+  )
+}
+
+/** Main body region of a {@link Card}, below the header. */
+export function CardContent(props: DivProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <div class={cn('p-6 pt-0', local.class)} {...rest}>
+      {local.children}
+    </div>
+  )
+}

package/src/ui/Carousel.tsx

@@ -0,0 +1,121 @@
+// Single-slide carousel: a translateX track that slides horizontally between
+// slides with a CSS transition, arrow + dot controls, keyboard navigation, and
+// optional hover-pausing autoplay (gated on prefers-reduced-motion via the
+// shared `motionReduced` helper).
+import { ChevronLeft, ChevronRight } from 'lucide-solid'
+import { For, createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface CarouselProps {
+  /** Slides to page through, one visible at a time. */
+  slides: JSX.Element[]
+  /** Auto-advance interval in ms. Omit to disable autoplay (also skipped under reduced motion / hover). */
+  autoplayMs?: number
+  class?: string
+}
+
+/**
+ * Horizontally-sliding carousel that shows one slide at a time inside a rounded,
+ * overflow-hidden viewport. Includes wrapping prev/next arrow buttons, a row of
+ * dot indicators, Left/Right arrow-key navigation when focused, and optional
+ * autoplay that pauses on hover and is disabled under `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * <Carousel
+ *   autoplayMs={4000}
+ *   slides={[<img src="/a.jpg" />, <img src="/b.jpg" />, <img src="/c.jpg" />]}
+ * />
+ * ```
+ */
+export function Carousel(props: CarouselProps): JSX.Element {
+  const [index, setIndex] = createSignal(0)
+  const count = (): number => props.slides.length
+
+  const go = (to: number): void => {
+    const n = count()
+    if (n === 0) return
+    setIndex(((to % n) + n) % n)
+  }
+  const prev = (): void => go(index() - 1)
+  const next = (): void => go(index() + 1)
+
+  const onKeyDown = (e: KeyboardEvent): void => {
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault()
+      prev()
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault()
+      next()
+    }
+  }
+
+  // --- autoplay (paused on hover, skipped under reduced motion) --------------
+  const [paused, setPaused] = createSignal(false)
+  onMount(() => {
+    if (props.autoplayMs === undefined || motionReduced()) return
+    const timer = setInterval(() => {
+      if (!paused()) next()
+    }, props.autoplayMs)
+    onCleanup(() => clearInterval(timer))
+  })
+
+  return (
+    <div
+      role="region"
+      aria-roledescription="carousel"
+      tabindex="0"
+      class={cn(
+        'flex flex-col gap-3 outline-none focus-visible:ring-2 focus-visible:ring-primary',
+        props.class,
+      )}
+      onKeyDown={onKeyDown}
+      onPointerEnter={() => setPaused(true)}
+      onPointerLeave={() => setPaused(false)}
+    >
+      <div class="relative overflow-hidden rounded-xl border border-border bg-card text-foreground">
+        <div
+          class="flex transition-transform duration-500 ease-out"
+          style={{ transform: `translateX(-${index() * 100}%)` }}
+        >
+          <For each={props.slides}>{(slide) => <div class="w-full shrink-0">{slide}</div>}</For>
+        </div>
+
+        <button
+          type="button"
+          aria-label="Previous slide"
+          onClick={prev}
+          class="absolute left-2 top-1/2 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full bg-primary text-primary-foreground shadow transition-opacity hover:opacity-90"
+        >
+          <ChevronLeft class="h-5 w-5" />
+        </button>
+        <button
+          type="button"
+          aria-label="Next slide"
+          onClick={next}
+          class="absolute right-2 top-1/2 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full bg-primary text-primary-foreground shadow transition-opacity hover:opacity-90"
+        >
+          <ChevronRight class="h-5 w-5" />
+        </button>
+      </div>
+
+      <div class="flex items-center justify-center gap-2">
+        <For each={props.slides}>
+          {(_, i) => (
+            <button
+              type="button"
+              aria-label={`Go to slide ${i() + 1}`}
+              onClick={() => go(i())}
+              class={cn(
+                'h-2 w-2 rounded-full transition-colors',
+                index() === i() ? 'bg-primary' : 'bg-muted',
+              )}
+            />
+          )}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/ui/Cascader.tsx

@@ -0,0 +1,158 @@
+// Cascading multi-level select — pick a value by drilling through columns.
+import { ChevronDown, ChevronRight } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { For, Show, createMemo, createSignal, onCleanup, onMount } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A node in a {@link Cascader} tree. `children` makes it a branch column. */
+export interface CascaderOption {
+  value: string
+  label: string
+  children?: CascaderOption[]
+}
+
+export interface CascaderProps {
+  options: CascaderOption[]
+  /** The currently selected value-path (root → leaf). */
+  value?: string[]
+  /** Fired when a leaf is chosen, with the full value-path and label-path. */
+  onChange: (path: string[], labels: string[]) => void
+  placeholder?: string
+  class?: string
+}
+
+const TRIGGER_BASE =
+  'flex w-full items-center justify-between gap-2 rounded-md border border-input bg-background text-foreground px-3 py-2 text-sm outline-none transition-colors a4-field'
+
+// Walk the tree along `value`, collecting the matched options so we can resolve
+// their labels. Stops early if the path diverges from the current options.
+function resolvePath(options: CascaderOption[], value: string[]): CascaderOption[] {
+  const chain: CascaderOption[] = []
+  let level: CascaderOption[] | undefined = options
+  for (const v of value) {
+    const match: CascaderOption | undefined = level?.find((o) => o.value === v)
+    if (!match) break
+    chain.push(match)
+    level = match.children
+  }
+  return chain
+}
+
+/**
+ * Cascading multi-level select. Renders a Select-styled trigger showing the
+ * selected path (labels joined with " / "); clicking opens a floating panel of
+ * side-by-side columns. Hovering an option with children reveals the next
+ * column; clicking a leaf commits the selection and closes the panel.
+ *
+ * @example
+ * ```tsx
+ * <Cascader
+ *   options={[
+ *     { value: 'mx', label: 'Mexico', children: [
+ *       { value: 'son', label: 'Sonora' },
+ *       { value: 'jal', label: 'Jalisco' },
+ *     ] },
+ *   ]}
+ *   value={path()}
+ *   onChange={(p, labels) => { setPath(p); console.log(labels.join(' / ')) }}
+ *   placeholder="Select a region"
+ * />
+ * ```
+ */
+export function Cascader(props: CascaderProps): JSX.Element {
+  const [open, setOpen] = createSignal(false)
+  // The chain of options hovered/chosen so far — drives which columns show.
+  const [activePath, setActivePath] = createSignal<CascaderOption[]>([])
+  let root!: HTMLDivElement
+
+  const selected = createMemo(() => resolvePath(props.options, props.value ?? []))
+  const selectedLabel = createMemo(() =>
+    selected()
+      .map((o) => o.label)
+      .join(' / '),
+  )
+
+  // Columns to render: level 0 is the root, each further level is the children
+  // of the corresponding option on the active path (if it has any).
+  const columns = createMemo(() => {
+    const cols: CascaderOption[][] = [props.options]
+    for (const opt of activePath()) {
+      if (opt.children && opt.children.length) cols.push(opt.children)
+      else break
+    }
+    return cols
+  })
+
+  const onDocClick = (ev: MouseEvent) => {
+    if (root && !root.contains(ev.target as Node)) setOpen(false)
+  }
+  onMount(() => document.addEventListener('mousedown', onDocClick))
+  onCleanup(() => document.removeEventListener('mousedown', onDocClick))
+
+  function toggle() {
+    if (!open()) setActivePath(selected())
+    setOpen((o) => !o)
+  }
+
+  // Set the active path up to (and including) `opt` at `colIndex`.
+  function enter(colIndex: number, opt: CascaderOption) {
+    setActivePath([...activePath().slice(0, colIndex), opt])
+  }
+
+  function choose(colIndex: number, opt: CascaderOption) {
+    enter(colIndex, opt)
+    if (opt.children && opt.children.length) return
+    const chain = [...activePath().slice(0, colIndex), opt]
+    props.onChange(
+      chain.map((o) => o.value),
+      chain.map((o) => o.label),
+    )
+    setOpen(false)
+  }
+
+  return (
+    <div ref={root} class={cn('relative inline-block', props.class)}>
+      <button type="button" class={TRIGGER_BASE} aria-haspopup="true" aria-expanded={open()} onClick={toggle}>
+        <Show
+          when={selectedLabel()}
+          fallback={<span class="text-muted-foreground">{props.placeholder}</span>}
+        >
+          <span class="truncate">{selectedLabel()}</span>
+        </Show>
+        <ChevronDown class="h-4 w-4 shrink-0 opacity-60" />
+      </button>
+      <Show when={open()}>
+        <div class="absolute z-50 mt-1 flex overflow-hidden rounded-md border border-border bg-card text-card-foreground shadow-md">
+          <For each={columns()}>
+            {(column, colIndex) => (
+              <ul class="min-w-[10rem] max-h-64 overflow-y-auto border-r border-border p-1 last:border-r-0">
+                <For each={column}>
+                  {(opt) => {
+                    const hasChildren = () => !!opt.children && opt.children.length > 0
+                    const isActive = () => activePath()[colIndex()]?.value === opt.value
+                    return (
+                      <li
+                        class={cn(
+                          'flex items-center justify-between gap-4 rounded px-2 py-1.5 text-sm hover:bg-muted cursor-pointer',
+                          isActive() && 'bg-muted text-foreground',
+                        )}
+                        onMouseEnter={() => hasChildren() && enter(colIndex(), opt)}
+                        onClick={() => choose(colIndex(), opt)}
+                      >
+                        <span class="truncate">{opt.label}</span>
+                        <Show when={hasChildren()}>
+                          <ChevronRight class="h-4 w-4 shrink-0 opacity-60" />
+                        </Show>
+                      </li>
+                    )
+                  }}
+                </For>
+              </ul>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  )
+}

package/src/ui/Checkbox.tsx

@@ -0,0 +1,35 @@
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface CheckboxProps {
+  checked: boolean
+  /** Called with the new checked state whenever the input is toggled. */
+  onChange: (checked: boolean) => void
+  /** Visible label rendered next to the checkbox; also makes the whole row clickable. */
+  label: string
+  class?: string
+}
+
+/**
+ * Plain labeled checkbox (native `<input type="checkbox">`, not a Kobalte
+ * wrapper) for simple boolean toggles with a visible label.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={agreed()} onChange={setAgreed} label="I agree to the terms" />
+ * ```
+ */
+export function Checkbox(props: CheckboxProps): JSX.Element {
+  return (
+    <label class={cn('inline-flex items-center gap-2 text-sm text-foreground', props.class)}>
+      <input
+        type="checkbox"
+        class="h-4 w-4 rounded border-input accent-primary"
+        checked={props.checked}
+        onChange={(ev) => props.onChange(ev.currentTarget.checked)}
+      />
+      {props.label}
+    </label>
+  )
+}