@sero-ai/ui 0.3.2 → 0.4.0

package/src/components/dashboard/metric.tsx

@@ -0,0 +1,139 @@
+// Metric, MetricGroup and MetricCard — consistent numeric summaries.
+//
+// A metric is a label + value with optional icon, supporting text and a trend.
+// Metric works inline; MetricCard wraps it in a contained surface; MetricGroup
+// arranges several responsively. Values use tabular numerals so columns align.
+
+import * as React from "react";
+import { ArrowDown, ArrowRight, ArrowUp } from "lucide-react";
+
+import { cn } from "../../lib/utils";
+import { Icon } from "./typography";
+import { toneColor, type Tone } from "./tone";
+import { Grid, type GridProps } from "./layout";
+
+export interface MetricTrend {
+  direction: "up" | "down" | "flat";
+  /** Change label, e.g. "+12%". */
+  value?: React.ReactNode;
+  /** Colour of the trend. Defaults to neutral — "up" is not always good. */
+  tone?: Tone;
+}
+
+const trendIcon = {
+  up: ArrowUp,
+  down: ArrowDown,
+  flat: ArrowRight,
+} as const;
+
+export interface MetricProps extends Omit<React.ComponentProps<"div">, "title"> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  /** Leading icon component (e.g. a lucide-react icon). */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Supporting text under the value. */
+  supporting?: React.ReactNode;
+  trend?: MetricTrend;
+  /** Semantic colour for the value. */
+  tone?: Tone;
+  /** Vertical (default) or horizontal label/value arrangement. */
+  orientation?: "vertical" | "horizontal";
+}
+
+/** A single label + value metric, usable inline or inside a MetricCard. */
+function Metric({
+  className,
+  label,
+  value,
+  icon,
+  supporting,
+  trend,
+  tone,
+  orientation = "vertical",
+  ...props
+}: MetricProps) {
+  const TrendIcon = trend ? trendIcon[trend.direction] : null;
+  return (
+    <div
+      data-slot="metric"
+      className={cn(
+        "flex min-w-0",
+        orientation === "vertical"
+          ? "flex-col gap-0.5"
+          : "items-center justify-between gap-2",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex items-center gap-1.5">
+        {icon && <Icon icon={icon} size="sm" />}
+        <span className="truncate text-[11px] font-medium uppercase tracking-wide text-[var(--text-muted)]">
+          {label}
+        </span>
+      </div>
+      <div className="flex items-baseline gap-1.5">
+        <span
+          className={cn(
+            "text-lg font-semibold leading-none tabular-nums",
+            tone ? toneColor[tone] : "text-[var(--text-primary)]",
+          )}
+        >
+          {value}
+        </span>
+        {trend && TrendIcon && (
+          <span
+            className={cn(
+              "inline-flex items-center gap-0.5 text-xs font-medium tabular-nums",
+              trend.tone ? toneColor[trend.tone] : "text-[var(--text-muted)]",
+            )}
+          >
+            <TrendIcon className="size-3" aria-hidden />
+            {trend.value}
+          </span>
+        )}
+      </div>
+      {supporting && (
+        <span className="truncate text-xs text-[var(--text-muted)]">
+          {supporting}
+        </span>
+      )}
+    </div>
+  );
+}
+
+// ── MetricCard ───────────────────────────────────────────────────
+
+export interface MetricCardProps extends React.ComponentProps<"div"> {}
+
+/** A contained surface for a Metric (or any compact summary content). */
+function MetricCard({ className, ...props }: MetricCardProps) {
+  return (
+    <div
+      data-slot="metric-card"
+      className={cn(
+        "flex min-w-0 flex-col rounded-lg border border-[var(--surface-line)] bg-[var(--surface-raised)] p-3 shadow-[inset_0_1px_0_var(--surface-rim)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── MetricGroup ──────────────────────────────────────────────────
+
+export interface MetricGroupProps extends GridProps {}
+
+/** Arranges multiple metrics responsively in a bounded grid. */
+function MetricGroup({ columns = "auto", gap = "sm", minColumnWidth = 96, ...props }: MetricGroupProps) {
+  return (
+    <Grid
+      data-slot="metric-group"
+      columns={columns}
+      gap={gap}
+      minColumnWidth={minColumnWidth}
+      {...props}
+    />
+  );
+}
+
+export { Metric, MetricCard, MetricGroup };

package/src/components/dashboard/progress-ring.tsx

@@ -0,0 +1,100 @@
+// ProgressRing — an accessible circular progress / donut gauge.
+//
+// Pure SVG so consuming plugins need no charting dependency. Exposes an
+// accessible progressbar with value semantics and supports centre content.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { toneColor, type Tone } from "./tone";
+
+export interface ProgressRingProps
+  extends Omit<React.ComponentProps<"div">, "children"> {
+  /** Current value. */
+  value: number;
+  /** Maximum value the ring represents. */
+  max?: number;
+  /** Outer diameter in pixels. */
+  size?: number;
+  /** Stroke width in pixels. */
+  thickness?: number;
+  tone?: Tone;
+  /** Accessible name for the gauge. */
+  label?: string;
+  /** Show the percentage in the centre when no children are provided. */
+  showValue?: boolean;
+  /** Custom centre content (overrides `showValue`). */
+  children?: React.ReactNode;
+}
+
+/** Circular progress / donut gauge for a bounded value. */
+function ProgressRing({
+  className,
+  value,
+  max = 100,
+  size = 44,
+  thickness = 4,
+  tone = "info",
+  label,
+  showValue = true,
+  children,
+  ...props
+}: ProgressRingProps) {
+  const clamped = Math.min(Math.max(value, 0), max);
+  const pct = max > 0 ? clamped / max : 0;
+  const radius = (size - thickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const dashOffset = circumference * (1 - pct);
+  const center = size / 2;
+
+  return (
+    <div
+      data-slot="progress-ring"
+      role="progressbar"
+      aria-label={label}
+      aria-valuenow={Math.round(clamped)}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      className={cn(
+        "relative inline-flex shrink-0 items-center justify-center",
+        toneColor[tone],
+        className,
+      )}
+      style={{ width: size, height: size }}
+      {...props}
+    >
+      <svg width={size} height={size} className="-rotate-90">
+        <circle
+          cx={center}
+          cy={center}
+          r={radius}
+          fill="none"
+          stroke="var(--surface-line)"
+          strokeWidth={thickness}
+        />
+        <circle
+          cx={center}
+          cy={center}
+          r={radius}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={thickness}
+          strokeLinecap="round"
+          strokeDasharray={circumference}
+          strokeDashoffset={dashOffset}
+          className="transition-[stroke-dashoffset] duration-500"
+        />
+      </svg>
+      <div className="absolute inset-0 flex items-center justify-center text-[var(--text-primary)]">
+        {children ??
+          (showValue && (
+            <span className="text-xs font-semibold tabular-nums">
+              {Math.round(pct * 100)}%
+            </span>
+          ))}
+      </div>
+    </div>
+  );
+}
+
+export { ProgressRing };

package/src/components/dashboard/skeletons.tsx

@@ -0,0 +1,73 @@
+// Widget skeleton patterns — small compositions of the Skeleton primitive for
+// the common metric, list and activity loading layouts, so every widget shows a
+// consistent loading shape instead of hand-rolling one.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { Skeleton } from "../ui/skeleton";
+
+export interface SkeletonPatternProps extends React.ComponentProps<"div"> {
+  /** Number of rows / cells to render. */
+  count?: number;
+}
+
+/** A row of metric placeholders (label + value stacks). */
+function MetricSkeleton({ className, count = 3, ...props }: SkeletonPatternProps) {
+  return (
+    <div
+      data-slot="metric-skeleton"
+      className={cn("flex gap-4", className)}
+      {...props}
+    >
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="flex flex-1 flex-col gap-1.5">
+          <Skeleton className="h-2.5 w-12" />
+          <Skeleton className="h-5 w-8" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** A stack of list-row placeholders. */
+function ListSkeleton({ className, count = 4, ...props }: SkeletonPatternProps) {
+  return (
+    <div
+      data-slot="list-skeleton"
+      className={cn("flex flex-col gap-1", className)}
+      {...props}
+    >
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="flex items-center gap-2 rounded-md p-2">
+          <Skeleton className="size-2 rounded-full" />
+          <Skeleton className="h-3 flex-1" />
+          <Skeleton className="h-3 w-8" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** A stack of activity-row placeholders (marker + label + timestamp). */
+function ActivitySkeleton({ className, count = 4, ...props }: SkeletonPatternProps) {
+  return (
+    <div
+      data-slot="activity-skeleton"
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    >
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="flex items-start gap-2">
+          <Skeleton className="mt-0.5 size-2 rounded-full" />
+          <div className="flex flex-1 flex-col gap-1">
+            <Skeleton className="h-3 w-3/4" />
+            <Skeleton className="h-2.5 w-1/2" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export { MetricSkeleton, ListSkeleton, ActivitySkeleton };

package/src/components/dashboard/spacing.ts

@@ -0,0 +1,14 @@
+// Shared semantic spacing scale for dashboard layout components.
+//
+// One scale keeps gaps consistent across Stack, Inline, Grid and Section so
+// widgets do not drift into ad-hoc `gap-[7px]` values.
+
+export type Gap = "none" | "xs" | "sm" | "md" | "lg";
+
+export const gapClass: Record<Gap, string> = {
+  none: "gap-0",
+  xs: "gap-1",
+  sm: "gap-2",
+  md: "gap-3",
+  lg: "gap-4",
+};

package/src/components/dashboard/stale-indicator.tsx

@@ -0,0 +1,55 @@
+// StaleIndicator — a compact hint that displayed data may be out of date.
+//
+// Shows an optional last-updated value and an optional refresh action. The
+// component owns no fetching; the plugin passes the label and handles refresh.
+
+import * as React from "react";
+import { Clock, RotateCw } from "lucide-react";
+
+import { cn } from "../../lib/utils";
+import { Icon } from "./typography";
+import { IconButton } from "./icon-button";
+
+export interface StaleIndicatorProps extends React.ComponentProps<"div"> {
+  /** Pre-formatted last-updated value, e.g. "Updated 5m ago". */
+  lastUpdated?: React.ReactNode;
+  /** Refresh handler. When provided, a refresh button is shown. */
+  onRefresh?: () => void;
+  /** Spin the refresh icon while a refresh is in flight. */
+  refreshing?: boolean;
+}
+
+/** Compact "data may be stale" indicator with optional refresh. */
+function StaleIndicator({
+  className,
+  lastUpdated,
+  onRefresh,
+  refreshing = false,
+  ...props
+}: StaleIndicatorProps) {
+  return (
+    <div
+      data-slot="stale-indicator"
+      className={cn(
+        "flex items-center gap-1.5 text-[11px] text-[var(--text-muted)]",
+        className,
+      )}
+      {...props}
+    >
+      <Icon icon={Clock} size="xs" tone="warning" />
+      <span className="truncate">{lastUpdated ?? "Data may be out of date"}</span>
+      {onRefresh && (
+        <IconButton
+          icon={RotateCw}
+          label="Refresh"
+          size="xs"
+          onClick={onRefresh}
+          className={cn("ml-auto", refreshing && "animate-spin")}
+          disabled={refreshing}
+        />
+      )}
+    </div>
+  );
+}
+
+export { StaleIndicator };

package/src/components/dashboard/status.tsx

@@ -0,0 +1,75 @@
+// Status — a semantic status dot, label or pill.
+//
+// Replaces the hand-rolled `size-2 rounded-full` dots with inline hex colours
+// that appear across the existing widgets. Encodes only neutral semantic tones,
+// never plugin-specific status names — callers map their domain status onto a
+// tone.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { toneColor, toneDot, tonePill, type Tone } from "./tone";
+
+export interface StatusProps extends React.ComponentProps<"span"> {
+  tone?: Tone;
+  /** Presentation: coloured dot + label, a tinted pill, or a bare dot. */
+  variant?: "dot" | "pill";
+  /** Add a soft glow to the dot (e.g. a live/active indicator). */
+  pulse?: boolean;
+}
+
+/** Semantic status dot, label or pill with neutral/success/warning/error/info tones. */
+function Status({
+  className,
+  tone = "neutral",
+  variant = "dot",
+  pulse = false,
+  children,
+  ...props
+}: StatusProps) {
+  const hasLabel = children != null && children !== "";
+
+  if (variant === "pill") {
+    return (
+      <span
+        data-slot="status"
+        data-tone={tone}
+        className={cn(
+          "inline-flex w-fit items-center gap-1.5 rounded-full px-2 py-0.5 text-xs font-medium",
+          tonePill[tone],
+          className,
+        )}
+        {...props}
+      >
+        <span className={cn("size-1.5 shrink-0 rounded-full", toneDot[tone])} />
+        {children}
+      </span>
+    );
+  }
+
+  return (
+    <span
+      data-slot="status"
+      data-tone={tone}
+      // A bare dot carries no text, so surface the tone to assistive tech.
+      role={hasLabel ? undefined : "status"}
+      className={cn(
+        "inline-flex items-center gap-1.5 text-xs font-medium text-[var(--text-secondary)]",
+        className,
+      )}
+      {...props}
+    >
+      <span
+        className={cn(
+          "size-2 shrink-0 rounded-full",
+          toneDot[tone],
+          // ring-current picks up the tone's text colour for a matching glow.
+          pulse && cn(toneColor[tone], "ring-2 ring-current/25"),
+        )}
+      />
+      {children}
+    </span>
+  );
+}
+
+export { Status };

package/src/components/dashboard/tone.ts

@@ -0,0 +1,35 @@
+// Shared semantic tone vocabulary for dashboard components.
+//
+// Tones map to the `--status-*` design tokens in styles/globals.css so every
+// dashboard component speaks one status language. Components must never encode
+// plugin-specific status names (e.g. "running", "queued") — they map their
+// domain status onto one of these neutral tones.
+
+export type Tone = "neutral" | "success" | "warning" | "error" | "info";
+
+/** Solid foreground colour for a tone (dots, icons, emphasised text). */
+export const toneColor: Record<Tone, string> = {
+  neutral: "text-[var(--text-muted)]",
+  success: "text-[var(--status-success)]",
+  warning: "text-[var(--status-warning)]",
+  error: "text-[var(--status-error)]",
+  info: "text-[var(--status-info)]",
+};
+
+/** Solid background colour for a tone (status dots). */
+export const toneDot: Record<Tone, string> = {
+  neutral: "bg-[var(--text-muted)]",
+  success: "bg-[var(--status-success)]",
+  warning: "bg-[var(--status-warning)]",
+  error: "bg-[var(--status-error)]",
+  info: "bg-[var(--status-info)]",
+};
+
+/** Muted tinted background + matching text for a tone (pills, chips). */
+export const tonePill: Record<Tone, string> = {
+  neutral: "bg-[var(--surface-flat)] text-[var(--text-secondary)]",
+  success: "bg-[var(--status-success-muted)] text-[var(--status-success)]",
+  warning: "bg-[var(--status-warning-muted)] text-[var(--status-warning)]",
+  error: "bg-[var(--status-error-muted)] text-[var(--status-error)]",
+  info: "bg-[var(--status-info-muted)] text-[var(--status-info)]",
+};

package/src/components/dashboard/typography.tsx

@@ -0,0 +1,151 @@
+// Typography and media primitives for dashboard widgets.
+//
+// Text, Heading and Icon give one type scale and one icon treatment so
+// equivalent text and icons render identically across widgets, replacing the
+// scattered `text-[9px]`/`text-[10px]` and per-widget muted colours.
+
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../../lib/utils";
+import { toneColor, type Tone } from "./tone";
+
+// ── Text ─────────────────────────────────────────────────────────
+
+const textVariants = cva("min-w-0", {
+  variants: {
+    variant: {
+      body: "text-sm text-[var(--text-primary)]",
+      label:
+        "text-[11px] font-semibold uppercase tracking-wider text-[var(--text-muted)]",
+      supporting: "text-xs text-[var(--text-secondary)]",
+      muted: "text-xs text-[var(--text-muted)]",
+      numeric:
+        "text-sm font-semibold tabular-nums text-[var(--text-primary)]",
+    },
+  },
+  defaultVariants: { variant: "body" },
+});
+
+export interface TextProps
+  extends Omit<React.ComponentProps<"span">, "color">,
+    VariantProps<typeof textVariants> {
+  /** Truncate to a single line with an ellipsis. */
+  truncate?: boolean;
+  /** Clamp to N lines. Overrides `truncate`. */
+  clamp?: 1 | 2 | 3;
+  /** Semantic colour override (e.g. a numeric value that turns red on error). */
+  tone?: Tone;
+  asChild?: boolean;
+}
+
+const clampClass = {
+  1: "line-clamp-1",
+  2: "line-clamp-2",
+  3: "line-clamp-3",
+} as const;
+
+/** Semantic text with truncation, line-clamp and optional tone. */
+function Text({
+  className,
+  variant,
+  truncate,
+  clamp,
+  tone,
+  ...props
+}: TextProps) {
+  return (
+    <span
+      data-slot="text"
+      className={cn(
+        textVariants({ variant }),
+        clamp ? clampClass[clamp] : truncate && "truncate",
+        tone && toneColor[tone],
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Heading ──────────────────────────────────────────────────────
+
+const headingSize = {
+  sm: "text-xs font-semibold",
+  md: "text-sm font-semibold",
+  lg: "text-base font-semibold",
+} as const;
+
+export interface HeadingProps extends React.ComponentProps<"h2"> {
+  /** HTML heading level for correct document semantics (1–4). */
+  level?: 1 | 2 | 3 | 4;
+  /** Visual size, decoupled from the semantic level. */
+  size?: keyof typeof headingSize;
+  truncate?: boolean;
+}
+
+/** Compact heading with correct HTML semantics decoupled from visual size. */
+function Heading({
+  className,
+  level = 2,
+  size = "md",
+  truncate,
+  ...props
+}: HeadingProps) {
+  const Tag = `h${level}` as "h1" | "h2" | "h3" | "h4";
+  return (
+    <Tag
+      data-slot="heading"
+      className={cn(
+        "leading-snug text-[var(--text-primary)]",
+        headingSize[size],
+        truncate && "truncate",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Icon ─────────────────────────────────────────────────────────
+
+const iconSize = {
+  xs: "size-3",
+  sm: "size-3.5",
+  md: "size-4",
+  lg: "size-5",
+} as const;
+
+export interface IconProps extends React.ComponentProps<"span"> {
+  /** The icon component to render (e.g. a lucide-react icon). */
+  icon: React.ComponentType<{ className?: string }>;
+  size?: keyof typeof iconSize;
+  tone?: Tone;
+  /**
+   * Accessible label. When omitted the icon is decorative and hidden from
+   * assistive tech; when provided it is exposed as an image with this name.
+   */
+  label?: string;
+}
+
+/** Consistent icon wrapper for size, tone and accessibility. */
+function Icon({ className, icon: IconCmp, size = "md", tone, label, ...props }: IconProps) {
+  return (
+    <span
+      data-slot="icon"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={cn(
+        "inline-flex shrink-0 items-center justify-center",
+        tone ? toneColor[tone] : "text-[var(--text-muted)]",
+        className,
+      )}
+      {...props}
+    >
+      <IconCmp className={iconSize[size]} />
+    </span>
+  );
+}
+
+export { Text, Heading, Icon };