@k2b/cloud

Cloud dashboard widgets

The Cloud endpoint contract that feeds portable widget presentation components.

TSX

<Widget title="Account requests" icon="ti ti-users" size="compact">

<WidgetStat value={7} label="Open" sub="Needs review" accent={{ tone: "amber", icon: "ti ti-clock" }} />

<WidgetPills pills={[{ label: "New", value: 3, tone: "blue" }, { label: "Waiting", value: 4, tone: "amber" }]} />

</Widget>

<Widget title="Recent notes" icon="ti ti-notebook" size="compact">

<WidgetList grow items={recentNotes} />

</Widget>

<Widget title="Service health" icon="ti ti-heartbeat" size="compact">

<WidgetStatus tone="success" title="All systems operational" message="8 services report healthy." />

<WidgetHero title="No active incidents" icon="ti ti-circle-check" tone="emerald" />

</Widget>

Cloud applications can expose bounded WidgetResponse JSON endpoints to the shared dashboard. The endpoint, session, permissions, route, and response contract are Cloud-specific; the rendered widget components also exist portably in @k2b/ui.

Use Cloud dashboard widgets

Register an endpoint when users need a compact cross-application summary or a direct route into a common task. Do not reproduce an entire application screen.

Use the portable widget components directly when the host already owns its data and layout and does not need Cloud endpoint discovery.

Import

import type { WidgetResponse } from "@k2b/cloud/contracts";

Endpoint contract

The dashboard forwards the signed-in user's session cookie. The endpoint authenticates the request, applies every required permission, keeps its query bounded, and returns:

200 with WidgetResponse;
204 when there is no relevant content;
403 when the user lacks access;
another error only for a real failure.

One slow or failed endpoint must not block the dashboard.

Accessibility

Every stat needs a label and context. Widget and row links need destination-specific text. Status blocks must state their result in text instead of relying on tone or icons.

Runtime

Cloud discovers registered widget endpoints during server rendering and applies a bounded timeout. Endpoint responses are JSON; applications never return Solid elements through this contract.

Example

const body: WidgetResponse = {
  title: "Recent notes",
  icon: "ti ti-notebook",
  href: "/app/notebooks",
  blocks: [
    {
      kind: "list",
      grow: true,
      items: notes.map((note) => ({
        label: note.title,
        sub: note.notebookName,
        href: `/app/notebooks/${note.notebookId}/notes/${note.id}`,
      })),
    },
  ],
};

return c.json(body);