@sero-ai/ui 0.3.2 → 0.4.1

package/src/components/dashboard/key-value.tsx

@@ -0,0 +1,54 @@
+// KeyValue and KeyValueList — compact label/value metadata.
+//
+// For configuration summaries, totals and metadata where a full metric is too
+// heavy. Uses a semantic description list with predictable alignment and
+// value truncation.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+export interface KeyValueProps extends React.ComponentProps<"div"> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  /** Use mono + tabular numerals for the value (ids, counts, sizes). */
+  mono?: boolean;
+}
+
+/** A single label/value row rendered as a `dt`/`dd` pair. */
+function KeyValue({ className, label, value, mono, ...props }: KeyValueProps) {
+  return (
+    <div
+      data-slot="key-value"
+      className={cn("flex items-baseline justify-between gap-3", className)}
+      {...props}
+    >
+      <dt className="shrink-0 truncate text-xs text-[var(--text-muted)]">
+        {label}
+      </dt>
+      <dd
+        className={cn(
+          "min-w-0 truncate text-right text-xs text-[var(--text-primary)]",
+          mono && "font-mono tabular-nums",
+        )}
+      >
+        {value}
+      </dd>
+    </div>
+  );
+}
+
+export interface KeyValueListProps extends React.ComponentProps<"dl"> {}
+
+/** A vertical list of KeyValue rows. */
+function KeyValueList({ className, ...props }: KeyValueListProps) {
+  return (
+    <dl
+      data-slot="key-value-list"
+      className={cn("flex flex-col gap-1.5", className)}
+      {...props}
+    />
+  );
+}
+
+export { KeyValue, KeyValueList };

package/src/components/dashboard/layout.tsx

