@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-ui-component/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: mdk-ui-component
+description: >
+  Build a UI page/panel that renders data from an MDK Worker or Gateway
+  plugin. Use when the task mentions "UI / component / widget / dashboard",
+  "show telemetry", "chart / tile / heatmap", "render data from a
+  worker/plugin", or prompts like "create a UI to show <metric> for <device>".
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.5.0"
+license: Apache-2.0
+---
+
+# 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
+  `@tanstack/react-query` directly.
+- Hook owns fetch + shaping; panel stays presentational.
+- For reusable MDK-wide endpoints, prefer adding the hook to
+  `@tetherto/mdk-react-adapter` (see the dashboard
+  [`USAGE.md`](../../../../../examples/mdk-ui-shell-template/USAGE.md)'s layered data
+  flow). App-local hooks are correct for project-local plugins.
+
+### 4. Create the presentational panel
+
+`src/components/<Name>Panel.tsx`
+
+- Props: already-shaped `info` + `isLoading` + `error`
+- No `fetch`, no stores, no inline transforms beyond trivial display
+  (`Math.round`)
+- Handle three states: `error`, empty list, data
+- Render registry components with verified props
+
+### 5. Wire a thin page
+
+`src/pages/<Name>.tsx`:
+
+- Call the hook
+- Wrap in `PageLayout` with title + optional Refresh action
+- Pass hook outputs to the panel
+- Page holds **no** fetch / shaping
+
+### 6. Styles
+
+Add a BEM block under the shell namespace in `src/App.scss`, e.g.
+`.mdk-ui-shell-<name>`, matching the `className` on `PageLayout`. Reuse CSS
+variables (`--mdk-color-*`) and mirror the existing blocks in that file for
+structure (refresh button, card, error state).
+
+## Composition rules (do not break)
+
+From the dashboard [`USAGE.md`](../../../../../examples/mdk-ui-shell-template/USAGE.md):
+
+```
+Gateway plugin / foundation query
+  → adapter or app hook   (fetch + shape)
+    → thin page           (hook → panel)
+      → presentational panel + @tetherto/mdk-react-devkit
+```
+
+Forbidden:
+
+| Don't                            | Do                                                             |
+| -------------------------------- | -------------------------------------------------------------- |
+| `fetch` inside a panel/component | Hook                                                           |
+| Guess `SingleStatCard` props     | [`references/ui-registry.json`](./references/ui-registry.json) |
+| Import Ant Design / MUI          | `@tetherto/mdk-react-devkit`                                   |
+| Edit `router.tsx` for feature pages | A one-line entry in `routes.ts`                             |
+| Hard-code units ignoring the contract | Use `unit` from the API payload                           |
+
+## Worked recipe: "UI to show `<metric>` for `<device family>`"
+
+End-to-end chain this kind of prompt implies (router skill expands this):
+
+1. `mdk-gateway-plugin` — ensure `GET /api/<domain>/<resource>` exists and
+   returns a shaped payload (e.g. `{ unit, total, devices[] }`) grounded in
+   the Worker contract's telemetry channel.
+2. This skill — hook + `SingleStatCard` grid (total + per-device) + page +
+   route.
+3. `mdk-deployment` — app listed in `mdk.yaml` → `spec.apps`, `mdk run` up (app runtime + Gateway),
+   Worker online with a device.
+
+Detailed file checklist: [`references/page-recipe.md`](./references/page-recipe.md).
+
+## Hand-off
+
+| Problem                    | Skill                       |
+| -------------------------- | --------------------------- |
+| No API route / wrong shape | `mdk-gateway-plugin`        |
+| Stack not running / app not declared | `mdk-deployment` |
+| Device / telemetry channel missing | `mdk-worker-plugin` |

package/dist/skills/mdk-ui-component/references/page-recipe.md

@@ -0,0 +1,78 @@
+# Page recipe — API-backed metric page
+
+Checklist for a new dashboard page that shows live Worker/plugin data.
+
+## Files to add or touch
+
+```
+<dashboard>/
+├── src/hooks/use-<thing>.ts          # fetch + shape (useQuery)
+├── src/components/<Thing>Panel.tsx   # presentational
+├── src/pages/<Thing>.tsx             # thin PageLayout glue
+├── src/routes.ts                     # one-line route entry
+└── src/App.scss                      # .mdk-ui-shell-<thing> block
+```
+
+Optional: `src/constants/navigation.tsx` only if you need a custom nav icon
+(default explorer icon is fine).
+
+## Layer responsibilities
+
+| Layer | Owns | Must not |
+| --- | --- | --- |
+| Hook | `fetch`, JSON → typed `info`, polling | JSX |
+| Panel | Markup, loading/empty/error UI, registry components | `fetch`, business rules |
+| Page | Hook call, `PageLayout`, Refresh button | Shaping, direct HTTP |
+| Plugin (backend) | Aggregation across Workers | UI concerns |
+
+## Minimal page skeleton
+
+```tsx
+import { PageLayout } from '../components/PageLayout'
+import { ThingPanel } from '../components/ThingPanel'
+import { useThing } from '../hooks/use-thing'
+
+const Thing = () => {
+  const { info, isLoading, error, refetch } = useThing()
+  return (
+    <PageLayout
+      title="Thing"
+      className="mdk-ui-shell-thing"
+      actions={(
+        <button type="button" onClick={refetch} disabled={isLoading}>
+          {isLoading ? 'Refreshing…' : 'Refresh'}
+        </button>
+      )}
+    >
+      <ThingPanel info={info} isLoading={isLoading} error={error} />
+    </PageLayout>
+  )
+}
+
+export default Thing
+```
+
+## Route entry
+
+```ts
+{ path: '/thing', label: 'Thing', page: () => import('./pages/Thing') },
+// mdk:routes-end
+```
+
+Keep on one line. Path becomes the sidebar href.
+
+## Component lookup
+
+Before writing JSX:
+
+1. Open [`ui-registry.json`](./ui-registry.json).
+2. Find the component by name.
+3. Use only documented `props[]` names/types.
+4. Prefer `tier: "agent-ready"` / `public: true` components.
+
+## Composition rules
+
+See the shell's own [`USAGE.md`](../../../../../../examples/mdk-ui-shell-template/USAGE.md) ("The pattern every page should follow") for the
+layered data flow this checklist implements: a fresh scaffold ships no example
+page, so there is no file in the project to copy — follow the layer
+responsibilities above instead.