From 7ea9bc5a44a3849d31eae3f950ae0b6d6531d5bb Mon Sep 17 00:00:00 2001
From: Thibault Le Ouay <thibaultleouay@gmail.Com>
Date: Tue, 6 Oct 2026 12:24:38 +0200
Subject: [PATCH] dashboard: improve content (#2853)

* dashboard: improve content

* Apply batched suggestions from code review

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 .../(dashboard)/status-pages/[id]/sidebar.tsx | 13 +++-
 .../forms/status-page/form-configuration.tsx  | 75 +++++++++++--------
 .../concept/status-reports-and-incidents.mdx  |  6 +-
 .../concept/uptime-calculation-and-values.mdx | 42 ++++++-----
 .../guides/how-to-configure-status-page.mdx   | 20 ++---
 .../pages/docs/reference/page-components.mdx  |  6 +-
 .../pages/docs/reference/status-page.mdx      |  4 +-
 .../pages/docs/reference/status-report.mdx    |  6 +-
 8 files changed, 97 insertions(+), 75 deletions(-)

diff --git a/apps/dashboard/src/app/(dashboard)/status-pages/[id]/sidebar.tsx b/apps/dashboard/src/app/(dashboard)/status-pages/[id]/sidebar.tsx
index a3c6635e..27a0af52 100644
--- a/apps/dashboard/src/app/(dashboard)/status-pages/[id]/sidebar.tsx
+++ b/apps/dashboard/src/app/(dashboard)/status-pages/[id]/sidebar.tsx
@@ -13,6 +13,7 @@ import { useParams } from "next/navigation";
 
 import { Link } from "@/components/common/link";
 import { TableCellLink } from "@/components/data-table/table-cell-link";
+import { configurationLabels } from "@/components/forms/status-page/form-configuration";
 import { SidebarRight } from "@/components/nav/sidebar-right";
 import { getPageUrl } from "@/data/status-pages.client";
 import { useTRPC } from "@/lib/trpc/client";
@@ -92,12 +93,16 @@ export function Sidebar() {
               value: statusPage.configuration?.theme ?? "-",
             },
             {
-              label: "Bar Value",
-              value: statusPage.configuration?.type ?? "-",
+              label: "Status source",
+              value: statusPage.configuration?.type
+                ? configurationLabels.type[statusPage.configuration.type]
+                : "-",
             },
             {
-              label: "Card Value",
-              value: statusPage.configuration?.value ?? "-",
+              label: "Card shows",
+              value: statusPage.configuration?.value
+                ? configurationLabels.value[statusPage.configuration.value]
+                : "-",
             },
             {
               label: "Show Uptime",
diff --git a/apps/dashboard/src/components/forms/status-page/form-configuration.tsx b/apps/dashboard/src/components/forms/status-page/form-configuration.tsx
index 8bc361b5..bc2b303b 100644
--- a/apps/dashboard/src/components/forms/status-page/form-configuration.tsx
+++ b/apps/dashboard/src/components/forms/status-page/form-configuration.tsx
@@ -166,25 +166,21 @@ export function FormConfiguration({
                 name="configuration.type"
                 render={({ field }) => (
                   <FormItem>
-                    <FormLabel>Bar Type</FormLabel>
+                    <FormLabel>Status source</FormLabel>
                     <Select
                       onValueChange={field.onChange}
                       defaultValue={String(field.value) ?? "absolute"}
                       disabled={!hasMonitorComponents}
                     >
                       <FormControl>
-                        <SelectTrigger className="w-full capitalize">
-                          <SelectValue placeholder="Select a type" />
+                        <SelectTrigger className="w-full">
+                          <SelectValue placeholder="Select a source" />
                         </SelectTrigger>
                       </FormControl>
                       <SelectContent>
-                        {["absolute", "manual"].map((type) => (
-                          <SelectItem
-                            key={type}
-                            value={type}
-                            className="capitalize"
-                          >
-                            {type}
+                        {(["absolute", "manual"] as const).map((type) => (
+                          <SelectItem key={type} value={type}>
+                            {configurationLabels.type[type]}
                           </SelectItem>
                         ))}
                       </SelectContent>
@@ -198,7 +194,7 @@ export function FormConfiguration({
                 name="configuration.value"
                 render={({ field }) => (
                   <FormItem>
-                    <FormLabel>Card Value</FormLabel>
+                    <FormLabel>Card shows</FormLabel>
                     <Select
                       onValueChange={field.onChange}
                       defaultValue={String(field.value) ?? "duration"}
@@ -208,18 +204,20 @@ export function FormConfiguration({
                       }
                     >
                       <FormControl>
-                        <SelectTrigger className="w-full capitalize">
-                          <SelectValue placeholder="Select a type" />
+                        <SelectTrigger className="w-full">
+                          {watchConfigurationType === "manual" ? (
+                            <span className="text-muted-foreground">
+                              Not available for reports only
+                            </span>
+                          ) : (
+                            <SelectValue placeholder="Select a value" />
+                          )}
                         </SelectTrigger>
                       </FormControl>
                       <SelectContent>
-                        {["duration", "requests"].map((type) => (
-                          <SelectItem
-                            key={type}
-                            value={type}
-                            className="capitalize"
-                          >
-                            {type}
+                        {(["duration", "requests"] as const).map((value) => (
+                          <SelectItem key={value} value={value}>
+                            {configurationLabels.value[value]}
                           </SelectItem>
                         ))}
                       </SelectContent>
@@ -232,16 +230,17 @@ export function FormConfiguration({
                 {hasMonitorComponents ? (
                   <ul className="list-inside list-disc">
                     <li>
-                      <span>Bar Type </span>
+                      <span>Status source </span>
                       <span className="font-medium">
-                        {watchConfigurationType}
+                        {configurationLabels.type[watchConfigurationType]}
                       </span>
                       : <span>{message.type[watchConfigurationType]}</span>
                     </li>
                     <li>
-                      <span>Card Value </span>
+                      <span>Card shows </span>
                       <span className="font-medium">
-                        {watchConfigurationValue}
+                        {configurationLabels.value[watchConfigurationValue] ??
+                          configurationLabels.value.manual}
                       </span>
                       :{" "}
                       <span>
@@ -386,19 +385,31 @@ export function FormConfiguration({
   );
 }
 
-// TODO:
+// UI labels only - the stored enum values stay `absolute`/`manual` and
+// `duration`/`requests`/`manual` (DB, API and URL params).
+export const configurationLabels = {
+  type: {
+    absolute: "Monitor checks",
+    manual: "Reports only",
+  },
+  value: {
+    duration: "Time per status",
+    requests: "Number of checks",
+    manual: "Worst status of the day",
+  },
+} as const;
+
 const message = {
   type: {
+    absolute: "bars show your monitor's real results for each day.",
     manual:
-      "only shares the duration of reports and maintenances you are setting up - nothing else.",
-    absolute:
-      "shares the status of your endpoint for the duration of the different statuses.",
+      "bars only change when you post a status report or maintenance. Monitor results are hidden.",
   },
   value: {
-    duration: "shares the duration of the different statuses.",
-    requests:
-      "shares the number of requests received (success, degraded, error).",
-    default: "shares only the worse status of the day",
+    duration:
+      "cards show how long the monitor was operational, degraded or down.",
+    requests: "cards show how many checks succeeded, degraded or failed.",
+    default: "cards show only the worst status of the day.",
   },
   uptime: {
     true: "shares the uptime percentage and current status of your endpoint.",
diff --git a/apps/web/src/content/pages/docs/concept/status-reports-and-incidents.mdx b/apps/web/src/content/pages/docs/concept/status-reports-and-incidents.mdx
index bd8c07f7..ee1cdaa1 100644
--- a/apps/web/src/content/pages/docs/concept/status-reports-and-incidents.mdx
+++ b/apps/web/src/content/pages/docs/concept/status-reports-and-incidents.mdx
@@ -60,7 +60,7 @@ Each update can declare a per-component impact — `degraded_performance`, `part
 
 - A component's current impact is whatever the **latest update naming it** said. Components you omit from an update keep their previous impact — you only declare what changed.
 - Resolving the report sets every still-affected component back to `operational`, so the page clears deterministically.
-- On status pages using [manual uptime calculation](/docs/concept/uptime-calculation-and-values#manual-type), impacts also weight the uptime percentage: a major outage counts fully against uptime, a partial outage counts half, and degraded performance not at all.
+- On status pages using the [Reports only status source](/docs/concept/uptime-calculation-and-values#reports-only), impacts also weight the uptime percentage: a major outage counts fully against uptime, a partial outage counts half, and degraded performance not at all.
 
 The [Status report reference](/docs/reference/status-report) covers the exact impact semantics and weights.
 
@@ -76,7 +76,7 @@ A maintenance window is for disruption you know about **in advance** — a datab
 
 Two properties make it the right tool for planned work:
 
-- **It never counts against uptime.** Uptime is computed from raw check results (or report impacts in manual mode); a maintenance window only changes the displayed status.
+- **It never counts against uptime.** Uptime is computed from raw check results (or report impacts with the Reports only status source); a maintenance window only changes the displayed status.
 - **Subscribers can be notified when it's scheduled**, so the disruption is announced before it happens instead of explained after.
 
 If planned work goes sideways and overruns or breaks something, escalate: publish a status report. An unresolved report (or an active incident) takes display precedence over maintenance.
@@ -89,7 +89,7 @@ If planned work goes sideways and overruns or breaks something, escalate: publis
 | Scoped to | A monitor | A status page + components | A status page + components |
 | Audience | Your team | Your users | Your users |
 | Timing | When detection fires | During/after the event | Announced before the event |
-| Affects uptime | Yes — failed checks count | Only in manual mode, via impacts | Never |
+| Affects uptime | Yes — failed checks count | Only with Reports only status source, via impacts | Never |
 | Resolved by | Acknowledge/resolve, or auto-resolve | A `resolved` update | The window ending |
 
 On the status page itself, when several apply to one component, the worst wins: an active incident (error) outranks an unresolved status report (degraded), which outranks maintenance (info), which outranks operational.
diff --git a/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx
index 2ee44bc1..b31001cc 100644
--- a/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx
+++ b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx
@@ -1,7 +1,7 @@
 ---
 category: Concepts
 title: Uptime Calculation and Shared Values
-description: Understand how openstatus calculates uptime — absolute (duration or requests) and manual modes — and choose which values to share on your status page.
+description: Understand how openstatus calculates uptime — from monitor checks (time per status or number of checks) or from reports only — and choose which values to share on your status page.
 ---
 
 Uptime values can be a complete lie if they're not properly connected to monitoring. openstatus makes uptime transparent and configurable — you decide how it's calculated and which values to share on your status page.
@@ -12,28 +12,32 @@ When monitoring an endpoint, a check can end up in one of three states:
 - **Degraded** — slow or partially failing.
 - **Down** — no response or full failure.
 
-There are two top-level types of uptime calculation:
+In the dashboard, two settings on the status page's **Components** page control this:
 
-- **Absolute** (default) — derived directly from your monitoring data.
-    - **Duration** — aggregated from the incidents' duration.
-    - **Requests** (default) — aggregated from the request values.
-- **Manual** — for teams that prefer full control over what's shown.
+- **Status source** — where the status comes from:
+    - **Monitor checks** (default) — derived directly from your monitoring data.
+    - **Reports only** — only from the status reports and maintenances you publish.
+- **Card shows** — what the hover card (and uptime) is based on, when the source is **Monitor checks**:
+    - **Time per status** — aggregated from the incidents' duration.
+    - **Number of checks** (default) — aggregated from every check result.
+
+> **API and URL values:** in the API, SDKs and configuration links, **Monitor checks** is `type: absolute`, **Reports only** is `type: manual`, **Time per status** is `value: duration` and **Number of checks** is `value: requests`.
 
 **TL;DR**
 
-| Type        | Source of truth      | What users see                      | Best for                        |
+| Setting        | Source of truth      | What users see                      | Best for                        |
 |-------------|----------------------|-------------------------------------|----------------------------------|
-| **Duration** (absolute) | Incident duration    | Time-based uptime, proportional colours | Accurate long-term view         |
-| **Request** (absolute)  | Every ping result    | Request-based uptime %              | Real-time reflection            |
-| **Manual**   | Manually set status  | Controlled, narrative updates       | Transparency without monitoring |
+| **Monitor checks** + **Time per status** | Incident duration    | Time-based uptime, proportional colours | Accurate long-term view         |
+| **Monitor checks** + **Number of checks** | Every check result    | Check-based uptime %              | Real-time reflection            |
+| **Reports only**   | Your status reports and maintenances  | Controlled, narrative updates       | Transparency without monitoring |
 
-## Absolute type
+## Monitor checks
 
-The absolute type calculates uptime based on actual monitoring results. It's the most accurate reflection of what's really happening, and comes in two variants: _duration_ and _request_. Both share real data with your users — incidents, degraded states, and historical uptime — but they differ in how they aggregate and display that data.
+With **Monitor checks** as the status source (`absolute`), uptime is calculated from actual monitoring results. It's the most accurate reflection of what's really happening, and comes in two variants: _time per status_ and _number of checks_. Both share real data with your users — incidents, degraded states, and historical uptime — but they differ in how they aggregate and display that data.
 
-### Duration
+### Time per status
 
-The duration value is calculated from the **total monitoring time and the duration of incidents**.
+The time per status value (`duration`) is calculated from the **total monitoring time and the duration of incidents**.
 
 In simple terms: `uptime = (total time - incident duration) / total time`
 
@@ -43,19 +47,19 @@ Temporary single-region ping failures (e.g., one location failing once, sometime
 
 The proportional colours in the status bar are drawn from these duration values. Hovering over a day shows both incidents and status reports, so users can explore what happened.
 
-### Request
+### Number of checks
 
-The request value is more straightforward — it looks at each ping result individually. **Every check we run contributes to your uptime score**.
+The number of checks value (`requests`) is more straightforward — it looks at each ping result individually. **Every check we run contributes to your uptime score**.
 
 In simple terms: `uptime = (success + degraded) / total requests`
 
 This is the current default mode for most openstatus users. It's simple, data-driven, and updates immediately as new results come in.
 
-Like with duration, hover cards display incidents and status reports, giving your users a quick overview of recent events.
+Like with time per status, hover cards display incidents and status reports, giving your users a quick overview of recent events.
 
-## Manual type
+## Reports only
 
-The manual type is for teams who want to **fully control what's shown** on your status page, without relying on automatic checks. By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes — independent of any monitoring data.
+The **Reports only** status source (`manual`) is for teams who want to **fully control what's shown** on your status page, without relying on automatic checks. By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes — independent of any monitoring data.
 
 This is ideal if:
 
diff --git a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
index 56b8dccf..deafeabd 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
@@ -48,37 +48,39 @@ The **Components Configuration** card, on the **Components** page, controls two
 
 These settings only apply to **monitor components** — the fields are disabled until your status page has at least one.
 
-**Bar type** — how every day is displayed in a status tracker. Either **absolute** or **manual**.
+**Status source** — where the bars get their status from:
+- **Monitor checks** — bars show your monitor's real results for each day.
+- **Reports only** — bars only change when you post a status report or maintenance. Monitor results are hidden.
 
-**Card value** — only configurable if the bar type is **absolute**. Choose between **duration**, which shows the duration of "success", "error", "degraded", or "maintenance" reports, or **requests**, which shares the number of request statuses themselves. If **manual** bar type is chosen, only the most significant status of the day is shown.
+**Card shows** — only configurable if the status source is **Monitor checks**. Choose between **Time per status**, which shows how long the monitor was operational, degraded, down or in maintenance, or **Number of checks**, which shows how many checks succeeded, degraded or failed. With **Reports only**, the card shows only the worst status of the day.
 
 #### Uptime and history
 
-**Show uptime** — uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (including incidents). If you've chosen **manual**, it's calculated only from the duration of your status reports.
+**Show uptime** — with **Monitor checks**, uptime is calculated from either the **time per status** _or_ the **number of checks**, depending on what you've chosen for **Card shows** (including incidents). With **Reports only**, it's calculated only from the duration of your status reports.
 
 **History** — the number of days of history rendered on the bars. Choose between **30** or **45** days (defaults to **45**).
 
 A few examples to understand it:
 
-Example of **absolute bar** with **duration card** and **showing uptime**
+Example of **Monitor checks** with **Time per status** and **showing uptime**
 
 <Image
     src="/docs/tutorial/configure-status-page/status-page-beta-3.png"
-    alt="absolute bar type with duration card and showing uptime"
+    alt="monitor checks with time per status and showing uptime"
 />
 
-Example of **absolute bar** with **request card** and **hiding uptime**
+Example of **Monitor checks** with **Number of checks** and **hiding uptime**
 
 <Image
     src="/docs/tutorial/configure-status-page/status-page-beta-4.png"
-    alt="absolute bar type with request card and hiding uptime"
+    alt="monitor checks with number of checks and hiding uptime"
 />
 
-Example of **manual bar** with **simple card** and **hiding uptime**
+Example of **Reports only** and **hiding uptime**
 
 <Image
     src="/docs/tutorial/configure-status-page/status-page-beta-2.png"
-    alt="manual bar type and hiding uptime"
+    alt="reports only and hiding uptime"
 />
 
 ### 2. Appearance
diff --git a/apps/web/src/content/pages/docs/reference/page-components.mdx b/apps/web/src/content/pages/docs/reference/page-components.mdx
index 571a992f..9ad99ecb 100644
--- a/apps/web/src/content/pages/docs/reference/page-components.mdx
+++ b/apps/web/src/content/pages/docs/reference/page-components.mdx
@@ -50,9 +50,9 @@ The component reflects the current operational state of your monitor. If the mon
 
 **Historical data visualization:**
 Monitor components display historical uptime data through status trackers. Depending on your [tracker configuration](/docs/guides/how-to-configure-status-page#1-components-configuration), you can show:
-- **Absolute bar with duration card**: Shows the time spent in each status (success, error, degraded, maintenance).
-- **Absolute bar with request card**: Shows the number of successful vs. failed requests.
-- **Manual bar**: Shows only the most significant status of each day.
+- **Monitor checks with Time per status**: Shows the time spent in each status (success, error, degraded, maintenance).
+- **Monitor checks with Number of checks**: Shows the number of successful, degraded, and failed checks.
+- **Reports only**: Shows only the most significant status of each day, based on your status reports and maintenances.
 
 **Uptime calculations:**
 Monitor components calculate uptime percentages based on:
diff --git a/apps/web/src/content/pages/docs/reference/status-page.mdx b/apps/web/src/content/pages/docs/reference/status-page.mdx
index 90ed5034..e86be93b 100644
--- a/apps/web/src/content/pages/docs/reference/status-page.mdx
+++ b/apps/web/src/content/pages/docs/reference/status-page.mdx
@@ -169,8 +169,8 @@ the **Components** page in the dashboard; see
 
 | Field | Values | Default | Description |
 |---|---|---|---|
-| `type` | `absolute`, `manual` | `absolute` | Bar type. `absolute` draws each day proportionally; `manual` shows only the most significant status of the day. |
-| `value` | `duration`, `requests`, `manual` | `requests` | What the hover card and uptime percentage are derived from. Only meaningful when `type` is `absolute`. |
+| `type` | `absolute`, `manual` | `absolute` | **Status source** in the dashboard. `absolute` (**Monitor checks**) draws each day proportionally from monitor results; `manual` (**Reports only**) uses only status reports and maintenances and shows the most significant status of the day. |
+| `value` | `duration`, `requests`, `manual` | `requests` | **Card shows** in the dashboard: `duration` (**Time per status**) or `requests` (**Number of checks**). What the hover card and uptime percentage are derived from. Only meaningful when `type` is `absolute`. |
 | `uptime` | boolean | `true` | Whether the uptime percentage is shown at all. |
 | `days` | `30`, `45` | `45` | Number of days of history rendered on the bars. |
 
diff --git a/apps/web/src/content/pages/docs/reference/status-report.mdx b/apps/web/src/content/pages/docs/reference/status-report.mdx
index 694ee8e6..789792a5 100644
--- a/apps/web/src/content/pages/docs/reference/status-report.mdx
+++ b/apps/web/src/content/pages/docs/reference/status-report.mdx
@@ -72,7 +72,7 @@ All attached components must belong to the same status page. Adding a component
 
 ## Component impacts
 
-Beyond marking a component as affected, each update of a status report can declare **how badly** each component is affected. This per-component impact drives the component's live status, the report's overall indicator, and — for status pages using manual uptime — the uptime percentage.
+Beyond marking a component as affected, each update of a status report can declare **how badly** each component is affected. This per-component impact drives the component's live status, the report's overall indicator, and the uptime percentage. Reports only uses these impacts as its uptime source, while Monitor checks with **Time per status** also includes report intervals alongside monitor downtime.
 
 ### Impact levels
 
@@ -107,7 +107,7 @@ After update 2, the API shows _partial outage_ (latest update naming it) and the
 
 - **Component status:** `major_outage` renders the component and its status bar red; `degraded_performance` and `partial_outage` render orange; `operational` renders green.
 - **Report indicator:** the report's overall state is derived from the **worst** active component impact — it is not stored separately.
-- **Manual uptime:** on status pages using [manual uptime calculation](/docs/concept/uptime-calculation-and-values#manual-type), each interval between updates counts against uptime weighted by its impact:
+- **Reports only uptime:** on status pages using the [Reports only status source](/docs/concept/uptime-calculation-and-values#reports-only), each interval between updates counts against uptime weighted by its impact:
 
 | Impact | Downtime weight |
 |--------|-----------------|
@@ -117,7 +117,7 @@ After update 2, the API shows _partial outage_ (latest update naming it) and the
 | `major_outage` | 1 — full downtime |
 
 <Aside>
-Status reports created before component impacts existed (or via API clients that don't send impacts) have no impact rows. They keep the previous behavior: the affected components render orange and, in manual mode, the report's full duration counts as downtime.
+Status reports created before component impacts existed (or via API clients that don't send impacts) have no impact rows. They keep the previous behavior: the affected components render orange and, with the Reports only status source, the report's full duration counts as downtime.
 </Aside>
 
 ## Related resources
-- 
2.51.2