@a4ui/core 0.11.1 → 0.13.0

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/Parallax.tsx

@@ -0,0 +1,51 @@
+// Parallax — moves its children at a fraction of scroll speed for depth,
+// driven by Motion's `scroll` progress callback (0..1) as the element passes
+// through the viewport. No-op (static) under reduced motion.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced, scroll } from '../lib/motion'
+
+export interface ParallaxProps {
+  children: JSX.Element
+  /** Parallax strength; positive moves slower/opposite. Pixels of travel across the scroll range. @default 80 */
+  amount?: number
+  class?: string
+}
+
+/**
+ * Wraps `children` in an element that drifts vertically as the page scrolls,
+ * creating a depth effect. Tracks scroll progress of the element itself
+ * against the viewport via Motion's `scroll`; respects `prefers-reduced-motion`
+ * (renders static).
+ *
+ * @example
+ * ```tsx
+ * <Parallax amount={120}>
+ *   <img src="/hero.png" alt="" />
+ * </Parallax>
+ * ```
+ */
+export function Parallax(props: ParallaxProps): JSX.Element {
+  let root!: HTMLDivElement
+
+  onMount(() => {
+    if (motionReduced()) return
+
+    const amount = props.amount ?? 80
+    const stop = scroll(
+      (progress: number) => {
+        root.style.transform = `translateY(${(progress - 0.5) * -2 * amount}px)`
+      },
+      { target: root },
+    )
+
+    onCleanup(() => stop())
+  })
+
+  return (
+    <div ref={root} class={cn('will-change-transform', props.class)}>
+      {props.children}
+    </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>
+  )
+}

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>
+  )
+}