Skip to content

Open-source status page, incident response and uptime monitoring

feat: openstatus registry (#1838)

Maximilian Kaske6b5ec72960a0
diff --git a/apps/web/src/content/mdx.tsx b/apps/web/src/content/mdx.tsx
index 8c3ec93d0..4b2d1ee78 100644
--- a/apps/web/src/content/mdx.tsx
+++ b/apps/web/src/content/mdx.tsx
@@ -13,6 +13,7 @@ import { CopyButton } from "./copy-button";
import { HighlightText } from "./highlight-text";
import { ImageZoom } from "./image-zoom";
import { LatencyChartTable } from "./latency-chart-table";
+import { StatusPageExample } from "./shadcn-registry-example";
function Table({
data,
@@ -362,6 +363,7 @@ export const components = {
</div>
);
},
+ StatusPageExample,
};
function MDXContent(props: MDXRemoteProps) {
diff --git a/apps/web/src/content/pages/unrelated/about.mdx b/apps/web/src/content/pages/unrelated/about.mdx
index 56ab3249c..48baf493f 100644
--- a/apps/web/src/content/pages/unrelated/about.mdx
+++ b/apps/web/src/content/pages/unrelated/about.mdx
@@ -3,7 +3,7 @@ title: "About openstatus"
publishedAt: "2025-11-10"
author: "openstatus"
description: "openstatus is built by a small team of passionate developers, committed to creating the best open-source status page and uptime monitoring solution."
-category: "Company"
+category: "company"
---
<Grid cols={3}>
diff --git a/apps/web/src/content/pages/unrelated/not-found.mdx b/apps/web/src/content/pages/unrelated/not-found.mdx
index 6292d87fe..9d33642e0 100644
--- a/apps/web/src/content/pages/unrelated/not-found.mdx
+++ b/apps/web/src/content/pages/unrelated/not-found.mdx
@@ -3,7 +3,7 @@ title: "404 - Not Found"
publishedAt: "2025-11-10"
author: "openstatus"
description: "The page you are looking for does not exist."
-category: "Company"
+category: "company"
---
---
diff --git a/apps/web/src/content/pages/unrelated/pricing.mdx b/apps/web/src/content/pages/unrelated/pricing.mdx
index b66950be3..44c76600d 100644
--- a/apps/web/src/content/pages/unrelated/pricing.mdx
+++ b/apps/web/src/content/pages/unrelated/pricing.mdx
@@ -3,7 +3,7 @@ title: "Pricing"
publishedAt: "2025-11-10"
author: "Maximilian Kaske"
description: "All plans. Start free today, upgrade later."
-category: "Company"
+category: "company"
---
<Table
diff --git a/apps/web/src/content/pages/unrelated/registry.mdx b/apps/web/src/content/pages/unrelated/registry.mdx
new file mode 100644
index 000000000..263b5525d
--- /dev/null
+++ b/apps/web/src/content/pages/unrelated/registry.mdx
@@ -0,0 +1,78 @@
+---
+title: "Component Registry"
+publishedAt: "2026-02-08"
+author: "openstatus"
+description: "Install beautiful, accessible React components for status pages. Pre-built, customizable components compatible with shadcn/ui."
+category: "Documentation"
+---
+
+Build your status page in minutes, not hours. The Openstatus registry gives you production-ready React components specifically designed for status pages. Built on top of shadcn/ui, these components are accessible, customizable, and battle-tested in production.
+
+## What is the Registry?
+
+The Openstatus registry is a shadcn/ui-compatible collection of pre-built components for common status page patterns. Instead of building status indicators, event timelines, and monitoring displays from scratch, you can install and customize these components directly into your project.
+
+All components are:
+- **Accessible** - Built with ARIA patterns and keyboard navigation
+- **Customizable** - Fully themeable with Tailwind CSS
+- **Type-safe** - Written in TypeScript with complete type definitions
+- **Production-ready** - Battle-tested in production at Openstatus
+
+## Complete Example
+
+<Grid cols={1}>
+
+<div>
+
+<StatusPageExample />
+
+</div>
+
+</Grid>
+
+> We are working on matching the component `Props` and the [`@openstatus/sdk-node`](https://jsr.io/@openstatus/sdk-node) return values, allowing you to use our SDK to build your own custom status page.
+
+See the [complete example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) for full source code and usage patterns.
+
+## Installation
+
+Install any component with a single command:
+
+```bash
+npx shadcn@latest add https://openstatus.dev/r/status-complete
+```
+
+### Available Components
+
+Components are organized by function:
+
+- **Collections:** `status-complete`, `status-essentials` - Full status page bundles
+- **Building Blocks:** `status-banner`, `status-bar`, `status-feed`, `status-events`, `status-component`, `status-icon`, `status-layout`, `status-timestamp` - Individual components
+
+Browse the full registry at [openstatus.dev/r/registry.json](https://openstatus.dev/r/registry.json)
+
+---
+
+Using openstatus but want a custom theme?
+
+<ButtonLink href="https://themes.openstatus.dev" children="Go to Themes Explorer" />
+
+---
+
+## Learn More
+
+- [Complete Example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) - See all components in action
+- [Openstatus SDK](https://jsr.io/@openstatus/sdk-node) - Build on top of openstatus with our SDK
+- [shadcn/ui Documentation](https://ui.shadcn.com) - Learn about the underlying component system
+- [Openstatus GitHub](https://github.com/openstatusHQ/openstatus) - Star the project and contribute
+- [Component Source Code](https://github.com/openstatusHQ/openstatus/tree/main/packages/ui/src/components) - Browse the implementation
+- [Theme Explorer](https://themes.openstatus.dev) - Explore community themes
+
+## Support
+
+If you encounter issues, have questions, or want to share feedback:
+
+- [Open an issue](https://github.com/openstatusHQ/openstatus/issues)
+- [Join our Discord](https://openstatus.dev/discord)
+- [Check the documentation](https://docs.openstatus.dev)
+- [Send an email](mailto:[email protected])
diff --git a/apps/web/src/content/pages/unrelated/subprocessors.mdx b/apps/web/src/content/pages/unrelated/subprocessors.mdx
index afeb641b3..805496de2 100644
--- a/apps/web/src/content/pages/unrelated/subprocessors.mdx
+++ b/apps/web/src/content/pages/unrelated/subprocessors.mdx
@@ -2,8 +2,8 @@
title: "Subprocessors"
publishedAt: "2025-11-10"
author: "openstatus"
-description: ""
-category: "Company"
+description: "The list of subprocessors for openstatus"
+category: "company"
---
## List of Subprocessors
diff --git a/apps/web/src/content/shadcn-registry-example.tsx b/apps/web/src/content/shadcn-registry-example.tsx
new file mode 100644
index 000000000..9b1e10a99
--- /dev/null
+++ b/apps/web/src/content/shadcn-registry-example.tsx
@@ -0,0 +1,438 @@
+/**
+ * OpenStatus Registry Example
+ *
+ * This file demonstrates how to compose status page components together
+ * to create a complete status page. It serves as a reference implementation
+ * for users installing components via the shadcn CLI.
+ *
+ * Components used:
+ * - Status, StatusHeader, StatusTitle, StatusDescription, StatusContent (layout)
+ * - StatusBanner (system status indicator)
+ * - StatusBar (45-day uptime visualization)
+ * - StatusComponent block components (clean monitor composition)
+ * - StatusComponentGroup (collapsible group container)
+ * - StatusFeed (incidents and maintenance timeline)
+ */
+
+import { StatusBanner } from "@openstatus/ui/components/blocks/status-banner";
+import { StatusBar } from "@openstatus/ui/components/blocks/status-bar";
+import {
+ StatusComponent,
+ StatusComponentBody,
+ StatusComponentFooter,
+ StatusComponentHeader,
+ StatusComponentHeaderLeft,
+ StatusComponentHeaderRight,
+ StatusComponentStatus,
+ StatusComponentTitle,
+ StatusComponentUptime,
+} from "@openstatus/ui/components/blocks/status-component";
+import { StatusComponentGroup } from "@openstatus/ui/components/blocks/status-component-group";
+import { StatusFeed } from "@openstatus/ui/components/blocks/status-feed";
+import {
+ Status,
+ StatusContent,
+ StatusDescription,
+ StatusHeader,
+ StatusTitle,
+} from "@openstatus/ui/components/blocks/status-layout";
+import type {
+ Maintenance,
+ StatusBarData,
+ StatusReport,
+ StatusType,
+} from "@openstatus/ui/components/blocks/status.types";
+import { Separator } from "@openstatus/ui/components/ui/separator";
+
+/**
+ * Generates realistic mock uptime data for the last 45 days
+ * Simulates ~98% uptime with occasional degraded periods
+ */
+function generateMockUptimeData(): StatusBarData[] {
+ const data: StatusBarData[] = [];
+ const now = new Date();
+
+ for (let i = 44; i >= 0; i--) {
+ const day = new Date(now);
+ day.setDate(day.getDate() - i);
+ day.setHours(0, 0, 0, 0);
+
+ // Generate random status with high success rate
+ const rand = Math.random();
+ let bar: { status: StatusType; height: number }[];
+
+ if (rand < 0.02) {
+ // 2% chance of error day - partial outage
+ bar = [
+ { status: "success", height: 70 },
+ { status: "error", height: 30 },
+ ];
+ } else if (rand < 0.05) {
+ // 3% chance of degraded day
+ bar = [
+ { status: "success", height: 85 },
+ { status: "degraded", height: 15 },
+ ];
+ } else if (rand < 0.08) {
+ // 3% chance of minor degradation
+ bar = [
+ { status: "success", height: 95 },
+ { status: "degraded", height: 5 },
+ ];
+ } else {
+ // 92% fully operational
+ bar = [{ status: "success", height: 100 }];
+ }
+
+ // Calculate card durations based on actual bar segments (24 hours per day)
+ const totalHeight = bar.reduce((sum, segment) => sum + segment.height, 0);
+ const statusCounts: Record<string, number> = {
+ success: 0,
+ degraded: 0,
+ error: 0,
+ };
+
+ // Sum up heights by status
+ for (const segment of bar) {
+ statusCounts[segment.status] += segment.height;
+ }
+
+ // Create card entries only for statuses with non-zero values
+ const card = (["success", "degraded", "error"] as const)
+ .map((status) => {
+ const percentage = statusCounts[status] / totalHeight;
+ const totalHours = percentage * 24;
+ const hours = Math.floor(totalHours);
+ const minutes = Math.round((totalHours - hours) * 60);
+
+ // Format duration
+ let value: string;
+ if (totalHours < 1) {
+ // Less than 1 hour: show only minutes
+ value = `${Math.round(totalHours * 60)}m`;
+ } else if (minutes === 0) {
+ // Whole hours: show only hours
+ value = `${hours}h`;
+ } else {
+ // Mixed: show hours and minutes
+ value = `${hours}h ${minutes}m`;
+ }
+
+ return { status, value, hours: totalHours };
+ })
+ .filter((entry) => entry.hours > 0) // Only show non-zero durations
+ .map(({ status, value }) => ({ status, value }));
+
+ data.push({
+ day: day.toISOString(),
+ bar,
+ card,
+ events: [],
+ });
+ }
+
+ return data;
+}
+
+/**
+ * Adds incidents and maintenance events to the uptime data
+ * This connects status reports to specific days on the status bar
+ */
+function addEventsToData(
+ data: StatusBarData[],
+ statusReports: StatusReport[],
+ maintenances: Maintenance[],
+): StatusBarData[] {
+ // Add status report incidents to the data
+ for (const report of statusReports) {
+ const incidentDate = report.updates[0].date; // Use first update as incident start
+ const dayIndex = data.findIndex((d) => {
+ const dayDate = new Date(d.day);
+ const incDate = new Date(incidentDate);
+ return (
+ dayDate.getFullYear() === incDate.getFullYear() &&
+ dayDate.getMonth() === incDate.getMonth() &&
+ dayDate.getDate() === incDate.getDate()
+ );
+ });
+
+ if (dayIndex >= 0) {
+ // Calculate incident duration from updates
+ const startTime = report.updates[0].date;
+ const endTime = report.updates[report.updates.length - 1].date;
+
+ data[dayIndex].events = [
+ ...(data[dayIndex].events || []),
+ {
+ id: report.id,
+ name: report.title,
+ type: "incident",
+ from: new Date(startTime),
+ to: new Date(endTime),
+ },
+ ];
+
+ // Update bar to show degraded/error status on incident day
+ const duration =
+ (endTime.getTime() - startTime.getTime()) / (1000 * 60 * 60); // hours
+ const affectedPercentage = Math.min((duration / 24) * 100, 100);
+
+ if (affectedPercentage > 0) {
+ data[dayIndex].bar = [
+ { status: "success" as const, height: 100 - affectedPercentage },
+ { status: "degraded" as const, height: affectedPercentage },
+ ].filter((segment) => segment.height > 0);
+
+ // Recalculate card with new bar data
+ const totalHeight = data[dayIndex].bar.reduce(
+ (sum, segment) => sum + segment.height,
+ 0,
+ );
+ const statusCounts: Record<string, number> = {
+ success: 0,
+ degraded: 0,
+ error: 0,
+ };
+
+ for (const segment of data[dayIndex].bar) {
+ statusCounts[segment.status] += segment.height;
+ }
+
+ data[dayIndex].card = (["success", "degraded", "error"] as const)
+ .map((status) => {
+ const percentage = statusCounts[status] / totalHeight;
+ const totalHours = percentage * 24;
+ const hours = Math.floor(totalHours);
+ const minutes = Math.round((totalHours - hours) * 60);
+
+ let value: string;
+ if (totalHours < 1) {
+ value = `${Math.round(totalHours * 60)}m`;
+ } else if (minutes === 0) {
+ value = `${hours}h`;
+ } else {
+ value = `${hours}h ${minutes}m`;
+ }
+
+ return { status, value, hours: totalHours };
+ })
+ .filter((entry) => entry.hours > 0)
+ .map(({ status, value }) => ({ status, value }));
+ }
+ }
+ }
+
+ // Add maintenance events to the data
+ for (const maintenance of maintenances) {
+ const maintenanceDate = new Date(maintenance.from);
+ const dayIndex = data.findIndex((d) => {
+ const dayDate = new Date(d.day);
+ return (
+ dayDate.getFullYear() === maintenanceDate.getFullYear() &&
+ dayDate.getMonth() === maintenanceDate.getMonth() &&
+ dayDate.getDate() === maintenanceDate.getDate()
+ );
+ });
+
+ if (dayIndex >= 0) {
+ data[dayIndex].events = [
+ ...(data[dayIndex].events || []),
+ {
+ id: maintenance.id,
+ name: maintenance.title,
+ type: "maintenance",
+ from: new Date(maintenance.from),
+ to: new Date(maintenance.to),
+ },
+ ];
+ }
+ }
+
+ return data;
+}
+
+interface Monitor {
+ name: string;
+ status: Exclude<StatusType, "empty">;
+ uptime: string;
+ data: StatusBarData[];
+}
+
+/**
+ * StatusPageExample - Complete working example of a status page
+ *
+ * This component demonstrates:
+ * - Overall system status with StatusBanner
+ * - Multiple monitors with uptime bars
+ * - Proper component composition
+ * - Mock data structure
+ *
+ * @example
+ * ```tsx
+ * import { StatusPageExample } from "./shadcn-registry"
+ *
+ * export default function Page() {
+ * return <StatusPageExample />
+ * }
+ * ```
+ */
+export function StatusPageExample() {
+ // Mock status reports (incidents) - defined first so we can link them to data
+ const statusReports: StatusReport[] = [
+ {
+ id: 1,
+ title: "API Response Time Degradation",
+ affected: ["API", "Database"],
+ updates: [
+ {
+ date: new Date(Date.now() - 5 * 24 * 60 * 60 * 1000), // 5 days ago
+ message:
+ "We are investigating elevated response times on our API endpoints.",
+ status: "investigating",
+ },
+ {
+ date: new Date(Date.now() - 5 * 24 * 60 * 60 * 1000 + 60 * 60 * 1000), // 1 hour later
+ message:
+ "We have identified a database query optimization issue causing the slowdown.",
+ status: "identified",
+ },
+ {
+ date: new Date(
+ Date.now() - 5 * 24 * 60 * 60 * 1000 + 2 * 60 * 60 * 1000,
+ ), // 2 hours later
+ message:
+ "Database queries have been optimized. Monitoring performance improvements.",
+ status: "monitoring",
+ },
+ {
+ date: new Date(
+ Date.now() - 5 * 24 * 60 * 60 * 1000 + 3 * 60 * 60 * 1000,
+ ), // 3 hours later
+ message:
+ "Response times have returned to normal. This incident has been resolved.",
+ status: "resolved",
+ },
+ ],
+ },
+ ];
+
+ // Mock maintenance windows
+ const maintenances: Maintenance[] = [
+ {
+ id: 3,
+ title: "Scheduled Database Maintenance",
+ affected: ["API", "Database"],
+ message:
+ "We will be performing routine database maintenance to improve performance and apply security updates. Expect brief periods of increased latency during this window.",
+ from: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000), // 3 days from now
+ to: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000 + 2 * 60 * 60 * 1000), // 2 hours duration
+ },
+ ];
+
+ // Generate mock data for each monitor and add events
+ let apiData = generateMockUptimeData();
+ apiData = addEventsToData(apiData, statusReports, maintenances);
+
+ const websiteData = generateMockUptimeData();
+ const databaseData = generateMockUptimeData();
+
+ const monitors: Monitor[] = [
+ {
+ name: "API",
+ status: "success",
+ uptime: "99.8%",
+ data: apiData,
+ },
+ {
+ name: "Website",
+ status: "success",
+ uptime: "99.9%",
+ data: websiteData,
+ },
+ {
+ name: "Database",
+ status: "success",
+ uptime: "100%",
+ data: databaseData,
+ },
+ ];
+
+ // Determine overall system status based on monitors
+ const hasError = monitors.some((m) => m.status === "error");
+ const hasDegraded = monitors.some((m) => m.status === "degraded");
+ const systemStatus: Exclude<StatusType, "empty"> = hasError
+ ? "error"
+ : hasDegraded
+ ? "degraded"
+ : "success";
+
+ return (
+ <Status variant={systemStatus} className="mx-auto max-w-2xl">
+ <StatusHeader>
+ <StatusTitle>System Status</StatusTitle>
+ <StatusDescription>
+ Current status of all services and infrastructure
+ </StatusDescription>
+ </StatusHeader>
+ <StatusBanner status={systemStatus} />
+ <StatusContent>
+ <StatusComponent variant={monitors[0].status}>
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentTitle>{monitors[0].name}</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ <StatusComponentHeaderRight>
+ <StatusComponentUptime>
+ {monitors[0].uptime}
+ </StatusComponentUptime>
+ <StatusComponentStatus />
+ </StatusComponentHeaderRight>
+ </StatusComponentHeader>
+ <StatusComponentBody>
+ <StatusBar data={monitors[0].data} />
+ <StatusComponentFooter data={monitors[0].data} />
+ </StatusComponentBody>
+ </StatusComponent>
+ <StatusComponentGroup
+ title="Infrastructure"
+ status={
+ monitors.slice(1).some((m) => m.status === "error")
+ ? "error"
+ : monitors.slice(1).some((m) => m.status === "degraded")
+ ? "degraded"
+ : "success"
+ }
+ defaultOpen={true}
+ >
+ {monitors.slice(1).map((monitor) => (
+ <StatusComponent key={monitor.name} variant={monitor.status}>
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentTitle>{monitor.name}</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ <StatusComponentHeaderRight>
+ <StatusComponentUptime>
+ {monitor.uptime}
+ </StatusComponentUptime>
+ <StatusComponentStatus />
+ </StatusComponentHeaderRight>
+ </StatusComponentHeader>
+ <StatusComponentBody>
+ <StatusBar data={monitor.data} />
+ <StatusComponentFooter data={monitor.data} />
+ </StatusComponentBody>
+ </StatusComponent>
+ ))}
+ </StatusComponentGroup>
+ <Separator className="my-6" />
+ <div className="space-y-4">
+ <h2 className="font-semibold text-lg">Recent Events</h2>
+ <StatusFeed
+ statusReports={statusReports}
+ maintenances={maintenances}
+ />
+ </div>
+ </StatusContent>
+ </Status>
+ );
+}
diff --git a/packages/ui/package.json b/packages/ui/package.json
index ff35f56c2..bb21ce526 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -7,6 +7,14 @@
"types": "./src/components/ui/*.tsx",
"default": "./src/components/ui/*.tsx"
},
+ "./components/blocks/status.types": {
+ "types": "./src/components/blocks/status.types.ts",
+ "default": "./src/components/blocks/status.types.ts"
+ },
+ "./components/blocks/status.utils": {
+ "types": "./src/components/blocks/status.utils.ts",
+ "default": "./src/components/blocks/status.utils.ts"
+ },
"./components/blocks/*": {
"types": "./src/components/blocks/*.tsx",
"default": "./src/components/blocks/*.tsx"
diff --git a/packages/ui/registry.json b/packages/ui/registry.json
index 758597416..54ee19f3f 100644
--- a/packages/ui/registry.json
+++ b/packages/ui/registry.json
@@ -45,20 +45,6 @@
}
},
"items": [
- {
- "name": "example",
- "type": "registry:block",
- "title": "Example",
- "description": "Example block",
- "registryDependencies": ["card", "button"],
- "files": [
- {
- "path": "src/components/blocks/example.tsx",
- "type": "registry:ui",
- "target": "components/blocks/example.tsx"
- }
- ]
- },
{
"name": "use-media-query",
"type": "registry:hook",
diff --git a/packages/ui/src/components/blocks/README.md b/packages/ui/src/components/blocks/README.md
index ba7d982d8..3fa417a19 100644
--- a/packages/ui/src/components/blocks/README.md
+++ b/packages/ui/src/components/blocks/README.md
@@ -1 +1,454 @@
-> elements composed out ui primitives
\ No newline at end of file
+# Status Blocks Components
+
+A sophisticated composition-based architecture for displaying system status information. This collection provides flexible, accessible, and beautifully designed components for building status pages, incident reports, and uptime dashboards.
+
+## Overview
+
+The blocks components are built on a **composition pattern** where simple primitives can be combined to create complex status displays. Rather than monolithic components with dozens of props, you compose smaller focused components together to achieve your desired layout and behavior.
+
+### Key Features
+
+- **Composition-First**: Build complex UIs from simple, focused primitives
+- **Type-Safe**: Full TypeScript support with discriminated unions
+- **Accessible**: ARIA roles, keyboard navigation, screen reader support
+- **Themeable**: CSS variables for colors, dark mode support
+- **Responsive**: Mobile-first design with adaptive layouts
+- **Interactive**: Keyboard navigation, hover cards, collapsible groups
+
+## Architecture
+
+### Design Principles
+
+1. **Separation of Concerns**: Each component has a single, clear purpose
+2. **Data Attributes**: Components use `data-*` attributes for status-based styling
+3. **CSS Group Patterns**: Parent components establish context via `group` classes
+4. **Headless Hooks**: Complex interactions separated from presentation (e.g., `useStatusBar`)
+5. **Composition over Configuration**: Combine components rather than configure via props
+
+### Component Layers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Layout Components (Status, StatusComponent, StatusEvent)│
+│ └─ Establish context via data-variant/data-status │
+├─────────────────────────────────────────────────────────┤
+│ Display Components (StatusIcon, StatusMessage, etc.) │
+│ └─ Respond to parent context via CSS selectors │
+├─────────────────────────────────────────────────────────┤
+│ Interactive Components (StatusBar, StatusComponentGroup)│
+│ └─ Manage state and interactions via hooks │
+├─────────────────────────────────────────────────────────┤
+│ Utility Components (StatusTimestamp, StatusBlank, etc.) │
+│ └─ Provide specialized functionality │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Core Concepts
+
+### Status Types
+
+All components work with a unified `StatusType`:
+
+- **success**: All systems operational (green)
+- **degraded**: Partial performance issues (yellow)
+- **error**: Outage or major issue (red)
+- **info**: Maintenance or informational (blue)
+- **empty**: No data available (muted gray)
+
+### Data Attributes
+
+Components use `data-variant` or `data-status` attributes to establish status context:
+
+```tsx
+<StatusComponent variant="degraded">
+ {/* Child components automatically style for degraded status */}
+</StatusComponent>
+```
+
+Child components use CSS selectors to respond:
+
+```css
+.group-data-[variant=degraded]/component:text-warning
+```
+
+### Composition Pattern
+
+Rather than:
+```tsx
+<Monitor
+ name="API"
+ status="success"
+ uptime="99.9%"
+ showIcon={true}
+ showStatus={true}
+/>
+```
+
+We compose:
+```tsx
+<StatusComponent variant="success">
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentIcon />
+ <StatusComponentTitle>API</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ <StatusComponentHeaderRight>
+ <StatusComponentUptime>99.9%</StatusComponentUptime>
+ <StatusComponentStatus />
+ </StatusComponentHeaderRight>
+ </StatusComponentHeader>
+</StatusComponent>
+```
+
+## Component Categories
+
+### 1. Layout Components
+
+Primary containers that establish page structure and status context.
+
+#### Status Components
+- **Status**: Root container for status pages
+- **StatusHeader**: Header with brand and title
+- **StatusTitle**: Page title
+- **StatusDescription**: Subtitle text
+- **StatusContent**: Main content area
+- **StatusBrand**: Logo/brand image
+- **StatusIcon**: Status indicator icon
+
+#### Monitor Components
+- **StatusComponent**: Individual monitor/service container
+- **StatusComponentHeader**: Monitor header layout
+- **StatusComponentHeaderLeft**: Left-aligned header content
+- **StatusComponentHeaderRight**: Right-aligned header content
+- **StatusComponentBody**: Monitor content area
+
+### 2. Status Display Components
+
+Components for showing monitor status, uptime, and metrics.
+
+- **StatusComponentIcon**: Status indicator for monitors
+- **StatusComponentTitle**: Monitor/service name
+- **StatusComponentDescription**: Info tooltip for monitors
+- **StatusComponentUptime**: Uptime percentage display
+- **StatusComponentStatus**: Automatic status label
+- **StatusComponentFooter**: Date range footer
+
+### 3. Status Banner Components
+
+Prominent banner for displaying system-wide status.
+
+- **StatusBanner**: Complete banner with icon/message/timestamp
+- **StatusBannerContainer**: Base container for custom banners
+- **StatusBannerMessage**: Automatic status message
+- **StatusBannerTitle**: Colored title bar
+- **StatusBannerContent**: Main content area
+- **StatusBannerIcon**: Banner status icon
+- **StatusBannerTabs**: Tab container for multi-section banners
+- **StatusBannerTabsList**: Tab navigation
+- **StatusBannerTabsTrigger**: Individual tab button
+- **StatusBannerTabsContent**: Tab panel content
+
+### 4. Status Bar Components
+
+Interactive uptime timeline with hover cards.
+
+- **StatusBar**: Main timeline component
+- **useStatusBar**: Headless hook for custom implementations
+- **StatusBarEvent**: Event badge in hover cards
+- **StatusBarSkeleton**: Loading skeleton
+
+### 5. Event Components
+
+Components for displaying incident reports and maintenance.
+
+#### Container Components
+- **StatusEventGroup**: Feed container
+- **StatusEvent**: Individual event container
+- **StatusEventContent**: Event content wrapper
+
+#### Content Components
+- **StatusEventTitle**: Event title
+- **StatusEventTitleCheck**: Resolved indicator
+- **StatusEventAffected**: Affected services container
+- **StatusEventAffectedBadge**: Single service badge
+
+#### Date/Time Components
+- **StatusEventDate**: Date with relative time
+- **StatusEventAside**: Sidebar date (desktop)
+
+#### Timeline Components
+- **StatusEventTimelineReport**: Incident updates timeline
+- **StatusEventTimelineReportUpdate**: Single update entry
+- **StatusEventTimelineMaintenance**: Maintenance entry
+- **StatusEventTimelineTitle**: Timeline entry title
+- **StatusEventTimelineMessage**: Timeline entry message
+- **StatusEventTimelineDot**: Colored status dot
+- **StatusEventTimelineSeparator**: Connecting line
+
+### 6. Empty State Components
+
+Visualizations for empty states.
+
+- **StatusBlankEvents**: Empty state for incidents
+- **StatusBlankMonitors**: Empty state for monitors
+- **StatusBlankContainer**: Generic empty state container
+- **StatusBlankTitle**: Empty state title
+- **StatusBlankDescription**: Empty state description
+
+### 7. Utility Components
+
+Specialized functionality components.
+
+- **StatusTimestamp**: Timezone-aware timestamp with hover details
+- **StatusFeed**: Unified feed of reports and maintenance
+- **StatusComponentGroup**: Collapsible monitor grouping
+
+## Composition Patterns
+
+### Pattern 1: Basic Monitor Display
+
+```tsx
+<StatusComponent variant="success">
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentIcon />
+ <StatusComponentTitle>Production API</StatusComponentTitle>
+ <StatusComponentDescription>
+ Handles all production traffic
+ </StatusComponentDescription>
+ </StatusComponentHeaderLeft>
+ <StatusComponentHeaderRight>
+ <StatusComponentUptime>99.95%</StatusComponentUptime>
+ <StatusComponentStatus />
+ </StatusComponentHeaderRight>
+ </StatusComponentHeader>
+ <StatusComponentBody>
+ <StatusBar data={uptimeData} />
+ <StatusComponentFooter data={uptimeData} />
+ </StatusComponentBody>
+</StatusComponent>
+```
+
+### Pattern 2: Status Banner with Tabs
+
+```tsx
+<StatusBannerTabs status="degraded" defaultValue="impact">
+ <StatusBannerTabsList>
+ <StatusBannerTabsTrigger value="impact" status="degraded">
+ Impact
+ </StatusBannerTabsTrigger>
+ <StatusBannerTabsTrigger value="updates" status="degraded">
+ Updates
+ </StatusBannerTabsTrigger>
+ </StatusBannerTabsList>
+
+ <StatusBannerTabsContent value="impact">
+ <StatusBannerTitle>Degraded Performance</StatusBannerTitle>
+ <StatusBannerContent>
+ <p>We are experiencing elevated latency across all regions.</p>
+ <StatusEventAffected>
+ <StatusEventAffectedBadge>API</StatusEventAffectedBadge>
+ <StatusEventAffectedBadge>Database</StatusEventAffectedBadge>
+ </StatusEventAffected>
+ </StatusBannerContent>
+ </StatusBannerTabsContent>
+
+ <StatusBannerTabsContent value="updates">
+ <StatusBannerContent>
+ <StatusEventTimelineReport updates={incidentUpdates} />
+ </StatusBannerContent>
+ </StatusBannerTabsContent>
+</StatusBannerTabs>
+```
+
+### Pattern 3: Incident Timeline
+
+```tsx
+<StatusEvent>
+ <StatusEventAside>
+ <StatusEventDate date={incidentDate} />
+ </StatusEventAside>
+
+ <StatusEventContent>
+ <div className="flex items-center gap-2">
+ <StatusEventTitle>API Gateway Outage</StatusEventTitle>
+ <StatusEventTitleCheck />
+ </div>
+
+ <StatusEventAffected>
+ <StatusEventAffectedBadge>API Gateway</StatusEventAffectedBadge>
+ <StatusEventAffectedBadge>Authentication</StatusEventAffectedBadge>
+ </StatusEventAffected>
+
+ <StatusEventTimelineReport
+ updates={[
+ {
+ status: "resolved",
+ message: "All services have been restored",
+ date: new Date("2024-01-15T12:00:00Z")
+ },
+ {
+ status: "monitoring",
+ message: "Fix deployed, monitoring recovery",
+ date: new Date("2024-01-15T11:45:00Z")
+ },
+ {
+ status: "identified",
+ message: "Root cause identified in load balancer",
+ date: new Date("2024-01-15T11:15:00Z")
+ },
+ {
+ status: "investigating",
+ message: "Investigating API timeouts",
+ date: new Date("2024-01-15T11:00:00Z")
+ }
+ ]}
+ />
+ </StatusEventContent>
+</StatusEvent>
+```
+
+### Pattern 4: Unified Feed
+
+```tsx
+<StatusFeed
+ statusReports={[
+ {
+ id: 1,
+ title: "API Outage",
+ affected: ["API", "Database"],
+ updates: [
+ {
+ status: "resolved",
+ message: "Issue resolved",
+ date: new Date()
+ }
+ ]
+ }
+ ]}
+ maintenances={[
+ {
+ id: 2,
+ title: "Database Upgrade",
+ message: "Upgrading to PostgreSQL 15",
+ affected: ["Database"],
+ from: new Date("2024-01-20T02:00:00Z"),
+ to: new Date("2024-01-20T04:00:00Z")
+ }
+ ]}
+/>
+```
+
+### Pattern 5: Grouped Monitors
+
+```tsx
+<StatusContent>
+ <StatusComponentGroup
+ title="Core Services"
+ status="success"
+ defaultOpen={true}
+ >
+ <StatusComponent variant="success">
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentIcon />
+ <StatusComponentTitle>API Server</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ </StatusComponentHeader>
+ </StatusComponent>
+
+ <StatusComponent variant="success">
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentIcon />
+ <StatusComponentTitle>Database</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ </StatusComponentHeader>
+ </StatusComponent>
+ </StatusComponentGroup>
+
+ <StatusComponentGroup
+ title="Third-Party Services"
+ status="degraded"
+ defaultOpen={false}
+ >
+ <StatusComponent variant="degraded">
+ <StatusComponentHeader>
+ <StatusComponentHeaderLeft>
+ <StatusComponentIcon />
+ <StatusComponentTitle>Payment Gateway</StatusComponentTitle>
+ </StatusComponentHeaderLeft>
+ </StatusComponentHeader>
+ </StatusComponent>
+ </StatusComponentGroup>
+</StatusContent>
+```
+
+## Theming & Styling
+
+### CSS Variables
+
+Components use CSS variables for status colors:
+
+```css
+--success: /* Green */
+--warning: /* Yellow */
+--destructive: /* Red */
+--info: /* Blue */
+--muted: /* Gray */
+```
+
+### Dark Mode
+
+All components support dark mode via CSS variables. Dark mode colors are automatically applied based on the `dark` class on a parent element.
+
+### Customization
+
+Override component styles using className:
+
+```tsx
+<StatusComponent variant="success" className="custom-styles">
+ {/* Component content */}
+</StatusComponent>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- **StatusBar**: Full arrow key navigation (←/→ between bars, ↑/↓ between monitors)
+- **StatusComponentGroup**: Space/Enter to toggle, standard collapsible keyboard support
+- **StatusBannerTabs**: Tab key navigation, arrow keys to switch tabs
+
+### ARIA Support
+
+- `role="toolbar"` on StatusBar for keyboard navigation context
+- `role="feed"` on StatusEventGroup for event feed semantics
+- `aria-label`, `aria-pressed`, `aria-expanded` where appropriate
+- Tooltip triggers have `aria-label` for screen readers
+
+### Screen Readers
+
+- StatusTimestamp includes timezone information in accessible format
+- StatusIcon variations are distinguished by accessible labels
+- Empty states include descriptive text for context
+
+## API Reference
+
+For detailed API documentation, see the JSDoc comments in each component file:
+
+- [status-layout.tsx](./status-layout.tsx) - Page layout components
+- [status-component.tsx](./status-component.tsx) - Monitor display components
+- [status-banner.tsx](./status-banner.tsx) - Status banner components
+- [status-bar.tsx](./status-bar.tsx) - Uptime timeline components
+- [status-events.tsx](./status-events.tsx) - Event and incident components
+- [status-feed.tsx](./status-feed.tsx) - Unified feed component
+- [status-timestamp.tsx](./status-timestamp.tsx) - Timestamp component
+- [status-blank.tsx](./status-blank.tsx) - Empty state components
+- [status-component-group.tsx](./status-component-group.tsx) - Grouping component
+- [status-icon.tsx](./status-icon.tsx) - Icon component
+- [status.utils.ts](./status.utils.ts) - Utility functions
+
+---
+
+**Note**: These components follow the headless UI pattern where applicable, separating state management from presentation. This allows for maximum flexibility while maintaining type safety and accessibility.
diff --git a/packages/ui/src/components/blocks/example.tsx b/packages/ui/src/components/blocks/example.tsx
deleted file mode 100644
index 09ce49eda..000000000
--- a/packages/ui/src/components/blocks/example.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import { Button } from "@openstatus/ui/components/ui/button";
-import {
- Card,
- CardContent,
- CardHeader,
- CardTitle,
-} from "@openstatus/ui/components/ui/card";
-
-export function ExampleBlock() {
- return (
- <Card>
- <CardHeader>
- <CardTitle>Example</CardTitle>
- </CardHeader>
- <CardContent>
- <Button>Click me</Button>
- </CardContent>
- </Card>
- );
-}
diff --git a/packages/ui/src/components/blocks/status-banner.tsx b/packages/ui/src/components/blocks/status-banner.tsx
index 3bc4937be..4b57268c7 100644
--- a/packages/ui/src/components/blocks/status-banner.tsx
+++ b/packages/ui/src/components/blocks/status-banner.tsx
@@ -10,6 +10,38 @@ import { StatusIcon as UnifiedStatusIcon } from "@openstatus/ui/components/block
import type { StatusType } from "@openstatus/ui/components/blocks/status.types";
import { StatusTimestamp } from "@openstatus/ui/components/blocks/status-timestamp";
+/**
+ * StatusBanner - Complete banner component with integrated icon, message, and timestamp
+ *
+ * A fully composed banner component that displays a prominent status message with:
+ * - Status-colored icon on the left
+ * - Automatic status message (e.g., "All Systems Operational")
+ * - Current timestamp on the right
+ *
+ * The banner automatically styles itself based on the status type with colored
+ * backgrounds and borders. This is the simplest way to display a status banner
+ * when you don't need custom content.
+ *
+ * For custom banner content, use StatusBannerContainer with manual composition.
+ *
+ * @param status - The status type that determines appearance and message
+ *
+ * @example
+ * ```tsx
+ * <StatusBanner status="success" />
+ * // Displays: [✓ icon] All Systems Operational | Jan 15, 2024 10:30 (UTC)
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StatusBanner status="degraded" />
+ * // Displays: [⚠ icon] Degraded Performance | Jan 15, 2024 10:30 (UTC)
+ * ```
+ *
+ * @see StatusBannerContainer - For custom banner composition
+ * @see StatusBannerMessage - For the automatic status message
+ * @see StatusTimestamp - For the timestamp display
+ */
export function StatusBanner({
className,
status,
@@ -37,6 +69,35 @@ export function StatusBanner({
);
}
+/**
+ * StatusBannerContainer - Base container for status banner composition
+ *
+ * Provides a rounded, bordered container with status-based styling via data
+ * attributes. The container acts as a CSS group (/status-banner) enabling child
+ * components to style themselves based on the status type.
+ *
+ * Background colors automatically adjust for light/dark mode:
+ * - success: Green tint (bg-success/5 light, bg-success/10 dark)
+ * - degraded: Yellow tint (bg-warning/5 light, bg-warning/10 dark)
+ * - error: Red tint (bg-destructive/5 light, bg-destructive/10 dark)
+ * - info: Blue tint (bg-info/5 light, bg-info/10 dark)
+ *
+ * @param status - The status type for styling
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerContainer status="error">
+ * <StatusBannerTitle>Active Incident</StatusBannerTitle>
+ * <StatusBannerContent>
+ * <p>We are experiencing issues with the API.</p>
+ * </StatusBannerContent>
+ * </StatusBannerContainer>
+ * ```
+ *
+ * @see StatusBanner - For a pre-composed banner with icon/message/timestamp
+ * @see StatusBannerTitle - For colored title bar
+ * @see StatusBannerContent - For main content area
+ */
export function StatusBannerContainer({
className,
children,
@@ -62,6 +123,30 @@ export function StatusBannerContainer({
);
}
+/**
+ * StatusBannerMessage - Automatic status message display
+ *
+ * Displays a status message that automatically shows the appropriate text based
+ * on the parent StatusBannerContainer's status. Uses CSS data attribute selectors
+ * to show only the relevant message:
+ * - success: "All Systems Operational"
+ * - degraded: "Degraded Performance"
+ * - error: "Partial Outage"
+ * - info: "Maintenance"
+ *
+ * The messages are sourced from systemStatusLabels.long for consistent messaging.
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerContainer status="success">
+ * <StatusBannerMessage className="text-xl font-semibold" />
+ * // Displays "All Systems Operational"
+ * </StatusBannerContainer>
+ * ```
+ *
+ * @see StatusBannerContainer - For setting the status context
+ * @see systemStatusLabels - For the message text definitions
+ */
export function StatusBannerMessage({
className,
...props
@@ -84,6 +169,33 @@ export function StatusBannerMessage({
);
}
+/**
+ * StatusBannerTitle - Colored title bar for banner sections
+ *
+ * Displays a title with a solid status-colored background and light text color.
+ * The background color automatically adjusts based on the parent StatusBannerContainer's
+ * status type:
+ * - success: Green background
+ * - degraded: Yellow background
+ * - error: Red background
+ * - info: Blue background
+ *
+ * Typically used to create distinct sections within a banner or to highlight
+ * important information.
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerContainer status="error">
+ * <StatusBannerTitle>Ongoing Incident</StatusBannerTitle>
+ * <StatusBannerContent>
+ * <p>Details about the incident...</p>
+ * </StatusBannerContent>
+ * </StatusBannerContainer>
+ * ```
+ *
+ * @see StatusBannerContainer - For setting the status context
+ * @see StatusBannerContent - For main content below the title
+ */
export function StatusBannerTitle({
className,
children,
@@ -106,6 +218,28 @@ export function StatusBannerTitle({
);
}
+/**
+ * StatusBannerContent - Main content area for banner messages
+ *
+ * Provides consistent padding and spacing (gap-2) for banner content. Used to
+ * display detailed messages, updates, or other information within a status banner.
+ *
+ * The padding is responsive: px-3 py-2 on mobile, px-4 py-3 on larger screens.
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerContainer status="info">
+ * <StatusBannerTitle>Scheduled Maintenance</StatusBannerTitle>
+ * <StatusBannerContent>
+ * <p>We will be performing maintenance on Jan 20 from 2-4 AM UTC.</p>
+ * <p>Some services may be temporarily unavailable.</p>
+ * </StatusBannerContent>
+ * </StatusBannerContainer>
+ * ```
+ *
+ * @see StatusBannerContainer - For the container
+ * @see StatusBannerTitle - For optional title bar above content
+ */
export function StatusBannerContent({
className,
children,
@@ -121,6 +255,30 @@ export function StatusBannerContent({
);
}
+/**
+ * StatusBannerIcon - Status indicator icon for banner context
+ *
+ * This component wraps the unified StatusIcon with variant="banner", configuring
+ * it to respond to the parent StatusBannerContainer's data-status attribute.
+ * The displayed icon automatically changes based on the status type:
+ * - success: CheckIcon
+ * - degraded: TriangleAlertIcon
+ * - error: AlertCircleIcon
+ * - info: WrenchIcon
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerContainer status="degraded">
+ * <div className="flex items-center gap-3">
+ * <StatusBannerIcon />
+ * <StatusBannerMessage />
+ * </div>
+ * </StatusBannerContainer>
+ * ```
+ *
+ * @see StatusBannerContainer - For setting the status context
+ * @see StatusIcon from status-icon.tsx - For the underlying unified icon implementation
+ */
export function StatusBannerIcon({
className,
...props
@@ -130,8 +288,49 @@ export function StatusBannerIcon({
);
}
-// Tabs Components
+// ============================================================================
+// Tab Components
+// ============================================================================
+/**
+ * StatusBannerTabs - Tab container for multi-section status banners
+ *
+ * Provides a tabbed interface for status banners, allowing multiple views or
+ * sections within a single banner. The tabs container automatically applies
+ * status-based background colors matching the banner theme.
+ *
+ * Built on Radix UI Tabs with status-aware styling.
+ *
+ * @param status - The status type for background color theming
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerTabs status="degraded" defaultValue="impact">
+ * <StatusBannerTabsList>
+ * <StatusBannerTabsTrigger value="impact" status="degraded">
+ * Impact
+ * </StatusBannerTabsTrigger>
+ * <StatusBannerTabsTrigger value="updates" status="degraded">
+ * Updates
+ * </StatusBannerTabsTrigger>
+ * </StatusBannerTabsList>
+ * <StatusBannerTabsContent value="impact">
+ * <StatusBannerContent>
+ * <p>Services affected by this incident...</p>
+ * </StatusBannerContent>
+ * </StatusBannerTabsContent>
+ * <StatusBannerTabsContent value="updates">
+ * <StatusBannerContent>
+ * <p>Latest updates on resolution...</p>
+ * </StatusBannerContent>
+ * </StatusBannerTabsContent>
+ * </StatusBannerTabs>
+ * ```
+ *
+ * @see StatusBannerTabsList - For the tab navigation
+ * @see StatusBannerTabsTrigger - For individual tab buttons
+ * @see StatusBannerTabsContent - For tab panel content
+ */
export function StatusBannerTabs({
className,
children,
@@ -159,6 +358,27 @@ export function StatusBannerTabs({
);
}
+/**
+ * StatusBannerTabsList - Tab navigation container
+ *
+ * Wraps the tab triggers in a scrollable container with rounded top corners.
+ * The container automatically handles overflow with horizontal scrolling on
+ * smaller screens.
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerTabsList>
+ * <StatusBannerTabsTrigger value="overview" status="success">
+ * Overview
+ * </StatusBannerTabsTrigger>
+ * <StatusBannerTabsTrigger value="details" status="success">
+ * Details
+ * </StatusBannerTabsTrigger>
+ * </StatusBannerTabsList>
+ * ```
+ *
+ * @see StatusBannerTabsTrigger - For individual tab buttons
+ */
export function StatusBannerTabsList({
className,
children,
@@ -180,6 +400,35 @@ export function StatusBannerTabsList({
);
}
+/**
+ * StatusBannerTabsTrigger - Individual tab button
+ *
+ * Displays a single tab trigger button with status-based coloring. The button
+ * shows:
+ * - Inactive state: 50% opacity status color background
+ * - Active state: Full status color background with light text
+ *
+ * The status parameter should match the parent StatusBannerTabs status for
+ * consistent theming.
+ *
+ * @param status - The status type for color theming
+ * @param value - The tab value (for Radix UI Tabs)
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerTabsList>
+ * <StatusBannerTabsTrigger value="affected" status="error">
+ * Affected Services
+ * </StatusBannerTabsTrigger>
+ * <StatusBannerTabsTrigger value="timeline" status="error">
+ * Timeline
+ * </StatusBannerTabsTrigger>
+ * </StatusBannerTabsList>
+ * ```
+ *
+ * @see StatusBannerTabsList - For the container
+ * @see StatusBannerTabsContent - For the corresponding content panels
+ */
export function StatusBannerTabsTrigger({
className,
children,
@@ -210,6 +459,28 @@ export function StatusBannerTabsTrigger({
);
}
+/**
+ * StatusBannerTabsContent - Tab panel content container
+ *
+ * Wraps the content for a single tab panel. The component includes negative
+ * horizontal margin (-mx-3) to align edge-to-edge with the banner container
+ * when used with StatusBannerContent.
+ *
+ * @param value - The tab value (must match a StatusBannerTabsTrigger value)
+ *
+ * @example
+ * ```tsx
+ * <StatusBannerTabsContent value="updates">
+ * <StatusBannerContent>
+ * <h3>Latest Update</h3>
+ * <p>We have identified the issue and are working on a fix...</p>
+ * </StatusBannerContent>
+ * </StatusBannerTabsContent>
+ * ```
+ *
+ * @see StatusBannerTabsTrigger - For the tab button that activates this content
+ * @see StatusBannerContent - Typically used as a child for proper padding
+ */
export function StatusBannerTabsContent({
className,
children,
diff --git a/packages/ui/src/components/blocks/status-bar.tsx b/packages/ui/src/components/blocks/status-bar.tsx
index 189306f4d..3f53eef03 100644
--- a/packages/ui/src/components/blocks/status-bar.tsx
+++ b/packages/ui/src/components/blocks/status-bar.tsx
@@ -46,8 +46,68 @@ interface UseStatusBarProps {
type InteractionType = "pin" | "hover" | "focus" | null;
/**
- * Custom hook to manage StatusBar state and interactions
- * Provides headless logic for keyboard navigation, mouse/touch interactions, and focus management
+ * useStatusBar - Headless hook for managing status bar interactions and keyboard navigation
+ *
+ * This hook provides the core logic for StatusBar interactions, implementing a
+ * headless UI pattern that separates state management from presentation. It handles:
+ *
+ * **Interaction Modes**:
+ * - **hover**: Desktop hover state (shows card on mouse hover, auto-hides on leave)
+ * - **pin**: Pinned state (click to pin card open, click again or Esc to close)
+ * - **focus**: Keyboard focus state (shows card while focused, hides on blur)
+ *
+ * **Keyboard Navigation**:
+ * - **Arrow Left/Right**: Navigate between bars in the same timeline
+ * - **Arrow Up/Down**: Navigate between timelines (different monitors)
+ * - **Enter/Space**: Pin/unpin the active bar
+ * - **Escape**: Close pinned card and remove focus
+ *
+ * **Touch Device Support**:
+ * - Disables hover state on touch devices (detected via `(hover: none)` media query)
+ * - Click interaction works on both touch and non-touch devices
+ *
+ * **Outside Click Handling**:
+ * - Automatically closes pinned cards when clicking outside the component
+ *
+ * @param dataLength - Total number of bars in the timeline
+ * @param isTouch - Whether the device supports touch (no hover capability)
+ *
+ * @returns Hook state and handlers:
+ * - `activeIndex`: Currently active bar index (null if none)
+ * - `isOpen`: Whether a card is currently displayed
+ * - `interactionType`: Current interaction mode ("pin" | "hover" | "focus" | null)
+ * - `containerRef`: Ref for the status bar container (for outside click detection)
+ * - `handlers`: Event handler functions for mouse/keyboard/focus interactions
+ * - `setButtonRef`: Function to register bar element refs (for keyboard navigation)
+ *
+ * @example
+ * ```tsx
+ * function CustomStatusBar({ data }) {
+ * const isTouch = useMediaQuery("(hover: none)");
+ * const { activeIndex, handlers, setButtonRef, containerRef } = useStatusBar({
+ * dataLength: data.length,
+ * isTouch,
+ * });
+ *
+ * return (
+ * <div ref={containerRef} role="toolbar">
+ * {data.map((item, index) => (
+ * <button
+ * key={index}
+ * ref={(el) => setButtonRef(index, el)}
+ * onClick={() => handlers.onClick(index)}
+ * onFocus={() => handlers.onFocus(index)}
+ * onKeyDown={(e) => handlers.onKeyDown(e, index)}
+ * >
+ * {// Custom bar rendering}
+ * </button>
+ * ))}
+ * </div>
+ * );
+ * }
+ * ```
+ *
+ * @see StatusBar - For the complete implementation using this hook
*/
function useStatusBar({ dataLength, isTouch }: UseStatusBarProps) {
const [activeIndex, setActiveIndex] = useState<number | null>(null);
@@ -248,26 +308,114 @@ function useStatusBar({ dataLength, isTouch }: UseStatusBarProps) {
}
/**
- * StatusBar - An interactive status timeline component
+ * StatusBar - Interactive uptime timeline with keyboard navigation and hover cards
+ *
+ * Displays a horizontal timeline of status bars, where each bar represents a day's
+ * status with color-coded segments. Interactive hover cards show detailed status
+ * information, events, and incidents for each day.
+ *
+ * **Key Features**:
+ * - **Visual Timeline**: Vertical bars with color-coded segments showing status over time
+ * - **Interactive Cards**: Hover/click to see detailed breakdowns and events
+ * - **Keyboard Navigation**: Full keyboard support with arrow keys, Enter, and Escape
+ * - **Touch Support**: Optimized interactions for touch devices
+ * - **Customizable Rendering**: Override default renderers for bars, cards, and events
+ * - **Accessibility**: ARIA roles, labels, and keyboard navigation
+ *
+ * **Interaction Modes**:
+ * - Desktop: Hover to preview, click to pin, Esc to close
+ * - Touch: Tap to toggle card open/closed
+ * - Keyboard: Arrow keys to navigate, Enter/Space to pin, Esc to close
*
- * Displays a timeline of status data with interactive hover cards showing detailed information.
- * Supports keyboard navigation, mouse hover, and touch interactions.
+ * **Keyboard Navigation**:
+ * - **Left/Right Arrows**: Move between bars in the timeline
+ * - **Up/Down Arrows**: Navigate between different monitor timelines
+ * - **Enter/Space**: Pin or unpin the active card
+ * - **Escape**: Close card and remove focus
+ *
+ * **Data Structure**:
+ * Each data item represents a day and contains:
+ * - `day`: Date string
+ * - `bar`: Array of segments with status and height percentage
+ * - `card`: Array of status breakdowns to display in hover card
+ * - `events`: Array of incidents/maintenance events for that day
+ *
+ * @param data - Array of status bar data items (one per day)
+ * @param renderCard - Optional custom renderer for card content items
+ * @param renderBar - Optional custom renderer for bar segments
+ * @param renderEvent - Optional custom renderer for event badges
+ *
+ * @example
+ * // Basic usage with default rendering
+ * ```tsx
+ * const uptimeData = [
+ * {
+ * day: "2024-01-15",
+ * bar: [{ status: "success", height: 100 }],
+ * card: [{ status: "success", value: "100%" }],
+ * events: []
+ * },
+ * {
+ * day: "2024-01-16",
+ * bar: [
+ * { status: "success", height: 80 },
+ * { status: "error", height: 20 }
+ * ],
+ * card: [
+ * { status: "success", value: "80%" },
+ * { status: "error", value: "20%" }
+ * ],
+ * events: [
+ * {
+ * id: "inc-1",
+ * type: "incident",
+ * name: "API Downtime",
+ * from: new Date("2024-01-16T10:00:00Z"),
+ * to: new Date("2024-01-16T10:30:00Z")
+ * }
+ * ]
+ * }
+ * ];
+ *
+ * <StatusBar data={uptimeData} />
+ * ```
*
* @example
+ * // With custom bar renderer
* ```tsx
- * <StatusBar data={statusData} />
+ * <StatusBar
+ * data={uptimeData}
+ * renderBar={(segment, index) => (
+ * <div
+ * key={index}
+ * className="w-full transition-all"
+ * style={{
+ * height: `${segment.height}%`,
+ * background: `linear-gradient(to top, ${statusColors[segment.status]}, transparent)`
+ * }}
+ * />
+ * )}
+ * />
* ```
*
* @example
+ * // With custom event renderer
* ```tsx
- * // With custom renderers
* <StatusBar
- * data={statusData}
- * renderCard={(card, index) => <CustomCard {...card} />}
- * renderBar={(bar, index) => <CustomBar {...bar} />}
- * renderEvent={(event, index) => <CustomEvent {...event} />}
+ * data={uptimeData}
+ * renderEvent={(event, index) => (
+ * <Link key={index} href={`/incidents/${event.id}`}>
+ * <div className="text-sm hover:underline">
+ * {event.name}
+ * </div>
+ * </Link>
+ * )}
* />
* ```
+ *
+ * @see useStatusBar - For the headless hook powering the interactions
+ * @see StatusBarSkeleton - For loading state
+ * @see StatusBarEvent - For event badge rendering
*/
export function StatusBar({
data,
@@ -422,7 +570,22 @@ interface StatusBarCardProps {
}
/**
- * StatusBarCard - The hover card content for a status bar item
+ * StatusBarCard - Internal hover card content component
+ *
+ * Displays detailed status information for a single day in a hover card, including:
+ * - Date header
+ * - Status breakdown percentages
+ * - Events/incidents for that day
+ * - Pin/unpin instructions (when pinned on desktop)
+ *
+ * The card automatically formats the date and renders status items and events
+ * using either custom renderers or default implementations.
+ *
+ * @param item - The status bar data for this day
+ * @param isPinned - Whether the card is currently pinned open
+ * @param isTouch - Whether the device supports touch
+ * @param renderCard - Optional custom renderer for status items
+ * @param renderEvent - Optional custom renderer for events
*/
function StatusBarCard({
item,
@@ -491,6 +654,23 @@ function StatusBarCard({
);
}
+/**
+ * StatusBarSkeleton - Loading skeleton for StatusBar
+ *
+ * Displays a skeleton loader matching the height and width of a StatusBar,
+ * used while status data is being fetched.
+ *
+ * @example
+ * ```tsx
+ * {isLoading ? (
+ * <StatusBarSkeleton />
+ * ) : (
+ * <StatusBar data={uptimeData} />
+ * )}
+ * ```
+ *
+ * @see StatusBar - For the actual status bar component
+ */
export function StatusBarSkeleton({
className,
...props
@@ -503,6 +683,22 @@ export function StatusBarSkeleton({
);
}
+/**
+ * StatusBarContent - Internal component for status breakdown rows
+ *
+ * Displays a single status item in the hover card with a colored indicator,
+ * status label, and percentage value. Used by StatusBarCard to show the
+ * breakdown of statuses for a day.
+ *
+ * @param status - The status type (success, degraded, error, info, empty)
+ * @param value - The percentage or count value to display
+ *
+ * @example
+ * ```tsx
+ * <StatusBarContent status="success" value="95.2%" />
+ * <StatusBarContent status="error" value="4.8%" />
+ * ```
+ */
function StatusBarContent({
status,
value,
@@ -529,7 +725,53 @@ function StatusBarContent({
}
/**
- * StatusBarEvent - Displays an event badge in the status bar card
+ * StatusBarEvent - Event badge for incidents and maintenance
+ *
+ * Displays an event within a status bar hover card, showing:
+ * - Color-coded indicator (red for incidents, yellow for reports, blue for maintenance)
+ * - Event name with truncation for long names
+ * - Date range (formatted as "Since", "Until", or "Jan 15 - Jan 16")
+ * - Duration (formatted as "2 hours", "ongoing", or "across 3 days" for multiple incidents)
+ *
+ * The component automatically determines the status color based on the event type:
+ * - incident → error (red)
+ * - report → degraded (yellow)
+ * - maintenance → info (blue)
+ *
+ * Returns null if no start date is provided.
+ *
+ * @param name - Event name or title
+ * @param from - Event start date
+ * @param to - Event end date (null for ongoing events)
+ * @param type - Event type ("incident", "report", or "maintenance")
+ *
+ * @example
+ * ```tsx
+ * <StatusBarEvent
+ * type="incident"
+ * name="API Downtime"
+ * from={new Date("2024-01-15T10:00:00Z")}
+ * to={new Date("2024-01-15T10:30:00Z")}
+ * />
+ * // Displays: [●] API Downtime
+ * // Jan 15, 10:00 AM - 10:30 AM 30 minutes
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Ongoing incident
+ * <StatusBarEvent
+ * type="incident"
+ * name="Database connectivity issues"
+ * from={new Date()}
+ * to={null}
+ * />
+ * // Displays: [●] Database connectivity issues
+ * // Since Jan 15, 2:30 PM ongoing
+ * ```
+ *
+ * @see StatusBarCard - For the card that contains event badges
+ * @see formatDateRange - For date range formatting
*/
export function StatusBarEvent({
name,
@@ -573,6 +815,21 @@ export function StatusBarEvent({
);
}
+/**
+ * formatDuration - Internal helper for formatting event durations
+ *
+ * Formats the duration of an event based on start/end dates and event name:
+ * - No start date: returns null
+ * - No end date: returns "ongoing"
+ * - Multiple incidents (detected by "Downtime (" in name): returns "across {duration}"
+ * - Zero seconds duration: returns null (hides duration)
+ * - Otherwise: returns formatted duration (e.g., "2 hours", "3 days")
+ *
+ * @param from - Event start date
+ * @param to - Event end date
+ * @param name - Event name (used to detect multiple incident aggregations)
+ * @returns Formatted duration string or null
+ */
const formatDuration = ({
from,
to,
diff --git a/packages/ui/src/components/blocks/status-blank.tsx b/packages/ui/src/components/blocks/status-blank.tsx
index 592f7282e..fd2b00e6e 100644
--- a/packages/ui/src/components/blocks/status-blank.tsx
+++ b/packages/ui/src/components/blocks/status-blank.tsx
@@ -1,5 +1,27 @@
import { cn } from "@openstatus/ui/lib/utils";
+// ============================================================================
+// Container Components
+// ============================================================================
+
+/**
+ * StatusBlankContainer - Main container for empty state displays
+ *
+ * Provides a centered, bordered container with muted background for displaying
+ * empty state content. The container is responsive with adaptive padding
+ * (sm:px-8 sm:py-6) and uses flexbox for vertical centering of content.
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankContainer>
+ * <StatusBlankTitle>No Data Available</StatusBlankTitle>
+ * <StatusBlankDescription>Add monitors to see data here</StatusBlankDescription>
+ * </StatusBlankContainer>
+ * ```
+ *
+ * @see StatusBlankTitle - For heading text
+ * @see StatusBlankDescription - For descriptive text
+ */
export function StatusBlankContainer({
children,
className,
@@ -18,6 +40,23 @@ export function StatusBlankContainer({
);
}
+// ============================================================================
+// Text Components
+// ============================================================================
+
+/**
+ * StatusBlankTitle - Title text for empty state displays
+ *
+ * Displays medium-weight title text within empty state containers.
+ * Typically used to communicate the empty state condition.
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankTitle>No monitors found</StatusBlankTitle>
+ * ```
+ *
+ * @see StatusBlankDescription - For additional descriptive text
+ */
export function StatusBlankTitle({
children,
className,
@@ -30,6 +69,22 @@ export function StatusBlankTitle({
);
}
+/**
+ * StatusBlankDescription - Descriptive text for empty state displays
+ *
+ * Displays muted, monospaced text providing additional context or guidance
+ * for the empty state. The monospace font helps distinguish it as secondary
+ * instructional text.
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankDescription>
+ * Add monitors to this page to see their status here
+ * </StatusBlankDescription>
+ * ```
+ *
+ * @see StatusBlankTitle - For primary heading text
+ */
export function StatusBlankDescription({
children,
className,
@@ -45,6 +100,20 @@ export function StatusBlankDescription({
);
}
+/**
+ * StatusBlankContent - Content wrapper for empty state text
+ *
+ * Provides vertical spacing (space-y-1) for stacking title and description
+ * components within an empty state display.
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankContent>
+ * <StatusBlankTitle>No Events</StatusBlankTitle>
+ * <StatusBlankDescription>No events to display</StatusBlankDescription>
+ * </StatusBlankContent>
+ * ```
+ */
export function StatusBlankContent({
children,
className,
@@ -57,6 +126,32 @@ export function StatusBlankContent({
);
}
+// ============================================================================
+// Visualization Components
+// ============================================================================
+
+/**
+ * StatusBlankReport - Visual representation of an empty incident report
+ *
+ * Displays a stylized preview of an incident report page with placeholder
+ * header, report updates, and an overlay gradient. Used to visualize what
+ * incident reports will look like when created.
+ *
+ * This component is typically rendered in multiple layers with different
+ * scales and opacities to create a stacked card effect.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative">
+ * <StatusBlankReport className="absolute scale-80 opacity-80" />
+ * <StatusBlankReport />
+ * </div>
+ * ```
+ *
+ * @see StatusBlankEvents - For composed empty state with stacked reports
+ * @see StatusBlankPageHeader - For the header visualization
+ * @see StatusBlankReportUpdate - For the update line visualizations
+ */
export function StatusBlankReport({ ...props }: React.ComponentProps<"div">) {
return (
<StatusBlankPage {...props}>
@@ -70,6 +165,28 @@ export function StatusBlankReport({ ...props }: React.ComponentProps<"div">) {
);
}
+/**
+ * StatusBlankMonitor - Visual representation of an empty monitor display
+ *
+ * Displays a stylized preview of a monitor page with placeholder header and
+ * uptime visualization bars. Used to show what monitor displays will look like
+ * when monitors are added.
+ *
+ * This component is typically rendered in multiple layers with different
+ * scales and opacities to create a stacked card effect.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative">
+ * <StatusBlankMonitor className="absolute scale-80 opacity-80" />
+ * <StatusBlankMonitor />
+ * </div>
+ * ```
+ *
+ * @see StatusBlankMonitors - For composed empty state with stacked monitors
+ * @see StatusBlankPageHeader - For the header visualization
+ * @see StatusBlankMonitorUptime - For the uptime bar visualization
+ */
export function StatusBlankMonitor({ ...props }: React.ComponentProps<"div">) {
return (
<StatusBlankPage {...props}>
@@ -80,6 +197,32 @@ export function StatusBlankMonitor({ ...props }: React.ComponentProps<"div">) {
);
}
+// ============================================================================
+// Animation Components (for visualization internals)
+// ============================================================================
+
+/**
+ * StatusBlankPage - Base container for blank page visualizations
+ *
+ * Provides a card-like container with border and background for page previews.
+ * This component is used as the foundation for StatusBlankReport and
+ * StatusBlankMonitor visualizations, providing consistent sizing and styling.
+ *
+ * The container uses relative positioning to enable absolutely positioned
+ * overlay gradients within the visualization.
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankPage>
+ * <StatusBlankPageHeader />
+ * <div>// Content here</div>
+ * <StatusBlankOverlay />
+ * </StatusBlankPage>
+ * ```
+ *
+ * @see StatusBlankReport - For report visualization using this container
+ * @see StatusBlankMonitor - For monitor visualization using this container
+ */
export function StatusBlankPage({
className,
children,
@@ -98,6 +241,26 @@ export function StatusBlankPage({
);
}
+/**
+ * StatusBlankPageHeader - Placeholder header for page visualizations
+ *
+ * Displays a stylized representation of a page header with placeholder elements
+ * for logo, navigation items, and actions. Uses accent-colored rounded rectangles
+ * to create a recognizable header pattern.
+ *
+ * The header shows:
+ * - Left: Single square (logo placeholder)
+ * - Center: Three rectangles (navigation items)
+ * - Right: Single rectangle (action button)
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankPage>
+ * <StatusBlankPageHeader />
+ * // Other visualization content
+ * </StatusBlankPage>
+ * ```
+ */
export function StatusBlankPageHeader({
className,
...props
@@ -121,6 +284,25 @@ export function StatusBlankPageHeader({
);
}
+/**
+ * StatusBlankMonitorUptime - Uptime visualization for monitor previews
+ *
+ * Displays a stylized uptime chart with placeholder labels and 30 vertical bars
+ * representing uptime data. Some bars have varying heights to create a realistic
+ * visualization pattern showing occasional incidents.
+ *
+ * The visualization includes:
+ * - Top: Three placeholder labels for time periods
+ * - Bottom: 30 vertical bars with most at full height and some shorter to indicate incidents
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankMonitor>
+ * <StatusBlankPageHeader />
+ * <StatusBlankMonitorUptime />
+ * </StatusBlankMonitor>
+ * ```
+ */
export function StatusBlankMonitorUptime({
className,
...props
@@ -154,6 +336,28 @@ export function StatusBlankMonitorUptime({
);
}
+/**
+ * StatusBlankReportUpdate - Single update entry for report visualizations
+ *
+ * Displays a stylized representation of an incident report update with placeholder
+ * elements for status indicator, timestamp, and message lines. Creates a timeline-like
+ * appearance when stacked vertically.
+ *
+ * The update shows:
+ * - Left: Square status indicator
+ * - Right: Two label placeholders (status + timestamp) and two message lines
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankPage>
+ * <StatusBlankPageHeader />
+ * <div className="flex flex-col">
+ * <StatusBlankReportUpdate />
+ * <StatusBlankReportUpdate />
+ * </div>
+ * </StatusBlankPage>
+ * ```
+ */
export function StatusBlankReportUpdate({
className,
...props
@@ -175,6 +379,25 @@ export function StatusBlankReportUpdate({
);
}
+/**
+ * StatusBlankOverlay - Gradient overlay for page visualizations
+ *
+ * Provides a bottom-to-top gradient overlay that fades the visualization content
+ * from transparent (top 40%) to background color (bottom), creating a subtle
+ * depth effect. The overlay is absolutely positioned to cover the entire parent.
+ *
+ * This overlay helps create visual separation between the preview visualization
+ * and any content that might be displayed on top of it (like call-to-action text).
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankPage>
+ * <StatusBlankPageHeader />
+ * <StatusBlankMonitorUptime />
+ * <StatusBlankOverlay />
+ * </StatusBlankPage>
+ * ```
+ */
export function StatusBlankOverlay({
children,
className,
@@ -193,6 +416,35 @@ export function StatusBlankOverlay({
);
}
+// ============================================================================
+// Composed Empty States
+// ============================================================================
+
+/**
+ * StatusBlankEvents - Complete empty state for incident reports
+ *
+ * Displays a fully composed empty state with stacked StatusBlankReport
+ * visualizations (three layers with varying scales and opacities) and
+ * customizable title/description text. This creates an engaging empty state
+ * that shows users what incident reports will look like.
+ *
+ * The visualization uses absolute positioning to create a layered card stack
+ * effect with the front card at full opacity and back cards progressively
+ * faded and scaled down.
+ *
+ * @param title - The empty state heading (default: "No reports found")
+ * @param description - The empty state description (default: "No reports found for this status page.")
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankEvents
+ * title="No incidents yet"
+ * description="Incident reports will appear here when created"
+ * />
+ * ```
+ *
+ * @see StatusBlankReport - For the underlying report visualization
+ */
export function StatusBlankEvents({
title = "No reports found",
description = "No reports found for this status page.",
@@ -216,6 +468,31 @@ export function StatusBlankEvents({
);
}
+/**
+ * StatusBlankMonitors - Complete empty state for monitors
+ *
+ * Displays a fully composed empty state with stacked StatusBlankMonitor
+ * visualizations (three layers with varying scales and opacities) and
+ * customizable title/description text. This creates an engaging empty state
+ * that shows users what monitor displays will look like.
+ *
+ * The visualization uses absolute positioning to create a layered card stack
+ * effect with the front card at full opacity and back cards progressively
+ * faded and scaled down.
+ *
+ * @param title - The empty state heading (default: "No public monitors")
+ * @param description - The empty state description (default: "No public monitors have been added to this page.")
+ *
+ * @example
+ * ```tsx
+ * <StatusBlankMonitors
+ * title="No monitors configured"
+ * description="Add monitors to start tracking uptime"
+ * />
+ * ```
+ *
+ * @see StatusBlankMonitor - For the underlying monitor visualization
+ */
export function StatusBlankMonitors({
title = "No public monitors",
description = "No public monitors have been added to this page.",
diff --git a/packages/ui/src/components/blocks/status-component-group.tsx b/packages/ui/src/components/blocks/status-component-group.tsx
index 5ce8a8de7..14135b9e6 100644
--- a/packages/ui/src/components/blocks/status-component-group.tsx
+++ b/packages/ui/src/components/blocks/status-component-group.tsx
@@ -13,6 +13,107 @@ import {
} from "@openstatus/ui/components/blocks/status-component";
import type { StatusType } from "@openstatus/ui/components/blocks/status.types";
+/**
+ * StatusComponentGroup - Collapsible group for organizing related monitors
+ *
+ * A collapsible container component for grouping related StatusComponent items,
+ * displaying an aggregate status for the group. The component shows:
+ * - Group title
+ * - Aggregate status label (e.g., "Operational", "Degraded")
+ * - Status icon with appropriate color
+ * - Expandable/collapsible content area for grouped monitors
+ *
+ * **Key Features**:
+ * - **Collapsible**: Click to expand/collapse grouped monitors
+ * - **Hydration-Aware Animations**: Prevents layout shift on initial render by delaying
+ * animations until after mount (avoids animation flash when defaultOpen=true)
+ * - **Aggregate Status**: Shows overall status for the entire group
+ * - **Keyboard Accessible**: Full keyboard support via Radix UI Collapsible
+ * - **Hover Effects**: Subtle border and background changes on hover/open
+ *
+ * The component uses a hydration-aware animation pattern: animations are disabled
+ * on the server and first client render, then enabled after mount. This prevents
+ * layout shifts when `defaultOpen={true}` is used.
+ *
+ * @param title - The group name/title
+ * @param status - The aggregate status type for the group (controls icon color and status label)
+ * @param defaultOpen - Whether the group starts expanded (default: false)
+ * @param children - StatusComponent items or other content to display when expanded
+ *
+ * @example
+ * // Basic collapsible group with multiple monitors
+ * ```tsx
+ * <StatusComponentGroup
+ * title="API Services"
+ * status="success"
+ * defaultOpen={false}
+ * >
+ * <StatusComponent variant="success">
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>REST API</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * </StatusComponentHeader>
+ * </StatusComponent>
+ * <StatusComponent variant="success">
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>GraphQL API</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * </StatusComponentHeader>
+ * </StatusComponent>
+ * </StatusComponentGroup>
+ * ```
+ *
+ * @example
+ * // Degraded group with mixed statuses
+ * ```tsx
+ * <StatusComponentGroup
+ * title="Database Cluster"
+ * status="degraded"
+ * defaultOpen={true}
+ * >
+ * <StatusComponent variant="success">
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>Primary DB</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * </StatusComponentHeader>
+ * </StatusComponent>
+ * <StatusComponent variant="degraded">
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>Replica DB</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * </StatusComponentHeader>
+ * </StatusComponent>
+ * </StatusComponentGroup>
+ * ```
+ *
+ * @example
+ * // Multiple groups for different service categories
+ * ```tsx
+ * <StatusContent>
+ * <StatusComponentGroup title="Core Services" status="success">
+ * // Core service monitors...
+ * </StatusComponentGroup>
+ * <StatusComponentGroup title="Third-Party APIs" status="degraded" defaultOpen>
+ * // Third-party monitors...
+ * </StatusComponentGroup>
+ * <StatusComponentGroup title="Internal Tools" status="success">
+ * // Internal tool monitors...
+ * </StatusComponentGroup>
+ * </StatusContent>
+ * ```
+ *
+ * @see StatusComponent - For individual monitor displays within the group
+ * @see StatusComponentIcon - For the status icon displayed in the header
+ * @see StatusComponentStatus - For the status label displayed in the header
+ */
export function StatusComponentGroup({
children,
title,
diff --git a/packages/ui/src/components/blocks/status-component.tsx b/packages/ui/src/components/blocks/status-component.tsx
index 10324962b..0e61b21b9 100644
--- a/packages/ui/src/components/blocks/status-component.tsx
+++ b/packages/ui/src/components/blocks/status-component.tsx
@@ -13,14 +13,234 @@ import { formatDistanceToNowStrict } from "date-fns";
import { InfoIcon } from "lucide-react";
import { useState } from "react";
import { StatusIcon as UnifiedStatusIcon } from "@openstatus/ui/components/blocks/status-icon";
-import type { StatusBarData } from "@openstatus/ui/components/blocks/status.types";
+import type {
+ StatusBarData,
+ StatusType,
+} from "@openstatus/ui/components/blocks/status.types";
import { systemStatusLabels } from "@openstatus/ui/components/blocks/status.utils";
-// NOTE: The main StatusComponent composed component has been removed - it contained business logic
-// The app should compose these primitives based on its own business logic
+// ============================================================================
+// Layout Components
+// ============================================================================
-// maybe add a StatusComponent as example how to use the primitives
+interface StatusComponentProps extends React.ComponentProps<"div"> {
+ variant: Exclude<StatusType, "empty">;
+}
+
+/**
+ * StatusComponent - Root container for individual monitor/service status displays
+ *
+ * This component serves as the main container for displaying a single monitor or
+ * service status. It establishes the status type context via data-variant attribute,
+ * which child components (like StatusComponentIcon and StatusComponentStatus) use
+ * to display the appropriate colors and icons.
+ *
+ * The component acts as a CSS group (/component) for advanced selector patterns,
+ * enabling child components to style themselves based on the parent's variant.
+ *
+ * @param variant - The status type (success, degraded, error, or info)
+ *
+ * @example
+ * ```tsx
+ * <StatusComponent variant="success">
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>API Server</StatusComponentTitle>
+ * <StatusComponentDescription>Main API endpoint</StatusComponentDescription>
+ * </StatusComponentHeaderLeft>
+ * <StatusComponentHeaderRight>
+ * <StatusComponentUptime>99.9%</StatusComponentUptime>
+ * <StatusComponentStatus />
+ * </StatusComponentHeaderRight>
+ * </StatusComponentHeader>
+ * <StatusComponentBody>
+ * <StatusBar data={uptimeData} />
+ * </StatusComponentBody>
+ * </StatusComponent>
+ * ```
+ *
+ * @see StatusComponentHeader - For header layout
+ * @see StatusComponentBody - For content area
+ * @see StatusComponentIcon - For status indicator icon
+ * @see StatusComponentStatus - For status label
+ */
+export function StatusComponent({
+ variant,
+ className,
+ children,
+ ...props
+}: StatusComponentProps) {
+ return (
+ <div
+ data-slot="status-monitor"
+ data-variant={variant}
+ className={cn("group/component space-y-2", className)}
+ {...props}
+ >
+ {children}
+ </div>
+ );
+}
+
+// ============================================================================
+// Header Components
+// ============================================================================
+
+/**
+ * StatusComponentHeader - Header container for monitor status information
+ *
+ * Provides a flex container with space-between alignment for the monitor header,
+ * typically containing title/description on the left and status/uptime on the right.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentHeader>
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>Database</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * <StatusComponentHeaderRight>
+ * <StatusComponentUptime>100%</StatusComponentUptime>
+ * </StatusComponentHeaderRight>
+ * </StatusComponentHeader>
+ * ```
+ *
+ * @see StatusComponentHeaderLeft - For left-aligned content
+ * @see StatusComponentHeaderRight - For right-aligned content
+ */
+export function StatusComponentHeader({
+ className,
+ children,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div
+ className={cn("flex items-center justify-between", className)}
+ {...props}
+ >
+ {children}
+ </div>
+ );
+}
+
+/**
+ * StatusComponentHeaderLeft - Left-aligned header content container
+ *
+ * Provides a flex container with gap-2 spacing for left-aligned header elements,
+ * typically containing the status icon, title, and optional description icon.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>API Gateway</StatusComponentTitle>
+ * <StatusComponentDescription>
+ * Handles all incoming requests
+ * </StatusComponentDescription>
+ * </StatusComponentHeaderLeft>
+ * ```
+ *
+ * @see StatusComponentIcon - For status indicator
+ * @see StatusComponentTitle - For service name
+ * @see StatusComponentDescription - For info tooltip
+ */
+export function StatusComponentHeaderLeft({
+ className,
+ children,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div className={cn("flex items-center gap-2", className)} {...props}>
+ {children}
+ </div>
+ );
+}
+
+/**
+ * StatusComponentHeaderRight - Right-aligned header content container
+ *
+ * Provides a flex container with gap-3 spacing for right-aligned header elements,
+ * typically containing uptime percentage and status label.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentHeaderRight>
+ * <StatusComponentUptime>99.95%</StatusComponentUptime>
+ * <StatusComponentStatus />
+ * </StatusComponentHeaderRight>
+ * ```
+ *
+ * @see StatusComponentUptime - For uptime percentage display
+ * @see StatusComponentStatus - For status label
+ */
+export function StatusComponentHeaderRight({
+ className,
+ children,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div className={cn("flex items-center gap-3", className)} {...props}>
+ {children}
+ </div>
+ );
+}
+
+// ============================================================================
+// Content Components
+// ============================================================================
+
+/**
+ * StatusComponentBody - Main content area for monitor visualizations
+ *
+ * Provides vertical spacing (space-y-2) for stacking content like status bars,
+ * charts, or other status visualizations within the component.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentBody>
+ * <StatusBar data={uptimeData} />
+ * <StatusComponentFooter data={uptimeData} />
+ * </StatusComponentBody>
+ * ```
+ *
+ * @see StatusBar - For uptime visualization bars
+ * @see StatusComponentFooter - For footer with date range
+ */
+export function StatusComponentBody({
+ className,
+ children,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div className={cn("space-y-2", className)} {...props}>
+ {children}
+ </div>
+ );
+}
+
+// ============================================================================
+// Display Components
+// ============================================================================
+/**
+ * StatusComponentTitle - Monitor or service name display
+ *
+ * Displays the monitor/service name in monospace font with truncation for long names.
+ * The text is medium weight and uses a base font size.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentTitle>Production API</StatusComponentTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentTitle>
+ * {monitor.name}
+ * </StatusComponentTitle>
+ * ```
+ */
export function StatusComponentTitle({
children,
className,
@@ -39,6 +259,33 @@ export function StatusComponentTitle({
);
}
+/**
+ * StatusComponentDescription - Info icon with tooltip for additional details
+ *
+ * Displays an info icon that shows a tooltip on hover (or tap on touch devices)
+ * with additional description text. Returns null if no children are provided,
+ * allowing for conditional rendering.
+ *
+ * Touch device support is built-in, toggling the tooltip on tap instead of
+ * requiring hover.
+ *
+ * @param children - The description text to show in the tooltip
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentDescription>
+ * This service handles user authentication and authorization
+ * </StatusComponentDescription>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditionally rendered - returns null if no description
+ * <StatusComponentDescription>
+ * {monitor.description}
+ * </StatusComponentDescription>
+ * ```
+ */
export function StatusComponentDescription({
onClick,
children,
@@ -70,6 +317,33 @@ export function StatusComponentDescription({
);
}
+/**
+ * StatusComponentIcon - Status indicator icon for component context
+ *
+ * This component wraps the unified StatusIcon with variant="component", configuring
+ * it to respond to the parent StatusComponent's data-variant attribute.
+ * The displayed icon and color automatically change based on the status type:
+ * - success: Green check icon
+ * - degraded: Yellow warning triangle
+ * - error: Red alert circle
+ * - info: Blue wrench icon
+ *
+ * The icon is smaller (size-[12.5px]) than other variants, optimized for inline
+ * display next to monitor titles.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponent variant="degraded">
+ * <StatusComponentHeaderLeft>
+ * <StatusComponentIcon />
+ * <StatusComponentTitle>CDN</StatusComponentTitle>
+ * </StatusComponentHeaderLeft>
+ * </StatusComponent>
+ * ```
+ *
+ * @see StatusComponent - For setting the variant context
+ * @see StatusIcon from status-icon.tsx - For the underlying unified icon implementation
+ */
export function StatusComponentIcon({
className,
...props
@@ -79,6 +353,34 @@ export function StatusComponentIcon({
);
}
+/**
+ * StatusComponentFooter - Date range footer for status visualizations
+ *
+ * Displays a date range footer showing the time span of the displayed data,
+ * with the start date on the left (formatted as relative time like "45 days ago")
+ * and "today" on the right. Shows a skeleton loader when data is loading.
+ *
+ * If no data is available, displays a dash (-) on the left side.
+ *
+ * @param data - Array of status bar data points (uses first item's date for start)
+ * @param isLoading - Whether the data is currently loading
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentBody>
+ * <StatusBar data={uptimeData} />
+ * <StatusComponentFooter data={uptimeData} isLoading={false} />
+ * </StatusComponentBody>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With loading state
+ * <StatusComponentFooter data={[]} isLoading={true} />
+ * ```
+ *
+ * @see StatusBar - For the visualization that this footer describes
+ */
export function StatusComponentFooter({
data,
isLoading,
@@ -105,6 +407,26 @@ export function StatusComponentFooter({
);
}
+/**
+ * StatusComponentUptime - Uptime percentage display
+ *
+ * Displays the uptime percentage in monospace font with slightly muted foreground
+ * color. Typically shows values like "99.9%" or "100%".
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentUptime>99.95%</StatusComponentUptime>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentUptime>
+ * {calculateUptime(data)}%
+ * </StatusComponentUptime>
+ * ```
+ *
+ * @see StatusComponentUptimeSkeleton - For loading state
+ */
export function StatusComponentUptime({
className,
children,
@@ -123,6 +445,25 @@ export function StatusComponentUptime({
);
}
+/**
+ * StatusComponentUptimeSkeleton - Loading skeleton for uptime percentage
+ *
+ * Displays a skeleton loader matching the size of the uptime percentage display
+ * (h-4 w-16), used while uptime data is being fetched.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponentHeaderRight>
+ * {isLoading ? (
+ * <StatusComponentUptimeSkeleton />
+ * ) : (
+ * <StatusComponentUptime>{uptime}%</StatusComponentUptime>
+ * )}
+ * </StatusComponentHeaderRight>
+ * ```
+ *
+ * @see StatusComponentUptime - For the actual uptime display
+ */
export function StatusComponentUptimeSkeleton({
className,
...props
@@ -130,6 +471,43 @@ export function StatusComponentUptimeSkeleton({
return <Skeleton className={cn("h-4 w-16", className)} {...props} />;
}
+/**
+ * StatusComponentStatus - Automatic status label display
+ *
+ * Displays a status label that automatically shows the appropriate text and color
+ * based on the parent StatusComponent's variant. The component uses CSS data
+ * attribute selectors to show only the relevant status label:
+ * - success: "Operational" (green)
+ * - degraded: "Degraded" (yellow)
+ * - error: "Outage" (red)
+ * - info: "Maintenance" (blue)
+ *
+ * The labels are sourced from systemStatusLabels.short for consistent messaging
+ * across the application.
+ *
+ * @example
+ * ```tsx
+ * <StatusComponent variant="success">
+ * <StatusComponentHeaderRight>
+ * <StatusComponentStatus />
+ * // Displays "Operational" in green
+ * </StatusComponentHeaderRight>
+ * </StatusComponent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StatusComponent variant="degraded">
+ * <StatusComponentHeaderRight>
+ * <StatusComponentStatus />
+ * // Displays "Degraded" in yellow
+ * </StatusComponentHeaderRight>
+ * </StatusComponent>
+ * ```
+ *
+ * @see StatusComponent - For setting the variant that controls the displayed status
+ * @see systemStatusLabels - For the status label text definitions
+ */
export function StatusComponentStatus({
className,
...props
diff --git a/packages/ui/src/components/blocks/status-events.tsx b/packages/ui/src/components/blocks/status-events.tsx
index ca050a578..8315852bc 100644
--- a/packages/ui/src/components/blocks/status-events.tsx
+++ b/packages/ui/src/components/blocks/status-events.tsx
@@ -18,6 +18,31 @@ import {
import type { StatusReportUpdateType } from "@openstatus/ui/components/blocks/status.types";
import { StatusTimestamp } from "@openstatus/ui/components/blocks/status-timestamp";
+// ============================================================================
+// Container Components
+// ============================================================================
+
+/**
+ * StatusEventGroup - Root container for status events and incident reports
+ *
+ * Provides a vertical flex container with consistent spacing (gap-4) for
+ * displaying a feed of status events, incident reports, and maintenance notices.
+ * The component includes ARIA role="feed" for accessibility.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventGroup>
+ * <StatusEvent>
+ * // First incident...
+ * </StatusEvent>
+ * <StatusEvent>
+ * // Second incident...
+ * </StatusEvent>
+ * </StatusEventGroup>
+ * ```
+ *
+ * @see StatusEvent - For individual event items
+ */
export function StatusEventGroup({
className,
children,
@@ -35,6 +60,25 @@ export function StatusEventGroup({
);
}
+/**
+ * StatusEvent - Individual event container within StatusEventGroup
+ *
+ * Container for a single event (incident, report, or maintenance) with relative
+ * positioning to support absolutely positioned date aside elements.
+ *
+ * @example
+ * ```tsx
+ * <StatusEvent>
+ * <StatusEventAside>
+ * <StatusEventDate date={new Date()} />
+ * </StatusEventAside>
+ * <StatusEventContent>
+ * <StatusEventTitle>API Outage</StatusEventTitle>
+ * // Event details...
+ * </StatusEventContent>
+ * </StatusEvent>
+ * ```
+ */
export function StatusEvent({
className,
children,
@@ -47,6 +91,26 @@ export function StatusEvent({
);
}
+// ============================================================================
+// Content Components
+// ============================================================================
+
+/**
+ * StatusEventContent - Main content container for event details
+ *
+ * Provides a hoverable container with rounded borders and muted background on hover.
+ * The hoverable behavior can be disabled for non-interactive events.
+ *
+ * @param hoverable - Whether to show hover effects (default: true)
+ *
+ * @example
+ * ```tsx
+ * <StatusEventContent>
+ * <StatusEventTitle>Database Maintenance</StatusEventTitle>
+ * <p>Scheduled maintenance from 2-4 AM UTC</p>
+ * </StatusEventContent>
+ * ```
+ */
export function StatusEventContent({
className,
hoverable = true,
@@ -70,6 +134,17 @@ export function StatusEventContent({
);
}
+/**
+ * StatusEventTitle - Title for status events
+ *
+ * Displays the event title in medium-weight font, typically used for incident
+ * names or maintenance titles.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTitle>API Gateway Outage</StatusEventTitle>
+ * ```
+ */
export function StatusEventTitle({
className,
children,
@@ -82,6 +157,20 @@ export function StatusEventTitle({
);
}
+/**
+ * StatusEventTitleCheck - Resolved status indicator with tooltip
+ *
+ * Displays a green check icon in a circular badge with a tooltip explaining
+ * that the report has been resolved. Typically displayed next to event titles.
+ *
+ * @example
+ * ```tsx
+ * <div className="flex items-center gap-2">
+ * <StatusEventTitle>API Outage</StatusEventTitle>
+ * <StatusEventTitleCheck />
+ * </div>
+ * ```
+ */
export function StatusEventTitleCheck({
className,
children,
@@ -105,6 +194,25 @@ export function StatusEventTitleCheck({
);
}
+// ============================================================================
+// Affected Services Components
+// ============================================================================
+
+/**
+ * StatusEventAffected - Container for affected service badges
+ *
+ * Displays a wrapping flex container for StatusEventAffectedBadge components,
+ * showing which services were impacted by an incident.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventAffected>
+ * <StatusEventAffectedBadge>API</StatusEventAffectedBadge>
+ * <StatusEventAffectedBadge>Database</StatusEventAffectedBadge>
+ * <StatusEventAffectedBadge>CDN</StatusEventAffectedBadge>
+ * </StatusEventAffected>
+ * ```
+ */
export function StatusEventAffected({
className,
children,
@@ -117,6 +225,17 @@ export function StatusEventAffected({
);
}
+/**
+ * StatusEventAffectedBadge - Badge for individual affected service
+ *
+ * Displays a small secondary-style badge representing a single affected service.
+ * Uses a smaller font size (text-[10px]) for compact display.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventAffectedBadge>REST API</StatusEventAffectedBadge>
+ * ```
+ */
export function StatusEventAffectedBadge({
className,
children,
@@ -133,6 +252,25 @@ export function StatusEventAffectedBadge({
);
}
+// ============================================================================
+// Date/Time Components
+// ============================================================================
+
+/**
+ * StatusEventDate - Date display with relative time badge
+ *
+ * Displays a formatted date with a relative time badge (e.g., "2 days ago").
+ * For future dates, the badge is highlighted in info color. The layout is
+ * responsive: horizontal on mobile (gap-2), vertical on desktop (flex-col).
+ *
+ * @param date - The event date to display
+ *
+ * @example
+ * ```tsx
+ * <StatusEventDate date={new Date("2024-01-15")} />
+ * // Displays: "Jan 15, 2024" with "2 days ago" badge
+ * ```
+ */
export function StatusEventDate({
className,
date,
@@ -160,6 +298,25 @@ export function StatusEventDate({
);
}
+/**
+ * StatusEventAside - Sidebar date container (desktop only)
+ *
+ * Positions the date to the left of event content on desktop screens (lg breakpoint).
+ * On mobile, it appears inline. Uses sticky positioning on desktop to keep dates
+ * visible while scrolling through long events.
+ *
+ * @example
+ * ```tsx
+ * <StatusEvent>
+ * <StatusEventAside>
+ * <StatusEventDate date={incidentDate} />
+ * </StatusEventAside>
+ * <StatusEventContent>
+ * // Event content...
+ * </StatusEventContent>
+ * </StatusEvent>
+ * ```
+ */
export function StatusEventAside({
className,
children,
@@ -180,6 +337,56 @@ interface StatusReportUpdate {
status: StatusReportUpdateType;
}
+// ============================================================================
+// Timeline Components
+// ============================================================================
+
+/**
+ * StatusEventTimelineReport - Timeline of incident report updates
+ *
+ * Displays a chronological timeline of incident updates, sorted from newest to
+ * oldest. Each update shows the status (investigating → identified → monitoring → resolved),
+ * timestamp, message, and time elapsed between updates.
+ *
+ * **Automatic Duration Calculation**:
+ * - First update (most recent): Shows total time from start to resolution (if resolved)
+ * - Other updates: Shows time elapsed since the previous update
+ *
+ * @param updates - Array of report updates to display
+ * @param withDot - Whether to show colored status dots (default: true)
+ * @param maxUpdates - Maximum number of updates to display (optional, shows all if not specified)
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTimelineReport
+ * updates={[
+ * {
+ * status: "resolved",
+ * message: "All services restored",
+ * date: new Date("2024-01-15T12:00:00Z")
+ * },
+ * {
+ * status: "monitoring",
+ * message: "Fix deployed, monitoring recovery",
+ * date: new Date("2024-01-15T11:45:00Z")
+ * },
+ * {
+ * status: "identified",
+ * message: "Root cause identified in database",
+ * date: new Date("2024-01-15T11:15:00Z")
+ * },
+ * {
+ * status: "investigating",
+ * message: "Investigating API timeouts",
+ * date: new Date("2024-01-15T11:00:00Z")
+ * }
+ * ]}
+ * />
+ * // Displays timeline with: "Resolved (in 1 hour)" → "Monitoring (15 minutes earlier)" → etc.
+ * ```
+ *
+ * @see StatusEventTimelineReportUpdate - For individual update rendering
+ */
export function StatusEventTimelineReport({
className,
updates,
@@ -235,6 +442,39 @@ export function StatusEventTimelineReport({
);
}
+/**
+ * StatusEventTimelineReportUpdate - Single update entry in incident timeline
+ *
+ * Displays one update in the incident timeline with:
+ * - Colored dot indicator (red=investigating, yellow=identified, blue=monitoring, green=resolved)
+ * - Status label and timestamp (with StatusTimestamp for rich hover details)
+ * - Duration text (e.g., "in 1 hour" or "15 minutes earlier")
+ * - Update message
+ * - Optional vertical separator line connecting to next update
+ *
+ * @param report - The update data (status, message, date)
+ * @param duration - Optional duration text to display
+ * @param withSeparator - Whether to show separator line to next update (default: true)
+ * @param withDot - Whether to show colored status dot (default: true)
+ * @param isLast - Whether this is the last update (affects bottom margin)
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTimelineReportUpdate
+ * report={{
+ * status: "resolved",
+ * message: "All systems operational",
+ * date: new Date()
+ * }}
+ * duration="(in 45 minutes)"
+ * withSeparator={false}
+ * isLast={true}
+ * />
+ * ```
+ *
+ * @see StatusEventTimelineDot - For the colored dot indicator
+ * @see StatusEventTimelineSeparator - For the connecting line
+ */
export function StatusEventTimelineReportUpdate({
report,
duration,
@@ -297,6 +537,35 @@ interface StatusMaintenanceUpdate {
to: Date;
}
+/**
+ * StatusEventTimelineMaintenance - Timeline entry for maintenance windows
+ *
+ * Displays a maintenance window with title, date range, duration, and message.
+ * Uses a blue dot indicator to distinguish from incident updates.
+ *
+ * The date range is formatted and split to allow individual StatusTimestamp
+ * components for each date, providing rich hover details.
+ *
+ * @param maintenance - The maintenance data (title, message, from, to dates)
+ * @param withDot - Whether to show the blue maintenance dot (default: true)
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTimelineMaintenance
+ * maintenance={{
+ * title: "Database Upgrade",
+ * message: "Upgrading to PostgreSQL 15",
+ * from: new Date("2024-01-20T02:00:00Z"),
+ * to: new Date("2024-01-20T04:00:00Z")
+ * }}
+ * />
+ * // Displays: [●] Database Upgrade · Jan 20, 2:00 AM - 4:00 AM (for 2 hours)
+ * // Upgrading to PostgreSQL 15
+ * ```
+ *
+ * @see StatusEventTimelineDot - For the colored indicator
+ * @see StatusTimestamp - For rich timestamp hover cards
+ */
export function StatusEventTimelineMaintenance({
maintenance,
withDot = true,
@@ -357,6 +626,19 @@ export function StatusEventTimelineMaintenance({
);
}
+/**
+ * StatusEventTimelineTitle - Title line for timeline entries
+ *
+ * Displays the title line of timeline entries with medium font weight,
+ * typically containing status label, timestamp, and duration.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTimelineTitle>
+ * <span>Resolved</span> · <span>Jan 15, 10:30 AM</span>
+ * </StatusEventTimelineTitle>
+ * ```
+ */
export function StatusEventTimelineTitle({
className,
children,
@@ -372,6 +654,19 @@ export function StatusEventTimelineTitle({
);
}
+/**
+ * StatusEventTimelineMessage - Message content for timeline entries
+ *
+ * Displays the update message in monospace font with muted color and
+ * consistent padding.
+ *
+ * @example
+ * ```tsx
+ * <StatusEventTimelineMessage>
+ * We have identified the root cause and deployed a fix
+ * </StatusEventTimelineMessage>
+ * ```
+ */
export function StatusEventTimelineMessage({
className,
children,
@@ -390,6 +685,24 @@ export function StatusEventTimelineMessage({
);
}
+/**
+ * StatusEventTimelineDot - Colored status indicator dot
+ *
+ * Displays a small circular dot with color based on the parent's data-variant:
+ * - investigating: Red (destructive)
+ * - identified: Yellow (warning)
+ * - monitoring: Blue (info)
+ * - resolved: Green (success)
+ * - maintenance: Blue (info)
+ *
+ * @example
+ * ```tsx
+ * <div data-variant="resolved">
+ * <StatusEventTimelineDot />
+ * // Displays green dot
+ * </div>
+ * ```
+ */
export function StatusEventTimelineDot({
className,
...props
@@ -410,6 +723,22 @@ export function StatusEventTimelineDot({
);
}
+/**
+ * StatusEventTimelineSeparator - Vertical line connecting timeline entries
+ *
+ * Displays a vertical separator line between timeline updates, colored to match
+ * the status of the update it's connected to. Uses the same color scheme as
+ * StatusEventTimelineDot.
+ *
+ * @example
+ * ```tsx
+ * <div data-variant="monitoring">
+ * <StatusEventTimelineDot />
+ * <StatusEventTimelineSeparator />
+ * // Displays blue connecting line
+ * </div>
+ * ```
+ */
export function StatusEventTimelineSeparator({
className,
...props
diff --git a/packages/ui/src/components/blocks/status-feed.tsx b/packages/ui/src/components/blocks/status-feed.tsx
index 7c6024ceb..f9da1fa7c 100644
--- a/packages/ui/src/components/blocks/status-feed.tsx
+++ b/packages/ui/src/components/blocks/status-feed.tsx
@@ -34,7 +34,21 @@ type UnifiedEvent = {
);
/**
- * Type guard to check if an event is a status report
+ * isStatusReport - Type guard for discriminating status reports
+ *
+ * Type guard function that narrows a UnifiedEvent to a status report event.
+ * Used internally by StatusFeed to distinguish between reports and maintenance.
+ *
+ * @param event - The unified event to check
+ * @returns True if the event is a status report
+ *
+ * @example
+ * ```tsx
+ * if (isStatusReport(event)) {
+ * // TypeScript knows event.data is StatusReport
+ * console.log(event.data.updates);
+ * }
+ * ```
*/
function isStatusReport(
event: UnifiedEvent,
@@ -43,7 +57,21 @@ function isStatusReport(
}
/**
- * Type guard to check if an event is a maintenance
+ * isMaintenance - Type guard for discriminating maintenance events
+ *
+ * Type guard function that narrows a UnifiedEvent to a maintenance event.
+ * Used internally by StatusFeed to distinguish between reports and maintenance.
+ *
+ * @param event - The unified event to check
+ * @returns True if the event is a maintenance
+ *
+ * @example
+ * ```tsx
+ * if (isMaintenance(event)) {
+ * // TypeScript knows event.data is Maintenance
+ * console.log(event.data.from, event.data.to);
+ * }
+ * ```
*/
function isMaintenance(
event: UnifiedEvent,
@@ -51,6 +79,93 @@ function isMaintenance(
return event.type === "maintenance";
}
+/**
+ * StatusFeed - Unified feed of incident reports and maintenance events
+ *
+ * Displays a chronological feed combining both status reports (incidents) and
+ * scheduled maintenance, sorted by date from newest to oldest. The component
+ * intelligently merges the two event types and renders them using a discriminated
+ * union pattern for type safety.
+ *
+ * **Key Features**:
+ * - **Unified Timeline**: Combines reports and maintenance in chronological order
+ * - **Discriminated Union**: Type-safe rendering using TypeScript discriminated unions
+ * - **Memoization**: Uses `useMemo` to prevent flicker on re-renders
+ * - **Empty State**: Shows a styled empty state when no events are present
+ * - **Automatic Rendering**: Each event type is rendered with appropriate components
+ *
+ * **Data Structure**:
+ * - **StatusReport**: Incident reports with updates timeline
+ * - id, title, affected services
+ * - updates array with status, message, date
+ * - **Maintenance**: Scheduled maintenance windows
+ * - id, title, message, affected services
+ * - from/to date range
+ *
+ * The component creates a unified event array internally, using stable keys
+ * (`${type}-${id}`) to prevent React flicker when data updates.
+ *
+ * @param statusReports - Array of incident reports to display
+ * @param maintenances - Array of maintenance events to display
+ *
+ * @example
+ * // Feed with both reports and maintenance
+ * ```tsx
+ * <StatusFeed
+ * statusReports={[
+ * {
+ * id: 1,
+ * title: "API Outage",
+ * affected: ["API", "Database"],
+ * updates: [
+ * {
+ * status: "resolved",
+ * message: "All systems operational",
+ * date: new Date("2024-01-15T12:00:00Z")
+ * },
+ * {
+ * status: "investigating",
+ * message: "Investigating API timeouts",
+ * date: new Date("2024-01-15T11:00:00Z")
+ * }
+ * ]
+ * }
+ * ]}
+ * maintenances={[
+ * {
+ * id: 2,
+ * title: "Database Upgrade",
+ * message: "Upgrading to PostgreSQL 15",
+ * affected: ["Database"],
+ * from: new Date("2024-01-20T02:00:00Z"),
+ * to: new Date("2024-01-20T04:00:00Z")
+ * }
+ * ]}
+ * />
+ * ```
+ *
+ * @example
+ * // Empty state (no events)
+ * ```tsx
+ * <StatusFeed statusReports={[]} maintenances={[]} />
+ * // Displays: "No recent notifications" empty state
+ * ```
+ *
+ * @example
+ * // Only incident reports
+ * ```tsx
+ * <StatusFeed
+ * statusReports={incidentReports}
+ * maintenances={[]}
+ * />
+ * ```
+ *
+ * @see StatusEventGroup - For the feed container
+ * @see StatusEventTimelineReport - For incident rendering
+ * @see StatusEventTimelineMaintenance - For maintenance rendering
+ * @see isStatusReport - For type guard discrimination
+ * @see isMaintenance - For type guard discrimination
+ */
export function StatusFeed({
statusReports = [],
maintenances = [],
diff --git a/packages/ui/src/components/blocks/status-layout.tsx b/packages/ui/src/components/blocks/status-layout.tsx
index 7c0e7718f..e3e6a5602 100644
--- a/packages/ui/src/components/blocks/status-layout.tsx
+++ b/packages/ui/src/components/blocks/status-layout.tsx
@@ -1,6 +1,36 @@
import { cn } from "@openstatus/ui/lib/utils";
import { StatusIcon as UnifiedStatusIcon } from "@openstatus/ui/components/blocks/status-icon";
+/**
+ * Status - Root container component for status page layouts
+ *
+ * This component serves as the primary container for status page content, providing
+ * consistent spacing and establishing the status type context via data attributes.
+ * The status type controls the visual appearance of child StatusIcon components
+ * through CSS data attribute selectors (group-data-[variant=...]).
+ *
+ * The component acts as both a CSS group and peer for advanced selector patterns,
+ * enabling child components to style themselves based on the parent's status.
+ *
+ * @param variant - The status type that determines the overall status indicator appearance
+ *
+ * @example
+ * ```tsx
+ * <Status variant="success">
+ * <StatusHeader>
+ * <StatusBrand src="/logo.png" alt="Company" />
+ * <StatusTitle>System Status</StatusTitle>
+ * </StatusHeader>
+ * <StatusContent>
+ * {// Status components here}
+ * </StatusContent>
+ * </Status>
+ * ```
+ *
+ * @see StatusHeader - For header content with brand and title
+ * @see StatusContent - For main status content area
+ * @see StatusIcon - For status indicator icons that respond to variant
+ */
export function Status({
children,
className,
@@ -21,6 +51,25 @@ export function Status({
);
}
+/**
+ * StatusBrand - Brand logo/image component for status page headers
+ *
+ * Displays a brand image (typically a company logo) with consistent sizing.
+ * The default size is 32x32px (size-8), suitable for header placement.
+ *
+ * @param src - Image source URL
+ * @param alt - Alternative text for the image (required for accessibility)
+ *
+ * @example
+ * ```tsx
+ * <StatusHeader>
+ * <StatusBrand src="/logo.png" alt="Company Name" />
+ * <StatusTitle>System Status</StatusTitle>
+ * </StatusHeader>
+ * ```
+ *
+ * @see StatusHeader - For positioning brand within header layout
+ */
export function StatusBrand({
src,
alt,
@@ -33,6 +82,33 @@ export function StatusBrand({
);
}
+/**
+ * StatusHeader - Header container for status page branding and title
+ *
+ * Provides a container-query context (@container/status-header) for responsive
+ * header layouts. Typically contains StatusBrand, StatusTitle, and StatusDescription
+ * components arranged in a flexible layout.
+ *
+ * The container query context enables child components to respond to the header's
+ * width rather than the viewport width, allowing for more modular layouts.
+ *
+ * @example
+ * ```tsx
+ * <StatusHeader>
+ * <div className="flex items-center gap-4">
+ * <StatusBrand src="/logo.png" alt="Company" />
+ * <div>
+ * <StatusTitle>System Status</StatusTitle>
+ * <StatusDescription>Current system health</StatusDescription>
+ * </div>
+ * </div>
+ * </StatusHeader>
+ * ```
+ *
+ * @see StatusBrand - For brand logo placement
+ * @see StatusTitle - For page title
+ * @see StatusDescription - For subtitle text
+ */
export function StatusHeader({
children,
className,
@@ -49,6 +125,25 @@ export function StatusHeader({
);
}
+/**
+ * StatusTitle - Primary heading for status page
+ *
+ * Displays the main title with consistent typography (semibold, large text, tight leading).
+ * Typically used within StatusHeader to show the page or organization name.
+ *
+ * The component uses semantic HTML div rather than h1 to allow flexible heading
+ * levels based on page context. Apply appropriate heading tags as needed.
+ *
+ * @example
+ * ```tsx
+ * <StatusHeader>
+ * <StatusTitle>Acme Inc. Status</StatusTitle>
+ * <StatusDescription>Live system status and uptime</StatusDescription>
+ * </StatusHeader>
+ * ```
+ *
+ * @see StatusDescription - For subtitle text below the title
+ */
export function StatusTitle({
children,
className,
@@ -67,6 +162,24 @@ export function StatusTitle({
);
}
+/**
+ * StatusDescription - Descriptive subtitle or secondary text
+ *
+ * Displays muted secondary text, typically used for subtitles, additional context,
+ * or descriptions. The text color is set to muted foreground for visual hierarchy.
+ *
+ * @example
+ * ```tsx
+ * <StatusHeader>
+ * <StatusTitle>System Status</StatusTitle>
+ * <StatusDescription>
+ * Real-time monitoring of all services
+ * </StatusDescription>
+ * </StatusHeader>
+ * ```
+ *
+ * @see StatusTitle - For primary heading text
+ */
export function StatusDescription({
children,
className,
@@ -76,6 +189,30 @@ export function StatusDescription({
);
}
+/**
+ * StatusContent - Main content area for status page components
+ *
+ * Provides a vertical flex container with consistent spacing (gap-3) for status
+ * page content. This is typically used to stack StatusComponent, StatusBanner,
+ * or other status-related components.
+ *
+ * @example
+ * ```tsx
+ * <Status variant="success">
+ * <StatusHeader>
+ * <StatusTitle>System Status</StatusTitle>
+ * </StatusHeader>
+ * <StatusContent>
+ * <StatusComponent variant="success">API</StatusComponent>
+ * <StatusComponent variant="success">Database</StatusComponent>
+ * <StatusComponent variant="degraded">CDN</StatusComponent>
+ * </StatusContent>
+ * </Status>
+ * ```
+ *
+ * @see Status - For root container
+ * @see StatusComponent - For individual service status displays
+ */
export function StatusContent({
children,
className,
@@ -83,6 +220,30 @@ export function StatusContent({
return <div className={cn("flex flex-col gap-3", className)}>{children}</div>;
}
+/**
+ * StatusIcon - Status indicator icon wrapper for Status component context
+ *
+ * This component wraps the unified StatusIcon with variant="default", configuring
+ * it to respond to the parent Status component's data-variant attribute.
+ * The displayed icon automatically changes based on the status type:
+ * - success: CheckIcon
+ * - degraded: TriangleAlertIcon
+ * - error: AlertCircleIcon
+ * - info: WrenchIcon
+ *
+ * @example
+ * ```tsx
+ * <Status variant="success">
+ * <StatusHeader>
+ * <StatusIcon />
+ * <StatusTitle>All Systems Operational</StatusTitle>
+ * </StatusHeader>
+ * </Status>
+ * ```
+ *
+ * @see Status - For setting the variant context
+ * @see StatusIcon from status-icon.tsx - For the underlying unified icon implementation
+ */
export function StatusIcon({
className,
...props
diff --git a/packages/ui/src/components/blocks/status-timestamp.tsx b/packages/ui/src/components/blocks/status-timestamp.tsx
index 1d40f1c49..87d4aee60 100644
--- a/packages/ui/src/components/blocks/status-timestamp.tsx
+++ b/packages/ui/src/components/blocks/status-timestamp.tsx
@@ -1,3 +1,5 @@
+"use client";
+
import { UTCDate } from "@date-fns/utc";
import { format, formatDistanceToNowStrict } from "date-fns";
import { Check, Copy } from "lucide-react";
@@ -42,6 +44,68 @@ type RichVariantProps = BaseProps &
type StatusTimestampProps = SimpleVariantProps | RichVariantProps;
+/**
+ * StatusTimestamp - Polymorphic timestamp display component with timezone support
+ *
+ * A flexible timestamp component that can display dates in two variants:
+ * - **simple**: Shows a tooltip on hover with the formatted date (default)
+ * - **rich**: Shows a hover card with local timezone, UTC, and relative time, plus copy-to-clipboard
+ *
+ * The component automatically detects the user's timezone using `Intl.DateTimeFormat()`
+ * and displays the date in both the local timezone and UTC. The rich variant includes
+ * a live-updating relative time display ("2 minutes ago") that refreshes every second
+ * while the hover card is open.
+ *
+ * Touch device support is built-in for the rich variant, toggling the hover card on tap
+ * instead of requiring hover.
+ *
+ * @param date - The date to display
+ * @param variant - Display style: "simple" for tooltip, "rich" for hover card with details
+ * @param side - (rich variant only) Placement of the hover card: "top" | "right" | "bottom" | "left"
+ * @param align - (rich variant only) Alignment of the hover card: "start" | "center" | "end"
+ * @param alignOffset - (rich variant only) Pixel offset for alignment (default: -4)
+ * @param sideOffset - (rich variant only) Pixel offset from the trigger
+ *
+ * @example
+ * // Simple variant with tooltip
+ * ```tsx
+ * <StatusTimestamp date={new Date()} />
+ * ```
+ *
+ * @example
+ * // Simple variant with custom children
+ * ```tsx
+ * <StatusTimestamp date={createdAt}>
+ * Created at
+ * </StatusTimestamp>
+ * ```
+ *
+ * @example
+ * // Rich variant with hover card showing timezone details
+ * ```tsx
+ * <StatusTimestamp
+ * date={new Date()}
+ * variant="rich"
+ * side="right"
+ * >
+ * 2 hours ago
+ * </StatusTimestamp>
+ * ```
+ *
+ * @example
+ * // Rich variant with custom positioning
+ * ```tsx
+ * <StatusTimestamp
+ * date={incidentDate}
+ * variant="rich"
+ * side="bottom"
+ * align="start"
+ * alignOffset={0}
+ * >
+ * {format(incidentDate, "MMM d, HH:mm")}
+ * </StatusTimestamp>
+ * ```
+ */
export function StatusTimestamp(props: StatusTimestampProps) {
const { date, variant = "simple", className, ...rest } = props;
@@ -84,6 +148,27 @@ export function StatusTimestamp(props: StatusTimestampProps) {
);
}
+/**
+ * SimpleTimestamp - Internal tooltip-based timestamp display
+ *
+ * Displays a formatted timestamp with an underlined, dashed decoration and shows
+ * the full formatted date in a tooltip on hover. The timestamp is shown in monospace
+ * font with muted foreground color.
+ *
+ * If no children are provided, displays the date in UTC format. If children are
+ * provided, they are used as the trigger text while the tooltip still shows the
+ * formatted date in the user's local timezone.
+ *
+ * @param date - The date to display
+ * @param children - Optional custom text to display (falls back to formatted UTC date)
+ *
+ * @example
+ * ```tsx
+ * <SimpleTimestamp date={new Date()}>
+ * 2 hours ago
+ * </SimpleTimestamp>
+ * ```
+ */
function SimpleTimestamp({
date,
className,
@@ -110,6 +195,41 @@ function SimpleTimestamp({
);
}
+/**
+ * RichTimestamp - Internal hover card timestamp display with timezone details
+ *
+ * Displays a hover card with comprehensive timestamp information:
+ * - Local timezone timestamp with timezone abbreviation (e.g., "PST", "EST")
+ * - UTC timestamp
+ * - Relative time ("2 hours ago") that updates every second while open
+ *
+ * Each row in the hover card is clickable to copy the value to clipboard, with
+ * a copy icon that appears on hover and changes to a check mark after copying.
+ *
+ * Touch device support: On touch devices (detected via `(hover: none)` media query),
+ * tapping toggles the hover card open/closed instead of requiring hover.
+ *
+ * The relative time automatically updates every second while the hover card is
+ * open, providing live feedback for recent timestamps.
+ *
+ * @param date - The date to display
+ * @param side - Placement of the hover card (default: "right")
+ * @param align - Alignment of the hover card (default: "start")
+ * @param alignOffset - Pixel offset for alignment (default: -4)
+ * @param sideOffset - Pixel offset from the trigger
+ * @param children - Custom trigger content
+ *
+ * @example
+ * ```tsx
+ * <RichTimestamp
+ * date={new Date()}
+ * side="bottom"
+ * align="center"
+ * >
+ * Click for details
+ * </RichTimestamp>
+ * ```
+ */
function RichTimestamp({
date,
side = "right",
@@ -168,6 +288,19 @@ function RichTimestamp({
);
}
+/**
+ * Row - Internal component for hover card timestamp rows
+ *
+ * Displays a single row in the rich timestamp hover card with a label (e.g., "UTC")
+ * and value (e.g., "Jan 15, 2024 10:30:45"). The entire row is clickable to copy
+ * the value to clipboard.
+ *
+ * The copy icon appears on hover and changes to a check mark after successful copy.
+ * A toast notification is shown when the value is copied.
+ *
+ * @param value - The timestamp string to display and copy
+ * @param label - The label for this timestamp (e.g., "UTC", "PST", "Relative")
+ */
function Row({ value, label }: { value: string; label: string }) {
const { copy, isCopied } = useCopyToClipboard();