@a4ui/core 0.11.1 → 0.12.0

package/src/ui/AlertDialog.tsx

@@ -0,0 +1,58 @@
+// Confirmation dialog on Kobalte's AlertDialog primitive — centered modal,
+// reuses the modal-overlay/modal-content keyframes from styles.css.
+import { AlertDialog as KAlertDialog } from '@kobalte/core/alert-dialog'
+import type { JSX, ParentProps } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface AlertDialogProps extends ParentProps {
+  /** Whether the dialog is currently visible. */
+  open: boolean
+  /** Called when the dialog requests to open/close (overlay click, Escape, etc). */
+  onOpenChange: (open: boolean) => void
+  /** Optional heading rendered above the description. */
+  title?: string
+  class?: string
+}
+
+/**
+ * Centered, focus-trapped confirmation modal built on Kobalte's `AlertDialog`
+ * primitive. Use for interruptive confirmations (e.g. "Delete this item?")
+ * rather than for general-purpose dialogs.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialog open={confirmOpen()} onOpenChange={setConfirmOpen} title="Delete project?">
+ *   This action cannot be undone.
+ * </AlertDialog>
+ * ```
+ */
+export function AlertDialog(props: AlertDialogProps): JSX.Element {
+  return (
+    <KAlertDialog open={props.open} onOpenChange={props.onOpenChange}>
+      <KAlertDialog.Portal>
+        <KAlertDialog.Overlay class="modal-overlay 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">
+          <KAlertDialog.Content
+            class={cn(
+              'modal-content w-full max-w-md rounded-xl border border-border bg-card text-card-foreground shadow-sm',
+              props.class,
+            )}
+          >
+            <div class="p-6">
+              <Show when={props.title}>
+                <KAlertDialog.Title class="text-lg font-semibold leading-none tracking-tight">
+                  {props.title}
+                </KAlertDialog.Title>
+              </Show>
+              <KAlertDialog.Description class="mt-3 text-sm text-muted-foreground">
+                {props.children}
+              </KAlertDialog.Description>
+            </div>
+          </KAlertDialog.Content>
+        </div>
+      </KAlertDialog.Portal>
+    </KAlertDialog>
+  )
+}

package/src/ui/Anchor.tsx

@@ -0,0 +1,100 @@
+// Anchor — a table-of-contents nav with scroll-spy. An IntersectionObserver
+// (bound in onMount, client-only, so it's SSR-safe) tracks which section is in
+// view and highlights the matching link; clicks smooth-scroll to the target.
+import type { JSX } from 'solid-js'
+import { createSignal, For, onCleanup, onMount } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface AnchorItem {
+  /** The `id` of the section element this link points to. */
+  id: string
+  /** Text shown for the link. */
+  label: string
+}
+
+export interface AnchorProps {
+  /** Ordered list of sections to build the table of contents from. */
+  items: AnchorItem[]
+  class?: string
+}
+
+/**
+ * A vertical table-of-contents nav with scroll-spy. Each item links to a page
+ * section by `id`; the link whose section is topmost in the viewport is marked
+ * active. Clicking a link smooth-scrolls to its section.
+ *
+ * @example
+ * ```tsx
+ * <Anchor
+ *   items={[
+ *     { id: 'intro', label: 'Introduction' },
+ *     { id: 'usage', label: 'Usage' },
+ *   ]}
+ * />
+ * ```
+ */
+export function Anchor(props: AnchorProps): JSX.Element {
+  const [activeId, setActiveId] = createSignal<string>()
+
+  onMount(() => {
+    // Track which observed sections are currently intersecting, then pick the
+    // one nearest the top of the document as the active anchor.
+    const visible = new Map<string, number>()
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const id = entry.target.id
+          if (entry.isIntersecting) visible.set(id, entry.boundingClientRect.top)
+          else visible.delete(id)
+        }
+        let topId: string | undefined
+        let topOffset = Infinity
+        for (const [id, offset] of visible) {
+          if (offset < topOffset) {
+            topOffset = offset
+            topId = id
+          }
+        }
+        if (topId) setActiveId(topId)
+      },
+      { rootMargin: '0px 0px -70% 0px' },
+    )
+
+    for (const item of props.items) {
+      const el = document.getElementById(item.id)
+      if (el) observer.observe(el)
+    }
+
+    onCleanup(() => observer.disconnect())
+  })
+
+  const onClick = (e: MouseEvent, id: string) => {
+    e.preventDefault()
+    document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' })
+    setActiveId(id)
+  }
+
+  return (
+    <nav class={cn('flex flex-col gap-0.5', props.class)}>
+      <For each={props.items}>
+        {(item) => (
+          <a
+            href={'#' + item.id}
+            onClick={(e) => onClick(e, item.id)}
+            aria-current={activeId() === item.id ? 'true' : undefined}
+            class={cn(
+              'block rounded px-3 py-1.5 text-sm transition-colors',
+              activeId() === item.id
+                ? 'border-l-2 border-primary font-medium text-primary'
+                : 'text-muted-foreground hover:text-foreground',
+            )}
+          >
+            {item.label}
+          </a>
+        )}
+      </For>
+    </nav>
+  )
+}

