@checkstack/maintenance-frontend 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @checkstack/maintenance-frontend
 
+## 0.7.0
+
+### Minor Changes
+
+- 1ef2e79: feat: hotlinks on incidents/maintenances and additional links on systems
+
+  Users with `manage` access on an incident, maintenance, or system can now
+  attach free-form URL "hotlinks" — Jira tickets, runbooks, dashboards, ticket
+  tools, etc. — alongside the existing fields.
+
+  - **Incidents** & **maintenances**: links live on the entity itself and are
+    surfaced both in the editor dialog and on the public detail page. Two new
+    RPC procedures per plugin (`addLink`, `removeLink`) gated behind the
+    existing `manage` access rule. Links are returned as part of
+    `getIncident` / `getMaintenance` and cache-invalidated on every link
+    mutation.
+  - **Systems**: a parallel `system_links` table with `getSystemLinks`,
+    `addSystemLink`, `removeSystemLink` procedures. Surfaced inside the
+    system editor (next to contacts) and on the read-only system detail
+    sidebar. Cache-scoped per-system so list endpoints remain hot.
+  - **Shared UI**: a `LinksEditor` component in `@checkstack/ui` does the
+    presentation; the three plugins each own their own RPC wiring.
+
+  Database changes ship as additive migrations (new `incident_links`,
+  `maintenance_links`, `system_links` tables, all FK-cascaded on parent
+  delete). No existing columns or rows are touched.
+
+  The system incident and maintenance history pages now sort by relevance:
+  active entries (non-`resolved` incidents, `scheduled` or `in_progress`
+  maintenances) appear at the top, with creation date descending as the
+  tiebreaker.
+
+- 3547670: Wire the new tips infrastructure across the frontends:
+
+  **Empty-state coaching.** Replace generic "no items" copy with onboarding
+  guidance — short description, three numbered steps and a primary CTA — on
+  every EmptyState that has a meaningful next action. Affects: catalog
+  (systems + groups), dashboard, health-check page, integrations (subscriptions
+
+  - provider connections), GitOps providers + secrets, GitOps provenance,
+    SLO config + overview, maintenance config, satellites, plugin manager,
+    incident config, announcements. Read-only EmptyStates (incident history,
+    maintenance history, plugin events) get clearer descriptions explaining
+    what would populate them.
+
+  **First-run anchored tips.** Add `<Tip>` popovers to the most important
+  "Create" affordances so first-time users see a one-line explanation of
+  what they're about to make and why it matters: catalog “Add System” /
+  “Add Group”, healthcheck “Create Check”, integrations “New Subscription”,
+  GitOps “Add Provider”, SLO “Create SLO”, maintenance “Create Maintenance”,
+  satellite “Create Satellite”, plugin-manager “Install plugin”, incident
+  “Report Incident”, announcement “New Announcement”. Each tip is dismissed
+  per user (server-backed when signed in, localStorage otherwise) and
+  namespaced through `qualifyTipId(plugin, …)` so it cannot escape the
+  plugin's own namespace.
+
+  **Welcome banner on the dashboard.** A `<TipBanner>` at the top of the
+  dashboard introduces Checkstack's main flow ("add a system, then a health
+  check") with a one-click jump into the catalog.
+
+### Patch Changes
+
+- 950d6ec: Fix mobile UserMenu items rendering at zero height, group menu items by
+  section, and unstack cramped card headers on small viewports.
+
+  - **UserMenu mobile bug**: On mobile, the user-menu Sheet rendered every
+    menu item as a grid row, which combined with `flex-shrink: 1` on each
+    item collapsed the buttons whose internal layout uses `display: flex`
+    (the items registered with `useNavigate` rather than `<Link>`) to zero
+    content height. Switched the mobile container to a flex column with
+    `[&>*]:shrink-0` and added `min-h-0` so the sheet scrolls correctly
+    when the list overflows.
+
+  - **UserMenu grouping**: Slot extensions now accept an optional `group`
+    field. The user menu buckets `UserMenuItemsSlot` extensions by `group`
+    and renders each group under a labeled header (`Workspace`,
+    `Reliability`, `Configuration`, `Documentation`, `Account`). Existing
+    core plugins are tagged with the appropriate group; third-party plugins
+    can pick any of these or supply their own label. Untagged extensions
+    render last with no header. `UserMenuItemsBottomSlot` is unaffected.
+
+  - **Card header responsiveness**: `CardHeaderRow` (the primitive shared by
+    Incident, Maintenance, Auth, Catalog, GitOps and other config cards) now
+    stacks vertically on narrow viewports and only switches to a single row
+    at the `sm` breakpoint, so titles and adjacent filter controls (e.g.
+    status `Select`, "Show resolved" checkbox) no longer cram together on
+    mobile. Refactored the Incident and Maintenance config pages to use the
+    primitive instead of a hand-rolled `flex items-center justify-between`
+    row, and made their `Select` triggers full-width on mobile.
+
+- Updated dependencies [42abfff]
+- Updated dependencies [3547670]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+- Updated dependencies [3547670]
+- Updated dependencies [3547670]
+- Updated dependencies [950d6ec]
+- Updated dependencies [3547670]
+- Updated dependencies [3547670]
+  - @checkstack/common@0.9.0
+  - @checkstack/ui@1.8.0
+  - @checkstack/maintenance-common@1.1.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/frontend-api@0.5.0
+  - @checkstack/notification-frontend@0.4.0
+  - @checkstack/tips-frontend@0.2.0
+  - @checkstack/auth-frontend@0.6.0
+  - @checkstack/dashboard-frontend@0.7.0
+  - @checkstack/notification-common@1.0.2
+  - @checkstack/signal-frontend@0.1.2
+
 ## 0.6.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-frontend",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
