@sero-ai/ui 0.3.1 → 0.4.0

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 exported
+// separately from `@sero-ai/ui/dashboard-catalog`, not 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 };

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 };