@sero-ai/ui 0.3.2 → 0.4.1

package/src/components/dashboard/__tests__/catalog.test.ts

@@ -0,0 +1,62 @@
+// Catalogue integrity — keeps the JSON catalogue honest against the exports.
+
+import { describe, expect, it } from "vitest";
+
+import type { DashboardComponentCatalogEntry } from "../catalog";
+import catalogJson from "../catalog.json";
+import * as dashboard from "../index";
+
+// The JSON is the source of truth. JSON imports widen literal unions to
+// `string`, so assert the authored entry shape for the checks below.
+const dashboardComponentCatalog = catalogJson as DashboardComponentCatalogEntry[];
+
+// Reused primitives live in other component folders, not the dashboard barrel.
+const REUSED_PRIMITIVES = new Set(["Badge", "Alert", "Button", "Skeleton"]);
+
+const names = dashboardComponentCatalog.map((e) => e.name);
+
+describe("dashboard catalogue", () => {
+  it("has no duplicate component names", () => {
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it("every composite entry is exported from the dashboard barrel", () => {
+    const missing = dashboardComponentCatalog
+      .filter((e) => e.kind === "composite")
+      .filter((e) => !(e.name in dashboard))
+      .map((e) => e.name);
+    expect(missing).toEqual([]);
+  });
+
+  it("every primitive entry is a known reused primitive", () => {
+    const bad = dashboardComponentCatalog
+      .filter((e) => e.kind === "primitive")
+      .filter((e) => !REUSED_PRIMITIVES.has(e.name))
+      .map((e) => e.name);
+    expect(bad).toEqual([]);
+  });
+
+  it("every related name resolves to a catalogue entry", () => {
+    const known = new Set(names);
+    const broken: string[] = [];
+    for (const entry of dashboardComponentCatalog) {
+      for (const rel of entry.related ?? []) {
+        if (!known.has(rel)) broken.push(`${entry.name} -> ${rel}`);
+      }
+    }
+    expect(broken).toEqual([]);
+  });
+
+  it("every composite exported from the barrel appears in the catalogue", () => {
+    // The barrel also exports helpers (tone maps, gapClass) and types; only
+    // check the React components (PascalCase functions) are catalogued.
+    const catalogued = new Set(names);
+    const uncatalogued = Object.entries(dashboard)
+      .filter(
+        ([name, value]) =>
+          /^[A-Z]/.test(name) && typeof value === "function" && !catalogued.has(name),
+      )
+      .map(([name]) => name);
+    expect(uncatalogued).toEqual([]);
+  });
+});

package/src/components/dashboard/__tests__/glass.test.tsx

@@ -0,0 +1,42 @@
+// Glass-scope tests: WidgetContent applies the token scope, and surfaces
+// route through the scope-aware `--surface-*` tokens rather than solid ones.
+
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { WidgetContent } from "../layout";
+import { MetricCard } from "../metric";
+import { ItemList, ItemListItem } from "../item-list";
+
+describe("WidgetContent glass scope", () => {
+  it("applies the glass class by default", () => {
+    const html = renderToStaticMarkup(<WidgetContent />);
+    expect(html).toContain("glass");
+  });
+
+  it("omits the glass class when glass={false}", () => {
+    const html = renderToStaticMarkup(<WidgetContent glass={false} />);
+    expect(html).not.toContain(' class="glass');
+    expect(html).not.toMatch(/\bglass\b/);
+  });
+});
+
+describe("surface token routing", () => {
+  it("MetricCard reads raised surface + rim tokens, not solid bg-surface", () => {
+    const html = renderToStaticMarkup(<MetricCard />);
+    expect(html).toContain("--surface-raised");
+    expect(html).toContain("--surface-line");
+    expect(html).toContain("--surface-rim");
+    expect(html).not.toContain("--bg-surface");
+  });
+
+  it("ItemListItem reads the flat surface token, not the muted variant", () => {
+    const html = renderToStaticMarkup(
+      <ItemList>
+        <ItemListItem primary="Row" />
+      </ItemList>,
+    );
+    expect(html).toContain("--surface-flat");
+    expect(html).not.toContain("bg-muted/50");
+  });
+});

package/src/components/dashboard/__tests__/state.test.tsx

@@ -0,0 +1,127 @@
+// State-selection + accessibility-contract tests for dashboard components.
+
+import { renderToStaticMarkup } from "react-dom/server";
+import { RotateCw, Clock } from "lucide-react";
+import { describe, expect, it } from "vitest";
+
+import { DataBoundary } from "../data-boundary";
+import { EmptyState } from "../empty-state";
+import { IconButton } from "../icon-button";
+import { Icon } from "../typography";
+import { ProgressRing } from "../progress-ring";
+import { Status } from "../status";
+
+describe("DataBoundary", () => {
+  const slots = {
+    loading: <div>LOADING</div>,
+    empty: <div>EMPTY</div>,
+    error: <div>ERROR</div>,
+    stale: <div>STALE</div>,
+    children: <div>READY</div>,
+  };
+
+  it("renders only the loading slot when loading", () => {
+    const html = renderToStaticMarkup(
+      <DataBoundary state="loading" {...slots} />,
+    );
+    expect(html).toContain("LOADING");
+    expect(html).not.toContain("READY");
+    expect(html).not.toContain("EMPTY");
+  });
+
+  it("renders only the empty slot when empty", () => {
+    const html = renderToStaticMarkup(<DataBoundary state="empty" {...slots} />);
+    expect(html).toContain("EMPTY");
+    expect(html).not.toContain("READY");
+  });
+
+  it("renders only the error slot when error", () => {
+    const html = renderToStaticMarkup(<DataBoundary state="error" {...slots} />);
+    expect(html).toContain("ERROR");
+    expect(html).not.toContain("READY");
+  });
+
+  it("renders the stale banner above ready content when stale", () => {
+    const html = renderToStaticMarkup(<DataBoundary state="stale" {...slots} />);
+    expect(html).toContain("STALE");
+    expect(html).toContain("READY");
+    expect(html.indexOf("STALE")).toBeLessThan(html.indexOf("READY"));
+  });
+
+  it("renders ready children when ready", () => {
+    const html = renderToStaticMarkup(<DataBoundary state="ready" {...slots} />);
+    expect(html).toContain("READY");
+    expect(html).not.toContain("STALE");
+  });
+});
+
+describe("accessibility contracts", () => {
+  it("ProgressRing exposes progressbar value semantics", () => {
+    const html = renderToStaticMarkup(
+      <ProgressRing value={30} max={60} label="Usage" />,
+    );
+    expect(html).toContain('role="progressbar"');
+    expect(html).toContain('aria-label="Usage"');
+    expect(html).toContain('aria-valuenow="30"');
+    expect(html).toContain('aria-valuemax="60"');
+    // 30 / 60 = 50%
+    expect(html).toContain("50%");
+  });
+
+  it("ProgressRing clamps out-of-range values", () => {
+    const html = renderToStaticMarkup(<ProgressRing value={999} max={100} />);
+    expect(html).toContain('aria-valuenow="100"');
+    expect(html).toContain("100%");
+  });
+
+  it("Icon is hidden from assistive tech without a label", () => {
+    const html = renderToStaticMarkup(<Icon icon={Clock} />);
+    expect(html).toContain('aria-hidden="true"');
+    expect(html).not.toContain('role="img"');
+  });
+
+  it("Icon is exposed as an image with a label", () => {
+    const html = renderToStaticMarkup(<Icon icon={Clock} label="Time" />);
+    expect(html).toContain('role="img"');
+    expect(html).toContain('aria-label="Time"');
+  });
+
+  it("IconButton carries its required accessible label", () => {
+    const html = renderToStaticMarkup(
+      <IconButton icon={RotateCw} label="Refresh" />,
+    );
+    expect(html).toContain('aria-label="Refresh"');
+    expect(html).toContain('type="button"');
+  });
+
+  it("a bare Status dot exposes its tone as announceable text", () => {
+    const html = renderToStaticMarkup(<Status tone="success" />);
+    expect(html).toContain('role="status"');
+    // Not an empty live region: assistive tech gets a text alternative.
+    expect(html).toContain('class="sr-only">Success<');
+  });
+
+  it("a bare Status dot honours a caller aria-label instead of the tone", () => {
+    const html = renderToStaticMarkup(
+      <Status tone="success" aria-label="Backup succeeded" />,
+    );
+    expect(html).toContain('aria-label="Backup succeeded"');
+    // The caller supplied the name, so no generic fallback is added.
+    expect(html).not.toContain("sr-only");
+  });
+
+  it("a labelled Status uses its visible text and adds no fallback", () => {
+    const html = renderToStaticMarkup(<Status tone="neutral">Idle</Status>);
+    expect(html).toContain("Idle");
+    expect(html).not.toContain('role="status"');
+    expect(html).not.toContain("sr-only");
+  });
+
+  it("EmptyState renders its title and message", () => {
+    const html = renderToStaticMarkup(
+      <EmptyState title="Nothing here" message="Add an item to start" />,
+    );
+    expect(html).toContain("Nothing here");
+    expect(html).toContain("Add an item to start");
+  });
+});

package/src/components/dashboard/__tests__/variants.test.tsx

@@ -0,0 +1,95 @@
+// Variant / tone tests for dashboard components.
+
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { Badge } from "../../ui/badge";
+import { Grid, Inline, Stack } from "../layout";
+import { Metric } from "../metric";
+import { Status } from "../status";
+import { Text } from "../typography";
+
+describe("Status tones", () => {
+  it("renders a tinted pill for a tone", () => {
+    const html = renderToStaticMarkup(
+      <Status tone="warning" variant="pill">
+        Degraded
+      </Status>,
+    );
+    expect(html).toContain("--status-warning-muted");
+    expect(html).toContain("Degraded");
+    expect(html).toContain('data-tone="warning"');
+  });
+
+  it("maps neutral tone to the muted token", () => {
+    const html = renderToStaticMarkup(<Status tone="neutral">Idle</Status>);
+    expect(html).toContain("--text-muted");
+  });
+});
+
+describe("Badge semantic tones", () => {
+  it.each([
+    ["success", "--status-success"],
+    ["warning", "--status-warning"],
+    ["info", "--status-info"],
+  ] as const)("badge %s uses its status token", (variant, token) => {
+    const html = renderToStaticMarkup(<Badge variant={variant}>x</Badge>);
+    expect(html).toContain(token);
+  });
+});
+
+describe("Text variants", () => {
+  it("numeric variant uses tabular numerals", () => {
+    const html = renderToStaticMarkup(<Text variant="numeric">42</Text>);
+    expect(html).toContain("tabular-nums");
+  });
+
+  it("clamp overrides truncate", () => {
+    const html = renderToStaticMarkup(
+      <Text truncate clamp={2}>
+        long
+      </Text>,
+    );
+    expect(html).toContain("line-clamp-2");
+    expect(html).not.toContain("truncate");
+  });
+});
+
+describe("Metric", () => {
+  it("renders label, value and a trend", () => {
+    const html = renderToStaticMarkup(
+      <Metric
+        label="Jobs"
+        value={6}
+        trend={{ direction: "up", value: "+2", tone: "success" }}
+      />,
+    );
+    expect(html).toContain("Jobs");
+    expect(html).toContain("6");
+    expect(html).toContain("+2");
+    expect(html).toContain("--status-success");
+  });
+});
+
+describe("layout spacing scale", () => {
+  it("Stack maps semantic gap to a utility", () => {
+    expect(renderToStaticMarkup(<Stack gap="lg" />)).toContain("gap-4");
+  });
+  it("Stack fill grows without scrolling; scroll adds overflow", () => {
+    const fill = renderToStaticMarkup(<Stack fill />);
+    expect(fill).toContain("flex-1");
+    expect(fill).not.toContain("overflow-auto");
+    expect(renderToStaticMarkup(<Stack scroll />)).toContain("overflow-auto");
+  });
+  it("Inline wraps when asked", () => {
+    expect(renderToStaticMarkup(<Inline wrap />)).toContain("flex-wrap");
+  });
+  it("Grid with fixed columns uses a column utility", () => {
+    expect(renderToStaticMarkup(<Grid columns={3} />)).toContain("grid-cols-3");
+  });
+  it("Grid auto uses an inline template", () => {
+    expect(renderToStaticMarkup(<Grid columns="auto" minColumnWidth={80} />)).toContain(
+      "minmax(80px",
+    );
+  });
+});

package/src/components/dashboard/activity-list.tsx

@@ -0,0 +1,99 @@
+// ActivityList and ActivityListItem — a compact chronological event list.
+//
+// Each row carries a status marker or icon, a label, a timestamp and optional
+// supporting detail. Timestamps are passed as pre-formatted strings — the
+// component never computes relative time, so it stays stateless and the plugin
+// owns any refresh.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { Icon } from "./typography";
+import { toneDot, type Tone } from "./tone";
+
+export interface ActivityListItemProps
+  extends Omit<React.ComponentProps<"li">, "title"> {
+  label: React.ReactNode;
+  /** Pre-formatted timestamp, e.g. "08:00" or "in 2h". */
+  timestamp?: React.ReactNode;
+  /** Supporting detail under the label. */
+  detail?: React.ReactNode;
+  /** Status marker tone. Ignored when `icon` is provided. */
+  tone?: Tone;
+  /** Leading icon component, used instead of the status dot. */
+  icon?: React.ComponentType<{ className?: string }>;
+}
+
+/** A single chronological event row. */
+function ActivityListItem({
+  className,
+  label,
+  timestamp,
+  detail,
+  tone = "neutral",
+  icon,
+  ...props
+}: ActivityListItemProps) {
+  return (
+    <li
+      data-slot="activity-list-item"
+      className={cn("flex items-start gap-2 py-1", className)}
+      {...props}
+    >
+      <span className="mt-1 flex size-3.5 shrink-0 items-center justify-center">
+        {icon ? (
+          <Icon icon={icon} size="xs" tone={tone === "neutral" ? undefined : tone} />
+        ) : (
+          <span className={cn("size-2 rounded-full", toneDot[tone])} />
+        )}
+      </span>
+      <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+        <div className="flex items-baseline justify-between gap-2">
+          <span className="truncate text-xs text-[var(--text-primary)]">
+            {label}
+          </span>
+          {timestamp && (
+            <span className="shrink-0 text-[11px] tabular-nums text-[var(--text-muted)]">
+              {timestamp}
+            </span>
+          )}
+        </div>
+        {detail && (
+          <span className="line-clamp-1 text-xs text-[var(--text-muted)]">
+            {detail}
+          </span>
+        )}
+      </div>
+    </li>
+  );
+}
+
+export interface ActivityListProps extends React.ComponentProps<"ul"> {
+  /** Count of events not shown; renders a "+N more" footer when > 0. */
+  overflowCount?: number;
+}
+
+/** A chronological list of ActivityListItem rows. */
+function ActivityList({
+  className,
+  overflowCount = 0,
+  children,
+  ...props
+}: ActivityListProps) {
+  return (
+    <ul
+      data-slot="activity-list"
+      className={cn("flex min-w-0 flex-col", className)}
+      {...props}
+    >
+      {children}
+      {overflowCount > 0 && (
+        <li className="pl-5 pt-0.5 text-[11px] text-[var(--text-muted)]">
+          +{overflowCount} more
+        </li>
+      )}
+    </ul>
+  );
+}
+
+export { ActivityList, ActivityListItem };