@@ -13,16 +13,17 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/auth-frontend": "0.5.32",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/common": "0.7.0",
-    "@checkstack/dashboard-frontend": "0.6.0",
-    "@checkstack/frontend-api": "0.4.1",
-    "@checkstack/maintenance-common": "1.0.0",
-    "@checkstack/notification-common": "1.0.0",
-    "@checkstack/notification-frontend": "0.3.0",
-    "@checkstack/signal-frontend": "0.1.0",
-    "@checkstack/ui": "1.7.0",
+    "@checkstack/auth-frontend": "0.5.33",
+    "@checkstack/catalog-common": "2.0.1",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/dashboard-frontend": "0.6.1",
+    "@checkstack/frontend-api": "0.4.2",
+    "@checkstack/maintenance-common": "1.0.1",
+    "@checkstack/notification-common": "1.0.1",
+    "@checkstack/notification-frontend": "0.3.1",
+    "@checkstack/signal-frontend": "0.1.1",
+    "@checkstack/tips-frontend": "0.1.0",
+    "@checkstack/ui": "1.7.1",
     "date-fns": "^4.1.0",
     "lucide-react": "^0.344.0",
     "react": "^18.2.0",
@@ -31,7 +32,7 @@
   "devDependencies": {
     "typescript": "^5.0.0",
     "@types/react": "^18.2.0",
-    "@checkstack/tsconfig": "0.0.6",
-    "@checkstack/scripts": "0.1.2"
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
   }
 }

package/src/components/MaintenanceEditor.tsx

@@ -21,6 +21,7 @@ import {
   useToast,
   DateTimePicker,
   StatusUpdateTimeline,
+  LinksEditor,
 } from "@checkstack/ui";
 import { Plus, MessageSquare, Loader2, AlertCircle } from "lucide-react";
 import { MaintenanceUpdateForm } from "./MaintenanceUpdateForm";
@@ -88,6 +89,24 @@ export const MaintenanceEditor: React.FC<Props> = ({
     },
   });
 
