@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/components/ListFooter.tsx

@@ -1,5 +1,7 @@
 import { FOCUS_RING } from "../lib/focus-ring.js"
+import { cn } from "../lib/utils.js"
 import { useToolkitLocale, useToolkitMessages } from "../locale/locale-provider.js"
+import type { ListFooterMessages } from "../locale/message-types.js"
 import { formatCount } from "../locale/toolkit-messages.js"
 
 export interface ListFooterProps {
@@ -15,14 +17,40 @@ export interface ListFooterProps {
   onLoadMore: () => void
   /** Plural noun for the count, e.g. `"instances"`. Default: the locale's word for rows. */
   noun?: string
+  /**
+   * A new first page is in flight while these rows stay on screen (a search,
+   * a filter, a refetch): the status line adds a visible "Updating…".
+   */
+  refreshing?: boolean
+  /**
+   * The rows on screen are the PREVIOUS result (a changed search or filter is
+   * in flight or failed): the count and "Load more" hide, so the old count
+   * never reads as the new search's answer.
+   */
+  stale?: boolean
+  /** Override strings of the active catalog's `listFooter` section. */
+  labels?: Partial<ListFooterMessages>
+  /**
+   * Make the count line a polite live region (`role="status"`). Default
+   * `true`. Set `false` only where the caller already announces the count in
+   * a live region of its own, so a screen reader hears it once.
+   */
+  announce?: boolean
+  className?: string
 }
 
 /**
  * Footer for a paginated list: an honest "Showing X of Y" total plus an
  * explicit "Load more" control. Deliberately not infinite scroll — the user
- * gets the total, a reachable footer, and control over fetching. Renders
- * nothing when `total` is 0. Text and number format follow the active locale
- * (`LocaleProvider`, else the host's inside `McpAppView`).
+ * gets the total, a reachable footer, and control over fetching. The count
+ * is a polite live region (`role="status"`), so a keyboard or screen-reader
+ * user hears the new total after "Load more" or a filter change; while a
+ * first page is in flight it also says "Updating…". With nothing to count and
+ * nothing in flight it shows nothing, but the live region stays mounted
+ * (visually hidden) and says "No entries": a search that finds nothing is
+ * announced too, and the region is never re-created with its news already in
+ * it (a screen reader stays silent then). Text and number format follow the
+ * active locale (`LocaleProvider`, else the host's inside `McpAppView`).
  */
 export function ListFooter({
   shown,
@@ -31,20 +59,40 @@ export function ListFooter({
   loadingMore = false,
   onLoadMore,
   noun,
+  refreshing = false,
+  stale = false,
+  labels,
+  announce = true,
+  className,
 }: ListFooterProps) {
-  const locale = useToolkitLocale()
-  const { listFooter } = useToolkitMessages()
-  if (total <= 0) return null
+  const listFooter = { ...useToolkitMessages().listFooter, ...labels }
+  const counted = total > 0 && !stale
+  const visible = counted || refreshing
+  // Without a live region of its own there is nothing to keep mounted.
+  if (!visible && !announce) return null
   return (
-    <div className="text-muted-foreground flex items-center justify-between gap-3 px-1 py-2 text-xs">
-      <span>
-        {listFooter.showing({
-          shown: formatCount(shown, locale),
-          total: formatCount(total, locale),
-          noun: noun ?? listFooter.defaultNoun,
-        })}
-      </span>
-      {hasMore && (
+    <div
+      data-slot="list-footer"
+      // The same element tree in both states, so React keeps the live region.
+      className={visible ? cn(FOOTER_CLASS, className) : "sr-only"}
+    >
+      <p
+        role={announce ? "status" : undefined}
+        data-slot="list-footer-status"
+        className="flex flex-wrap items-center gap-x-2"
+      >
+        <StatusLine
+          messages={listFooter}
+          shown={shown}
+          total={total}
+          noun={noun}
+          counted={counted}
+          refreshing={refreshing}
+          // Zero rows, not a stale previous result (its failure the caller reports).
+          empty={!visible && !stale}
+        />
+      </p>
+      {counted && hasMore && (
         <button
           type="button"
           onClick={onLoadMore}
@@ -57,3 +105,42 @@ export function ListFooter({
     </div>
   )
 }
+
+const FOOTER_CLASS =
+  "text-small text-muted-foreground flex items-center justify-between gap-3 px-1 py-2"
+
+/** What the live region says: the count, "Updating…", or "No entries" at zero rows. */
+function StatusLine({
+  messages,
+  shown,
+  total,
+  noun,
+  counted,
+  refreshing,
+  empty,
+}: {
+  messages: ListFooterMessages
+  shown: number
+  total: number
+  noun: string | undefined
+  counted: boolean
+  refreshing: boolean
+  empty: boolean
+}) {
+  const locale = useToolkitLocale()
+  return (
+    <>
+      {empty && <span>{messages.noResults}</span>}
+      {counted && (
+        <span>
+          {messages.showing({
+            shown: formatCount(shown, locale),
+            total: formatCount(total, locale),
+            noun: noun ?? messages.defaultNoun,
+          })}
+        </span>
+      )}
+      {refreshing && <span data-slot="list-footer-updating">{messages.updating}</span>}
+    </>
+  )
+}

package/src/components/PagedListFooter.test.tsx

@@ -0,0 +1,140 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { LocaleProvider } from "../locale/locale-provider.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { attribute, openingTags, userFacingTexts } from "../render-scan.js"
+import { PagedListFooter, type PagedListState } from "./PagedListFooter.js"
+
+/**
+ * The paged-list tail on its SSR markup (the house render path): a page-0
+ * failure over the previous rows and a load-more failure stay two separate
+ * alerts with their own retries; the count is a live region that says
+ * "Updating…" while page 0 is in flight and hides while the rows are stale.
+ */
+
+const noop = (): void => {}
+const loadMore = (): void => {}
+const retry = (): void => {}
+
+/** A settled page 0: two of three rows on screen, nothing in flight. */
+function paged(overrides: Partial<PagedListState> = {}): PagedListState {
+  return {
+    items: ["a", "b"],
+    firstPage: {},
+    total: 3,
+    hasMore: true,
+    loadMore,
+    retry,
+    ...overrides,
+  }
+}
+
+function render(state: PagedListState, locale = "en") {
+  return renderToStaticMarkup(
+    <LocaleProvider locale={locale}>
+      <PagedListFooter paged={state} noun="items" />
+    </LocaleProvider>,
+  )
+}
+
+const alerts = (html: string) =>
+  openingTags(html, "div").filter((t) => attribute(t, "role") === "alert")
+const statusOf = (html: string) =>
+  /<p role="status"[^>]*>([\s\S]*?)<\/p>/
+    .exec(html)?.[1]
+    ?.replace(/<[^>]*>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+
+describe("PagedListFooter — settled and in-flight states", () => {
+  it("a settled page: the count in the live region, Load more, no alert", () => {
+    const html = render(paged())
+    expect(statusOf(html)).toBe("Showing 2 of 3 items")
+    expect(alerts(html)).toHaveLength(0)
+    expect(html).toContain("Load more</button>")
+  })
+
+  it("a search that finds nothing: the live region stays and says so, nothing visible", () => {
+    const html = render(paged({ items: [], total: 0, hasMore: false }))
+    expect(statusOf(html)).toBe("No entries")
+    expect(html.match(/role="status"/g)).toHaveLength(1)
+    const footer = openingTags(html, "div").find((t) => /data-slot="list-footer"/.test(t)) ?? ""
+    expect(attribute(footer, "class")).toBe("sr-only")
+    expect(statusOf(render(paged({ items: [], total: 0, hasMore: false }), "de"))).toBe(
+      TOOLKIT_MESSAGES.de.listFooter.noResults,
+    )
+  })
+
+  it("a new search in flight: a visible Updating…, no count beside the previous rows", () => {
+    const html = render(paged({ stale: true, refreshing: true }))
+    expect(statusOf(html)).toBe("Updating…")
+    expect(html).not.toMatch(/Showing/)
+    expect(html).not.toContain("Load more")
+  })
+
+  it("a same-filter refetch: Updating… and the count of THIS filter stay", () => {
+    expect(statusOf(render(paged({ refreshing: true })))).toBe("Showing 2 of 3 items Updating…")
+  })
+})
+
+describe("PagedListFooter — two failures, two retries", () => {
+  const failed = new Error("[503] engine down")
+
+  it("a failed search over the previous rows: a warning alert whose retry re-runs page 0", () => {
+    const html = render(paged({ stale: true, error: failed }))
+    const [alert] = alerts(html)
+    expect(attribute(alert ?? "", "data-tone")).toBe("warning")
+    const texts = userFacingTexts(html).map((t) => t.value)
+    expect(texts).toContain(TOOLKIT_MESSAGES.en.listFooter.refreshFailed)
+    expect(texts).toContain(TOOLKIT_MESSAGES.en.listFooter.refreshFailedHint)
+    // The raw reason sits under Details, never in the sentence.
+    expect(html).toMatch(/<summary[^>]*>Details<\/summary><pre[^>]*>\[503\] engine down<\/pre>/)
+    expect(html).toContain("Try again</button>")
+    expect(html).not.toMatch(/Showing/)
+  })
+
+  it("leaves a page-0 failure WITHOUT rows on screen to the caller's loading guard", () => {
+    expect(alerts(render(paged({ firstPage: null, error: failed })))).toHaveLength(0)
+    expect(alerts(render(paged({ firstPage: undefined, error: failed })))).toHaveLength(0)
+  })
+
+  it("a failed load-more: a danger alert next to a still-current count", () => {
+    const html = render(paged({ loadMoreError: failed }))
+    const [alert] = alerts(html)
+    expect(attribute(alert ?? "", "data-tone")).toBe("danger")
+    expect(userFacingTexts(html).map((t) => t.value)).toContain(
+      TOOLKIT_MESSAGES.en.listFooter.loadMoreFailed,
+    )
+    expect(statusOf(html)).toBe("Showing 2 of 3 items")
+  })
+
+  it("keeps both failures apart, each with its own retry, in German", () => {
+    const html = render(paged({ stale: true, error: failed, loadMoreError: failed }), "de")
+    expect(alerts(html).map((a) => attribute(a, "data-tone"))).toEqual(["warning", "danger"])
+    const texts = userFacingTexts(html).map((t) => t.value)
+    expect(texts).toContain("Die Liste konnte nicht aktualisiert werden")
+    expect(texts).toContain("Weitere Einträge konnten nicht geladen werden")
+    expect(openingTags(html, "button")).toHaveLength(2)
+    expect(html.match(/Erneut versuchen<\/button>/g)).toHaveLength(2)
+  })
+
+  it("offers no retry it cannot run, and takes the caller's labels", () => {
+    // A paged state without a page-0 retry callback.
+    const noRetryState = paged({ error: failed })
+    delete noRetryState.retry
+    const withoutRetry = render(noRetryState)
+    expect(alerts(withoutRetry)).toHaveLength(1)
+    // Only Load more is a button: the alert offers no retry without paged.retry.
+    expect(openingTags(withoutRetry, "button")).toHaveLength(1)
+    expect(withoutRetry).not.toContain("Try again</button>")
+    const custom = renderToStaticMarkup(
+      <PagedListFooter
+        paged={paged({ loadMoreError: failed, loadMore: noop })}
+        labels={{ loadMoreFailed: "More tasks didn't load" }}
+        retryLabel="Load again"
+      />,
+    )
+    expect(userFacingTexts(custom).map((t) => t.value)).toContain("More tasks didn't load")
+    expect(custom).toContain("Load again</button>")
+  })
+})

package/src/components/PagedListFooter.tsx

@@ -0,0 +1,107 @@
+import { useToolkitMessages } from "../locale/locale-provider.js"
+import type { ListFooterMessages } from "../locale/message-types.js"
+import { ErrorState } from "./ErrorState.js"
+import { ListFooter } from "./ListFooter.js"
+
+/**
+ * What {@link PagedListFooter} reads from a paged list — structural, so a
+ * paged-query hook's result (`items`, `total`, `loadMore`, …) passes as is.
+ */
+export interface PagedListState {
+  /** The rows on screen (all loaded pages); its length is the "shown" count. */
+  items: readonly unknown[]
+  /** The server's total for the rows on screen. */
+  total: number
+  /** Whether another page exists. */
+  hasMore: boolean
+  /** Fetch the next page (also the retry of a failed load-more). */
+  loadMore: () => void
+  /** A next page is in flight. */
+  loadingMore?: boolean
+  /** A first page is in flight while rows are on screen (a search, a filter, a refetch). */
+  refreshing?: boolean
+  /** The rows on screen are the previous result: a changed search or filter is in flight or failed. */
+  stale?: boolean
+  /**
+   * The first page that is on screen, if any. A first-page {@link error} only
+   * belongs in the footer while one is shown; without rows on screen it is
+   * the load error the caller's loading guard renders.
+   */
+  firstPage?: unknown
+  /** The first-page failure (see {@link firstPage}). */
+  error?: Error | null
+  /** Re-run the first page — the retry of {@link error}. */
+  retry?: () => void
+  /** The last load-more failure; {@link loadMore} retries it, the rows above stay current. */
+  loadMoreError?: Error | null
+}
+
+export interface PagedListFooterProps {
+  /** The paged list's state. */
+  paged: PagedListState
+  /** Plural noun for "Showing X of Y {noun}". Default: the locale's word for rows. */
+  noun?: string
+  /** Override strings of the active catalog's `listFooter` section. */
+  labels?: Partial<ListFooterMessages>
+  /** Retry button label of both error lines. Default: the locale's "Try again". */
+  retryLabel?: string
+}
+
+/** The raw reason of a failure, for the "Details" disclosure (never the sentence). */
+function rawReason(error: Error): string {
+  return error.message || error.name
+}
+
+/**
+ * The tail of a paged list: its failures and the honest {@link ListFooter}.
+ * Two failures stay apart because their retries differ — a failed first page
+ * over the rows still on screen ("You're seeing the previous result", its
+ * retry re-runs page 0) and a failed load-more ("The entries above are
+ * current", its retry fetches the next offset). Each is an inline
+ * `ErrorState` (role="alert") with the raw reason under "Details". The
+ * footer's count line is a polite live region that says "Updating…" while a
+ * first page is in flight, hides the count while the rows are stale, and
+ * stays mounted at zero rows ("No entries", visually hidden), so a search
+ * that finds nothing is announced.
+ */
+export function PagedListFooter({ paged, noun, labels, retryLabel }: PagedListFooterProps) {
+  const catalog = useToolkitMessages().listFooter
+  const L = { ...catalog, ...labels }
+  const refreshError = paged.firstPage != null ? (paged.error ?? null) : null
+  return (
+    <div data-slot="paged-list-footer" className="flex flex-col gap-2">
+      {refreshError && (
+        <ErrorState
+          variant="inline"
+          tone="warning"
+          title={L.refreshFailed}
+          description={L.refreshFailedHint}
+          details={rawReason(refreshError)}
+          onRetry={paged.retry}
+          retryLabel={retryLabel}
+        />
+      )}
+      {paged.loadMoreError && (
+        <ErrorState
+          variant="inline"
+          title={L.loadMoreFailed}
+          description={L.loadMoreFailedHint}
+          details={rawReason(paged.loadMoreError)}
+          onRetry={paged.loadMore}
+          retryLabel={retryLabel}
+        />
+      )}
+      <ListFooter
+        shown={paged.items.length}
+        total={paged.total}
+        hasMore={paged.hasMore}
+        loadingMore={paged.loadingMore}
+        onLoadMore={paged.loadMore}
+        noun={noun}
+        refreshing={paged.refreshing}
+        stale={paged.stale}
+        labels={labels}
+      />
+    </div>
+  )
+}

package/src/components/Pills.test.tsx

@@ -0,0 +1,77 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { attribute, openingTags, userFacingTexts } from "../render-scan.js"
+import { TONE_BORDER, TONE_DOT, TONE_SOFT, TONE_VARIANTS } from "../lib/tone-utils.js"
+import { CountPill, LivePill, StatusBadge } from "./Pills.js"
+
+const classOf = (tag: string | undefined) => attribute(tag ?? "", "class") ?? ""
+
+describe("StatusBadge: the state in words, marked in its tone", () => {
+  it.each(TONE_VARIANTS)("%s: tint, edge and a decorative dot next to foreground text", (tone) => {
+    const html = renderToStaticMarkup(<StatusBadge tone={tone}>Suspended</StatusBadge>)
+    const [badge, dot] = openingTags(html, "span")
+    expect(attribute(badge ?? "", "data-tone")).toBe(tone)
+    expect(classOf(badge)).toContain(TONE_SOFT[tone])
+    expect(classOf(badge)).toContain(TONE_BORDER[tone])
+    expect(classOf(badge)).toContain("text-small")
+    expect(attribute(dot ?? "", "aria-hidden")).toBe("true")
+    expect(classOf(dot)).toContain(TONE_DOT[tone])
+    // The words carry the state; no tone colour reaches them.
+    expect(html).not.toMatch(/\btext-(?:success|warning|danger|info)(?:-ink)?\b/)
+    expect(userFacingTexts(html).map((t) => t.value)).toEqual(["Suspended"])
+  })
+
+  it("maps a retired tone name onto the vocabulary (critical → danger)", () => {
+    const html = renderToStaticMarkup(<StatusBadge tone="critical">Open</StatusBadge>)
+    expect(attribute(openingTags(html, "span")[0] ?? "", "data-tone")).toBe("danger")
+  })
+
+  it("requires its text: colour is never the only signal", () => {
+    // @ts-expect-error — children are mandatory
+    const bare = <StatusBadge tone="danger" />
+    // @ts-expect-error — null is no text either
+    const nothing = <StatusBadge tone="danger">{null}</StatusBadge>
+    expect(bare.props).not.toHaveProperty("children")
+    expect(nothing.props).toHaveProperty("children", null)
+    const mixed = renderToStaticMarkup(
+      <StatusBadge tone="info">
+        {3} open {"incidents"}
+      </StatusBadge>,
+    )
+    expect(mixed.replace(/<!-- -->/g, "")).toContain("3 open incidents")
+  })
+})
+
+describe("LivePill and CountPill", () => {
+  it("LivePill pulses only without reduced motion and defaults to the locale's Live", () => {
+    const html = renderToStaticMarkup(<LivePill />)
+    const dot = openingTags(html, "span")[1] ?? ""
+    expect(classOf(dot)).toContain("motion-safe:animate-pulse")
+    expect(classOf(dot).split(/\s+/)).not.toContain("animate-pulse")
+    expect(html).toContain(">Live</span>")
+    expect(classOf(openingTags(html, "span")[0])).toContain(TONE_SOFT.info)
+  })
+
+  it("CountPill keeps a neutral count in the foreground on the muted tint", () => {
+    const html = renderToStaticMarkup(<CountPill>7</CountPill>)
+    expect(classOf(openingTags(html, "span")[0])).toContain("bg-muted text-foreground")
+    expect(html).not.toContain("text-muted-foreground")
+  })
+
+  it("both take a className and resolve tone aliases", () => {
+    const live = renderToStaticMarkup(
+      <LivePill tone="ok" className="ml-2">
+        On
+      </LivePill>,
+    )
+    expect(classOf(openingTags(live, "span")[0])).toContain(TONE_SOFT.success)
+    expect(classOf(openingTags(live, "span")[0])).toContain("ml-2")
+    const count = renderToStaticMarkup(
+      <CountPill tone="error" className="ml-auto">
+        3
+      </CountPill>,
+    )
+    expect(classOf(openingTags(count, "span")[0])).toContain(TONE_BORDER.danger)
+    expect(classOf(openingTags(count, "span")[0])).toContain("ml-auto")
+  })
+})

package/src/components/Pills.tsx

@@ -1,12 +1,14 @@
-import type { ReactNode } from "react"
+import type { ReactElement, ReactNode } from "react"
 import { useToolkitMessages } from "../locale/locale-provider.js"
-import { TONE_BORDER, TONE_DOT, TONE_SOFT, type ToneVariant } from "../lib/tone-utils.js"
+import { resolveTone, TONE_BORDER, TONE_DOT, TONE_SOFT, type ToneName } from "../lib/tone-utils.js"
+import { cn } from "../lib/utils.js"
 
 export interface LivePillProps {
   /** Status tone driving the dot, tint and border. Default `"info"`. */
-  tone?: ToneVariant
+  tone?: ToneName
   /** Pill label. Defaults to the locale's "Live". */
   children?: ReactNode
+  className?: string
 }
 
 /**
@@ -15,38 +17,89 @@ export interface LivePillProps {
  * text in the foreground), so it inherits the active theme. The pulse stops
  * under `prefers-reduced-motion`.
  */
-export function LivePill({ tone = "info", children }: LivePillProps) {
+export function LivePill({ tone = "info", children, className }: LivePillProps) {
   const messages = useToolkitMessages()
+  const t = resolveTone(tone, "info")
   return (
     <span
-      className={`inline-flex items-center gap-1.5 rounded-sm border px-2 py-0.5 text-xs font-semibold ${TONE_SOFT[tone]} ${TONE_BORDER[tone]}`}
+      className={cn(
+        "text-small inline-flex items-center gap-1.5 rounded-sm border px-2 py-0.5 font-semibold",
+        TONE_SOFT[t],
+        TONE_BORDER[t],
+        className,
+      )}
     >
       <span
         aria-hidden="true"
-        className={`size-1.5 animate-pulse rounded-full ${TONE_DOT[tone]}`}
+        className={cn("size-1.5 rounded-full motion-safe:animate-pulse", TONE_DOT[t])}
       />
       {children ?? messages.pills.live}
     </span>
   )
 }
 
+/** The words a {@link StatusBadge} must carry: text, a number or an element — never nothing. */
+export type StatusBadgeText = string | number | ReactElement | (string | number | ReactElement)[]
+
+export interface StatusBadgeProps {
+  /** The state, in words ("Suspended", "3 open incidents"). Required: colour is never the only signal. */
+  children: StatusBadgeText
+  /** The state's tone: tint, edge and dot. */
+  tone: ToneName
+  className?: string
+}
+
+/**
+ * A state in words, marked in its tone: tint, edge and a static dot next to
+ * foreground text (CI §3.3: the colour marks the state, the words say it).
+ * For a detail-page header (`WidgetHeader`'s `badge`) or a table cell. The
+ * text is required — a badge without words would make colour the only
+ * signal. The pulsing dot is {@link LivePill}'s live-data semantic.
+ */
+export function StatusBadge({ children, tone, className }: StatusBadgeProps) {
+  const t = resolveTone(tone)
+  return (
+    <span
+      data-slot="status-badge"
+      data-tone={t}
+      className={cn(
+        "text-small inline-flex w-fit items-center gap-1.5 rounded-sm border px-2.5 py-0.5 font-semibold",
+        TONE_SOFT[t],
+        TONE_BORDER[t],
+        className,
+      )}
+    >
+      <span aria-hidden="true" className={cn("size-1.5 shrink-0 rounded-full", TONE_DOT[t])} />
+      {children}
+    </span>
+  )
+}
+
 export interface CountPillProps {
   /** Status tone driving the tint and border. Default `"neutral"`. */
-  tone?: ToneVariant
+  tone?: ToneName
   /** The count/value to display (tabular numbers). */
   children: ReactNode
+  className?: string
 }
 
 /**
  * Compact count badge — tabular numbers on a tinted background with a border
  * in the tone. Use as the right-aligned indicator on a list/group row (e.g. a
  * per-group item count). The number stays in the foreground in every tone
- * (no coloured digits): the tint and the border carry the tone.
+ * (no coloured digits): the tint and the border carry the tone. A count
+ * without a state stays `neutral`.
  */
-export function CountPill({ tone = "neutral", children }: CountPillProps) {
+export function CountPill({ tone = "neutral", children, className }: CountPillProps) {
+  const t = resolveTone(tone)
   return (
     <span
-      className={`inline-flex min-w-[2.5rem] items-center justify-center rounded-sm border px-2.5 py-0.5 text-sm font-semibold tabular-nums ${TONE_SOFT[tone]} ${TONE_BORDER[tone]}`}
+      className={cn(
+        "text-dense inline-flex min-w-10 items-center justify-center rounded-sm border px-2.5 py-0.5 font-semibold tabular-nums",
+        TONE_SOFT[t],
+        TONE_BORDER[t],
+        className,
+      )}
     >
       {children}
     </span>

package/src/components/SectionHeading.tsx

@@ -1,4 +1,6 @@
 import type { ReactNode } from "react"
+import { MICRO_LABEL } from "../lib/typography.js"
+import { cn } from "../lib/utils.js"
 
 export interface SectionHeadingProps {
   /** The section title. */
@@ -12,14 +14,18 @@ export interface SectionHeadingProps {
 /**
  * Section title row — a small semibold heading with an optional muted hint or
  * control on the right. Use to label a block inside a widget body (e.g. a list
- * or sub-table) without the visual weight of a full card header.
+ * or sub-table) without the visual weight of a full card header. The title is
+ * a caption ({@link MICRO_LABEL}: 13 px semibold, normal case); a section that
+ * needs a real heading takes `text-section` (21 px) instead.
  */
 export function SectionHeading({ title, hint, trailing }: SectionHeadingProps) {
   return (
-    <div className="text-muted-foreground mb-3 flex items-center justify-between text-sm font-semibold">
+    <div
+      className={cn("text-muted-foreground mb-3 flex items-center justify-between", MICRO_LABEL)}
+    >
       <span>{title}</span>
       {(hint || trailing) && (
-        <span className="text-muted-foreground text-xs font-medium">{trailing ?? hint}</span>
+        <span className="text-muted-foreground text-small font-medium">{trailing ?? hint}</span>
       )}
     </div>
   )