@a4ui/core 0.11.1 → 0.12.0

package/src/ui/NotificationCenter.tsx

@@ -0,0 +1,103 @@
+// Bell-triggered notification panel built on A4ui's Popover primitive.
+import { Bell, X } from 'lucide-solid'
+import { For, type JSX, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Popover } from './Popover'
+
+/** A single entry rendered by {@link NotificationCenter}. */
+export interface NotificationItem {
+  id: string
+  title: string
+  description?: string
+  time?: string
+  read?: boolean
+}
+
+export interface NotificationCenterProps {
+  /** Notifications to display, newest first. */
+  items: NotificationItem[]
+  /** Called with an item's id when its dismiss button is clicked. */
+  onDismiss?: (id: string) => void
+  /** Called when the "Mark all read" action is clicked. */
+  onMarkAllRead?: () => void
+  class?: string
+}
+
+/**
+ * Bell button that opens a popover listing notifications, with an unread count
+ * badge, per-item dismiss, and a "mark all read" action. Built on {@link Popover}.
+ *
+ * @example
+ * ```tsx
+ * <NotificationCenter
+ *   items={items}
+ *   onDismiss={(id) => remove(id)}
+ *   onMarkAllRead={() => markAll()}
+ * />
+ * ```
+ */
+export function NotificationCenter(props: NotificationCenterProps): JSX.Element {
+  const unread = () => props.items.filter((item) => !item.read).length
+
+  const trigger = (
+    <span class={cn('relative inline-grid place-items-center rounded-md p-2 text-foreground', props.class)}>
+      <Bell class="h-5 w-5" />
+      <Show when={unread() > 0}>
+        <span class="absolute -right-1 -top-1 grid h-4 min-w-4 place-items-center rounded-full bg-primary px-1 text-[10px] text-primary-foreground">
+          {unread()}
+        </span>
+      </Show>
+    </span>
+  )
+
+  return (
+    <Popover trigger={trigger} class="w-80 p-0">
+      <div class="flex items-center justify-between border-b border-border px-4 py-3">
+        <span class="text-sm font-semibold text-foreground">Notifications</span>
+        <button
+          type="button"
+          class="text-xs font-medium text-primary hover:underline"
+          onClick={() => props.onMarkAllRead?.()}
+        >
+          Mark all read
+        </button>
+      </div>
+      <Show
+        when={props.items.length > 0}
+        fallback={<p class="px-4 py-8 text-center text-sm text-muted-foreground">You're all caught up</p>}
+      >
+        <ul class="max-h-96 divide-y divide-border overflow-y-auto">
+          <For each={props.items}>
+            {(item) => (
+              <li class="flex items-start gap-2 px-4 py-3">
+                <div class="min-w-0 flex-1">
+                  <p class="flex items-center gap-1.5 text-sm font-medium text-foreground">
+                    <Show when={!item.read}>
+                      <span class="h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />
+                    </Show>
+                    <span class="truncate">{item.title}</span>
+                  </p>
+                  <Show when={item.description}>
+                    <p class="mt-0.5 text-xs text-muted-foreground">{item.description}</p>
+                  </Show>
+                  <Show when={item.time}>
+                    <p class="mt-1 text-[11px] text-muted-foreground">{item.time}</p>
+                  </Show>
+                </div>
+                <button
+                  type="button"
+                  aria-label="Dismiss"
+                  class="shrink-0 rounded-md p-1 text-muted-foreground hover:bg-muted hover:text-foreground"
+                  onClick={() => props.onDismiss?.(item.id)}
+                >
+                  <X class="h-4 w-4" />
+                </button>
+              </li>
+            )}
+          </For>
+        </ul>
+      </Show>
+    </Popover>
+  )
+}

package/src/ui/NumberInput.tsx

@@ -0,0 +1,48 @@
+// Numeric field with −/+ steppers on Kobalte's NumberField primitive.
+import { NumberField as KNumberField } from '@kobalte/core/number-field'
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface NumberInputProps {
+  value: number
+  onChange: (value: number) => void
+  /** Lower bound; the decrement trigger disables itself at this value. */
+  min?: number
+  /** Upper bound; the increment trigger disables itself at this value. */
+  max?: number
+  class?: string
+}
+
+const TRIGGER_CLASS =
+  'grid h-9 w-9 shrink-0 place-items-center border border-input bg-background text-foreground transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50'
+
+/**
+ * Numeric field with −/+ stepper buttons, built on Kobalte's `NumberField` primitive.
+ * Use for bounded numeric input (quantities, counts) where clicking to nudge the
+ * value is preferable to typing alone.
+ *
+ * @example
+ * ```tsx
+ * <NumberInput value={qty()} onChange={setQty} min={0} max={99} />
+ * ```
+ */
+export function NumberInput(props: NumberInputProps): JSX.Element {
+  return (
+    <KNumberField
+      rawValue={props.value}
+      onRawValueChange={(v) => props.onChange(v)}
+      minValue={props.min}
+      maxValue={props.max}
+      class={cn('inline-flex items-stretch', props.class)}
+    >
+      <KNumberField.DecrementTrigger class={cn(TRIGGER_CLASS, 'rounded-l-md')} aria-label="Decrement">
+        −
+      </KNumberField.DecrementTrigger>
+      <KNumberField.Input class="w-16 border-y border-input bg-background px-3 py-2 text-center text-sm text-foreground outline-none transition-colors a4-field" />
+      <KNumberField.IncrementTrigger class={cn(TRIGGER_CLASS, 'rounded-r-md')} aria-label="Increment">
+        +
+      </KNumberField.IncrementTrigger>
+    </KNumberField>
+  )
+}

package/src/ui/PageHeader.tsx

@@ -0,0 +1,60 @@
+// Consistent page header: optional breadcrumb (last crumb highlighted), title,
+// subtitle, and a right-aligned actions slot.
+import { For, Show, type JSX } from 'solid-js'
+
+interface PageHeaderProps {
+  title: string
+  subtitle?: string
+  /** Trail of crumb labels, in order; the last one is rendered highlighted as the current page. */
+  breadcrumb?: string[]
+  /** Right-aligned slot for page-level actions (buttons, menus, etc.). */
+  actions?: JSX.Element
+}
+
+/**
+ * Consistent top-of-page header: optional breadcrumb trail, title, subtitle,
+ * and a right-aligned actions slot. Use at the top of a route/page for a
+ * uniform layout across the app.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   title="Invoices"
+ *   subtitle="Manage billing documents"
+ *   breadcrumb={['Home', 'Billing', 'Invoices']}
+ *   actions={<Button>New invoice</Button>}
+ * />
+ * ```
+ */
+export function PageHeader(props: PageHeaderProps): JSX.Element {
+  return (
+    <div class="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+      <div>
+        <Show when={props.breadcrumb?.length}>
+          <div class="flex items-center gap-2 text-[12px] text-muted-foreground">
+            <For each={props.breadcrumb}>
+              {(crumb, i) => (
+                <>
+                  <Show when={i() > 0}>
+                    {/* Same "/" separator as the standalone Breadcrumb component. */}
+                    <span class="text-muted-foreground/60">/</span>
+                  </Show>
+                  <span classList={{ 'text-foreground': i() === (props.breadcrumb?.length ?? 0) - 1 }}>
+                    {crumb}
+                  </span>
+                </>
+              )}
+            </For>
+          </div>
+        </Show>
+        <h1 class="mt-1 text-2xl font-bold tracking-tight">{props.title}</h1>
+        <Show when={props.subtitle}>
+          <p class="mt-0.5 text-[13px] text-muted-foreground">{props.subtitle}</p>
+        </Show>
+      </div>
+      <Show when={props.actions}>
+        <div class="flex items-center gap-2">{props.actions}</div>
+      </Show>
+    </div>
+  )
+}

package/src/ui/Pagination.tsx

@@ -0,0 +1,62 @@
+// Prev/next pager with a "Page X of Y" label and an optional left-aligned
+// summary slot (e.g. "1,234 registros · 1–50"). Client-side; the parent owns
+// the page signal and slices its own data.
+import { ChevronLeft, ChevronRight } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+
+interface PaginationProps {
+  /** Current page, 1-indexed. */
+  page: number
+  totalPages: number
+  onChange: (page: number) => void
+  /** Left-aligned slot, e.g. a row-count summary like "1,234 registros · 1–50". */
+  summary?: JSX.Element
+  /** Override default English labels/text for i18n. */
+  labels?: {
+    previous?: string
+    next?: string
+    /** Formats the center label; default is `` `Page ${page} of ${total}` ``. */
+    page?: (page: number, total: number) => string
+  }
+}
+
+/**
+ * Prev/next pager with a "Page X of Y" label and an optional summary slot.
+ * Purely client-side and controlled — the parent owns the `page` signal and
+ * is responsible for slicing its own data to match.
+ *
+ * @example
+ * ```tsx
+ * <Pagination page={page()} totalPages={totalPages()} onChange={setPage} />
+ * ```
+ */
+export function Pagination(props: PaginationProps): JSX.Element {
+  return (
+    <div class="flex flex-col gap-3 border-t border-border p-3 sm:flex-row sm:items-center sm:justify-between">
+      <div class="text-[12px] text-muted-foreground">{props.summary}</div>
+      <div class="flex items-center gap-1">
+        <button
+          type="button"
+          class="grid h-8 w-8 place-items-center rounded-lg border border-input transition hover:bg-muted disabled:pointer-events-none disabled:opacity-40"
+          disabled={props.page <= 1}
+          aria-label={props.labels?.previous ?? 'Previous page'}
+          onClick={() => props.onChange(props.page - 1)}
+        >
+          <ChevronLeft class="h-4 w-4" />
+        </button>
+        <span class="px-2 font-mono text-[12px] tabular-nums">
+          {(props.labels?.page ?? ((p, t) => `Page ${p} of ${t}`))(props.page, props.totalPages)}
+        </span>
+        <button
+          type="button"
+          class="grid h-8 w-8 place-items-center rounded-lg border border-input transition hover:bg-muted disabled:pointer-events-none disabled:opacity-40"
+          disabled={props.page >= props.totalPages}
+          aria-label={props.labels?.next ?? 'Next page'}
+          onClick={() => props.onChange(props.page + 1)}
+        >
+          <ChevronRight class="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/ui/Popover.tsx

@@ -0,0 +1,42 @@
+// Click-triggered floating panel on Kobalte's Popover primitive.
+import { Popover as KPopover } from '@kobalte/core/popover'
+import type { JSX, ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface PopoverProps extends ParentProps {
+  /** Element that opens the popover on click; wrapped in an inline-flex trigger. */
+  trigger: JSX.Element
+  class?: string
+}
+
+/**
+ * Click-triggered floating panel, built on Kobalte's `Popover` primitive
+ * (handles positioning, focus, dismiss, and portaling). Use for contextual
+ * content anchored to a trigger element, such as a filter panel or menu.
+ *
+ * @example
+ * ```tsx
+ * <Popover trigger={<Button>Filters</Button>}>
+ *   <p>Panel content</p>
+ * </Popover>
+ * ```
+ */
+export function Popover(props: PopoverProps): JSX.Element {
+  return (
+    <KPopover>
+      <KPopover.Trigger class="inline-flex">{props.trigger}</KPopover.Trigger>
+      <KPopover.Portal>
+        <KPopover.Content
+          class={cn(
+            'bg-glass z-50 rounded-lg border border-border p-4 text-card-foreground shadow-lg',
+            props.class,
+          )}
+        >
+          <KPopover.Arrow />
+          {props.children}
+        </KPopover.Content>
+      </KPopover.Portal>
+    </KPopover>
+  )
+}

package/src/ui/Portal.tsx

@@ -0,0 +1,34 @@
+// Renders children into a detached DOM node (default: <body>), escaping overflow
+// and stacking-context traps. A thin wrapper over Solid's own Portal so it's
+// available alongside the rest of the library.
+import type { JSX } from 'solid-js'
+import { Portal as SolidPortal } from 'solid-js/web'
+
+/** Props for {@link Portal}. */
+export interface PortalProps {
+  /** Where to mount. Defaults to `document.body`. */
+  mount?: Node
+  /** Use a Shadow DOM root for the portal container. */
+  useShadow?: boolean
+  children: JSX.Element
+}
+
+/**
+ * Renders its children into a different place in the DOM (by default
+ * `document.body`), so overlays aren't clipped by an ancestor's `overflow` or
+ * transformed stacking context. Built on Solid's `Portal`.
+ *
+ * @example
+ * ```tsx
+ * <Portal>
+ *   <div class="fixed inset-0 grid place-items-center">Floating layer</div>
+ * </Portal>
+ * ```
+ */
+export function Portal(props: PortalProps): JSX.Element {
+  return (
+    <SolidPortal mount={props.mount} useShadow={props.useShadow}>
+      {props.children}
+    </SolidPortal>
+  )
+}

package/src/ui/Progress.tsx

@@ -0,0 +1,55 @@
+// Determinate progress bar on Kobalte's Progress primitive.
+import { Progress as KProgress } from '@kobalte/core/progress'
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface ProgressProps {
+  value: number
+  /** Upper bound of `value`. Default: 100. */
+  max?: number
+  /** Label shown above the bar, paired with an auto-generated value label (e.g. "50%"). */
+  label?: string
+  class?: string
+}
+
+/**
+ * Determinate progress bar, built on Kobalte's `Progress` primitive. Use to
+ * show completion of a known-length task (upload, multi-step form, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Progress value={uploaded()} max={totalBytes()} label="Uploading" />
+ * ```
+ */
+export function Progress(props: ProgressProps): JSX.Element {
+  // Kobalte's Progress.Fill has no intrinsic width, so a bare block div fills the
+  // whole track (every bar reads 100%). Set the width from value/max ourselves.
+  const percent = () => {
+    const max = props.max ?? 100
+    if (max <= 0) return 0
+    return Math.max(0, Math.min(100, (props.value / max) * 100))
+  }
+  return (
+    <KProgress
+      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">
+          <KProgress.Label>{props.label}</KProgress.Label>
+          <KProgress.ValueLabel class="text-muted-foreground" />
+        </div>
+      </Show>
+      <KProgress.Track class="h-2 overflow-hidden rounded-full bg-muted">
+        <KProgress.Fill
+          class="h-full rounded-full bg-primary transition-all duration-500"
+          style={{ width: `${percent()}%` }}
+        />
+      </KProgress.Track>
+    </KProgress>
+  )
+}

package/src/ui/RadioGroup.tsx

@@ -0,0 +1,65 @@
+// Accessible single-choice group on Kobalte's RadioGroup primitive.
+import { RadioGroup as KRadioGroup } from '@kobalte/core/radio-group'
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single selectable choice within a {@link RadioGroup}. */
+export interface RadioOption {
+  value: string
+  label: string
+  disabled?: boolean
+}
+
+interface RadioGroupProps {
+  value: string
+  onChange: (value: string) => void
+  options: RadioOption[]
+  /** Group label rendered above the options. */
+  label?: string
+  class?: string
+}
+
+/**
+ * Accessible single-choice group, built on Kobalte's `RadioGroup` primitive
+ * (arrow-key navigation, ARIA roles). Use when all options should stay
+ * visible at once, unlike {@link Select} which hides options until opened.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup
+ *   label="Plan"
+ *   value={plan()}
+ *   onChange={setPlan}
+ *   options={[
+ *     { value: 'free', label: 'Free' },
+ *     { value: 'pro', label: 'Pro' },
+ *   ]}
+ * />
+ * ```
+ */
+export function RadioGroup(props: RadioGroupProps): JSX.Element {
+  return (
+    <KRadioGroup value={props.value} onChange={props.onChange} class={cn('flex flex-col gap-2', props.class)}>
+      <Show when={props.label}>
+        <KRadioGroup.Label class="text-sm font-medium text-foreground">{props.label}</KRadioGroup.Label>
+      </Show>
+      <For each={props.options}>
+        {(option) => (
+          <KRadioGroup.Item
+            value={option.value}
+            disabled={option.disabled}
+            class="flex items-center gap-2 text-sm text-foreground data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50"
+          >
+            <KRadioGroup.ItemInput />
+            <KRadioGroup.ItemControl class="grid h-4 w-4 place-items-center rounded-full border border-input transition-colors data-[checked]:border-primary">
+              <KRadioGroup.ItemIndicator class="h-2 w-2 rounded-full bg-primary" />
+            </KRadioGroup.ItemControl>
+            <KRadioGroup.ItemLabel>{option.label}</KRadioGroup.ItemLabel>
+          </KRadioGroup.Item>
+        )}
+      </For>
+    </KRadioGroup>
+  )
+}

package/src/ui/Rating.tsx

@@ -0,0 +1,98 @@
+// Star rating input. Filled/empty stars are driven by the current value (or a
+// transient hover preview); interactive mode renders each star as a keyboard-
+// accessible button, readonly mode renders a plain, labelled row of icons.
+import { Star } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface RatingProps {
+  /** Currently selected rating, from 0 to `max`. */
+  value: number
+  /** Called with the new rating when a star is clicked or set via keyboard. */
+  onChange?: (value: number) => void
+  /** Number of stars to render. Default: 5. */
+  max?: number
+  /** Render a non-interactive, display-only rating. Default: false. */
+  readonly?: boolean
+  class?: string
+}
+
+/**
+ * Star rating control. In interactive mode each star is a button: click or use
+ * the Left/Right arrow keys to set the rating, and hovering previews it. In
+ * `readonly` mode it renders as a static, labelled row of stars.
+ *
+ * @example
+ * ```tsx
+ * <Rating value={rating()} onChange={setRating} max={5} />
+ * ```
+ */
+export function Rating(props: RatingProps): JSX.Element {
+  const [hover, setHover] = createSignal(0)
+  const max = () => props.max ?? 5
+  const stars = () => Array.from({ length: max() }, (_, i) => i + 1)
+
+  // The value used to paint stars: hover preview takes precedence when active.
+  const active = () => (hover() > 0 ? hover() : props.value)
+
+  const set = (n: number) => {
+    if (props.readonly) return
+    props.onChange?.(n)
+  }
+
+  const starClass = (index: number) =>
+    cn(
+      'h-5 w-5 transition-colors',
+      index <= active() ? 'fill-primary text-primary' : 'fill-transparent text-muted-foreground',
+    )
+
+  return (
+    <Show
+      when={!props.readonly}
+      fallback={
+        <div
+          class={cn('inline-flex items-center gap-1', props.class)}
+          role="img"
+          aria-label={`Rating ${props.value} of ${max()}`}
+        >
+          <For each={stars()}>{(n) => <Star class={starClass(n)} aria-hidden="true" />}</For>
+        </div>
+      }
+    >
+      <div
+        class={cn('inline-flex items-center gap-1', props.class)}
+        role="radiogroup"
+        onMouseLeave={() => setHover(0)}
+      >
+        <For each={stars()}>
+          {(n) => (
+            <button
+              type="button"
+              role="radio"
+              aria-checked={props.value === n}
+              aria-label={`Rate ${n} of ${max()}`}
+              class="rounded outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+              onMouseEnter={() => setHover(n)}
+              onFocus={() => setHover(n)}
+              onBlur={() => setHover(0)}
+              onClick={() => set(n)}
+              onKeyDown={(e) => {
+                if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
+                  e.preventDefault()
+                  set(Math.min(props.value + 1, max()))
+                } else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
+                  e.preventDefault()
+                  set(Math.max(props.value - 1, 0))
+                }
+              }}
+            >
+              <Star class={starClass(n)} aria-hidden="true" />
+            </button>
+          )}
+        </For>
+      </div>
+    </Show>
+  )
+}

package/src/ui/Result.tsx

@@ -0,0 +1,75 @@
+// Full-status result screen: a centered vertical stack for terminal states like
+// success confirmations, errors, or HTTP 404/500 pages. A large status icon (or
+// the big HTTP number) sits in a tinted circle above the title/description; the
+// fixed semantic status colors mirror Alert (emerald/amber/rose) while the rest
+// stays theme-agnostic via semantic tokens.
+import { CircleCheck, CircleX, Compass, Info, ServerCrash, TriangleAlert } from 'lucide-solid'
+import type { Component, JSX } from 'solid-js'
+import { Show } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+
+/** Semantic status of a {@link Result}; drives the icon, tint, and optional HTTP number. */
+export type ResultStatus = 'success' | 'error' | 'info' | 'warning' | '404' | '500'
+
+export interface ResultProps {
+  /** Result status; drives the icon and color. Defaults to `'info'`. */
+  status?: ResultStatus
+  /** Bold headline describing the outcome. */
+  title: string
+  /** Optional supporting line under the title. */
+  description?: string
+  /** Optional action slot (e.g. Buttons) rendered below the text. */
+  actions?: JSX.Element
+  class?: string
+}
+
+const STATUS: Record<
+  ResultStatus,
+  { Icon: Component<{ class?: string }>; icon: string; tint: string; code?: string }
+> = {
+  success: { Icon: CircleCheck, icon: 'text-emerald-500', tint: 'bg-emerald-500/10' },
+  error: { Icon: CircleX, icon: 'text-destructive', tint: 'bg-destructive/10' },
+  warning: { Icon: TriangleAlert, icon: 'text-amber-500', tint: 'bg-amber-500/10' },
+  info: { Icon: Info, icon: 'text-primary', tint: 'bg-primary/10' },
+  '404': { Icon: Compass, icon: 'text-muted-foreground', tint: 'bg-muted', code: '404' },
+  '500': { Icon: ServerCrash, icon: 'text-destructive', tint: 'bg-destructive/10', code: '500' },
+}
+
+/**
+ * Full-status result screen — a large status icon in a tinted circle, a title,
+ * optional description, and an optional actions slot — for terminal states such
+ * as success/error confirmations or HTTP 404/500 pages. For `'404'`/`'500'` the
+ * big HTTP number is shown above the icon.
+ *
+ * @example
+ * ```tsx
+ * <Result
+ *   status="success"
+ *   title="Payment complete"
+ *   description="A receipt has been sent to your email."
+ *   actions={<Button>Back to dashboard</Button>}
+ * />
+ * ```
+ */
+export function Result(props: ResultProps): JSX.Element {
+  const status = () => STATUS[props.status ?? 'info']
+  return (
+    <div class={cn('flex flex-col items-center py-12 text-center', props.class)}>
+      <Show when={status().code}>
+        <p class="text-5xl font-bold text-muted-foreground">{status().code}</p>
+      </Show>
+      <div class={cn('grid h-16 w-16 place-items-center rounded-full', status().tint)}>
+        <Dynamic component={status().Icon} class={cn('h-8 w-8', status().icon)} />
+      </div>
+      <p class="mt-4 text-xl font-bold text-foreground">{props.title}</p>
+      <Show when={props.description}>
+        <p class="mt-2 max-w-md text-muted-foreground">{props.description}</p>
+      </Show>
+      <Show when={props.actions}>
+        <div class="mt-6">{props.actions}</div>
+      </Show>
+    </div>
+  )
+}