@sero-ai/ui 0.3.2 → 0.4.1

package/src/components/dashboard/catalog.json

@@ -0,0 +1,312 @@
+[
+  {
+    "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\" />"
+  },
+  {
+    "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\" />"
+  },
+  {
+    "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={…} />"
+  },
+  {
+    "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\" />"
+  },
+  {
+    "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\" />"
+  }
+]

package/src/components/dashboard/catalog.ts

@@ -0,0 +1,29 @@
+// Dashboard component catalogue — type for the JSON source of truth.
+//
+// The catalogue data lives in `catalog.json` (plain data, no compiler needed)
+// and ships as `@sero-ai/ui/dashboard-catalog.json`. Tooling and the agent read
+// that file directly; this module only provides the entry type so TypeScript
+// callers can type the parsed JSON.
+//
+// Keep `catalog.json` 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;
+}

package/src/components/dashboard/data-boundary.tsx

@@ -0,0 +1,54 @@
+// DataBoundary — a presentation boundary for runtime data states.
+//
+// It selects which content to show for loading / ready / empty / stale / error.
+// It is presentation only: it does not fetch data, subscribe to sources or own
+// retry behaviour. The plugin passes the current state and the fallback nodes.
+
+import * as React from "react";
+
+export type DataState = "loading" | "ready" | "empty" | "stale" | "error";
+
+export interface DataBoundaryProps {
+  state: DataState;
+  /** Shown while `state === "loading"`. */
+  loading?: React.ReactNode;
+  /** Shown while `state === "empty"`. */
+  empty?: React.ReactNode;
+  /** Shown while `state === "error"`. */
+  error?: React.ReactNode;
+  /** Banner rendered above children while `state === "stale"`. */
+  stale?: React.ReactNode;
+  /** Ready content, also shown (below `stale`) while `state === "stale"`. */
+  children?: React.ReactNode;
+}
+
+/** Selects presentation for the current data state. */
+function DataBoundary({
+  state,
+  loading,
+  empty,
+  error,
+  stale,
+  children,
+}: DataBoundaryProps) {
+  switch (state) {
+    case "loading":
+      return <>{loading ?? null}</>;
+    case "empty":
+      return <>{empty ?? null}</>;
+    case "error":
+      return <>{error ?? null}</>;
+    case "stale":
+      return (
+        <>
+          {stale}
+          {children}
+        </>
+      );
+    case "ready":
+    default:
+      return <>{children}</>;
+  }
+}
+
+export { DataBoundary };

package/src/components/dashboard/empty-state.tsx

@@ -0,0 +1,70 @@
+// EmptyState — a compact empty state built on the Empty primitives.
+//
+// Tightened for widget use (the base Empty primitive pads for full pages).
+// Optional icon, title, message and action.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../ui/empty";
+import { Icon } from "./typography";
+
+export interface EmptyStateProps
+  extends Omit<React.ComponentProps<typeof Empty>, "title"> {
+  /** Leading icon component (e.g. a lucide-react icon). */
+  icon?: React.ComponentType<{ className?: string }>;
+  title: React.ReactNode;
+  message?: React.ReactNode;
+  /** Optional action (e.g. a Button). */
+  action?: React.ReactNode;
+}
+
+/** Compact empty state for widgets and plugin views. */
+function EmptyState({
+  className,
+  icon,
+  title,
+  message,
+  action,
+  ...props
+}: EmptyStateProps) {
+  return (
+    <Empty
+      data-slot="empty-state"
+      className={cn(
+        "flex-1 gap-3 border-0 p-4 md:p-4",
+        className,
+      )}
+      {...props}
+    >
+      <EmptyHeader className="gap-1.5">
+        {icon && (
+          <EmptyMedia
+            variant="icon"
+            className="size-9 border-[var(--surface-line)] bg-[var(--surface-flat)] text-[var(--text-muted)]"
+          >
+            <Icon icon={icon} size="md" className="text-current" />
+          </EmptyMedia>
+        )}
+        <EmptyTitle className="text-sm font-medium text-[var(--text-primary)]">
+          {title}
+        </EmptyTitle>
+        {message && (
+          <EmptyDescription className="text-xs text-[var(--text-muted)]">
+            {message}
+          </EmptyDescription>
+        )}
+      </EmptyHeader>
+      {action && <EmptyContent className="gap-2">{action}</EmptyContent>}
+    </Empty>
+  );
+}
+
+export { EmptyState };

package/src/components/dashboard/icon-button.tsx