package/src/ui/Avatar.tsx

@@ -0,0 +1,34 @@
+// User avatar on Kobalte's Image primitive — shows the image or initials fallback.
+import { Image as KImage } from '@kobalte/core/image'
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface AvatarProps {
+  /** Image URL. If it fails to load (or is omitted), `fallback` is shown instead. */
+  src?: string
+  alt?: string
+  /** Text shown when there is no image or it fails to load (typically initials). */
+  fallback: string
+  class?: string
+}
+
+/**
+ * Circular user avatar built on Kobalte's `Image` primitive; automatically
+ * falls back to initials/text when the image is missing or fails to load.
+ *
+ * @example
+ * ```tsx
+ * <Avatar src={user.avatarUrl} alt={user.name} fallback="JD" />
+ * ```
+ */
+export function Avatar(props: AvatarProps): JSX.Element {
+  return (
+    <KImage class={cn('inline-flex h-9 w-9 shrink-0 overflow-hidden rounded-full bg-muted', props.class)}>
+      <KImage.Img src={props.src} alt={props.alt} class="h-full w-full object-cover" />
+      <KImage.Fallback class="grid h-full w-full place-items-center text-xs font-medium text-muted-foreground">
+        {props.fallback}
+      </KImage.Fallback>
+    </KImage>
+  )
+}

package/src/ui/AvatarGroup.tsx

