@a4ui/core 0.31.1 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",

package/src/charts/BarList.tsx

@@ -0,0 +1,83 @@
+// BarList — a ranked horizontal bar list built from plain flex `div`s (no
+// SVG, no charting library). Rows are sorted by value descending; each row
+// is a full-width track with a low-opacity theme-toned fill sized to
+// `value / max`, the `name` overlaid at the left (truncated, linked when
+// `href` is set) and the formatted value at the right. Colors come from
+// theme tokens only.
+import { For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface BarListDatum {
+  name: string
+  value: number
+  href?: string
+}
+
+export interface BarListProps {
+  data: BarListDatum[]
+  /** Formats the raw value shown at the row's end. Default `String`. */
+  valueFormat?: (n: number) => string
+  /** Fill color token. Default 'primary'. */
+  tone?: 'primary' | 'accent'
+  class?: string
+}
+
+/**
+ * Ranked horizontal bar list: rows sorted by `value` descending, each a
+ * full-width track with a low-opacity fill sized to `value / max` of the
+ * tallest row, the `name` overlaid at the left (truncated, rendered as a
+ * link when `href` is set) and the formatted value at the right. Compact
+ * and reflows with its container.
+ *
+ * @example
+ * ```tsx
+ * <BarList
+ *   data={[
+ *     { name: '/dashboard', value: 842, href: '/pages/dashboard' },
+ *     { name: '/settings', value: 231 },
+ *   ]}
+ *   tone="accent"
+ * />
+ * ```
+ */
+export function BarList(props: BarListProps): JSX.Element {
+  const tone = () => props.tone ?? 'primary'
+  const format = () => props.valueFormat ?? ((n: number) => String(n))
+  const fillClass = () => (tone() === 'accent' ? 'bg-accent/15' : 'bg-primary/15')
+  const sorted = () => [...props.data].sort((a, b) => b.value - a.value)
+  const max = () => Math.max(...props.data.map((d) => d.value), 0) || 1
+
+  return (
+    <div class={cn('flex w-full flex-col gap-1.5', props.class)}>
+      <For each={sorted()}>
+        {(datum) => (
+          <div class="relative isolate flex h-8 w-full min-w-0 items-center overflow-hidden rounded-md bg-muted/40">
+            <div
+              class={cn('absolute inset-y-0 left-0 rounded-md transition-all', fillClass())}
+              style={{ width: `${Math.max((datum.value / max()) * 100, 0)}%` }}
+            />
+            <Show
+              when={datum.href}
+              fallback={
+                <span class="relative z-10 min-w-0 flex-1 truncate px-2.5 text-sm text-foreground">
+                  {datum.name}
+                </span>
+              }
+            >
+              <a
+                href={datum.href}
+                class="relative z-10 min-w-0 flex-1 truncate px-2.5 text-sm text-foreground underline-offset-2 hover:underline"
+              >
+                {datum.name}
+              </a>
+            </Show>
+            <span class="relative z-10 shrink-0 px-2.5 text-sm tabular-nums text-muted-foreground">
+              {format()(datum.value)}
+            </span>
+          </div>
+        )}
+      </For>
+    </div>
+  )
+}

package/src/charts/CategoryBar.tsx

@@ -0,0 +1,95 @@
+// CategoryBar — a single horizontal segmented bar built from plain flex
+// `div`s (no SVG, no charting library). Each segment's width is its share of
+// the total (via CSS `flex-grow`), segments join seamlessly inside a
+// rounded track, an optional caret marks a value along the total (pure-CSS
+// border triangle), and cumulative boundary labels sit beneath. `success`/
+// `warning` tones reuse `Alert`/`Badge`'s `emerald-500`/`amber-500` (the repo
+// has no dedicated CSS token for them); `primary`/`accent`/`destructive` are
+// the shared semantic tokens.
+import { createMemo, For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export type CategoryBarTone = 'primary' | 'accent' | 'success' | 'warning' | 'destructive'
+
+export interface CategoryBarProps {
+  values: number[]
+  /** A value along the cumulative total to mark with a caret above the bar. */
+  marker?: number
+  /** Per-segment color tokens; cycles the default order below when omitted or shorter than `values`. */
+  tones?: CategoryBarTone[]
+  class?: string
+}
+
+const DEFAULT_TONES: CategoryBarTone[] = ['primary', 'accent', 'success', 'warning', 'destructive']
+
+const TONE_CLASSES: Record<CategoryBarTone, string> = {
+  primary: 'bg-primary',
+  accent: 'bg-accent',
+  success: 'bg-emerald-500',
+  warning: 'bg-amber-500',
+  destructive: 'bg-destructive',
+}
+
+/** Cumulative running sum of `values`, one boundary per entry (same length as `values`). */
+function cumulativeBounds(values: number[]): number[] {
+  let running = 0
+  return values.map((v) => (running += v))
+}
+
+/**
+ * Single segmented bar: each `values[i]` sets a segment's flex-grow share of
+ * the total, colored by `tones[i]` (cycling a sensible default), joined
+ * seamlessly inside one rounded track. An optional `marker` renders a caret
+ * above the bar at that value's position along the total, and cumulative
+ * boundary labels sit beneath (muted, tabular-nums).
+ *
+ * @example
+ * ```tsx
+ * <CategoryBar values={[40, 25, 20, 15]} marker={62} />
+ * ```
+ */
+export function CategoryBar(props: CategoryBarProps): JSX.Element {
+  const total = createMemo(() => props.values.reduce((sum, v) => sum + v, 0) || 1)
+  const bounds = createMemo(() => cumulativeBounds(props.values))
+  const tones = () => (props.tones && props.tones.length > 0 ? props.tones : DEFAULT_TONES)
+  const markerPct = createMemo(() =>
+    props.marker == null ? undefined : Math.min(Math.max((props.marker / total()) * 100, 0), 100),
+  )
+
+  return (
+    <div class={cn('w-full', props.class)}>
+      <div class="relative">
+        <Show when={markerPct() !== undefined}>
+          <div
+            class="absolute -top-1.5 h-0 w-0 -translate-x-1/2 border-x-4 border-t-4 border-x-transparent border-t-foreground"
+            style={{ left: `${markerPct()}%` }}
+            aria-hidden="true"
+          />
+        </Show>
+        <div class="flex h-2.5 w-full overflow-hidden rounded-full bg-muted">
+          <For each={props.values}>
+            {(value, i) => (
+              <div
+                class={cn('h-full', TONE_CLASSES[tones()[i() % tones().length] ?? 'primary'])}
+                style={{ flex: `${Math.max(value, 0)} 0 0%` }}
+              />
+            )}
+          </For>
+        </div>
+      </div>
+      <div class="relative mt-1 h-4 w-full text-xs tabular-nums text-muted-foreground">
+        <For each={bounds()}>
+          {(bound) => (
+            <span
+              class="absolute -translate-x-1/2 whitespace-nowrap"
+              style={{ left: `${Math.min(Math.max((bound / total()) * 100, 0), 100)}%` }}
+            >
+              {bound}
+            </span>
+          )}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/charts/GaugeChart.tsx

@@ -0,0 +1,175 @@
+// GaugeChart — a native SVG radial gauge (no charting library). A single
+// 270° arc (from -135° to +135°, leaving a 90° gap at the bottom) is drawn
+// twice: a static background track and a value arc revealed proportionally
+// to `value` within `[min, max]` via the classic stroke-dasharray/
+// stroke-dashoffset trick (dash length == full path length, offset shifts
+// how much of it is "on" from the arc's start). The value arc's color comes
+// from `tone`, or from the highest `threshold` the value has reached. The
+// sweep animates on mount and on value change (CSS transition on
+// stroke-dashoffset), jumping instantly under `motionReduced()`.
+import { createEffect, createSignal, on, onMount, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface GaugeThreshold {
+  value: number
+  tone: 'primary' | 'accent' | 'destructive' | 'muted'
+}
+
+export interface GaugeChartProps {
+  value: number
+  /** Value mapped to the arc's start (-135°). Default 0. */
+  min?: number
+  /** Value mapped to the arc's end (+135°). Default 100. */
+  max?: number
+  label?: JSX.Element
+  unit?: string
+  /** Overall SVG width/height in px (square). Default 160. */
+  size?: number
+  /** Value arc color when `thresholds` are omitted. Default 'primary'. */
+  tone?: 'primary' | 'accent'
+  /** Recolor the value arc once `value` reaches a threshold's `value` (highest match wins). */
+  thresholds?: GaugeThreshold[]
+  class?: string
+}
+
+// Explicit tone -> CSS custom property name.
+const TONE_TOKENS: Record<GaugeThreshold['tone'], string> = {
+  primary: '--primary',
+  accent: '--accent',
+  destructive: '--destructive',
+  muted: '--muted',
+}
+
+const DEG_TO_RAD = Math.PI / 180
+const START_ANGLE = -135
+const END_ANGLE = 135
+const SWEEP_ANGLE = END_ANGLE - START_ANGLE // 270°
+
+/** Cartesian point on a circle of radius `r` centered at `(cx, cy)`, `angleDeg` measured clockwise from 12 o'clock. */
+function pointOnArc(cx: number, cy: number, r: number, angleDeg: number): { x: number; y: number } {
+  const rad = angleDeg * DEG_TO_RAD
+  return { x: cx + r * Math.sin(rad), y: cy - r * Math.cos(rad) }
+}
+
+/** SVG path `d` for the fixed 270° arc (shared by the track and the value arc). */
+function gaugeArcPath(cx: number, cy: number, r: number): string {
+  const start = pointOnArc(cx, cy, r, START_ANGLE)
+  const end = pointOnArc(cx, cy, r, END_ANGLE)
+  return `M ${start.x} ${start.y} A ${r} ${r} 0 1 1 ${end.x} ${end.y}`
+}
+
+/** Highest threshold whose `value` the gauge has reached, falling back to `tone` when none match. */
+function resolveTone(value: number, tone: 'primary' | 'accent', thresholds?: GaugeThreshold[]): string {
+  if (!thresholds || thresholds.length === 0) return TONE_TOKENS[tone]
+  let resolved = TONE_TOKENS[tone]
+  for (const threshold of [...thresholds].sort((a, b) => a.value - b.value)) {
+    if (value >= threshold.value) resolved = TONE_TOKENS[threshold.tone]
+  }
+  return resolved
+}
+
+/**
+ * SVG radial gauge: a 270° arc (from -135° to +135°) with a background track
+ * and a value arc filled proportionally to `value` within `[min, max]`,
+ * colored by `tone` or by the highest `threshold` reached. The center shows
+ * the value plus optional `unit`/`label`. The sweep animates on mount and on
+ * value change, jumping instantly under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <GaugeChart
+ *   value={72}
+ *   unit="%"
+ *   label="CPU load"
+ *   thresholds={[
+ *     { value: 0, tone: 'primary' },
+ *     { value: 60, tone: 'accent' },
+ *     { value: 85, tone: 'destructive' },
+ *   ]}
+ * />
+ * ```
+ */
+export function GaugeChart(props: GaugeChartProps): JSX.Element {
+  const size = () => props.size ?? 160
+  const min = () => props.min ?? 0
+  const max = () => props.max ?? 100
+  const tone = () => props.tone ?? 'primary'
+  const thickness = () => size() / 8
+  const center = () => size() / 2
+  const radius = () => Math.max(size() / 2 - thickness() / 2, 0)
+  const totalLength = () => radius() * (SWEEP_ANGLE * DEG_TO_RAD)
+  const arcPath = () => gaugeArcPath(center(), center(), radius())
+
+  const clampedValue = () => Math.min(Math.max(props.value, min()), max())
+  const fraction = () => {
+    const range = max() - min()
+    return range > 0 ? (clampedValue() - min()) / range : 0
+  }
+  const strokeToken = () => resolveTone(clampedValue(), tone(), props.thresholds)
+
+  // Drives the visible sweep; starts at 0 so the mount animation reveals the
+  // arc from empty, then tracks `fraction()` (deferred, so mount handles the
+  // initial reveal and this only reacts to later value changes).
+  const [displayedFraction, setDisplayedFraction] = createSignal(0)
+
+  onMount(() => {
+    if (motionReduced()) {
+      setDisplayedFraction(fraction())
+      return
+    }
+    requestAnimationFrame(() => setDisplayedFraction(fraction()))
+  })
+
+  createEffect(on(fraction, (f) => setDisplayedFraction(f), { defer: true }))
+
+  const dashOffset = () => totalLength() * (1 - displayedFraction())
+  const transition = () => (motionReduced() ? 'none' : 'stroke-dashoffset 700ms ease-out')
+
+  const displayValue = () => Math.round(clampedValue())
+  const ariaLabel = () => `${displayValue()}${props.unit ?? ''}`
+
+  return (
+    <div
+      class={cn('relative inline-flex items-center justify-center', props.class)}
+      style={{ width: `${size()}px`, height: `${size()}px` }}
+      role="meter"
+      aria-valuenow={clampedValue()}
+      aria-valuemin={min()}
+      aria-valuemax={max()}
+      aria-label={ariaLabel()}
+    >
+      <svg width={size()} height={size()} viewBox={`0 0 ${size()} ${size()}`} role="img" aria-hidden="true">
+        <path
+          d={arcPath()}
+          fill="none"
+          stroke="hsl(var(--muted))"
+          stroke-width={thickness()}
+          stroke-linecap="round"
+        />
+        <path
+          d={arcPath()}
+          fill="none"
+          stroke={`hsl(var(${strokeToken()}))`}
+          stroke-width={thickness()}
+          stroke-linecap="round"
+          stroke-dasharray={`${totalLength()} ${totalLength()}`}
+          stroke-dashoffset={dashOffset()}
+          style={{ transition: transition() }}
+        />
+      </svg>
+      <div class="absolute inset-0 flex flex-col items-center justify-center gap-0.5 px-4 text-center">
+        <span class="text-2xl font-semibold tabular-nums text-foreground">
+          {displayValue()}
+          <Show when={props.unit}>
+            <span class="text-base font-medium">{props.unit}</span>
+          </Show>
+        </span>
+        <Show when={props.label}>
+          <span class="text-xs text-muted-foreground">{props.label}</span>
+        </Show>
+      </div>
+    </div>
+  )
+}

package/src/charts/LineChart.tsx

@@ -0,0 +1,264 @@
+// LineChart — a multi-series SVG line chart (no charting library). Every
+// series is scaled against the global min/max across *all* series so they
+// stay comparable, then drawn as one polyline each, with an optional
+// low-opacity area fill down to the baseline. Colors come from theme tokens
+// only, so the chart recolors with the active palette automatically.
+import { createSignal, For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface LineSeries {
+  name?: string
+  tone?: 'primary' | 'accent' | 'muted' | 'foreground'
+  data: number[]
+  area?: boolean
+}
+
+export interface LineChartProps {
+  series: LineSeries[]
+  labels?: string[]
+  /** Height of the plot area in px. Default 200. */
+  height?: number
+  /** Render a small circle at each data point. Default false. */
+  showDots?: boolean
+  /** Show a crosshair + value tooltip on pointer hover. Default false. */
+  showTooltip?: boolean
+  class?: string
+}
+
+/** Logical SVG width; the element itself scales to its container via viewBox. */
+const VIEW_W = 400
+const PAD_Y = 4
+const TONE_CYCLE: NonNullable<LineSeries['tone']>[] = ['primary', 'accent', 'muted']
+
+function toneFor(series: LineSeries, index: number): NonNullable<LineSeries['tone']> {
+  return series.tone ?? TONE_CYCLE[index % TONE_CYCLE.length]
+}
+
+function toneColor(tone: NonNullable<LineSeries['tone']>): string {
+  return tone === 'foreground' ? 'hsl(var(--foreground))' : `hsl(var(--${tone}))`
+}
+
+function toneColorAlpha(tone: NonNullable<LineSeries['tone']>, alpha: number): string {
+  const varName = tone === 'foreground' ? '--foreground' : `--${tone}`
+  return `hsl(var(${varName}) / ${alpha})`
+}
+
+/** Point count used for the x-axis: the longest `data` array across all series. */
+function pointCount(series: LineSeries[]): number {
+  return Math.max(0, ...series.map((s) => s.data.length))
+}
+
+/** Global min/max across every series' values, so all series share one y-scale. */
+function globalRange(series: LineSeries[]): { min: number; max: number } {
+  const values = series.flatMap((s) => s.data)
+  if (values.length === 0) return { min: 0, max: 1 }
+  const min = Math.min(...values)
+  const max = Math.max(...values)
+  return min === max ? { min: min - 1, max: max + 1 } : { min, max }
+}
+
+function yFor(value: number, min: number, max: number, h: number): number {
+  const span = max - min || 1
+  const innerH = Math.max(h - PAD_Y * 2, 0)
+  return PAD_Y + innerH - ((value - min) / span) * innerH
+}
+
+function xFor(index: number, count: number): number {
+  if (count <= 1) return VIEW_W / 2
+  return index * (VIEW_W / (count - 1))
+}
+
+function pointsFor(
+  data: number[],
+  count: number,
+  min: number,
+  max: number,
+  h: number,
+): { x: number; y: number }[] {
+  return data.map((value, i) => ({ x: xFor(i, count), y: yFor(value, min, max, h) }))
+}
+
+/**
+ * Multi-series SVG line chart scaled to fit its container (responsive
+ * viewBox, `preserveAspectRatio="none"`), with a shared y-scale across all
+ * series. Series with `area: true` also get a faint fill to the baseline.
+ * Assumes equal-length `data` arrays across series; if lengths differ, the
+ * x-axis is built from the longest one.
+ *
+ * @example
+ * ```tsx
+ * <LineChart
+ *   series={[
+ *     { name: 'Revenue', tone: 'primary', data: [4, 6, 5, 9, 8, 12], area: true },
+ *     { name: 'Costs', tone: 'muted', data: [2, 3, 3, 4, 5, 6] },
+ *   ]}
+ *   labels={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']}
+ *   showDots
+ *   showTooltip
+ * />
+ * ```
+ */
+export function LineChart(props: LineChartProps): JSX.Element {
+  const height = () => props.height ?? 200
+  const count = () => pointCount(props.series)
+  const range = () => globalRange(props.series)
+  const namedSeries = () => props.series.filter((s) => s.name)
+
+  const seriesPoints = () =>
+    props.series.map((s) => pointsFor(s.data, count(), range().min, range().max, height()))
+
+  const areaPath = (points: { x: number; y: number }[]): string => {
+    if (points.length === 0) return ''
+    const line = points.map((p) => `${p.x},${p.y}`).join(' L ')
+    const first = points[0]
+    const last = points[points.length - 1]
+    return `M ${first.x},${height()} L ${line} L ${last.x},${height()} Z`
+  }
+
+  let svgRef: SVGSVGElement | undefined
+  const [hoverIndex, setHoverIndex] = createSignal<number | null>(null)
+
+  const handlePointerMove = (event: PointerEvent) => {
+    if (!svgRef || count() === 0) return
+    const rect = svgRef.getBoundingClientRect()
+    const fraction = rect.width === 0 ? 0 : (event.clientX - rect.left) / rect.width
+    const clamped = Math.min(1, Math.max(0, fraction))
+    const idx = count() <= 1 ? 0 : Math.round(clamped * (count() - 1))
+    setHoverIndex(idx)
+  }
+
+  const handlePointerLeave = () => setHoverIndex(null)
+
+  const ariaLabel = () => {
+    const names = namedSeries()
+      .map((s) => s.name)
+      .join(', ')
+    const seriesLabel = names || `${props.series.length} series`
+    return `Line chart with ${seriesLabel}, ${count()} data points each`
+  }
+
+  return (
+    <div class={cn('w-full', props.class)}>
+      <Show when={namedSeries().length >= 2}>
+        <div class="mb-2 flex flex-wrap gap-x-3 gap-y-1">
+          <For each={props.series}>
+            {(s, i) => (
+              <Show when={s.name}>
+                <span class="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+                  <span
+                    class="inline-block size-2 rounded-full"
+                    style={{ 'background-color': toneColor(toneFor(s, i())) }}
+                  />
+                  {s.name}
+                </span>
+              </Show>
+            )}
+          </For>
+        </div>
+      </Show>
+
+      <div class="relative w-full">
+        <svg
+          ref={svgRef}
+          class="block w-full overflow-visible"
+          viewBox={`0 0 ${VIEW_W} ${height()}`}
+          preserveAspectRatio="none"
+          height={height()}
+          role="img"
+          aria-label={ariaLabel()}
+          onPointerMove={props.showTooltip ? handlePointerMove : undefined}
+          onPointerLeave={props.showTooltip ? handlePointerLeave : undefined}
+        >
+          <For each={props.series}>
+            {(s, i) => {
+              const points = () => seriesPoints()[i()]
+              const tone = () => toneFor(s, i())
+              const polylinePoints = () =>
+                points()
+                  .map((p) => `${p.x},${p.y}`)
+                  .join(' ')
+              return (
+                <>
+                  <Show when={s.area}>
+                    <path d={areaPath(points())} fill={toneColorAlpha(tone(), 0.15)} stroke="none" />
+                  </Show>
+                  <polyline
+                    points={polylinePoints()}
+                    fill="none"
+                    stroke={toneColor(tone())}
+                    stroke-width={2}
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    vector-effect="non-scaling-stroke"
+                  />
+                  <Show when={props.showDots}>
+                    <For each={points()}>
+                      {(p) => (
+                        <circle
+                          cx={p.x}
+                          cy={p.y}
+                          r={2.5}
+                          fill={toneColor(tone())}
+                          vector-effect="non-scaling-stroke"
+                        />
+                      )}
+                    </For>
+                  </Show>
+                </>
+              )
+            }}
+          </For>
+
+          <Show when={props.showTooltip && hoverIndex() !== null}>
+            <line
+              x1={xFor(hoverIndex() ?? 0, count())}
+              x2={xFor(hoverIndex() ?? 0, count())}
+              y1={0}
+              y2={height()}
+              stroke="hsl(var(--border))"
+              stroke-width={1}
+              vector-effect="non-scaling-stroke"
+            />
+          </Show>
+        </svg>
+
+        <Show when={props.showTooltip && hoverIndex() !== null}>
+          <div
+            class="pointer-events-none absolute top-0 z-10 -translate-y-1 rounded-md border border-border bg-popover px-2 py-1 text-xs text-popover-foreground shadow-md"
+            style={{
+              left: `${((hoverIndex() ?? 0) / Math.max(count() - 1, 1)) * 100}%`,
+              transform: `translateX(${
+                (hoverIndex() ?? 0) / Math.max(count() - 1, 1) > 0.8 ? '-100%' : '-8px'
+              }) translateY(-100%)`,
+            }}
+          >
+            <Show when={props.labels?.[hoverIndex() ?? -1]}>
+              <div class="mb-0.5 font-medium text-foreground">{props.labels?.[hoverIndex() ?? -1]}</div>
+            </Show>
+            <For each={props.series}>
+              {(s, i) => (
+                <Show when={s.data[hoverIndex() ?? -1] !== undefined}>
+                  <div class="flex items-center gap-1.5">
+                    <span
+                      class="inline-block size-1.5 rounded-full"
+                      style={{ 'background-color': toneColor(toneFor(s, i())) }}
+                    />
+                    <span>{s.name ?? `Series ${i() + 1}`}:</span>
+                    <span class="font-medium text-foreground">{s.data[hoverIndex() ?? -1]}</span>
+                  </div>
+                </Show>
+              )}
+            </For>
+          </div>
+        </Show>
+      </div>
+
+      <Show when={props.labels && props.labels.length > 0}>
+        <div class="mt-1 flex w-full text-xs text-muted-foreground">
+          <For each={props.labels}>{(label) => <span class="flex-1 truncate text-center">{label}</span>}</For>
+        </div>
+      </Show>
+    </div>
+  )
+}