+  const addLinkMutation = maintenanceClient.addLink.useMutation({
+    onSuccess: () => {
+      void refetchDetail();
+    },
+    onError: (error) => {
+      toast.error(extractErrorMessage(error, "Failed to add link"));
+    },
+  });
+
+  const removeLinkMutation = maintenanceClient.removeLink.useMutation({
+    onSuccess: () => {
+      void refetchDetail();
+    },
+    onError: (error) => {
+      toast.error(extractErrorMessage(error, "Failed to remove link"));
+    },
+  });
+
   // Sync updates from query
   useEffect(() => {
     if (maintenanceDetail) {
@@ -351,6 +370,30 @@ export const MaintenanceEditor: React.FC<Props> = ({
             </div>
           )}
 
+          {/* Hotlinks (change tickets, runbooks, ...) — editing only */}
+          {maintenance && (
+            <div className="border-t pt-4">
+              <LinksEditor
+                title="Hotlinks"
+                description="Attach change tickets, runbooks, dashboards, or any URL relevant to this maintenance."
+                links={maintenanceDetail?.links ?? []}
+                busy={
+                  addLinkMutation.isPending || removeLinkMutation.isPending
+                }
+                onAdd={async ({ label, url }) => {
+                  await addLinkMutation.mutateAsync({
+                    maintenanceId: maintenance.id,
+                    label,
+                    url,
+                  });
+                }}
+                onRemove={async (link) => {
+                  await removeLinkMutation.mutateAsync({ id: link.id });
+                }}
+              />
+            </div>
+          )}
+
           {/* Team Access Editor - only shown when editing existing maintenance */}
           {maintenance?.id && (
             <TeamAccessEditor

package/src/index.tsx

@@ -45,6 +45,7 @@ export default createFrontendPlugin({
     createSlotExtension(UserMenuItemsSlot, {
       id: "maintenance.user-menu.items",
       component: MaintenanceMenuItems,
+      metadata: { group: "Reliability" },
     }),
     createSlotExtension(SystemStateBadgesSlot, {
       id: "maintenance.system-maintenance-badge",

package/src/pages/MaintenanceConfigPage.tsx

@@ -11,11 +11,16 @@ import type {
   MaintenanceWithSystems,
   MaintenanceStatus,
 } from "@checkstack/maintenance-common";
-import { maintenanceAccess } from "@checkstack/maintenance-common";
+import {
+  maintenanceAccess,
+  pluginMetadata as maintenancePluginMetadata,
+} from "@checkstack/maintenance-common";
+import { Tip } from "@checkstack/tips-frontend";
 import { CatalogApi } from "@checkstack/catalog-common";
 import {
   Card,
   CardHeader,
+  CardHeaderRow,
   CardTitle,
   CardContent,
   Button,
@@ -176,15 +181,24 @@ const MaintenanceConfigPageContent: React.FC = () => {
       loading={accessLoading}
       allowed={canManage}
       actions={
-        <Button onClick={handleCreate}>
-          <Plus className="h-4 w-4 mr-2" />
-          Create Maintenance
-        </Button>
+        <Tip
+          plugin={maintenancePluginMetadata}
+          id="windows.create"
+          title="Tell Checkstack about expected downtime"
+          description="Maintenance windows mark a period where you expect a system to be partially or fully unavailable. Checkstack uses them to suppress incidents, mark systems as “under maintenance” on the public status page, and (optionally) exclude the window from SLO error budgets."
+          side="bottom"
+          align="end"
+        >
+          <Button onClick={handleCreate}>
+            <Plus className="h-4 w-4 mr-2" />
+            Create Maintenance
+          </Button>
+        </Tip>
       }
     >
       <Card>
         <CardHeader className="border-b border-border">
-          <div className="flex items-center justify-between">
+          <CardHeaderRow>
             <div className="flex items-center gap-2">
               <Wrench className="h-5 w-5 text-muted-foreground" />
               <CardTitle>Maintenances</CardTitle>
@@ -195,7 +209,7 @@ const MaintenanceConfigPageContent: React.FC = () => {
                 setStatusFilter(v as MaintenanceStatus | "all")
               }
             >
-              <SelectTrigger className="w-40">
+              <SelectTrigger className="w-full sm:w-40">
                 <SelectValue placeholder="Filter by status" />
               </SelectTrigger>
               <SelectContent>
@@ -206,7 +220,7 @@ const MaintenanceConfigPageContent: React.FC = () => {
                 <SelectItem value="cancelled">Cancelled</SelectItem>
               </SelectContent>
             </Select>
-          </div>
+          </CardHeaderRow>
         </CardHeader>
         <CardContent className="p-0">
           {loading ? (
@@ -215,8 +229,22 @@ const MaintenanceConfigPageContent: React.FC = () => {
             </div>
           ) : maintenances.length === 0 ? (
             <EmptyState
-              title="No maintenances found"
-              description="Create your first planned maintenance to get started."
+              icon={<Wrench className="size-10" />}
+              title="No planned maintenances"
+              description="A maintenance window tells Checkstack “this system is expected to be down or degraded” for a defined period. Failed health checks during the window are still recorded but are treated as expected — the system is flagged as “in maintenance” on the public status page, and notifications about it are suppressed."
+              steps={[
+                "Click “Create Maintenance” and pick the systems that will be affected.",
+                "Set a start time, end time, and a short summary your users will see.",
+                "Subscribers (groups, status page subscribers, integrations) are notified automatically when the window starts and ends.",
+              ]}
+              actions={
+                canManage ? (
+                  <Button onClick={handleCreate}>
+                    <Plus className="h-4 w-4 mr-2" />
+                    Schedule maintenance
+                  </Button>
+                ) : undefined
+              }
             />
           ) : (
             <Table>

package/src/pages/MaintenanceDetailPage.tsx

@@ -41,6 +41,7 @@ import {
   Plus,
   MessageSquare,
   CheckCircle2,
+  ExternalLink,
 } from "lucide-react";
 import { format } from "date-fns";
 import { MaintenanceUpdateForm } from "../components/MaintenanceUpdateForm";
@@ -240,6 +241,28 @@ const MaintenanceDetailPageContent: React.FC = () => {
                 ))}
               </div>
             </div>
+
+            {maintenance.links.length > 0 && (
+              <div>
+                <h4 className="text-sm font-medium text-muted-foreground mb-2">
+                  Hotlinks
+                </h4>
+                <div className="flex flex-wrap gap-2">
+                  {maintenance.links.map((link) => (
+                    <a
+                      key={link.id}
+                      href={link.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="inline-flex items-center gap-1 rounded-md border px-2 py-1 text-xs text-primary hover:bg-muted"
+                    >
+                      <ExternalLink className="h-3 w-3" />
+                      <span>{link.label ?? link.url}</span>
+                    </a>
+                  ))}
+                </div>
+              </div>
+            )}
           </CardContent>
         </Card>
 

package/src/pages/SystemMaintenanceHistoryPage.tsx

@@ -43,7 +43,18 @@ const SystemMaintenanceHistoryPageContent: React.FC = () => {
   const { data: systemsData, isLoading: systemsLoading } =
     catalogClient.getSystems.useQuery({});
 
-  const maintenances = maintenancesData?.maintenances ?? [];
+  // Sort: active maintenances (scheduled / in_progress) first, then by
+  // creation date desc.
+  const maintenances = (maintenancesData?.maintenances ?? []).toSorted(
+    (a, b) => {
+      const aActive =
+        a.status === "scheduled" || a.status === "in_progress" ? 0 : 1;
+      const bActive =
+        b.status === "scheduled" || b.status === "in_progress" ? 0 : 1;
+      if (aActive !== bActive) return aActive - bActive;
+      return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+    },
+  );
   const systems = systemsData?.systems ?? [];
   const system = systems.find((s) => s.id === systemId);
   const systemName = system?.name ?? "Unknown System";
@@ -111,8 +122,8 @@ const SystemMaintenanceHistoryPageContent: React.FC = () => {
             </div>
           ) : maintenances.length === 0 ? (
             <EmptyState
-              title="No maintenances found"
-              description="There are no recorded maintenances for this system."
+              title="No maintenance history"
+              description="This system has never had a planned maintenance window. When one is scheduled (or completes), it will appear here so you can see how often this system is taken offline and for how long."
             />
           ) : (
             <Table>

package/tsconfig.json

@@ -31,6 +31,9 @@
     {
       "path": "../signal-frontend"
     },
+    {
+      "path": "../tips-frontend"
+    },
     {
       "path": "../ui"
     }