mdk-ui-component

Files (3)

• SKILL.md
• page-recipe.md · references/
• ui-registry.json · references/

SKILL.md (first lines)

# Build an MDK UI page for worker/plugin data

MDK UI shells (`apps/dashboard/`, scaffolded by `mdk create dashboard` — or
`apps/<name>/` if named explicitly) are **composition only**. Data comes from
a Gateway route; shaping lives in a hook; visuals come from
`@tetherto/mdk-react-devkit`. Never invent component prop names — look them
up in [`references/ui-registry.json`](./references/ui-registry.json).

A fresh scaffold ships no example page — build one from these layers (see the
shell's own [`USAGE.md`](../../../../../examples/mdk-ui-shell-template/USAGE.md), "The pattern every page should follow"):

| Layer            | Owns                                                                           |
| ---------------- | ------------------------------------------------------------------------------ |
| Gateway route    | Your Gateway plugin's route — serves the data                                  |
| Hook             | app-local `src/hooks/use-<thing>.ts` — `useQuery` against the route, shapes the payload in `select` |
| Page             | `apps/dashboard/src/pages/<Name>.tsx` — thin glue, no fetch/shaping            |
| Panel            | `apps/dashboard/src/components/<Name>Panel.tsx` — props in, markup out         |
| Route            | `apps/dashboard/src/routes.ts` — one line                                      | 

## Prerequisites (do these first)

1. **Data source exists.** If no `/api/...` route returns the metric, stop and
   use `mdk-gateway-plugin` to create one. Confirm with `curl` that the JSON shape
   is stable.
2. **Contract units known.** Read the Worker `mdk-contract.json` so labels/units
   match (`power` → `W`, etc.). Resolve it from `mdk.yaml` → `spec.workers`:
   local `package` → `<package>/mdk-contract.json` (or legacy
   `<package>/plugin/mdk-contract.json`); npm package → the same under
   `node_modules/<package>/`.
3. **Dashboard app exists.** If missing: `mdk create dashboard` (see
   `mdk-deployment`).

## Workflow

```mermaid
flowchart TD
  intent["Plain-language intent"]
  route{"/api route returns the metric?"}
  gateway["mdk-gateway-plugin: create the route"]
  registry["Pick components from ui-registry.json"]
  contract["Match labels/units to the worker mdk-contract.json"]
  build["Build the hook, panel, and page"]
  wire["Wire the route in routes.ts"]

  intent --> route
  route -->|no| gateway --> registry
  route -->|yes| registry
  registry --> contract
  contract --> build --> wire
```

### 1. Pick the visual from the registry

Open [`references/ui-registry.json`](./references/ui-registry.json) (this skill). Use
`indexes.componentsByName` / `indexes.componentsByCategory`.

| Need                          | Typical component   |
| ----------------------------- | ------------------- |
| Single numeric metric / total | `SingleStatCard`    |
| Time-series                   | `LineChartCard`     |
| Fallback text when null       | `FALLBACK` constant |

Copy **exact** prop names and types from the registry entry. Example
`SingleStatCard`: `name`, `subtitle`, `value`, `unit`, `variant`, `flash`.

### 2. Add the page scaffold

Add the route to `src/routes.ts` yourself — append a one-line entry above the
`// mdk:routes-end` marker:

```ts
// src/routes.ts
export const ROUTES: AppRoute[] = [
  { path: "/<page-name>", label: "<Page Name>", page: () => import("./pages/<PageName>") },
  // mdk:routes-end
]
```

Keep each route on a **single line** and preserve the end marker; the file is
parsed line-wise by tooling. Do not add feature pages to `router.tsx`.

### 3. Create the data hook (shape the payload)

For a **project-local app** (one scaffolded under `apps/<app-name>` by `mdk create app`, referenced by
its package name in `mdk.yaml` → `spec.apps`), put the hook in the
dashboard. The Gateway serves the app's routes under `/apps/<app-name>` unless its entry sets
`mount: /`, so fetch `/apps/<app-name>/api/...`. In dev, the dashboard's Vite proxy must forward
`/apps` to the Gateway too; add `'/apps': gatewayUrl` next to `/api` in `vite.config.ts` if it is missing:

`src/hooks/use-<thing>.ts`

```ts
import { useQuery } from '@tetherto/mdk-react-adapter'

// types matching the route's JSON schema in mdk-plugin.json
export const useThing = () => {
  const result = useQuery({
    queryKey: ['thing'],
    queryFn: async () => {
      const res = await fetch('/apps/<app-name>/api/...')
      if (!res.ok) throw new Error(`Failed (HTTP ${res.status})`)
      const raw = await res.json()
      // shape → render-ready; never leave shaping to the panel
      return { /* ... */ }
    },
    refetchInterval: 5_000, // live tiles
  })
  return {
    info: result.data ?? EMPTY,
    isLoading: result.isLoading,
    error: result.error,
    refetch: () => { void result.refetch() },
  }
}
```

Rules:

- Import `useQuery` from `@tetherto/mdk-react-adapter`, **not** from

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk