@sero-ai/ui 0.3.2 → 0.4.1

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,88 @@
+// 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, toneLabel, 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 !== "";
+  const hasAccessibleName =
+    props["aria-label"] != null || props["aria-labelledby"] != null;
+
+  // A bare indicator (no visible children) is otherwise silent to assistive
+  // tech. Give it a text alternative — the caller's aria-label if provided,
+  // else the generic tone name — so its state is announced, not an empty region.
+  const hiddenLabel =
+    !hasLabel && !hasAccessibleName ? (
+      <span className="sr-only">{toneLabel[tone]}</span>
+    ) : null;
+
+  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}
+        {hiddenLabel}
+      </span>
+    );
+  }
+
+  return (
+    <span
+      data-slot="status"
+      data-tone={tone}
+      // A bare dot carries no visible text, so expose its state to assistive
+      // tech via role="status" plus the hidden label below.
+      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}
+      {hiddenLabel}
+    </span>
+  );
+}
+
+export { Status };

package/src/components/dashboard/tone.ts

@@ -0,0 +1,48 @@
+// 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)]",
+};
+
+/**
+ * Default accessible name for a tone, used as the text alternative when a
+ * status indicator carries no visible label. Generic by design — callers with
+ * a domain-specific meaning should pass their own `aria-label`.
+ */
+export const toneLabel: Record<Tone, string> = {
+  neutral: "Neutral",
+  success: "Success",
+  warning: "Warning",
+  error: "Error",
+  info: "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 };

package/src/components/reference/ActivityExample.tsx

@@ -0,0 +1,68 @@
+// ActivityExample — a scrollable item list with a header count and a
+// footer status row.
+//
+// Pure static presentation; a real feed would wire its rows through a
+// DataBoundary (loading / empty / error) driven by plugin state. See the
+// runtime-state components in the catalogue for those slots.
+
+import { FileText } from "lucide-react";
+
+import {
+  Inline,
+  ItemList,
+  ItemListItem,
+  Stack,
+  StaleIndicator,
+  Status,
+  Text,
+  WidgetContent,
+} from "../dashboard";
+import { Badge } from "../ui/badge";
+
+const ITEMS = [
+  { id: "1", title: "quarterly-report.pdf", meta: "2h", badge: "PDF" },
+  { id: "2", title: "design-tokens.json", meta: "5h", badge: "JSON" },
+  { id: "3", title: "release-notes.md", meta: "1d", badge: "MD" },
+];
+
+export function ActivityExample() {
+  return (
+    <WidgetContent>
+      <Stack gap="sm" fill>
+        <Inline justify="between" align="center">
+          <Inline gap="xs" align="center">
+            <Text variant="label">Recent files</Text>
+            <Badge variant="info">{ITEMS.length}</Badge>
+          </Inline>
+        </Inline>
+
+        <Stack gap="none" scroll>
+          <ItemList>
+            {ITEMS.map((f) => (
+              <ItemListItem
+                key={f.id}
+                leading={<FileText className="size-4 text-[var(--text-muted)]" />}
+                primary={f.title}
+                trailing={
+                  <Inline gap="xs" align="center">
+                    <Badge variant="secondary">{f.badge}</Badge>
+                    <span>{f.meta}</span>
+                  </Inline>
+                }
+              />
+            ))}
+          </ItemList>
+        </Stack>
+
+        <Inline justify="between" align="center">
+          <Status tone="info" variant="pill">
+            Synced
+          </Status>
+          <StaleIndicator lastUpdated="Synced 30s ago" />
+        </Inline>
+      </Stack>
+    </WidgetContent>
+  );
+}
+
+export default ActivityExample;

package/src/components/reference/ResourceExample.tsx

@@ -0,0 +1,78 @@
+// ResourceExample — a grid, gauges, key/value metadata and headings.
+//
+// Pure static presentation; a real resource monitor would read live host
+// metrics from its plugin.
+
+import {
+  Divider,
+  Grid,
+  Heading,
+  KeyValue,
+  KeyValueList,
+  Metric,
+  MetricGroup,
+  ProgressRing,
+  Section,
+  Stack,
+  Status,
+  Text,
+  WidgetContent,
+} from "../dashboard";
+
+function Ring({
+  value,
+  label,
+  tone,
+}: {
+  value: number;
+  label: string;
+  tone: "success" | "info" | "warning";
+}) {
+  return (
+    <Stack gap="xs" align="center">
+      <ProgressRing value={value} label={label} tone={tone} />
+      <Text variant="muted">{label}</Text>
+    </Stack>
+  );
+}
+
+export function ResourceExample() {
+  return (
+    <WidgetContent scroll>
+      <Stack gap="sm">
+        <Heading level={2} size="md">
+          Resources
+        </Heading>
+
+        <MetricGroup>
+          <Metric label="CPU" value="42%" tone="success" />
+          <Metric label="Memory" value="6.1 GB" />
+          <Metric label="Disk" value="71%" tone="warning" />
+        </MetricGroup>
+
+        <Divider />
+
+        <Section heading="Usage">
+          <Grid columns={3} gap="sm">
+            <Ring value={42} label="CPU" tone="success" />
+            <Ring value={61} label="Memory" tone="info" />
+            <Ring value={71} label="Disk" tone="warning" />
+          </Grid>
+        </Section>
+
+        <Divider />
+
+        <Section heading="Host">
+          <KeyValueList>
+            <KeyValue label="Region" value="eu-west-1" mono />
+            <KeyValue label="Instance" value="c7g.xlarge" mono />
+            <KeyValue label="Uptime" value="14d 6h" mono />
+            <KeyValue label="Status" value={<Status tone="success">Healthy</Status>} />
+          </KeyValueList>
+        </Section>
+      </Stack>
+    </WidgetContent>
+  );
+}
+
+export default ResourceExample;

package/src/components/reference/SchedulerExample.tsx

@@ -0,0 +1,88 @@
+// SchedulerExample — layout, metric cards, a gauge and an activity group.
+//
+// Pure static presentation (fixed sample data, no state or controls); a real
+// scheduler widget would read jobs and run stats from its plugin.
+
+import { ExternalLink } from "lucide-react";
+
+import {
+  ActivityList,
+  ActivityListItem,
+  DataBoundary,
+  Divider,
+  Inline,
+  Metric,
+  MetricCard,
+  ProgressRing,
+  Section,
+  Stack,
+  StaleIndicator,
+  Status,
+  WidgetContent,
+} from "../dashboard";
+import { Button } from "../ui/button";
+
+const UPCOMING = [
+  { id: "a", label: "Daily backup", timestamp: "08:00", tone: "success" as const },
+  { id: "b", label: "Publish report", timestamp: "in 2h", tone: "info" as const },
+  { id: "c", label: "Rotate API keys", timestamp: "tomorrow", tone: "warning" as const },
+];
+
+export function SchedulerExample() {
+  return (
+    <WidgetContent>
+      <Stack gap="sm">
+        <Inline justify="between" align="center">
+          <Status tone="success" pulse>
+            Scheduler active
+          </Status>
+          <ProgressRing value={92} label="Success rate" tone="success" size={40} />
+        </Inline>
+
+        <Section heading="Summary">
+          <Inline gap="sm" wrap>
+            <MetricCard className="flex-1">
+              <Metric label="Jobs" value={6} />
+            </MetricCard>
+            <MetricCard className="flex-1">
+              <Metric
+                label="Runs today"
+                value={18}
+                trend={{ direction: "up", value: "+4", tone: "success" }}
+              />
+            </MetricCard>
+          </Inline>
+        </Section>
+
+        <Divider />
+
+        <Section
+          heading="Next up"
+          action={
+            <Button size="xs" variant="ghost">
+              <ExternalLink className="size-3" />
+              All
+            </Button>
+          }
+        >
+          <DataBoundary state="ready">
+            <ActivityList>
+              {UPCOMING.map((e) => (
+                <ActivityListItem
+                  key={e.id}
+                  tone={e.tone}
+                  label={e.label}
+                  timestamp={e.timestamp}
+                />
+              ))}
+            </ActivityList>
+          </DataBoundary>
+        </Section>
+
+        <StaleIndicator lastUpdated="Updated 2m ago" />
+      </Stack>
+    </WidgetContent>
+  );
+}
+
+export default SchedulerExample;

package/src/components/reference/StarterExample.tsx

@@ -0,0 +1,48 @@
+// StarterExample — the smallest useful widget: a headline metric and a
+// short list. Copy this as the starting point for a new dashboard widget.
+//
+// Reference widgets are pure static presentation (fixed sample data, no
+// state or controls) so they render identically anywhere. A real widget
+// swaps the sample data for state read from its plugin.
+
+import { CheckCircle2 } from "lucide-react";
+
+import {
+  ActivityList,
+  ActivityListItem,
+  Metric,
+  Section,
+  Stack,
+  WidgetContent,
+} from "../dashboard";
+
+const RECENT = [
+  { id: "a", label: "Nightly build", timestamp: "12m", tone: "success" as const },
+  { id: "b", label: "Deploy to staging", timestamp: "1h", tone: "info" as const },
+  { id: "c", label: "Dependency audit", timestamp: "3h", tone: "neutral" as const },
+];
+
+export function StarterExample() {
+  return (
+    <WidgetContent>
+      <Stack gap="sm">
+        <Metric label="Tasks done" value={12} icon={CheckCircle2} tone="success" />
+
+        <Section heading="Recent">
+          <ActivityList>
+            {RECENT.map((e) => (
+              <ActivityListItem
+                key={e.id}
+                tone={e.tone}
+                label={e.label}
+                timestamp={e.timestamp}
+              />
+            ))}
+          </ActivityList>
+        </Section>
+      </Stack>
+    </WidgetContent>
+  );
+}
+
+export default StarterExample;

package/src/components/reference/index.ts

@@ -0,0 +1,10 @@
+// Reference dashboard widgets — worked examples of the @sero-ai/ui dashboard
+// components, glass-styled and ready to copy. Pure static presentation.
+//
+// Exposed to widget authors via the `@sero-ai/ui/reference` subpath, not the
+// main barrel.
+
+export { StarterExample } from "./StarterExample";
+export { SchedulerExample } from "./SchedulerExample";
+export { ResourceExample } from "./ResourceExample";
+export { ActivityExample } from "./ActivityExample";

package/src/components/ui/badge.tsx

@@ -18,6 +18,12 @@ const badgeVariants = cva(
           "border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
         ghost: "[a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
         link: "text-primary underline-offset-4 [a&]:hover:underline",
+        // Semantic status tones (error is covered by `destructive`).
+        success:
+          "bg-[var(--status-success-muted)] text-[var(--status-success)]",
+        warning:
+          "bg-[var(--status-warning-muted)] text-[var(--status-warning)]",
+        info: "bg-[var(--status-info-muted)] text-[var(--status-info)]",
       },
     },
     defaultVariants: {

package/src/index.ts

@@ -131,6 +131,13 @@ export * from "./components/ai-elements/voice-selector-accent";
 export * from "./components/ai-elements/voice-selector";
 export * from "./components/ai-elements/web-preview";
 
+// ── Dashboard Components ──
+// Compact presentation components for dashboard widgets and full plugin views.
+// The discovery catalogue is plain data at "@sero-ai/ui/dashboard-catalog.json";
+// its entry type is re-exported here for callers that type the parsed JSON.
+export * from "./components/dashboard";
+export type { DashboardComponentCatalogEntry } from "./components/dashboard/catalog";
+
 // ── Model Selection Components ──
 export * from "./components/model-selection/available-model-picker";
 export * from "./components/model-selection/model-warning-list";

package/src/reference.ts

@@ -0,0 +1,15 @@
+// Stable subpath for the reference dashboard widgets.
+//
+//   import { SchedulerExample } from "@sero-ai/ui/reference";
+//
+// These are worked, glass-styled examples of the dashboard components —
+// importable to preview, or copy-pasteable as a starting point for a real
+// widget. Kept out of the main barrel so they don't ship with app bundles
+// that only need the components.
+
+export {
+  StarterExample,
+  SchedulerExample,
+  ResourceExample,
+  ActivityExample,
+} from "./components/reference";