@@ -0,0 +1,55 @@
+// Overlapping stack of avatars with a "+N" overflow counter past `max`.
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Avatar } from './Avatar'
+
+export interface AvatarGroupProps {
+  avatars: { src?: string; fallback: string; alt?: string }[]
+  /** Maximum number of avatars to render before collapsing the rest into `+N`. */
+  max?: number
+  class?: string
+}
+
+/**
+ * Renders a row of overlapping {@link Avatar}s. When there are more avatars than
+ * `max` (default 4), the remainder collapse into a trailing `+N` counter.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup
+ *   max={3}
+ *   avatars={[
+ *     { src: a.avatarUrl, alt: a.name, fallback: 'AA' },
+ *     { src: b.avatarUrl, alt: b.name, fallback: 'BB' },
+ *     { fallback: 'CC' },
+ *     { fallback: 'DD' },
+ *   ]}
+ * />
+ * ```
+ */
+export function AvatarGroup(props: AvatarGroupProps): JSX.Element {
+  const max = () => props.max ?? 4
+  const shown = () => props.avatars.slice(0, max())
+  const overflow = () => props.avatars.length - shown().length
+
+  return (
+    <div class={cn('flex items-center', props.class)}>
+      <For each={shown()}>
+        {(avatar, index) => (
+          <div class={cn('ring-2 ring-background rounded-full', index() > 0 && '-ml-2')}>
+            <Avatar src={avatar.src} alt={avatar.alt} fallback={avatar.fallback} />
+          </div>
+        )}
+      </For>
+      {overflow() > 0 && (
+        <div class="-ml-2 ring-2 ring-background rounded-full">
+          <span class="grid h-9 w-9 shrink-0 place-items-center rounded-full bg-muted text-xs font-medium text-muted-foreground">
+            +{overflow()}
+          </span>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/ui/BackToTop.tsx

@@ -0,0 +1,51 @@
+// BackToTop — a fixed circular button that scrolls the window back to the top.
+// Only appears once the page has scrolled past `threshold` px. Listener is bound
+// in onMount (client-only), so it's SSR-safe.
+import type { JSX } from 'solid-js'
+import { createSignal, onCleanup, onMount, Show } from 'solid-js'
+import { ArrowUp } from 'lucide-solid'
+
+import { cn } from '../lib/cn'
+
+export interface BackToTopProps {
+  /** Scroll distance (px) after which the button appears. Defaults to `300`. */
+  threshold?: number
+  class?: string
+}
+
+/**
+ * A floating "scroll to top" button, fixed to the bottom-right of the viewport.
+ * It fades in once the user scrolls past `threshold` and smooth-scrolls back up
+ * on click.
+ *
+ * @example
+ * ```tsx
+ * <BackToTop threshold={500} />
+ * ```
+ */
+export function BackToTop(props: BackToTopProps): JSX.Element {
+  const [visible, setVisible] = createSignal(false)
+
+  onMount(() => {
+    const onScroll = () => setVisible(window.scrollY > (props.threshold ?? 300))
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    onCleanup(() => window.removeEventListener('scroll', onScroll))
+  })
+
+  return (
+    <Show when={visible()}>
+      <button
+        type="button"
+        aria-label="Back to top"
+        onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}
+        class={cn(
+          'fixed bottom-6 right-6 z-40 grid h-11 w-11 place-items-center rounded-full bg-primary text-primary-foreground shadow-lg',
+          props.class,
+        )}
+      >
+        <ArrowUp class="h-5 w-5" />
+      </button>
+    </Show>
+  )
+}

package/src/ui/Badge.tsx

@@ -0,0 +1,46 @@
+// Badge — generic tone pill. The app-specific tone/label mappers
+// (flowBadgeProps, statusBadgeTone, priorityBadgeTone, …) stay in the consuming
+// app: they encode business vocabulary (income/expense, project priority, user
+// roles), not design-system concerns.
+import { type JSX, type ParentProps, splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** Semantic tone of a {@link Badge}; drives its background/text/ring color. */
+export type BadgeTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info'
+
+const TONE_CLASSES: Record<BadgeTone, string> = {
+  neutral: 'bg-muted text-muted-foreground ring-border',
+  success: 'bg-emerald-500/15 text-emerald-600 ring-emerald-500/30',
+  warning: 'bg-amber-500/15 text-amber-600 ring-amber-500/30',
+  danger: 'bg-rose-500/15 text-rose-600 ring-rose-500/30',
+  info: 'bg-sky-500/15 text-sky-600 ring-sky-500/30',
+}
+
+const BADGE_BASE =
+  'badge inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-semibold ring-1 ring-inset whitespace-nowrap'
+
+interface BadgeProps extends ParentProps {
+  /** Visual/semantic tone. Defaults to `'neutral'`. */
+  tone?: BadgeTone
+  class?: string
+}
+
+/**
+ * Small rounded pill for status/labels, e.g. counts, states, or tags.
+ * Generic design-system primitive — app-specific tone mappers (e.g. mapping a
+ * business status to a {@link BadgeTone}) should live in the consuming app.
+ *
+ * @example
+ * ```tsx
+ * <Badge tone="success">Active</Badge>
+ * ```
+ */
+export function Badge(props: BadgeProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['tone', 'class', 'children'])
+  return (
+    <span class={cn(BADGE_BASE, TONE_CLASSES[local.tone ?? 'neutral'], local.class)} {...rest}>
+      {local.children}
+    </span>
+  )
+}

package/src/ui/BottomNavigation.tsx

@@ -0,0 +1,65 @@
+// Horizontal bottom navigation bar of equal-width icon + label items,
+// rendered inline where placed so the consumer controls positioning.
+import type { JSX } from 'solid-js'
+import { For } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single destination within a {@link BottomNavigation}. */
+export interface BottomNavItem {
+  value: string
+  label: string
+  icon: JSX.Element
+}
+
+export interface BottomNavigationProps {
+  items: BottomNavItem[]
+  value: string
+  onChange: (value: string) => void
+  class?: string
+}
+
+/**
+ * Horizontal bar of equal-width navigation items, each stacking an icon above
+ * a short label. The active item (matching `value`) is highlighted and marked
+ * with `aria-current="page"`. Renders inline where placed — the consumer is
+ * responsible for positioning (e.g. `fixed inset-x-0 bottom-0`).
+ *
+ * @example
+ * ```tsx
+ * <BottomNavigation
+ *   value={tab()}
+ *   onChange={setTab}
+ *   items={[
+ *     { value: 'home', label: 'Home', icon: <HomeIcon /> },
+ *     { value: 'search', label: 'Search', icon: <SearchIcon /> },
+ *     { value: 'profile', label: 'Profile', icon: <UserIcon /> },
+ *   ]}
+ * />
+ * ```
+ */
+export function BottomNavigation(props: BottomNavigationProps): JSX.Element {
+  return (
+    <nav class={cn('flex items-stretch border-t border-border bg-glass', props.class)}>
+      <For each={props.items}>
+        {(item) => {
+          const active = () => item.value === props.value
+          return (
+            <button
+              type="button"
+              aria-current={active() ? 'page' : undefined}
+              onClick={() => props.onChange(item.value)}
+              class={cn(
+                'flex flex-1 flex-col items-center gap-0.5 py-2 text-[11px] transition-colors',
+                active() ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+              )}
+            >
+              {item.icon}
+              <span>{item.label}</span>
+            </button>
+          )
+        }}
+      </For>
+    </nav>
+  )
+}

package/src/ui/Breadcrumb.tsx

@@ -0,0 +1,64 @@
+// Navigation trail on Kobalte's Breadcrumbs primitive. Last item is current.
+import { Breadcrumbs as KBreadcrumbs } from '@kobalte/core/breadcrumbs'
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single crumb rendered by {@link Breadcrumb}. */
+export interface BreadcrumbItem {
+  label: string
+  /** Link target. Omit (or leave undefined on the last item) to render plain text for the current page. */
+  href?: string
+}
+
+interface BreadcrumbProps {
+  /** Ordered trail from root to current page; the last item is treated as the current location. */
+  items: BreadcrumbItem[]
+  class?: string
+}
+
+/**
+ * Navigation trail built on Kobalte's `Breadcrumbs` primitive. The last item
+ * in `items` is rendered as plain (non-link) text to indicate the current page.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb
+ *   items={[
+ *     { label: 'Projects', href: '/projects' },
+ *     { label: 'A4ui' },
+ *   ]}
+ * />
+ * ```
+ */
+export function Breadcrumb(props: BreadcrumbProps): JSX.Element {
+  return (
+    <KBreadcrumbs class={cn('text-sm', props.class)}>
+      <ol class="flex items-center gap-2 text-muted-foreground">
+        <For each={props.items}>
+          {(item, index) => {
+            const isLast = () => index() === props.items.length - 1
+            return (
+              <li class="flex items-center gap-2">
+                <Show
+                  when={item.href && !isLast()}
+                  fallback={
+                    <span class={isLast() ? 'font-medium text-foreground' : undefined}>{item.label}</span>
+                  }
+                >
+                  <KBreadcrumbs.Link href={item.href} class="transition-colors hover:text-foreground">
+                    {item.label}
+                  </KBreadcrumbs.Link>
+                </Show>
+                <Show when={!isLast()}>
+                  <KBreadcrumbs.Separator class="text-muted-foreground/60" />
+                </Show>
+              </li>
+            )
+          }}
+        </For>
+      </ol>
+    </KBreadcrumbs>
+  )
+}

package/src/ui/Button.tsx

@@ -0,0 +1,49 @@
+import type { JSX, ParentProps } from 'solid-js'
+import { splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** Visual style of a {@link Button}. Defaults to `'primary'`. */
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost'
+
+const VARIANT_CLASSES: Record<ButtonVariant, string> = {
+  primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  secondary: 'bg-muted text-foreground hover:bg-muted/70',
+  outline: 'border border-border bg-transparent text-foreground hover:bg-muted',
+  ghost: 'bg-transparent text-foreground hover:bg-muted',
+}
+
+// transition-colors (hover) + transform (press) — both compositor-only, CSS
+// handles it so there's no JS gesture-recognition cost per button.
+const BUTTON_BASE =
+  'inline-flex items-center justify-center rounded-md px-3 py-2 text-sm font-medium transition-[color,background-color,transform] duration-150 active:scale-[0.97] focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50'
+
+interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+  /** Visual style. Defaults to `'primary'`. */
+  variant?: ButtonVariant
+  class?: string
+  /** Defaults to "button" so action buttons inside a form never submit it by accident. */
+  type?: 'button' | 'submit' | 'reset'
+}
+
+/**
+ * Base button primitive: a plain `<button>` with A4ui's variants, focus ring,
+ * and press/hover transitions. Accepts all standard button HTML attributes.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="outline" onClick={() => save()}>Save</Button>
+ * ```
+ */
+export function Button(props: ButtonProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['variant', 'class', 'type', 'children'])
+  return (
+    <button
+      type={local.type ?? 'button'}
+      class={cn(BUTTON_BASE, VARIANT_CLASSES[local.variant ?? 'primary'], local.class)}
+      {...rest}
+    >
+      {local.children}
+    </button>
+  )
+}

package/src/ui/Calendar.tsx

@@ -0,0 +1,40 @@
+// Full-month calendar view — an always-visible wrapper around the shared
+// CalendarCore (which provides the day/month/year drill-down + year jumps).
+// Sunday-first weekday order; speaks `Date` rather than YYYY-MM-DD strings.
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { CalendarCore } from './internal/CalendarCore'
+
+export interface CalendarProps {
+  /** Currently selected day. */
+  value?: Date
+  /** Called with the newly picked day. */
+  onChange?: (date: Date) => void
+  class?: string
+}
+
+/**
+ * Full-month calendar: a header with month/year navigation and a 6×7 grid of
+ * day buttons. Click the month or year in the header to jump straight to a month
+ * or year picker; the double chevrons step a whole year at a time. The selected
+ * day is filled and "today" gets a ring. Theme-agnostic, always visible.
+ *
+ * @example
+ * ```tsx
+ * const [date, setDate] = createSignal(new Date())
+ * <Calendar value={date()} onChange={setDate} />
+ * ```
+ */
+export function Calendar(props: CalendarProps): JSX.Element {
+  return (
+    <div class={cn('w-72', props.class)}>
+      <CalendarCore
+        selected={props.value}
+        initialView={props.value}
+        onPick={(d) => props.onChange?.(d)}
+        weekStart={0}
+      />
+    </div>
+  )
+}