@@ -0,0 +1,286 @@
+// Layout and structure primitives for dashboard widgets.
+//
+// WidgetContent, Stack, Inline, Grid, Section and Divider give widgets a
+// consistent frame, spacing and container-query boundary without re-declaring
+// `flex h-full flex-col gap-2 p-3` in every widget. They compose normal React
+// children and accept `className` for escape hatches.
+
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../../lib/utils";
+import { Separator } from "../ui/separator";
+import { gapClass, type Gap } from "./spacing";
+
+// ── WidgetContent ────────────────────────────────────────────────
+
+const widgetContentVariants = cva(
+  // Full-height frame with a container-query boundary so child components can
+  // respond to the widget's own size rather than the viewport.
+  "@container/widget flex h-full min-h-0 flex-col",
+  {
+    variants: {
+      padding: {
+        none: "p-0",
+        sm: "p-2",
+        md: "p-3",
+        lg: "p-4",
+      },
+      scroll: {
+        true: "overflow-auto",
+        false: "overflow-hidden",
+      },
+    },
+    defaultVariants: { padding: "md", scroll: false },
+  },
+);
+
+export interface WidgetContentProps
+  extends React.ComponentProps<"div">,
+    VariantProps<typeof widgetContentVariants> {
+  /**
+   * Apply the glass token scope so surfaces read as translucent on the
+   * frosted dashboard tile. On by default; set `false` for solid full
+   * plugin views (outside a dashboard tile).
+   */
+  glass?: boolean;
+}
+
+/** Full-height widget content frame with standard padding + a container query. */
+function WidgetContent({
+  className,
+  padding,
+  scroll,
+  glass = true,
+  ...props
+}: WidgetContentProps) {
+  return (
+    <div
+      data-slot="widget-content"
+      className={cn(widgetContentVariants({ padding, scroll }), glass && "glass", className)}
+      {...props}
+    />
+  );
+}
+
+// ── Stack ────────────────────────────────────────────────────────
+
+const alignClass = {
+  start: "items-start",
+  center: "items-center",
+  end: "items-end",
+  stretch: "items-stretch",
+} as const;
+
+const justifyClass = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+  around: "justify-around",
+} as const;
+
+export interface StackProps extends React.ComponentProps<"div"> {
+  gap?: Gap;
+  align?: keyof typeof alignClass;
+  justify?: keyof typeof justifyClass;
+  /**
+   * Grow to fill the remaining height of a flex parent (e.g. the top-level
+   * Stack under `WidgetContent`, so a nested `scroll` region can bound).
+   */
+  fill?: boolean;
+  /** Fill remaining height and scroll overflow. Use for the main content flow. */
+  scroll?: boolean;
+}
+
+/** Vertical layout with semantic spacing, alignment and optional scrolling. */
+function Stack({
+  className,
+  gap = "sm",
+  align,
+  justify,
+  fill = false,
+  scroll = false,
+  ...props
+}: StackProps) {
+  return (
+    <div
+      data-slot="stack"
+      className={cn(
+        "flex flex-col",
+        gapClass[gap],
+        align && alignClass[align],
+        justify && justifyClass[justify],
+        (fill || scroll) && "min-h-0 flex-1",
+        scroll && "overflow-auto",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Inline ───────────────────────────────────────────────────────
+
+export interface InlineProps extends React.ComponentProps<"div"> {
+  gap?: Gap;
+  align?: keyof typeof alignClass;
+  justify?: keyof typeof justifyClass;
+  wrap?: boolean;
+}
+
+/** Horizontal layout with semantic spacing, alignment, wrap and justify. */
+function Inline({
+  className,
+  gap = "sm",
+  align = "center",
+  justify,
+  wrap = false,
+  ...props
+}: InlineProps) {
+  return (
+    <div
+      data-slot="inline"
+      className={cn(
+        "flex flex-row",
+        gapClass[gap],
+        alignClass[align],
+        justify && justifyClass[justify],
+        wrap ? "flex-wrap" : "min-w-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Grid ─────────────────────────────────────────────────────────
+
+const columnsClass = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+} as const;
+
+export interface GridProps extends React.ComponentProps<"div"> {
+  /** Fixed column count, or `auto` for a responsive min-width fill. */
+  columns?: keyof typeof columnsClass | "auto";
+  gap?: Gap;
+  /** Minimum column width for `columns="auto"`. */
+  minColumnWidth?: number;
+}
+
+/** Responsive grid with bounded columns for metric and summary layouts. */
+function Grid({
+  className,
+  columns = "auto",
+  gap = "sm",
+  minColumnWidth = 120,
+  style,
+  ...props
+}: GridProps) {
+  const auto = columns === "auto";
+  return (
+    <div
+      data-slot="grid"
+      className={cn(
+        "grid",
+        gapClass[gap],
+        !auto && columnsClass[columns],
+        className,
+      )}
+      style={
+        auto
+          ? {
+              gridTemplateColumns: `repeat(auto-fill, minmax(${minColumnWidth}px, 1fr))`,
+              ...style,
+            }
+          : style
+      }
+      {...props}
+    />
+  );
+}
+
+// ── Section ──────────────────────────────────────────────────────
+
+export interface SectionProps extends React.ComponentProps<"div"> {
+  /** Section heading text or node. Omit for an unlabelled group. */
+  heading?: React.ReactNode;
+  /** Supporting text shown under the heading. */
+  description?: React.ReactNode;
+  /** Trailing action aligned to the heading row (e.g. an IconButton). */
+  action?: React.ReactNode;
+  gap?: Gap;
+}
+
+/** Compact section with optional heading, description and trailing action. */
+function Section({
+  className,
+  heading,
+  description,
+  action,
+  gap = "sm",
+  children,
+  ...props
+}: SectionProps) {
+  return (
+    <section
+      data-slot="section"
+      className={cn("flex flex-col", gapClass[gap], className)}
+      {...props}
+    >
+      {(heading || action) && (
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex min-w-0 flex-col gap-0.5">
+            {heading && (
+              <h3 className="truncate text-[11px] font-semibold uppercase tracking-wider text-[var(--text-muted)]">
+                {heading}
+              </h3>
+            )}
+            {description && (
+              <p className="truncate text-xs text-[var(--text-muted)]">
+                {description}
+              </p>
+            )}
+          </div>
+          {action && <div className="shrink-0">{action}</div>}
+        </div>
+      )}
+      {children}
+    </section>
+  );
+}
+
+// ── Divider ──────────────────────────────────────────────────────
+
+export interface DividerProps
+  extends React.ComponentProps<typeof Separator> {
+  /** Vertical spacing around a horizontal divider. */
+  spacing?: "none" | "sm" | "md";
+}
+
+const dividerSpacing = { none: "my-0", sm: "my-1", md: "my-2" } as const;
+
+/** Compact divider built on the Separator primitive. */
+function Divider({
+  className,
+  orientation = "horizontal",
+  spacing = "sm",
+  ...props
+}: DividerProps) {
+  return (
+    <Separator
+      data-slot="divider"
+      orientation={orientation}
+      className={cn(
+        orientation === "horizontal" ? dividerSpacing[spacing] : "mx-1",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { WidgetContent, Stack, Inline, Grid, Section, Divider };

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",
+};