@@ -0,0 +1,58 @@
+// IconButton — a small icon-only button built on the Button primitive.
+//
+// Widget-appropriate sizing with a required accessible label, since an
+// icon-only control carries no text for assistive tech.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { Button } from "../ui/button";
+import { Icon } from "./typography";
+
+const sizeMap = {
+  xs: "icon-xs",
+  sm: "icon-sm",
+  md: "icon",
+} as const;
+
+const iconSizeMap = {
+  xs: "xs",
+  sm: "sm",
+  md: "md",
+} as const;
+
+export interface IconButtonProps
+  extends Omit<React.ComponentProps<typeof Button>, "size" | "children"> {
+  /** The icon component to render (e.g. a lucide-react icon). */
+  icon: React.ComponentType<{ className?: string }>;
+  /** Required accessible label — the control has no visible text. */
+  label: string;
+  size?: keyof typeof sizeMap;
+}
+
+/** A compact icon-only button with a required accessible label. */
+function IconButton({
+  className,
+  icon,
+  label,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: IconButtonProps) {
+  return (
+    <Button
+      data-slot="icon-button"
+      type="button"
+      variant={variant}
+      size={sizeMap[size]}
+      aria-label={label}
+      title={label}
+      className={cn("text-[var(--text-muted)]", className)}
+      {...props}
+    >
+      <Icon icon={icon} size={iconSizeMap[size]} className="text-current" />
+    </Button>
+  );
+}
+
+export { IconButton };

package/src/components/dashboard/index.ts

@@ -0,0 +1,21 @@
+// @sero-ai/ui dashboard components — shared compact presentation for widgets
+// and full plugin views. Import from the package root: `@sero-ai/ui`.
+//
+// The component catalogue (metadata for discovery tooling) is plain data at
+// `@sero-ai/ui/dashboard-catalog.json`, not exported from here.
+
+export * from "./tone";
+export * from "./spacing";
+export * from "./layout";
+export * from "./typography";
+export * from "./metric";
+export * from "./status";
+export * from "./key-value";
+export * from "./item-list";
+export * from "./activity-list";
+export * from "./progress-ring";
+export * from "./stale-indicator";
+export * from "./data-boundary";
+export * from "./empty-state";
+export * from "./skeletons";
+export * from "./icon-button";

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

@@ -0,0 +1,106 @@
+// ItemList and ItemListItem — compact rows for dashboard lists.
+//
+// Built on the existing Item primitive, tightened for dense widget use. Each
+// row takes optional leading media, primary/secondary text, trailing metadata
+// and actions. ItemList adds a shared overflow ("+N more") treatment so widgets
+// stop hand-rolling it.
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import {
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemMedia,
+  ItemTitle,
+} from "../ui/item";
+
+export interface ItemListItemProps
+  extends Omit<React.ComponentProps<typeof Item>, "children"> {
+  /** Leading media — an icon, avatar or status marker. */
+  leading?: React.ReactNode;
+  primary: React.ReactNode;
+  secondary?: React.ReactNode;
+  /** Trailing metadata (e.g. a timestamp or count). */
+  trailing?: React.ReactNode;
+  /** Trailing interactive actions (e.g. an IconButton). */
+  actions?: React.ReactNode;
+}
+
+/** A single compact list row with optional media, text, metadata and actions. */
+function ItemListItem({
+  className,
+  leading,
+  primary,
+  secondary,
+  trailing,
+  actions,
+  variant = "default",
+  ...props
+}: ItemListItemProps) {
+  return (
+    <Item
+      data-slot="item-list-item"
+      variant={variant}
+      size="sm"
+      className={cn(
+        "gap-2 rounded-md bg-[var(--surface-flat)] p-2 transition-colors hover:bg-[var(--glass-hover)]",
+        className,
+      )}
+      {...props}
+    >
+      {leading && (
+        <ItemMedia className="self-center">{leading}</ItemMedia>
+      )}
+      <ItemContent className="gap-0.5">
+        <ItemTitle className="truncate text-xs font-medium text-[var(--text-primary)]">
+          {primary}
+        </ItemTitle>
+        {secondary && (
+          <ItemDescription className="line-clamp-1 text-xs text-[var(--text-muted)]">
+            {secondary}
+          </ItemDescription>
+        )}
+      </ItemContent>
+      {trailing && (
+        <span className="shrink-0 text-[11px] tabular-nums text-[var(--text-muted)]">
+          {trailing}
+        </span>
+      )}
+      {actions && <ItemActions>{actions}</ItemActions>}
+    </Item>
+  );
+}
+
+export interface ItemListProps extends React.ComponentProps<"div"> {
+  /** Count of items not shown; renders a "+N more" footer when > 0. */
+  overflowCount?: number;
+}
+
+/** A vertical stack of ItemListItem rows with a shared overflow footer. */
+function ItemList({
+  className,
+  overflowCount = 0,
+  children,
+  ...props
+}: ItemListProps) {
+  return (
+    <div
+      data-slot="item-list"
+      role="list"
+      className={cn("flex min-w-0 flex-col gap-1", className)}
+      {...props}
+    >
+      {children}
+      {overflowCount > 0 && (
+        <span className="px-2 text-[11px] text-[var(--text-muted)]">
+          +{overflowCount} more
+        </span>
+      )}
+    </div>
+  );
+}
+
+export { ItemList, ItemListItem };