@sero-ai/ui 0.3.2 → 0.4.0

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

@@ -0,0 +1,110 @@
+// 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 is announced as a status", () => {
+    const html = renderToStaticMarkup(<Status tone="success" />);
+    expect(html).toContain('role="status"');
+    expect(html).toContain('data-tone="success"');
+  });
+
+  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 };

package/src/components/dashboard/catalog.ts

@@ -0,0 +1,351 @@
+// Dashboard component catalogue — the source of truth for discovery.
+//
+// This is package metadata, not a runtime service. It changes through normal
+// source review and ships with @sero-ai/ui. Widget code imports the React
+// components from "@sero-ai/ui"; tooling and the agent read this metadata via
+// "@sero-ai/ui/dashboard-catalog" to discover the supported vocabulary.
+//
+// Keep this in step with the two readable views on release:
+//   - packages/templates/skills/sero-dashboard-ui/references/component-catalog.md
+//   - the docs-site dashboard component catalogue page
+// (Generation + drift validation is a deferred follow-up.)
+
+export interface DashboardComponentCatalogEntry {
+  name: string;
+  category:
+    | "layout"
+    | "typography"
+    | "data-display"
+    | "state"
+    | "action"
+    | "filter";
+  /** `primitive` = existing @sero-ai/ui primitive; `composite` = new dashboard component. */
+  kind: "primitive" | "composite";
+  summary: string;
+  useWhen: string;
+  related?: string[];
+  status: "stable" | "experimental";
+  example?: string;
+}
+
+export const dashboardComponentCatalog: DashboardComponentCatalogEntry[] = [
+  // ── Layout and structure ──────────────────────────────────────
+  {
+    name: "WidgetContent",
+    category: "layout",
+    kind: "composite",
+    summary:
+      "Full-height widget frame with standard padding and a container-query boundary.",
+    useWhen: "As the outermost element of every dashboard widget.",
+    related: ["Stack", "Inline"],
+    status: "stable",
+    example: "<WidgetContent><Stack gap=\"sm\">…</Stack></WidgetContent>",
+  },
+  {
+    name: "Stack",
+    category: "layout",
+    kind: "composite",
+    summary: "Vertical layout with semantic spacing, alignment and optional scrolling.",
+    useWhen: "For the primary top-to-bottom content flow inside a widget.",
+    related: ["Inline", "WidgetContent"],
+    status: "stable",
+    example: "<Stack gap=\"sm\" scroll>…</Stack>",
+  },
+  {
+    name: "Inline",
+    category: "layout",
+    kind: "composite",
+    summary: "Horizontal layout with spacing, alignment, wrap and justify.",
+    useWhen: "For a row of items such as a header with a trailing action.",
+    related: ["Stack"],
+    status: "stable",
+    example: "<Inline justify=\"between\" align=\"center\">…</Inline>",
+  },
+  {
+    name: "Grid",
+    category: "layout",
+    kind: "composite",
+    summary: "Responsive grid with bounded columns and gap.",
+    useWhen: "For metric and summary layouts that reflow by width.",
+    related: ["MetricGroup"],
+    status: "stable",
+    example: "<Grid columns=\"auto\" minColumnWidth={120}>…</Grid>",
+  },
+  {
+    name: "Section",
+    category: "layout",
+    kind: "composite",
+    summary: "Compact section with optional heading, description and trailing action.",
+    useWhen: "To group related content under a labelled heading.",
+    related: ["Divider", "Heading"],
+    status: "stable",
+    example: "<Section heading=\"Summary\" action={…}>…</Section>",
+  },
+  {
+    name: "Divider",
+    category: "layout",
+    kind: "composite",
+    summary: "Compact horizontal or vertical divider built on Separator.",
+    useWhen: "To separate sections without a heavy border.",
+    related: ["Section"],
+    status: "stable",
+    example: "<Divider spacing=\"sm\" />",
+  },
+  // ── Typography and media ──────────────────────────────────────
+  {
+    name: "Text",
+    category: "typography",
+    kind: "composite",
+    summary:
+      "Semantic text variants (body, label, supporting, muted, numeric) with truncation.",
+    useWhen: "For any text, instead of ad-hoc font-size utilities.",
+    related: ["Heading"],
+    status: "stable",
+    example: "<Text variant=\"label\">Jobs</Text>",
+  },
+  {
+    name: "Heading",
+    category: "typography",
+    kind: "composite",
+    summary: "Compact heading levels and sizes that keep correct HTML semantics.",
+    useWhen: "For section and view titles.",
+    related: ["Section", "Text"],
+    status: "stable",
+    example: "<Heading level={2} size=\"md\">Overview</Heading>",
+  },
+  {
+    name: "Icon",
+    category: "typography",
+    kind: "composite",
+    summary: "Consistent icon wrapper for size, tone and accessibility.",
+    useWhen: "To render an icon component with a shared size and tone.",
+    related: ["IconButton"],
+    status: "stable",
+    example: "<Icon icon={Clock} size=\"sm\" tone=\"warning\" />",
+  },
+  // ── Data display ──────────────────────────────────────────────
+  {
+    name: "Metric",
+    category: "data-display",
+    kind: "composite",
+    summary: "Label + value with optional icon, supporting text and trend.",
+    useWhen: "To show a single number inline.",
+    related: ["MetricCard", "MetricGroup"],
+    status: "stable",
+    example: "<Metric label=\"Jobs\" value={6} />",
+  },
+  {
+    name: "MetricCard",
+    category: "data-display",
+    kind: "composite",
+    summary: "A contained surface for a Metric or compact summary.",
+    useWhen: "To give a metric its own bounded card.",
+    related: ["Metric", "MetricGroup"],
+    status: "stable",
+    example: "<MetricCard><Metric label=\"Jobs\" value={6} /></MetricCard>",
+  },
+  {
+    name: "MetricGroup",
+    category: "data-display",
+    kind: "composite",
+    summary: "Arranges multiple metrics responsively in a bounded grid.",
+    useWhen: "To show several metrics that reflow by width.",
+    related: ["Metric", "Grid"],
+    status: "stable",
+    example: "<MetricGroup><Metric … /><Metric … /></MetricGroup>",
+  },
+  {
+    name: "Status",
+    category: "data-display",
+    kind: "composite",
+    summary: "Semantic status dot, label or pill with neutral/success/warning/error/info tones.",
+    useWhen: "To show a health or state indicator. Map domain status onto a tone.",
+    related: ["Badge"],
+    status: "stable",
+    example: "<Status tone=\"success\">Active</Status>",
+  },
+  {
+    name: "Badge",
+    category: "data-display",
+    kind: "primitive",
+    summary: "Existing badge primitive, extended with success/warning/info tones.",
+    useWhen: "For compact counts, tags and category labels.",
+    related: ["Status"],
+    status: "stable",
+    example: "<Badge variant=\"success\">Passed</Badge>",
+  },
+  {
+    name: "KeyValue",
+    category: "data-display",
+    kind: "composite",
+    summary: "A single label/value row with predictable alignment and truncation.",
+    useWhen: "For metadata, totals and configuration summaries.",
+    related: ["KeyValueList"],
+    status: "stable",
+    example: "<KeyValue label=\"Region\" value=\"eu-west-1\" mono />",
+  },
+  {
+    name: "KeyValueList",
+    category: "data-display",
+    kind: "composite",
+    summary: "A vertical list of KeyValue rows.",
+    useWhen: "For a block of metadata pairs.",
+    related: ["KeyValue"],
+    status: "stable",
+    example: "<KeyValueList><KeyValue … /></KeyValueList>",
+  },
+  {
+    name: "ItemList",
+    category: "data-display",
+    kind: "composite",
+    summary: "Compact rows with leading media, text, trailing metadata, actions and overflow.",
+    useWhen: "For entity lists (files, notes, results).",
+    related: ["ItemListItem", "ActivityList"],
+    status: "stable",
+    example: "<ItemList overflowCount={3}><ItemListItem … /></ItemList>",
+  },
+  {
+    name: "ItemListItem",
+    category: "data-display",
+    kind: "composite",
+    summary: "A single compact list row with media, primary/secondary text and actions.",
+    useWhen: "As the row inside an ItemList.",
+    related: ["ItemList"],
+    status: "stable",
+    example: "<ItemListItem primary=\"Report.pdf\" trailing=\"2h\" />",
+  },
+  {
+    name: "ActivityList",
+    category: "data-display",
+    kind: "composite",
+    summary: "A chronological list for recent events with a shared overflow footer.",
+    useWhen: "For time-ordered activity or upcoming events.",
+    related: ["ActivityListItem", "ItemList"],
+    status: "stable",
+    example: "<ActivityList><ActivityListItem … /></ActivityList>",
+  },
+  {
+    name: "ActivityListItem",
+    category: "data-display",
+    kind: "composite",
+    summary: "An event row with a status marker or icon, label, timestamp and detail.",
+    useWhen: "As the row inside an ActivityList.",
+    related: ["ActivityList", "Status"],
+    status: "stable",
+    example: "<ActivityListItem label=\"Backup\" timestamp=\"08:00\" tone=\"success\" />",
+  },
+  {
+    name: "ProgressRing",
+    category: "data-display",
+    kind: "composite",
+    summary: "Accessible circular progress / donut gauge, no charting dependency.",
+    useWhen: "For a bounded value such as a success rate or usage percentage.",
+    related: ["Metric"],
+    status: "stable",
+    example: "<ProgressRing value={75} label=\"Success rate\" tone=\"success\" />",
+  },
+  {
+    name: "StaleIndicator",
+    category: "data-display",
+    kind: "composite",
+    summary: "Compact hint that data may be out of date, with optional refresh action.",
+    useWhen: "When displayed data can lag its source.",
+    related: ["DataBoundary"],
+    status: "stable",
+    example: "<StaleIndicator lastUpdated=\"Updated 5m ago\" onRefresh={…} />",
+  },
+  // ── Runtime states and feedback ───────────────────────────────
+  {
+    name: "DataBoundary",
+    category: "state",
+    kind: "composite",
+    summary: "Selects presentation for loading / ready / empty / stale / error states.",
+    useWhen: "To switch a widget's content by data state without owning fetching.",
+    related: ["EmptyState", "MetricSkeleton", "StaleIndicator"],
+    status: "stable",
+    example: "<DataBoundary state={state} loading={…} empty={…} error={…}>…</DataBoundary>",
+  },
+  {
+    name: "EmptyState",
+    category: "state",
+    kind: "composite",
+    summary: "Compact empty state built on the Empty primitives.",
+    useWhen: "When there is nothing to show yet.",
+    related: ["DataBoundary"],
+    status: "stable",
+    example: "<EmptyState icon={Inbox} title=\"No activity yet\" />",
+  },
+  {
+    name: "Alert",
+    category: "state",
+    kind: "primitive",
+    summary: "Existing alert primitive for inline warnings and errors.",
+    useWhen: "For a persistent inline message inside a widget or view.",
+    related: ["DataBoundary"],
+    status: "stable",
+    example: "<Alert variant=\"destructive\">Failed to load</Alert>",
+  },
+  {
+    name: "MetricSkeleton",
+    category: "state",
+    kind: "composite",
+    summary: "Loading placeholder for a row of metrics.",
+    useWhen: "As the `loading` fallback for metric layouts.",
+    related: ["DataBoundary", "ListSkeleton"],
+    status: "stable",
+    example: "<MetricSkeleton count={3} />",
+  },
+  {
+    name: "ListSkeleton",
+    category: "state",
+    kind: "composite",
+    summary: "Loading placeholder for a list of rows.",
+    useWhen: "As the `loading` fallback for item lists.",
+    related: ["DataBoundary", "ItemList"],
+    status: "stable",
+    example: "<ListSkeleton count={4} />",
+  },
+  {
+    name: "ActivitySkeleton",
+    category: "state",
+    kind: "composite",
+    summary: "Loading placeholder for an activity list.",
+    useWhen: "As the `loading` fallback for activity feeds.",
+    related: ["DataBoundary", "ActivityList"],
+    status: "stable",
+    example: "<ActivitySkeleton count={4} />",
+  },
+  {
+    name: "Skeleton",
+    category: "state",
+    kind: "primitive",
+    summary: "Existing skeleton primitive for bespoke loading shapes.",
+    useWhen: "When the prebuilt skeleton patterns do not fit.",
+    related: ["MetricSkeleton", "ListSkeleton", "ActivitySkeleton"],
+    status: "stable",
+    example: "<Skeleton className=\"h-4 w-24\" />",
+  },
+  // ── Actions ───────────────────────────────────────────────────
+  {
+    name: "Button",
+    category: "action",
+    kind: "primitive",
+    summary: "Existing button primitive, the standard text-action control.",
+    useWhen: "For a labelled action.",
+    related: ["IconButton"],
+    status: "stable",
+    example: "<Button size=\"sm\">Open</Button>",
+  },
+  {
+    name: "IconButton",
+    category: "action",
+    kind: "composite",
+    summary: "Small icon-only button with a required accessible label.",
+    useWhen: "For a compact action such as refresh or dismiss.",
+    related: ["Button", "Icon"],
+    status: "stable",
+    example: "<IconButton icon={RotateCw} label=\"Refresh\" size=\"xs\" />",
+  },
+];
+
+export default dashboardComponentCatalog;