feat(dashboard): render text widget markdown content in dashboard view (#624)

## Summary

- Add `TextResult` data type and render text widget markdown content in
`dashboard view` instead of showing an "unsupported" placeholder
- Text widgets don't query any API — their content lives in
`widget.description`, so we intercept them early and return a
`TextResult` directly
- Markdown is rendered via the existing `renderMarkdown()` pipeline,
width-constrained with `wrap-ansi` to fit inside the widget box
- Empty/whitespace-only content shows an `(empty)` placeholder

## Changes

| File | Change |
|------|--------|
| `src/types/dashboard.ts` | Add `TextResult` type, update
`WidgetDataResult` union |
| `src/lib/api/dashboards.ts` | Early return for text widgets in
`queryWidgetData` (no API call) |
| `src/commands/dashboard/view.ts` | Pass `description` through
`buildViewData` for JSON output |
| `src/lib/formatters/dashboard.ts` | Add `renderTextContent()`, `text`
case in renderer, `description` field on view type |
| `test/lib/formatters/dashboard.test.ts` | Text widget rendering tests
(content, empty, whitespace) |
| `test/types/dashboard.test.ts` | `TextResult` type conformance tests |

Author: BYK

src/commands/dashboard/view.ts

@@ -113,6 +113,9 @@ function buildViewData(
       title: w.title,
       displayType: w.displayType,
       widgetType: w.widgetType,
+      description: (w as Record<string, unknown>).description as
+        | string
+        | undefined,
       layout: w.layout,
       queries: w.queries,
       data: widgetResults.get(i) ?? {

src/lib/api/dashboards.ts

@@ -20,6 +20,7 @@ import {
   type ScalarResult,
   TABLE_DISPLAY_TYPES,
   type TableResult,
+  type TextResult,
   TIMESERIES_DISPLAY_TYPES,
   type TimeseriesResult,
   type WidgetDataResult,
@@ -442,6 +443,16 @@ async function queryWidgetData(
   params: WidgetQueryParams
 ): Promise<WidgetDataResult> {
   const { widget } = params;
+
+  // Text widgets carry markdown in `description`, no API query needed
+  if (widget.displayType === "text") {
+    const description = (widget as Record<string, unknown>).description;
+    return {
+      type: "text",
+      content: typeof description === "string" ? description : "",
+    } satisfies TextResult;
+  }
+
   const dataset = mapWidgetTypeToDataset(widget.widgetType);
   if (!dataset) {
     return {

src/lib/formatters/dashboard.ts

@@ -10,6 +10,7 @@
 
 import chalk from "chalk";
 import stringWidth from "string-width";
+import wrapAnsi from "wrap-ansi";
 
 import type {
   DashboardWidgetQuery,
@@ -19,6 +20,7 @@ import type {
   WidgetDataResult,
 } from "../../types/dashboard.js";
 import { COLORS, muted, terminalLink } from "./colors.js";
+import { renderMarkdown } from "./markdown.js";
 
 import type { HumanRenderer } from "./output.js";
 import { isPlainOutput } from "./plain-detect.js";
@@ -45,6 +47,8 @@ export type DashboardViewWidget = {
   title: string;
   displayType: string;
   widgetType?: string;
+  /** Markdown content for text widgets (from API passthrough field) */
+  description?: string;
   layout?: { x: number; y: number; w: number; h: number };
   queries?: DashboardWidgetQuery[];
   data: WidgetDataResult;
@@ -1537,6 +1541,26 @@ function buildTimeAxis(opts: {
   return [plain ? axisStr : muted(axisStr), plain ? labelStr : muted(labelStr)];
 }
 
+/**
+ * Render text widget markdown content as terminal lines.
+ *
+ * Pipeline: markdown → renderMarkdown() (ANSI-styled) → wrap-ansi
+ * (width-constrained) → split into lines. Empty/missing content renders
+ * as a muted placeholder.
+ */
+function renderTextContent(content: string, innerWidth: number): string[] {
+  if (!content.trim()) {
+    return [isPlainOutput() ? "(empty)" : muted("(empty)")];
+  }
+
+  const rendered = renderMarkdown(content);
+  const wrapped = wrapAnsi(rendered, innerWidth, {
+    hard: true,
+    trim: false,
+  });
+  return wrapped.split("\n");
+}
+
 /** Render placeholder content for unsupported/error widgets (no title/border). */
 function renderPlaceholderContent(message: string): string[] {
   return [isPlainOutput() ? `(${message})` : muted(`(${message})`)];
@@ -1573,6 +1597,9 @@ function renderContentLines(opts: {
     case "scalar":
       return renderBigNumberContent(data, { innerWidth, contentHeight });
 
+    case "text":
+      return renderTextContent(data.content, innerWidth);
+
     case "unsupported":
       return renderPlaceholderContent(data.reason);
 

src/types/dashboard.ts

@@ -922,6 +922,12 @@ export type ScalarResult = {
   unit?: string | null;
 };
 
+/** Markdown text content for text widgets (no API query — content from widget.description) */
+export type TextResult = {
+  type: "text";
+  content: string;
+};
+
 /** Widget type not supported for data fetching */
 export type UnsupportedResult = {
   type: "unsupported";
@@ -941,13 +947,15 @@ export type ErrorResult = {
  * - `timeseries` → sparkline charts
  * - `table` → text table
  * - `scalar` → big number display
+ * - `text` → rendered markdown content
  * - `unsupported` → placeholder message
  * - `error` → error message
  */
 export type WidgetDataResult =
   | TimeseriesResult
   | TableResult
   | ScalarResult
+  | TextResult
   | UnsupportedResult
   | ErrorResult;
 

test/lib/api/dashboards.test.ts

@@ -1,16 +1,20 @@
 /**
  * Dashboard API helper tests
  *
- * Tests for periodToSeconds and computeOptimalInterval from
- * src/lib/api/dashboards.ts.
+ * Tests for periodToSeconds, computeOptimalInterval, and queryAllWidgets
+ * from src/lib/api/dashboards.ts.
  */
 
 import { describe, expect, test } from "bun:test";
 import {
   computeOptimalInterval,
   periodToSeconds,
+  queryAllWidgets,
 } from "../../../src/lib/api/dashboards.js";
-import type { DashboardWidget } from "../../../src/types/dashboard.js";
+import type {
+  DashboardDetail,
+  DashboardWidget,
+} from "../../../src/types/dashboard.js";
 
 // ---------------------------------------------------------------------------
 // periodToSeconds
@@ -138,3 +142,73 @@ describe("computeOptimalInterval", () => {
     expect(result).toBe("1m");
   });
 });
+
+// ---------------------------------------------------------------------------
+// queryAllWidgets — text widget handling
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal DashboardDetail with the given widgets.
+ *
+ * Text widgets carry markdown in `description` (a passthrough field not in
+ * the typed schema), so widgets are cast via `as any`.
+ */
+function makeDashboard(widgets: Record<string, unknown>[]): DashboardDetail {
+  return { id: "1", title: "Test Dashboard", widgets } as DashboardDetail;
+}
+
+describe("queryAllWidgets", () => {
+  // Text widgets return immediately — no API call, no mocking needed.
+  // regionUrl and orgSlug are unused for text widgets.
+  const UNUSED_URL = "https://unused.example.com";
+  const UNUSED_ORG = "unused-org";
+
+  test("returns TextResult for text widget with description", async () => {
+    const dashboard = makeDashboard([
+      { title: "Notes", displayType: "text", description: "# Hello\n**bold**" },
+    ]);
+
+    const results = await queryAllWidgets(UNUSED_URL, UNUSED_ORG, dashboard);
+
+    expect(results.size).toBe(1);
+    expect(results.get(0)).toEqual({
+      type: "text",
+      content: "# Hello\n**bold**",
+    });
+  });
+
+  test("returns TextResult with empty content when description is missing", async () => {
+    const dashboard = makeDashboard([
+      { title: "Empty Notes", displayType: "text" },
+    ]);
+
+    const results = await queryAllWidgets(UNUSED_URL, UNUSED_ORG, dashboard);
+
+    expect(results.get(0)).toEqual({ type: "text", content: "" });
+  });
+
+  test("returns TextResult with empty content for non-string description", async () => {
+    const dashboard = makeDashboard([
+      { title: "Bad Description", displayType: "text", description: 42 },
+    ]);
+
+    const results = await queryAllWidgets(UNUSED_URL, UNUSED_ORG, dashboard);
+
+    expect(results.get(0)).toEqual({ type: "text", content: "" });
+  });
+
+  test("handles multiple text widgets in a single dashboard", async () => {
+    const dashboard = makeDashboard([
+      { title: "Notes 1", displayType: "text", description: "First" },
+      { title: "Notes 2", displayType: "text", description: "Second" },
+      { title: "Notes 3", displayType: "text", description: "Third" },
+    ]);
+
+    const results = await queryAllWidgets(UNUSED_URL, UNUSED_ORG, dashboard);
+
+    expect(results.size).toBe(3);
+    expect(results.get(0)).toEqual({ type: "text", content: "First" });
+    expect(results.get(1)).toEqual({ type: "text", content: "Second" });
+    expect(results.get(2)).toEqual({ type: "text", content: "Third" });
+  });
+});

test/lib/formatters/dashboard.test.ts

@@ -33,6 +33,7 @@ import type {
   ErrorResult,
   ScalarResult,
   TableResult,
+  TextResult,
   TimeseriesResult,
   UnsupportedResult,
 } from "../../../src/types/dashboard.js";
@@ -184,6 +185,14 @@ function makeScalarData(overrides: Partial<ScalarResult> = {}): ScalarResult {
   };
 }
 
+function makeTextData(overrides: Partial<TextResult> = {}): TextResult {
+  return {
+    type: "text",
+    content: "# Notes\nSome **important** text here.",
+    ...overrides,
+  };
+}
+
 function makeUnsupportedData(
   overrides: Partial<UnsupportedResult> = {}
 ): UnsupportedResult {
@@ -1036,6 +1045,55 @@ describe("formatDashboardWithData", () => {
     });
   });
 
+  describe("text widget", () => {
+    test("renders markdown content", () => {
+      const data = makeDashboardData({
+        widgets: [
+          makeWidget({
+            title: "Notes",
+            displayType: "text",
+            data: makeTextData({
+              content: "# Hello\nSome **bold** text",
+            }),
+          }),
+        ],
+      });
+      const output = formatDashboardWithData(data);
+      expect(output).toContain("Notes");
+      expect(output).toContain("Hello");
+      expect(output).toContain("bold");
+    });
+
+    test("renders empty placeholder for missing content", () => {
+      const data = makeDashboardData({
+        widgets: [
+          makeWidget({
+            title: "Empty Notes",
+            displayType: "text",
+            data: makeTextData({ content: "" }),
+          }),
+        ],
+      });
+      const output = formatDashboardWithData(data);
+      expect(output).toContain("Empty Notes");
+      expect(output).toContain("(empty)");
+    });
+
+    test("renders empty placeholder for whitespace-only content", () => {
+      const data = makeDashboardData({
+        widgets: [
+          makeWidget({
+            title: "Whitespace Notes",
+            displayType: "text",
+            data: makeTextData({ content: "   \n  " }),
+          }),
+        ],
+      });
+      const output = formatDashboardWithData(data);
+      expect(output).toContain("(empty)");
+    });
+  });
+
   describe("mixed widget types (no layout — sequential blocks)", () => {
     test("renders all widget types in order", () => {
       const widgets: DashboardViewWidget[] = [

test/types/dashboard.test.ts

@@ -31,9 +31,11 @@ import {
   SpanAggregateFunctionSchema,
   stripWidgetServerFields,
   TABLE_DISPLAY_TYPES,
+  type TextResult,
   TIMESERIES_DISPLAY_TYPES,
   validateWidgetLayout,
   WIDGET_TYPES,
+  type WidgetDataResult,
   type WidgetType,
 } from "../../src/types/dashboard.js";
 
@@ -879,3 +881,29 @@ describe("display type sets", () => {
     expect(TABLE_DISPLAY_TYPES.has("line")).toBe(false);
   });
 });
+
+describe("TextResult", () => {
+  test("satisfies WidgetDataResult discriminated union", () => {
+    const result: WidgetDataResult = {
+      type: "text",
+      content: "# Hello",
+    } satisfies TextResult;
+    expect(result.type).toBe("text");
+  });
+
+  test("is included in WidgetDataResult union", () => {
+    const results: WidgetDataResult[] = [
+      { type: "timeseries", series: [] },
+      { type: "table", columns: [], rows: [] },
+      { type: "scalar", value: 42 },
+      { type: "text", content: "some markdown" },
+      { type: "unsupported", reason: "not supported" },
+      { type: "error", message: "failed" },
+    ];
+    const textResult = results.find((r) => r.type === "text");
+    expect(textResult).toBeDefined();
+    if (textResult?.type === "text") {
+      expect(textResult.content).toBe("some markdown");
+    }
+  });
+});