` | `capabilities.telemetry` or `capabilities.commands` must be an array | | `ERR_PLUGIN_ENTRY_NAME_MISSING:

` | Give every telemetry/command entry a non-empty string `name` | | `ERR_PLUGIN_HANDLER_MISSING:

.` | Add that entry's relative `handler` path | | `ERR_PLUGIN_HANDLER_NOT_FOUND:

.: : ` | Verify the displayed resolved path is relative to `plugin.dir`. Preserve and inspect the nested module error: the file may exist while one of its own imports is missing or incompatible | | `ERR_PLUGIN_HANDLER_NOT_FUNCTION:

.: ` | The CommonJS module must assign a function to `module.exports` | | `ERR_PLUGIN_DUPLICATE_NAME:

.` | Rename or remove the duplicate entry in that section | These fire only once a host process constructs `WorkerRuntime` with your plugin — for errors from that point on (runtime construction, Kernel registration, live requests), see [Troubleshooting](/guides/workers/test-a-worker) in Test a Worker with MDK. ## Next steps - Test your new [Worker's integration with MDK](/guides/workers/test-a-worker) - Understand the [security boundaries](/concepts/security-boundaries) Understand the end-user experience of controlling and monitoring your device via the Worker: - Build a [minimal dashboard](/tutorials/quickstart/build-a-dashboard) around one Worker - Run the [full-site example](https://github.com/tetherto/mdk/blob/main/examples/full-site/README.md) with the supported Worker fleet - Connect an [AI agent via the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command your Workers # Test a new Worker with MDK (/guides/workers/test-a-worker) This guide is for users of third-party worker packages or such partners who have integrated their own hardware, firmware, or data feed with MDK by shipping a [Worker plugin package](/guides/workers/build-a-worker). ## Overview Worker packages are the contract between the hardware and the Kernel, before relying on such a contract you will want to test its integration. To seed devices and register with Kernel, host the plugin on `WorkerRuntime` in a Node.js host process. The host module may live in the Worker plugin package itself; a second npm package is **not required**. A separate host directory is recommended when independent plugin publication and plugin-only tests are useful: ```text your-worker-host/ index.js # host module: WorkerRuntime, devices, lifecycle run-live.js # live Kernel registration and compatibility check ``` This mirrors [`examples/backend/demo-worker-caller/`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js), which is an example directory containing one host module, not a standalone npm package. ## Prerequisites - Node.js `>=24` (all MDK core packages declare this `engines` constraint) - A completed [Worker Plugin package](/guides/workers/build-a-worker), including its bundled mock device - Comfort with plain async JS — no additional MDK framework knowledge is required beyond what building the package already covered ### Install MDK `@tetherto/mdk-worker` (the package that ships `WorkerRuntime`) is **not yet published to the npm registry** — MDK is pre-1.0 and still distributed as this monorepo. Until it is, the working path from an external repo is a git dependency plus a deep `require()` into the checked-out repo, exactly mirroring how every in-repo Worker already resolves it (by relative path, not through `node_modules` package resolution): ```bash npm install github:tetherto/mdk#main ``` This installs the whole monorepo under `node_modules/@tetherto/mdk` (its root `package.json` name). It does **not** auto-install the nested package's own dependencies — this repo's install is a federated set of scripts, not a single root dependency graph — so run its installer once after adding it: ```bash (cd node_modules/@tetherto/mdk/backend/core && ./install-packages.sh) ``` The same deep-path pattern also gets you `getKernel`, `startGateway`, and `waitForDiscovery` from `require('@tetherto/mdk/backend/core/mdk')`, used in Step 3 below. ### Write the host module `host/index.js`, modeled on [`examples/backend/demo-worker-caller/index.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js): ```js "use strict"; const { WorkerRuntime } = require("@tetherto/mdk/backend/core/mdk-worker"); const plugin = require("../your-worker-repo/plugin"); async function startVendorWorker({ workerId, kernelTopic, seedDevices }) { const runtime = new WorkerRuntime(plugin, { workerId, kernelTopic: kernelTopic || null, devices: (seedDevices || []).map((d) => ({ deviceId: d.id, config: d.opts, })), }); await runtime.start(); return { runtime, stop: () => runtime.stop(), }; } module.exports = { startVendorWorker }; ``` Required `WorkerRuntime` options are `workerId` and a non-empty `devices` array. Each `config` object is passed to the plugin's `connect()`. `kernelTopic` is needed only for DHT discovery. Without a `store`, `WorkerRuntime` generates a new RPC keypair on restart. Pass a process-owned store if deployment requires stable identity. The host process also owns persistence, sampling loops, retries, secrets, and shutdown. See the [demo host module](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) for a SQLite sampler example. `WorkerRuntime` also exposes two read accessors for the host process: `getPublicKey()` returns the runtime's RPC public key (used to register with Kernel, shown in the next step), and `getDeviceContext(deviceId)` returns the same frozen `ctx` a handler receives (`{ deviceId, device, config, services }`) for a device that is currently `online`, or `null` otherwise — useful for wiring an external service (for example, a snapshot collector) to a live device outside the request/response cycle. ### Register directly with a live Kernel When Kernel and the Worker host share a process, register the runtime's public key directly. This complete `host/run-live.js` proves that Kernel accepted the Worker, that it reached `READY`, and that telemetry traverses the real client → Kernel → Worker path: ```js "use strict"; const os = require("os"); const path = require("path"); const { getKernel, waitForDiscovery, shutdown, } = require("@tetherto/mdk/backend/core/mdk"); const { createMdkClient } = require("@tetherto/mdk/backend/core/client"); const { startVendorWorker } = require("./index"); const vendorMock = require("../your-worker-repo/mock/server"); const ROOT = path.join(os.tmpdir(), `vendor-worker-${process.pid}`); function onceListening(mock) { if (mock.server.listening) return Promise.resolve(); return new Promise((resolve) => mock.server.once("listening", resolve)); } function withTimeout(promise, timeoutMs, code) { let timer; const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error(code)), timeoutMs); }); return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)); } async function main() { let mock; let worker; let kernel; let client; try { mock = vendorMock.createServer({ host: "127.0.0.1", port: 9001, hashrateThs: 200, }); await onceListening(mock); kernel = await getKernel({ root: ROOT }); worker = await startVendorWorker({ workerId: "vendor-demo", seedDevices: [ { id: "vendor-0", opts: { host: "127.0.0.1", port: 9001 } }, ], }); await kernel.registerWorker(worker.runtime.getPublicKey()); const workers = await waitForDiscovery(kernel, { minWorkers: 1, timeoutMs: 30000, }); const ready = workers.find( (w) => w.workerId === "vendor-demo" && w.state === "READY", ); if (!ready || !ready.deviceIds.includes("vendor-0")) { throw new Error("ERR_WORKER_NOT_READY"); } client = createMdkClient({ hrpc: { key: kernel.getPublicKey() } }); await client.connect(); const telemetry = await withTimeout( client.pullTelemetry("vendor-0", "metrics"), 8000, "ERR_TELEMETRY_TIMEOUT", ); if (typeof telemetry.metrics?.hashrate_rt !== "number") { throw new Error("ERR_TELEMETRY_INVALID"); } console.log(`READY ${ready.workerId}: ${ready.deviceIds.join(", ")}`); console.log(`hashrate_rt=${telemetry.metrics.hashrate_rt}`); } finally { if (client) await client.close(); if (kernel) await shutdown(kernel); if (worker) await worker.stop(); if (mock) mock.exit(); } } main().catch((err) => { console.error(err); process.exitCode = 1; }); ``` Expected output: ```text READY vendor-demo: vendor-0 hashrate_rt=200 ``` The timeout wrapper bounds the client's wait but cannot cancel the current HRPC request. Always close the client during shutdown. Device-protocol cancellation is separately owned by the device client from Step 2. ### Use DHT discovery across processes or hosts For DHT discovery, generate and securely distribute one 32-byte hex topic, start the Worker first with `kernelTopic`, then start Kernel with the same `topic`. Do **not** also call `registerWorker()`: ```js "use strict"; const crypto = require("crypto"); const os = require("os"); const path = require("path"); const { getKernel, waitForDiscovery, shutdown, } = require("@tetherto/mdk/backend/core/mdk"); const { startVendorWorker } = require("./index"); const ROOT = path.join(os.tmpdir(), `vendor-worker-dht-${process.pid}`); async function main() { const topic = process.env.MDK_TOPIC || crypto.randomBytes(32).toString("hex"); let worker; let kernel; try { worker = await startVendorWorker({ workerId: "vendor-demo", kernelTopic: topic, seedDevices: [ { id: "vendor-0", opts: { host: "10.0.0.20", port: 9001 } }, ], }); kernel = await getKernel({ root: ROOT, topic }); const workers = await waitForDiscovery(kernel, { minWorkers: 1, timeoutMs: 45000, }); const ready = workers.find( (w) => w.workerId === "vendor-demo" && w.state === "READY", ); if (!ready) throw new Error("ERR_WORKER_NOT_READY"); console.log(`READY ${ready.workerId}: ${ready.deviceIds.join(", ")}`); } finally { if (kernel) await shutdown(kernel); if (worker) await worker.stop(); } } main().catch((err) => { console.error(err); process.exitCode = 1; }); ``` For separate production processes, each process must install signal handlers and close every handle it owns. DHT topics enable rendezvous; they are not authentication secrets or command-authorization tokens. See the [discovery model](/concepts/stack/workers) for DHT, Local, and Same-process trade-offs. ## Troubleshooting ### Runtime construction | Error | Diagnostic and remediation | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `ERR_WORKER_ID_REQUIRED` | Pass a non-empty string `workerId` | | `ERR_DEVICES_REQUIRED` | Pass a non-empty `devices` array, unless this is an intentional provisioning-first host using `allowEmptyDevices` | | `ERR_DEVICE_ID_MISSING` | Every device spec needs a non-empty string `deviceId` | | `ERR_DEVICE_ID_DUPLICATE: ` | Device IDs must be unique within one runtime | | `ERR_DEVICE_CONFIG_INVALID: ` | `config`, when supplied, must be a non-null object | `allowEmptyDevices` opts a host into a provisioning-first bootstrap: the runtime constructs with zero devices instead of throwing `ERR_DEVICES_REQUIRED`, then takes `registerThing` writes (a built-in command — see [Worker Runtime legacy services](https://github.com/tetherto/mdk/blob/main/docs/reference/maintainers/worker-runtime-legacy-services.md)) that persist new device configs to the store. Those writes only take effect once the host is stopped and restarted with the provisioned set — there is no hot-add. It is off by default; every shipped miner Worker in this monorepo sets it to `true` in its boot function. ### Startup and discovery | Symptom | Diagnostic and remediation | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Device remains offline after `runtime.start()` | `connect()` failed. Check the device timeout, credentials, address, protocol, and redacted host logs. The current runtime does not reconnect; restore reachability and restart the Worker host | | `waitForDiscovery()` returns no `READY` Worker | For direct registration, await `runtime.start()` and `kernel.registerWorker(runtime.getPublicKey())`. For DHT, start the Worker first and verify both processes use the same 32-byte hex topic and can reach the DHT network | | Worker is present but never `READY` | Inspect identity and capability failures. Confirm at least one device ID is reported and the contract has valid `metadata` and `capabilities` | ### Request time | Error | Diagnostic and remediation | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ERR_DEVICE_UNAVAILABLE: ` | The device was held offline because `connect()` failed; follow the documented restart/recovery path | | `ERR_DEVICE_NOT_FOUND: ` | The request targeted an ID not seeded in this runtime; compare it with the Kernel registry's `deviceIds` | | `ERR_DEVICE_ID_REQUIRED: ` | A named telemetry pull or command omitted its target device ID | | `ERR_UNKNOWN_QUERY_TYPE: ` | Use `metrics` or the exact `name` of a telemetry entry; the entry's return `type` is not its channel name | | `ERR_UNKNOWN_COMMAND: ` | Use the exact declared command name and confirm its handler loaded | | `ERR_UNKNOWN_ACTION: ` | Use a public MDK client helper instead of constructing protocol actions manually | | Command returns `status: 'FAILED'` | Read the stable `ERR_*` value, check validation/cooldown/device logs, and do not retry a timed-out physical write until its actual device state is known | ## Next steps - Understand the [security boundaries](/concepts/security-boundaries) Understand the end-user experience of controlling and monitoring your device via the Worker: - Build a [minimal dashboard](/tutorials/quickstart/build-a-dashboard) around one Worker - Run the [full-site example](https://github.com/tetherto/mdk/blob/main/examples/full-site/README.md) with the supported Worker fleet - Connect an [AI agent via the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command your Workers # Quickstart (/quickstart) } title={Connect hardware} href="/quickstart/connect-hardware" description={ <> Drive a running MDK stack with a mock miner — live telemetry and commands over IPC ⏱️ ~3 min } /> } title={Build dashboards with your AI agent} href="/quickstart/connect-agents" description={ <> Use the CLI to wire Cursor or Claude to MDK with two commands, then build from plain-language prompts ⏱️ ~2 min } /> } title={Build dashboards with React} href="/quickstart/wire-react" description={ <> Install the three MDK React packages and wire MdkProvider ⏱️ ~3 min } /> } title={Explore the demo app} href="/tutorials/ui/explore-the-demo" description={ <> See the UI components rendered in a single demo app ⏱️ ~3 min } /> # Build dashboards with AI (/quickstart/connect-agents) MDK is built so your AI coding agent can build mining dashboards straight from plain-language prompts, without you wiring components by hand. There are two steps: wire your IDE once, then describe what you want. ## Wire your IDE once ### Run init Point the UI CLI at your IDE from your project root: ```bash npx @tetherto/mdk-ui-cli init --ide cursor ``` Use `--ide claude` for Claude. This writes a `.mdk/context.md` agent-context file and an IDE rule (`.cursor/rules/mdk.mdc` for Cursor, `CLAUDE.md` for Claude) so every AI session knows about MDK automatically. ### Prompt your agent Describe the dashboard you want in plain language: > Build me an operations dashboard with live hashrate and a device list. Your agent takes it from there: it finds the right components and hooks, scaffolds the page, and checks that it compiles. You review and run it. ## Next steps

Build any dashboard with an agent Stats Lab walkthrough with UI CLI commands — no fleet backend Runtime agents via MCP Server Monitor and control a live fleet at runtime through the MCP server

- [How agents build with MDK](/concepts/agents): why the results are trustworthy — the local manifests and stable-export contract behind the flow - [UI CLI reference](/reference/app-toolkit/ui-cli): every command your agent (or you) can run - [UI Devkit](/reference/ui): browse the component library your agent draws from # Connect hardware (/quickstart/connect-hardware) ## Overview This quickstart walks the shortest path from a fresh clone to a fully wired MDK stack you can drive interactively from a CLI. Everything runs in one Node process, no real hardware required. What you'll have at the end: - A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028` - An Kernel with one Worker registered and one device discovered - An interactive `client.js` REPL talking to Kernel over its IPC socket — pull metrics, list Workers, send commands like `reboot` and `setpower` - (Optional) An Gateway HTTP API on `:3000` so non-Node consumers (browsers, AI agents over MCP) can hit the same stack over REST The example lives in [`examples/backend/mdk-e2e/`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md#end-to-end-mdk-e2e) and contains six runnable scripts. This tutorial uses three of them: `run.js` for a smoke test, `server.js` for the long-running stack, and `client.js` for interactive control. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 The stack starts an Kernel whose control plane is peer-to-peer over a Hyperswarm DHT, so it needs outbound network access. Without it, the stack stalls at startup while the Kernel tries to reach DHT bootstrap nodes. See [how Workers connect](/concepts/stack/workers) for the Kernel/DHT mechanics. ### Clone and install #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies The monorepo has two workspaces with their own dependency trees. Install both: ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` Each script walks every `package.json` under its workspace and runs `npm ci`. The `examples/mdk-e2e/` package is included automatically — no extra install step needed.

(1.3 Optional) Smoke test the stack

Before going interactive, prove the wiring works. `run.js` starts a mock Whatsminer + Worker + Kernel in one process, exercises a few queries, prints the results, and exits cleanly: ```bash node examples/backend/mdk-e2e/run.js ``` Expected output (the UUID and metric values vary): ```text Devices: [ '8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b [miner-wm-m56s]' ] Telemetry: ONLINE hashrate=170000 power=3500W Commands: reboot, setPowerMode, setLED, setPowerPct, setupPools, saveComment ``` If you see those three lines, every layer is working: the mock is responding, the Worker registered the device, Kernel discovered the Worker over the local DHT topic, and IPC routing is delivering envelopes both ways. The script tears itself down and exits with code 0. If the smoke test fails with `EADDRINUSE` on port 14028, a previous run left a Node process alive. Kill stragglers with `pkill -f mdk-e2e` and retry.

### Run the interactive demo #### 3.1 Start the stack In your terminal: ```bash node examples/backend/mdk-e2e/server.js ``` `server.js` starts the same mock + Worker + Kernel as `run.js`, but stays running and prints the IDs you'll need: ```text Kernel key: 7a4c8b...e3f0 Device: 8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' Ctrl+C to stop. ``` The `Kernel key` is a 64-char hex public key. `Device` is a UUIDv4 generated at registration time. Both vary per run — note the device UUID for the next step. The two `hp-rpc-cli` lines are paste-ready commands for inspecting Kernel over HRPC from another machine. You don't need them for this tutorial — they're there if you have [`hp-rpc-cli`](https://github.com/holepunchto/hp-rpc-cli) installed and want to go off-script. #### 3.2 Connect the interactive client Open a second terminal in the same `mdk` directory: ```bash node examples/backend/mdk-e2e/client.js ``` `client.js` connects to Kernel's default IPC socket and gives you an MDK REPL: ```text MDK Client — connected to IPC: /tmp/mdk/ork.sock Type "help" for commands, "quit" to exit. mdk> ``` #### 3.3 Drive the stack 3.3.1 Discover the telemetry of your (mock) device by entering commands at the `mdk>` prompt, substituting `` with the UUID printed in Step 3.1: ```text mdk> metrics ``` Each command builds an MDK Protocol envelope, writes it to Kernel's IPC socket, and prints the JSON response. 3.3.2 Try changing the power mode and observing the effect: ```text mdk> setpower low mdk> metrics ``` After `setpower ... low` the second `metrics` call should reflect the power mode change. {/* sync with examples/backend/mdk-e2e/client.js help block */}

Full command reference

##### Reads ```text workers — list workers list [deviceId] — list devices count [deviceId] — device count metrics — live telemetry from hardware logs — recent logs settings [deviceId] — worker settings stats [deviceId] — fleet stats config — device config (pools, etc.) capabilities — mdk-contract capabilities state [deviceId] — worker state snapshot ``` ##### Commands ```text reboot — reboot miner setpower — set power mode (normal/low/high) setled [on|off] — toggle LED ``` ```text quit / exit — exit client ```

#### 3.4 Tear down When you're done, exit the client and stop the stack: ```text mdk> quit ``` Then `Ctrl+C` in Terminal 1. ### 4 (Optional) enable Gateway for HTTP access In **Terminal 1**, `Ctrl+C` the running stack, then restart with `--app-node`: ```bash node examples/backend/mdk-e2e/server.js --app-node ``` You'll see an extra line in the startup banner: ```text App-node: http://localhost:3000 (noAuth mode) ``` Confirm it's alive — Gateway has no index page, so hit `/auth/site` directly: ```bash curl http://localhost:3000/auth/site ``` You should see something like `{"site":"Site_Name"}`. In `noAuth` mode most data endpoints (e.g. `/auth/list-things`, `/auth/miners`) are unavailable — they require the cache and auth config that the full Gateway service sets up. `--app-node` in `server.js` is a development shortcut; for full REST access to device telemetry, run Gateway as a full service. See [`backend/core/app-node/`](https://github.com/tetherto/mdk/blob/main/backend/core/app-node/README.md) for setup. `--app-node` runs in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost. ## What just happened Your stack wired up, in order: 1. **Mock device**:`server.js` calls `wmMock.createServer({ port: 14028, ... })` — an HTTP server speaking the Whatsminer protocol with canned telemetry. 2. **Kernel**: `getOrk()` boots the kernel, generates a random DHT topic, and opens an IPC socket at the default path (`os.tmpdir()/mdk/ork.sock`). 3. **Worker**: `startWorker(WM_M56S, { ork })` instantiates the Whatsminer manager, mounts its protocol adapter, and registers with Kernel directly — no DHT round-trip because they share the process. 4. **Thing registration**: `manager.registerThing({ info, opts })` tells the Worker about the device at `127.0.0.1:14028`. The Worker stores the registration and starts polling. 5. **Client**: `client.js` opens the IPC socket from a second process and sends MDK Protocol envelopes (`worker.list`, `telemetry.pull`, `command.request`, ...). Kernel routes them to the Worker, the Worker hits the mock, and the response flows back over IPC. No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel. `client.js` already speaks MDK Protocol over IPC, so it talks to Kernel directly. Gateway becomes mandatory only when the consumer can't open a UNIX socket. See [`architecture.md#gateway`](/concepts/architecture#gateway). ## Cleanup `Ctrl+C` in Terminal 1 stops the Worker, Kernel, and mock cleanly. `run.js` deletes its own state directory on exit. `server.js` leaves data under `os.tmpdir()/mdk/` — safe to ignore, or remove with: ```bash rm -rf "$TMPDIR/mdk" /tmp/mdk ``` ## Next steps - Go deeper and [run the dashboard demo](/tutorials/full-stack/dashboard): put a browser dashboard on a running stack with live charts. - Or go simpler and walk the simpler [single-script Antminer path](/tutorials/backend-stack/run) - Run a [full site (multiple Workers and devices):](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - Understand the [install pattern for any Worker](https://github.com/tetherto/mdk/blob/main/backend/workers/install-pattern.md) - Read all [runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # Wire React (/quickstart/wire-react) This page walks through the minimum integration of the MDK UI toolkit into a React application. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ {/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */} ## Install ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` Then add to your app's `package.json`: ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` [Wrap your app](/quickstart/wire-react) in `` from `@tetherto/mdk-react-adapter` when using connected foundation components or adapter store hooks. > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. ## Wrap your app in MdkProvider `MdkProvider` sets up the TanStack `QueryClient` and the API base URL context. It is required for foundation hooks and components that read shared app state. ```tsx // main.tsx ReactDOM.createRoot(rootElement).render( , ) ``` ## Use the adapter hooks inside React Each hook subscribes the component to the relevant Zustand store and re-renders only when the selected slice changes. ```tsx const Toolbar = () => { const { permissions } = useAuth() const { selectedDevices } = useDevices() const { setAddPendingSubmissionAction } = useActions() // ... } ``` ## Or read / write stores directly outside React The vanilla stores expose `getState()` / `setState()` so utility code, side-effect handlers, and tests can interact with the same source of truth. ```tsx // Outside React (utilities, sagas, etc.) you can read/write directly: devicesStore.getState().setSelectedDevices([]) actionsStore.getState().setAddPendingSubmissionAction({ /* … */ }) ``` ## Theme via design tokens and @layer mdk The compiled stylesheet declares `@layer base`, `mdk`, `app` — so unlayered or `@layer app` styles in your application always win against devkit component styles. MDK ships with `--mdk-color-primary: #f7931a`; override tokens in `:root` only when reskinning. ```css /* app.css — imported AFTER @tetherto/mdk-react-devkit/styles.css */ :root { --mdk-color-primary: #f7931a; --mdk-radius: 6px; } @layer app { .mdk-button--variant-primary { letter-spacing: 0.04em; } } ``` See [Theme](/reference/ui/react/core/theme) for design tokens and `@layer` override rules. ## Next steps - [Tutorial](/tutorials/ui/react/tutorial) — full integration walkthrough - [Hooks](/reference/app-toolkit/hooks) — [state hooks](/reference/app-toolkit/hooks/state), [component hooks](/reference/app-toolkit/hooks/components), and [utility hooks](/reference/app-toolkit/hooks/utilities) - [Explore the demo](/tutorials/ui/explore-the-demo) — run the demo browser without adding MDK to your own app yet - [Core](/reference/ui/react/core) — building block reference (`@tetherto/mdk-react-devkit/core`) - [Foundation](/reference/ui/react/foundation) — mining-domain components (`@tetherto/mdk-react-devkit/foundation`) # Reference (/reference) The Reference section indexes the canonical specs for everything MDK exposes: field semantics, signatures, transition rules, and contracts. Reach for it when you need exact shapes. For narrative explanations, see [Architecture](/concepts/architecture); for step-by-step instructions, see [Get started](/quickstart). ## Browse by stack area ### App Toolkit - **[UI Devkit](/reference/app-toolkit/ui-devkit)**: constants, hooks, types, and utilities for the React UI Devkit - **[UI Foundation](/reference/app-toolkit/ui-foundation)**: framework-agnostic headless Zustand stores and TanStack Query factory - **[Hooks](/reference/app-toolkit/hooks)**: complete hook catalog: data, state, component, and utility hooks across the adapter and devkit packages - **[UI CLI](/reference/app-toolkit/ui-cli)**: command reference for the UI CLI (agent registry, scaffold, and verify) ### Kernel - **[Kernel](/reference/kernel)**: kernel module specs, state machines, transition tables, and recovery behavior ### MDK Protocol - **[Protocol](/reference/protocol)**: envelope schema, request/response examples, action catalogue, and base command set - *Capability contract*: coming soon ### Hardware - **[Supported hardware](/reference/supported-hardware)**: miners, containers, power meters, sensors, and mining-pool integrations # Hooks (/reference/app-toolkit/hooks) Complete hook catalog for the MDK App Toolkit, covering hooks from both `@tetherto/mdk-react-adapter` (data, state, utilities) and `@tetherto/mdk-react-devkit` (component hooks). Grouped by what each hook depends on rather than which package ships it — this matches the [Developer entry points](/concepts/stack/app-toolkit#developer-entry-points) model where the adapter and the UI Devkit are siblings, so you can adopt only the layers you need. ## At a glance | Bucket | Page | What it covers | Needs | |---|---|---|---| | Components | [Component hooks](/reference/app-toolkit/hooks/components) | Hooks coupled to MDK styled components or shell layout (notifications, forms, charts, dashboards, filters, widgets, tables, reporting) | `@tetherto/mdk-react-devkit` and (for some) `` | | Data | [Data hooks](/reference/app-toolkit/hooks/data) | Adapter hooks that fetch and shape site, pool, dashboard, chart, and auth data | `` from `@tetherto/mdk-react-adapter` | | State | [State hooks](/reference/app-toolkit/hooks/state) | React-bound views of the headless `@tetherto/mdk-ui-foundation` Zustand stores | `` from `@tetherto/mdk-react-adapter` | | Utilities | [Utility hooks](/reference/app-toolkit/hooks/utilities) | Generic React helpers, mining-domain transforms, permission checks, and TanStack Query re-exports | `@tetherto/mdk-react-adapter` and (for some) `` | ## All hooks ### Components @tetherto/mdk-react-devkit | Sub-group | Hooks | |---|---| | Charts | [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck), [`useEbitda`](/reference/app-toolkit/hooks/components#useebitda), [`useEnergyBalanceViewModel`](/reference/app-toolkit/hooks/components#useenergybalanceviewmodel) | | Dashboards | [`usePoolConfigs`](/reference/app-toolkit/hooks/components#usepoolconfigs), [`useSiteOverviewDetailsData`](/reference/app-toolkit/hooks/components#usesiteoverviewdetailsdata) | | Filters | [`useReportTimeFrameSelectorState`](/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate), [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols) | | Forms | [`useFormField`](/reference/app-toolkit/hooks/components#useformfield), [`useFormReset`](/reference/app-toolkit/hooks/components#useformreset) | | Notifications | [`useNotification`](/reference/app-toolkit/hooks/components#usenotification) | | Reporting | [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate), [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite) | | Shell | [`useHeaderControls`](/reference/app-toolkit/hooks/components#useheadercontrols), [`useSidebarExpandedState`](/reference/app-toolkit/hooks/components#usesidebarexpandedstate), [`useSidebarSectionState`](/reference/app-toolkit/hooks/components#usesidebarsectionstate) | | Tables | [`useGetAvailableDevices`](/reference/app-toolkit/hooks/components#usegetavailabledevices) | | Widgets | [`useFinancialDateRange`](/reference/app-toolkit/hooks/components#usefinancialdaterange) | ### Data @tetherto/mdk-react-adapter | Sub-group | Hooks | |---|---| | Auth and token | [`useAuthToken`](/reference/app-toolkit/hooks/data#useauthtoken), [`useTokenPolling`](/reference/app-toolkit/hooks/data#usetokenpolling) | | Chart data | [`useConsumptionChartData`](/reference/app-toolkit/hooks/data#useconsumptionchartdata), [`useHashrateChartData`](/reference/app-toolkit/hooks/data#usehashratechartdata), [`usePowerModeTimelineData`](/reference/app-toolkit/hooks/data#usepowermodetimelinedata) | | Dashboard | [`useDashboardDateRange`](/reference/app-toolkit/hooks/data#usedashboarddaterange), [`useDashboardExport`](/reference/app-toolkit/hooks/data#usedashboardexport), [`useDashboardTimeRange`](/reference/app-toolkit/hooks/data#usedashboardtimerange) | | Incidents | [`useActiveIncidents`](/reference/app-toolkit/hooks/data#useactiveincidents) | | Pool data | [`usePoolRows`](/reference/app-toolkit/hooks/data#usepoolrows), [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | | Site data | [`useSiteConsumption`](/reference/app-toolkit/hooks/data#usesiteconsumption), [`useSiteConsumptionChartData`](/reference/app-toolkit/hooks/data#usesiteconsumptionchartdata), [`useSiteContainerCapacity`](/reference/app-toolkit/hooks/data#usesitecontainercapacity), [`useSiteEfficiency`](/reference/app-toolkit/hooks/data#usesiteefficiency), [`useSiteHashrate`](/reference/app-toolkit/hooks/data#usesitehashrate), [`useSiteMinerCounts`](/reference/app-toolkit/hooks/data#usesiteminercounts), [`useSiteMinerStats`](/reference/app-toolkit/hooks/data#usesiteminerstats), [`useSitePowerMeter`](/reference/app-toolkit/hooks/data#usesitepowermeter), [`useSitesOverviewData`](/reference/app-toolkit/hooks/data#usesitesoverviewdata) | ### State @tetherto/mdk-react-adapter | Hook | Summary | |---|---| | [`useAuth`](/reference/app-toolkit/hooks/state#useauth) | React view of the headless `authStore` (token, permissions) | | [`useDevices`](/reference/app-toolkit/hooks/state#usedevices) | React view of the headless `devicesStore` (device list, selection) | | [`useTimezone`](/reference/app-toolkit/hooks/state#usetimezone) | React view of the headless `timezoneStore` (operator timezone) | | [`useNotifications`](/reference/app-toolkit/hooks/state#usenotifications) | React view of the headless `notificationStore` (unread counter) | | [`useActions`](/reference/app-toolkit/hooks/state#useactions) | React view of the headless `actionsStore` (pending submissions) | ### Utilities @tetherto/mdk-react-adapter + @tetherto/mdk-react-devkit/foundation | Sub-group | Hooks | |---|---| | Device and IP | [`usePduViewer`](/reference/app-toolkit/hooks/utilities#usepduviewer) | | Domain transforms | [`useCostSummary`](/reference/app-toolkit/hooks/utilities#usecostsummary), [`useHashBalance`](/reference/app-toolkit/hooks/utilities#usehashbalance), [`useSubsidyFees`](/reference/app-toolkit/hooks/utilities#usesubsidyfees), [`useUpdateExistedActions`](/reference/app-toolkit/hooks/utilities#useupdateexistedactions) | | Generic React | [`useLocalStorage`](/reference/app-toolkit/hooks/utilities#uselocalstorage), [`useKeyDown`](/reference/app-toolkit/hooks/utilities#usekeydown), [`useWindowSize`](/reference/app-toolkit/hooks/utilities#usewindowsize), [`usePlatform`](/reference/app-toolkit/hooks/utilities#useplatform), [`useDeviceResolution`](/reference/app-toolkit/hooks/utilities#usedeviceresolution), [`useBeepSound`](/reference/app-toolkit/hooks/utilities#usebeepsound), [`usePagination`](/reference/app-toolkit/hooks/utilities#usepagination), [`useSubtractedTime`](/reference/app-toolkit/hooks/utilities#usesubtractedtime), [`useTimezoneFormatter`](/reference/app-toolkit/hooks/utilities#usetimezoneformatter) | | Permissions | [`useCheckPerm`](/reference/app-toolkit/hooks/utilities#usecheckperm), [`useHasPerms`](/reference/app-toolkit/hooks/utilities#usehasperms), [`useIsFeatureEditingEnabled`](/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) | | TanStack Query re-exports | [Re-exports table](/reference/app-toolkit/hooks/utilities#tanstack-query-re-exports) | ## Imports ```tsx // Data hooks ``` # Component hooks (/reference/app-toolkit/hooks/components) @tetherto/mdk-react-devkit Hooks that wrap or compose styled MDK components — notifications, sidebar/header shell, forms, filters, widgets, tables, charts, and dashboards. Adopt these when you are using `@tetherto/mdk-react-devkit` for your UI. If you bring your own components, you may not need anything here. Start with [State hooks](/reference/app-toolkit/hooks/state) or [Utility hooks](/reference/app-toolkit/hooks/utilities) instead. ## At a glance | Sub-group | Hooks | |---|---| | [Notifications](#notifications) | `useNotification` | | [Shell](#shell) | `useHeaderControls`, `useSidebarExpandedState`, `useSidebarSectionState` | | [Forms](#forms) | `useFormField`, `useFormReset` | | [Filters](#filters) | `useReportTimeFrameSelectorState`, `useTimeframeControls` | | [Widgets](#widgets) | `useFinancialDateRange` | | [Tables](#tables) | `useGetAvailableDevices` | | [Charts](#charts) | `useChartDataCheck`, `useEbitda`, `useEnergyBalanceViewModel` | | [Dashboards](#dashboards) | `usePoolConfigs`, `useSiteOverviewDetailsData` | | [Reporting](#reporting) | `useOperationsDashboard`, `useHashrate`, `useEnergyReportSite` | ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) - For hooks that read from headless stores (`useNotification`, view-model hooks): [wrap your app in ``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) ## Import ```tsx useChartDataCheck, useEbitda, useEnergyBalanceViewModel, useFinancialDateRange, useGetAvailableDevices, useHeaderControls, useNotification, useOperationsDashboard, usePoolConfigs, useReportTimeFrameSelectorState, useSiteOverviewDetailsData, useTimeframeControls, } from '@tetherto/mdk-react-devkit/foundation' useFormField, useFormReset, useSidebarExpandedState, useSidebarSectionState, } from '@tetherto/mdk-react-devkit/core' ``` ## Notifications ### `useNotification` @tetherto/mdk-react-devkit/foundation Show toast notifications backed by the headless `notificationStore`. Supports success, error, info, and warning variants. ```tsx ``` #### Returns | Member | Type | Description | |--------|------|-------------| | `notifySuccess` | `function` | Show success toast | | `notifyError` | `function` | Show error toast | | `notifyInfo` | `function` | Show info toast | | `notifyWarning` | `function` | Show warning toast | #### Method signature ```tsx notifySuccess(message: string, description?: string, options?: NotificationOptions) ``` #### Options Notification methods accept an optional third `options` argument: | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `duration` | Optional | `number` | `3000` | Duration in milliseconds (`0` = no autoclose) | | `position` | Optional | `ToastPosition` | `'top-left'` | Toast position on screen | | `dontClose` | Optional | `boolean` | `false` | When `true`, prevents autoclose | #### Example ```tsx function SaveButton() { const { notifySuccess, notifyError } = useNotification() const handleSave = async () => { try { await saveData() notifySuccess('Saved', 'Your changes have been saved.') } catch (error) { notifyError('Error', 'Failed to save changes.', { dontClose: true }) } } return } ``` ## Shell ### `useHeaderControls` @tetherto/mdk-react-devkit/foundation Read/write hook for the global header-controls store (toggles, sticky flag, theme). ```tsx ``` #### Returns | Member | Type | Description | |--------|------|-------------| | `preferences` | `HeaderPreferences` | Current visibility state for each header item | | `isLoading` | `boolean` | Loading state | | `error` | `Error \| null` | Error state | | `handleToggle` | `function` | Toggle a header item visibility | | `handleReset` | `function` | Reset to default preferences | `handleToggle` and `handleReset` both call `notifySuccess` internally. Every invocation produces a toast notification; avoid calling them in response to fast-changing state. #### Example ```tsx function HeaderSettings() { const { preferences, handleToggle, handleReset } = useHeaderControls() return (

{Object.entries(preferences).map(([key, visible]) => ( handleToggle(key, value)} /> ))}

) } ``` ### `useSidebarExpandedState` @tetherto/mdk-react-devkit/core Persist sidebar expanded/collapsed state in `localStorage` so the layout survives reloads. ```tsx ``` #### Example ```tsx function AppSidebar() { const [expanded, setExpanded] = useSidebarExpandedState(false) return ( ) } ``` ### `useSidebarSectionState` @tetherto/mdk-react-devkit/core Persist individual sidebar section open/closed states in `localStorage`. ```tsx ``` #### Example ```tsx function SidebarSection({ id, title, children }) { const [open, setOpen] = useSidebarSectionState(id, true) return (

{open ? children : null}

) } ``` ## Forms ### `useFormField` @tetherto/mdk-react-devkit/core Read-only context hook for form field children — returns the field's id, error state, and ARIA attributes. ```tsx ``` #### Example ```tsx // Custom component that reads field context — must be rendered inside / function FieldStatusDot() { const { invalid, isDirty } = useFormField() return ( ) } ``` ### `useFormReset` @tetherto/mdk-react-devkit/core Hook to handle form reset with callbacks. ```tsx ``` #### Example ```tsx type MinerFields = { name: string; ip: string } function MinerEditForm({ onSubmit }: { onSubmit: (v: MinerFields) => void }) { const form = useForm({ defaultValues: { name: '', ip: '' } }) const { resetForm, isDirty } = useFormReset({ form, onAfterReset: () => console.log('Form reset'), }) return (

) } ``` ## Filters ### `useReportTimeFrameSelectorState` @tetherto/mdk-react-devkit/foundation State hook backing the reporting time-frame selector — exposes the active window and setters. ```tsx ``` #### Example ```tsx function ReportDateBar() { const { start, end, presetTimeFrame, setPresetTimeFrame } = useReportTimeFrameSelectorState() return (

{start.toLocaleDateString()} – {end.toLocaleDateString()}

) } ``` ### `useTimeframeControls` @tetherto/mdk-react-devkit/foundation Core state machine for TimeframeControls — owns year / month / week selection and resolves the date-range output. ```tsx ``` #### Example ```tsx function YearMonthPicker({ dateRange, onRangeChange, onTimeframeTypeChange }) { const { selectedYear, selectedMonth, handleYearChange, handleMonthTreeChange, yearSelectValue, monthSelectValue, } = useTimeframeControls({ dateRange, timeframeType: null, onRangeChange, onTimeframeTypeChange, isWeekSelectVisible: false, weekTree: false, }) return (

) } ``` ## Widgets ### `useFinancialDateRange` @tetherto/mdk-react-devkit/foundation Resolves the active financial date range (start/end) used by every reporting-section query. ```tsx ``` #### Example ```tsx function ReportingToolbar({ timezone }: { timezone: string }) { const { datePicker, dateRange, onDateRangeReset } = useFinancialDateRange({ timezone }) return (

{datePicker} {dateRange && (

{new Date(dateRange.start).toLocaleDateString()} –{' '} {new Date(dateRange.end).toLocaleDateString()}

)}

) } ``` ## Tables ### `useGetAvailableDevices` @tetherto/mdk-react-devkit/foundation Transforms the host's device list into the available container and miner type sets used by device explorer. Pass `data` from your query result. ```tsx ``` #### Example ```tsx function DeviceTypeFilter({ devices }) { const { availableContainerTypes, availableMinerTypes } = useGetAvailableDevices({ data: devices }) return (

) } ``` ## Charts ### `useChartDataCheck` @tetherto/mdk-react-devkit/foundation Check if chart data is empty or unavailable. Returns `true` if empty (show empty state), `false` if data exists (show chart). ```tsx ``` Pass chart input in one of two shapes: 1. **`dataset`**: direct dataset for BarChart-style usage. 2. **`data`**: Chart.js-shaped object with `datasets` (LineChart) or a `dataset` property. Provide at least one of `dataset` or `data` for a meaningful empty check. #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `dataset` | Optional | `object \| array` | none | Direct dataset for BarChart; set `dataset` or `data` (at least one) for a meaningful check | | `data` | Optional | `object` | none | Chart.js-shaped object with `datasets` (LineChart) or `dataset` property; set `dataset` or `data` (at least one) | #### Returns | Type | Description | |------|-------------| | `boolean` | `true` if data is empty, `false` if data exists | #### Example ```tsx function HashrateChart({ dataset }) { const isEmpty = useChartDataCheck({ dataset }) if (isEmpty) { return } return } ``` ```tsx function TemperatureChart({ data }) { const isEmpty = useChartDataCheck({ data }) return isEmpty ? ( ) : ( ) } ``` #### Chart utility integration `useChartDataCheck` expects **Chart.js-shaped** `data` (`{ labels, datasets }`), not raw `{ labels, series }` from app hooks. Convert hook output with the [**`buildBarChartData` utility**](/reference/ui/react/core/components/charts/composition#chart-utilities) from `@tetherto/mdk-react-devkit/core`, then pass the result to **`useChartDataCheck`**. ```tsx function RevenueBarChart({ hookOutput }) { const chartData = buildBarChartData(hookOutput) const isEmpty = useChartDataCheck({ data: chartData }) return ( ) } ``` For the full `BarChartInput` shape, per-dataset `datalabels` merge, and all-zero empty rules, see [Hook-shaped bar data (`buildBarChartData`)](/reference/ui/react/core/components/charts/composition#hook-shaped-bar-data). ### `useEbitda` @tetherto/mdk-react-devkit/foundation Transforms an `EbitdaResponse` and date-range options into query params and a chart-ready EBITDA view-model. ```tsx ``` #### Example ```tsx // Wire your query result in; consume queryParams to drive the fetch function EbitdaSection({ ebitdaResponse, isLoading, fetchErrors }) { const { datePicker, dateRange, queryParams, errors } = useEbitda({ ebitda: ebitdaResponse, isLoading, fetchErrors, }) // Pass queryParams to your data-fetching layer whenever the date range changes // e.g. useGetEbitdaQuery(queryParams, { skip: !queryParams }) return (

{datePicker} {errors.length > 0 &&

{errors.join(', ')}

}

) } ``` ### `useEnergyBalanceViewModel` @tetherto/mdk-react-devkit/foundation Computes the full EnergyBalance view model from raw API data, managing tab selection and display-mode state. ```tsx ``` #### Example ```tsx function EnergyBalancePanel({ data, isLoading, fetchErrors, dateRange, availablePowerMW }) { const { viewModel, onTabChange, onRevenueDisplayModeChange } = useEnergyBalanceViewModel({ data, isLoading, fetchErrors, dateRange, availablePowerMW, }) return (

{viewModel.isLoading &&

Loading…

} {viewModel.errors.length > 0 &&

{viewModel.errors.join(', ')}

}

) } ``` ## Dashboards ### `usePoolConfigs` @tetherto/mdk-react-devkit/foundation Transforms raw pool-configuration rows from your API into `PoolSummary` objects for the Pool Manager UI. Fetch with TanStack Query in the host app, then pass `data`, `isLoading`, and `error` into this hook. Typical usage: fetch with TanStack Query in the host app, then pass `data`, `isLoading`, and `error` into this hook. Foundation components such as [`PoolManagerPools`](/reference/ui/react/foundation/pool-manager/pools) and [`Miner explorer`](/reference/ui/react/foundation/pool-manager/miner-explorer) expect data shaped this way. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `data` | Optional | `PoolConfigData[]` | none | Raw pool configuration rows from your API | | `isLoading` | Optional | `boolean` | `false` | When `true`, the host should show a loading state | | `error` | Optional | `unknown` | none | Error from your query; surfaced to pool-manager components | #### Returns | Member | Type | Description | |--------|------|-------------| | `pools` | `PoolSummary[]` | Normalized pool list for lists and accordions | | `poolIdMap` | `Record` | Lookup by pool `id` | | `isLoading` | `boolean` | Same as the option you passed in | | `error` | `unknown` | Same as the option you passed in | #### Example ```tsx const { data, isLoading, error } = useGetPoolConfigsQuery({}) return usePoolConfigs({ data, isLoading, error }) } ``` ```tsx function PoolsPage({ poolConfig }: { poolConfig: PoolConfigData[] }) { const { pools, isLoading, error } = usePoolConfigs({ data: poolConfig }) if (isLoading) return if (error) return Failed to load pools return (

{pool.name}

) } ``` ### `useSiteOverviewDetailsData` @tetherto/mdk-react-devkit/foundation Composes the per-site overview view-model: pools, performance series, and recent activity. ```tsx ``` #### Example ```tsx function SiteOverviewCard({ unit, pdus, connectedMiners, isLoading }) { const { containerHashRate, isContainerRunning, minersHashmap, segregatedPduSections, } = useSiteOverviewDetailsData(unit, { pdus, connectedMiners, isLoading }) return (

Hashrate: {containerHashRate}

Status: {isContainerRunning ? 'Running' : 'Offline'}

Miners mapped: {Object.keys(minersHashmap).length}

PDU sections: {Object.keys(segregatedPduSections).join(', ')}

) } ``` ## Reporting ### `useOperationsDashboard` @tetherto/mdk-react-devkit/foundation Shapes raw operational metric logs into chart-ready payloads for the four [`OperationalDashboard`](/reference/ui/react/foundation/reporting/operational#operationaldashboard) cards. It never fetches — wire your data layer (TanStack Query, RTK Query, fixtures) and pass the results in. All unit conversion and series shaping (MH/s → TH/s, W → MW) happens inside the hook so the dashboard components stay purely presentational. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `hashrate` | Optional | `OperationsTrendInput` | none | Hashrate log and loading/error state; `log` entries carry `{ ts, value }` with `value` in MH/s (converted to TH/s internally) | | `consumption` | Optional | `OperationsTrendInput` | none | Power consumption log; `value` in Watts (converted to MW internally) | | `efficiency` | Optional | `OperationsTrendInput` | none | Site efficiency log; `value` in W/TH/s (no conversion) | | `miners` | Optional | `OperationsMinersInput` | none | Per-day miner status counts; `log` entries carry `{ ts, online, error, offline, sleep, maintenance }` | Each `OperationsTrendInput` entry also accepts `nominalValue` (same base unit as `log`) which renders a flat reference line on the chart, and `isLoading` / `error` passed through to the card. #### Returns | Member | Type | Description | |--------|------|-------------| | `hashrate` | `{ data, isLoading, error }` | `LineChartCardData` payload for the hashrate card | | `consumption` | `{ data, isLoading, error }` | `LineChartCardData` payload for the power-consumption card | | `efficiency` | `{ data, isLoading, error }` | `LineChartCardData` payload for the site-efficiency card | | `miners` | `{ data, isLoading, error }` | `{ labels, datasets }` stacked-bar payload for the miners-status card | #### Example ```tsx function OperationsDashboardPage({ hashrateLog, consumptionLog, efficiencyLog, minersLog, isLoading }) { const vm = useOperationsDashboard({ hashrate: { log: hashrateLog, nominalValue: 150_000, isLoading }, consumption: { log: consumptionLog, isLoading }, efficiency: { log: efficiencyLog, isLoading }, miners: { log: minersLog, isLoading }, }) return ( ) } ``` ### `useHashrate` @tetherto/mdk-react-devkit/foundation Base hook for a single Hashrate tab in single-site mode. Normalises a grouped-hashrate query result into the `{ log, isLoading, error }` shape consumed by ``, ``, and ``. Call once per tab — each tab fetches independently because they use different `groupBy` axes. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `query` | Optional | `HashrateQueryState` | none | Result of fetching the v2 `/auth/metrics/hashrate?groupBy=…` endpoint. Wire your data layer (TanStack Query, RTK Query, fixtures) and pass the result here — this hook never fetches directly. | #### Returns | Member | Type | Description | |--------|------|-------------| | `log` | `HashrateGroupedLog \| undefined` | Normalised grouped-hashrate log; `undefined` while loading. | | `isLoading` | `boolean` | Loading state from the upstream query. | | `error` | `unknown` | Error from the upstream query, if any. | #### Example ```tsx function HashrateTab({ groupBy }) { const query = useQuery({ queryKey: ['hashrate', groupBy], queryFn: fetchHashrate }) const { log, isLoading, error } = useHashrate({ query }) return } ``` --- ### `useEnergyReportSite` @tetherto/mdk-react-devkit/foundation Merges site energy consumption data (from the v2 `/auth/metrics/consumption` endpoint) with snapshot tail-log and container list data for the Energy report site tab. Returns the combined view-model consumed by the energy report components. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `dateRange` | Required | `object` | none | **Required.** Active date range `{ start, end }` in ms epoch. | | `consumptionLog` | Required | `object` | none | **Required.** Raw consumption log from the `/auth/metrics/consumption` response. | | `consumptionLoading` | Required | `boolean` | none | **Required.** Loading state of the consumption query. | | `consumptionFetching` | Required | `boolean` | none | **Required.** Background-refetch state of the consumption query. | | `consumptionError` | Required | `unknown` | none | **Required.** Error state of the consumption query. | | `nominalPowerAvailabilityMw` | Required | `number \| undefined` | none | **Required.** Site nominal power capacity in MW from the nominal config. | | `nominalConfigLoading` | Required | `boolean` | none | **Required.** Loading state of the nominal config query. | | `tailLog` | Required | `object` | none | **Required.** Raw tail-log snapshot data. | | `tailLogLoading` | Required | `boolean` | none | **Required.** Loading state of the tail-log query. | | `containers` | Required | `object[]` | none | **Required.** Container list from the device query. | | `containersLoading` | Required | `boolean` | none | **Required.** Loading state of the container query. | #### Returns Returns a `UseEnergyReportSiteResult` object containing the merged power-consumption view-model, power-mode table rows, and combined loading/error states for each data source. Pass directly to the Energy report site-tab components. # Data hooks (/reference/app-toolkit/hooks/data) @tetherto/mdk-react-adapter TanStack Query–backed hooks that fetch live data from the MDK backend and project it into view-model shapes ready for MDK foundation components. These hooks sit in the adapter layer so that tag names, aggregate field keys, and unit conversions stay out of the devkit component layer. All hooks require [``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) to be mounted in the tree. ## At a glance | Sub-group | Hooks | |---|---| | [Alerts](#alerts) | `useCurrentAlertDevices`, `useHistoricalAlerts` | | [Auth and token](#auth-and-token) | `useAuthToken`, `useTokenPolling` | | [Chart data](#chart-data) | `useConsumptionChartData`, `useHashrateChartData`, `usePowerModeTimelineData` | | [Dashboard](#dashboard) | `useDashboardDateRange`, `useDashboardExport`, `useDashboardTimeRange` | | [Incidents](#incidents) | `useActiveIncidents` | | [Pool data](#pool-data) | `usePoolRows`, `usePoolStats` | | [Site data](#site-data) | `useSiteConsumption`, `useSiteConsumptionChartData`, `useSiteContainerCapacity`, `useSiteEfficiency`, `useSiteHashrate`, `useSiteMinerCounts`, `useSiteMinerStats`, `useSitePowerMeter`, `useSitesOverviewData` | ## Prerequisites - [Wrap your app in ``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx useActiveIncidents, useAuthToken, useConsumptionChartData, useCurrentAlertDevices, useDashboardDateRange, useDashboardExport, useDashboardTimeRange, useHashrateChartData, useHistoricalAlerts, usePoolRows, usePoolStats, usePowerModeTimelineData, useSiteConsumption, useSiteConsumptionChartData, useSiteContainerCapacity, useSiteEfficiency, useSiteHashrate, useSiteMinerCounts, useSiteMinerStats, useSitePowerMeter, useSitesOverviewData, useTokenPolling, } from '@tetherto/mdk-react-adapter' ``` ## Site data ### `useSitesOverviewData` Projects raw site-overview container rows and pool stats into a ``-ready shape. Each container receives its per-container hashrate in MH/s, an attached pool-stats row, and a `mining` / `offline` status derived from the underlying snapshot. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `units` | Required | `ContainerUnit[]` | none | **Required.** Raw container rows from the site overview query. | | `poolStats` | Required | `ContainerPoolStat[]` | none | **Required.** Per-container pool stat rows keyed by container id. | | `isLoading` | Required | `boolean` | none | **Required.** Combined loading state from the upstream queries. | | `tailLogItem` | Required | `SitesOverviewTailLogItem` | none | **Required.** Latest tail-log row from a `stat-1m` miner query; pass `_head(_head(rawResponse))`. | #### Returns | Member | Type | Description | |--------|------|-------------| | `units` | `ProcessedContainerUnit[]` | Processed containers with `hashrateMhs`, `status`, and `poolStats` attached. | | `isLoading` | `boolean` | Passes through the combined loading state from the options. | #### Example ```tsx function SiteOverview({ rawUnits, rawPoolStats, loading, latestTailLog }) { const { units, isLoading } = useSitesOverviewData({ units: rawUnits, poolStats: rawPoolStats, isLoading: loading, tailLogItem: latestTailLog, }) return } ``` ### `useSiteConsumption` Projects the freshest power sample from the dashboard's existing tail-log query into a scalar MW value for the header stats strip (``). Delegates fetching to [`useSiteConsumptionChartData`](#usesiteconsumptionchartdata). ```tsx ``` #### Options Accepts the same `UseConsumptionChartDataParams` object as [`useSiteConsumptionChartData`](#usesiteconsumptionchartdata). | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix, e.g. `'5m'`. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `tag` | Optional | `string` | `'t-miner'` | Thing tag. Use `'t-powermeter'` for transformer-level readings. | | `powerAttribute` | Optional | `string` | `'power_w_sum_aggr'` | Aggregate field name to read from the tail-log row. | | `refetchInterval` | Optional | `number` | `60000` | Polling interval in ms. Pass `0` to disable. | #### Returns | Member | Type | Description | |--------|------|-------------| | `valueMw` | `number \| undefined` | Latest aggregate value in MW; `undefined` while loading or with no data. | | `valueW` | `number \| undefined` | Raw backend value in watts. | | `isLoading` | `boolean` | Loading state from the upstream query. | ### `useSiteConsumptionChartData` TanStack Query hook that fetches site consumption tail-log samples and returns a ``-ready `ChartCardData` payload. Applies site-powermeter defaults and converts watts to MW. ```tsx ``` #### Options Same `UseConsumptionChartDataParams` as [`useSiteConsumption`](#usesiteconsumption). #### Returns A TanStack `UseQueryResult` whose `data` field is `ChartCardData` — the object accepted by ``. #### Example ```tsx function ConsumptionChart() { const { data, isLoading } = useSiteConsumptionChartData({ timeline: '5m' }) return } ``` ### `useSiteContainerCapacity` Reads the aggregated nominal miner capacity across all site containers from the 5-minute tail-log aggregate, giving the denominator shown in the header (e.g. the "2,188" in "MOS / 2,188"). ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | `300000` | Polling interval in ms. Pass `0` to disable. | #### Returns | Member | Type | Description | |--------|------|-------------| | `value` | `number \| undefined` | Total nominal miner slots across all site containers; `undefined` while loading. | | `isLoading` | `boolean` | Loading state. | ### `useSiteEfficiency` Derives site efficiency in W/TH/s by dividing the latest site consumption by the latest hashrate. Both upstream hooks are called internally; pass `powerW` to override the consumption source (e.g. to use a power-meter reading instead). ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix forwarded to both upstream hooks. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `tag` | Optional | `string` | none | Thing tag override forwarded to the consumption hook. | | `powerAttribute` | Optional | `string` | none | Aggregate field override forwarded to the consumption hook. | | `refetchInterval` | Optional | `number` | none | Polling interval in ms forwarded to both upstream hooks. | | `powerW` | Optional | `number` | none | When provided, skips the internal `useSiteConsumption` call and uses this watts value as the numerator directly. Pair with `useSitePowerMeter().valueW` for meter-level efficiency. | #### Returns | Member | Type | Description | |--------|------|-------------| | `valueWthS` | `number \| undefined` | Watts per TH/s; `undefined` while loading or when hashrate is zero. | | `isLoading` | `boolean` | `true` while either upstream hook is loading. | ### `useSiteHashrate` TanStack Query hook that reads the latest aggregate hashrate from the site tail-log and returns both a PH/s display value and the raw MH/s backend value. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix, e.g. `'5m'`. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `refetchInterval` | Optional | `number` | `60000` | Polling interval in ms. Pass `0` to disable. | #### Returns | Member | Type | Description | |--------|------|-------------| | `valuePhs` | `number \| undefined` | Latest aggregate value in PH/s; `undefined` while loading or with no data. | | `valueMhs` | `number \| undefined` | Latest aggregate value in MH/s (raw backend unit). | | `isLoading` | `boolean` | Loading state. | ### `useSiteMinerCounts` Polls the device list for miners and aggregates them into online / offline / error counts. Uses the `last.status` field on each device row. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | none | Polling interval in ms. | #### Returns | Member | Type | Description | |--------|------|-------------| | `total` | `number` | Total miner device count. | | `online` | `number` | Miners with status `online` or `on`. | | `offline` | `number` | Miners not online and not in error. | | `error` | `number` | Miners with status `error` or `alert`. | ### `useSiteMinerStats` Polls the `stat-rtd` realtime aggregate for the live miner stat summary — the MOS total, online/offline breakdown, and active pool worker count shown in the header. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | none | Polling interval in ms. | #### Returns | Member | Type | Description | |--------|------|-------------| | `mosTotal` | `number` | Count of miners that reported hashrate in the last minute (the MOS denominator). | | `online` | `number` | Miners online or with minor errors (green column). | | `offline` | `number` | Offline or sleeping miners. | | `notMining` | `number` | Miners not currently mining. | | `isLoading` | `boolean` | Loading state. | ### `useSitePowerMeter` Reads the current power-meter reading in watts from the site-level device tagged `t-powermeter`. Returns a MW conversion alongside the raw watts value. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `tag` | Optional | `string` | `'t-powermeter'` | Device tag to filter by. | | `refetchInterval` | Optional | `number` | none | Polling interval in ms. | #### Returns | Member | Type | Description | |--------|------|-------------| | `valueMw` | `number \| undefined` | Latest power-meter reading in MW; `undefined` when no device or no data. | | `valueW` | `number \| undefined` | Raw value in watts. | | `isLoading` | `boolean` | Loading state. | ## Pool data ### `usePoolRows` TanStack Query hook that fetches per-pool stats and transforms them into `PoolRow[]` objects shaped for the pool manager table. Hashrate is normalised from raw H/s to PH/s. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | `120000` | Polling interval in ms. Pass `0` to disable. | #### Returns A TanStack `UseQueryResult` whose `data` is `PoolRow[]`. | Member | Type | Description | |--------|------|-------------| | `id` | `string` | Stable React key derived from `poolType`. | | `name` | `string` | Display name in Moria style — `minerpool-{poolType}-shelf-0`. | | `poolType` | `string` | Raw pool type string, e.g. `'f2pool'`, `'ocean'`. | | `revenue24hBtc` | `number \| undefined` | 24 h revenue in BTC if reported. | | `hashrateHs` | `number \| undefined` | Hashrate in raw H/s. | | `hashratePhsDisplay` | `number \| undefined` | Hashrate in PH/s for display. | | `details` | `PoolDetail[]` | Array of label/value pairs for the expanded row. | ### `usePoolStats` TanStack Query hook that fetches per-pool stats and aggregates them into site-level totals — total workers, online workers, mismatch count, and aggregate hashrate in PH/s. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | `120000` | Polling interval in ms. Pass `0` to disable. | #### Returns | Member | Type | Description | |--------|------|-------------| | `total` | `number` | Total miners reported across all configured pools. | | `online` | `number` | Pool-reported active workers. | | `mismatch` | `number` | Difference between configured and active workers. | | `hashratePhs` | `number \| undefined` | Aggregate pool hashrate in PH/s; `undefined` while loading or with no data. | | `hashrateHs` | `number \| undefined` | Aggregate pool hashrate in raw H/s. | | `isLoading` | `boolean` | Loading state. | ## Dashboard ### `useDashboardDateRange` Owns the single source of truth for the dashboard's date-range picker: a `start` / `end` ms-epoch pair with setters and a reset helper that restores the default 24-hour window. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `initial` | Optional | `{ start: number; end: number }` | last 24 h | Initial date range. Defaults to the last 24 hours ending now. | #### Returns | Member | Type | Description | |--------|------|-------------| | `start` | `number` | Lower bound (ms epoch). | | `end` | `number` | Upper bound (ms epoch). | | `setRange` | `function` | Replace the current range. | | `reset` | `function` | Convenience: restore the default 24-hour window ending now. | #### Example ```tsx function DashboardHeader() { const { start, end, setRange, reset } = useDashboardDateRange() return } ``` ### `useDashboardExport` Reads cached query data for hashrate, consumption, incidents, and pool stats from the TanStack Query client and exposes `exportCsv`, `exportJson`, and a unified `export(format)` callable. Does not trigger refetches — the export represents exactly what is currently displayed. ```tsx ``` #### Options Accepts a `UseDashboardExportOptions` object containing `DashboardQueryRange` fields (`timeline`, `start`, `end`, `tag`) needed to reconstruct the query keys. | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix used to locate the cached chart queries. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `tag` | Optional | `string` | none | Thing tag override. | #### Returns | Member | Type | Description | |--------|------|-------------| | `exportCsv` | `function` | Triggers a browser file-download of the dashboard data as CSV. | | `exportJson` | `function` | Triggers a browser file-download as JSON. | | `export` | `function` | Unified callable — `export('csv')` or `export('json')`. | ### `useDashboardTimeRange` Tiny piece of scoped state for the dashboard's timeline selector. Owns the current `timeline` string and the canonical option list. Chart hooks (`useHashrateChartData`, `useSiteConsumptionChartData`, etc.) consume `timeline` as a prop. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `initial` | Optional | `string` | `'5m'` | Initial timeline value. | | `options` | Optional | `TimelineOption[]` | canonical list | Custom option list; defaults to the canonical set from `getTimelineOptions`. | #### Returns | Member | Type | Description | |--------|------|-------------| | `timeline` | `string` | Currently selected timeline string, e.g. `'5m'`. | | `options` | `TimelineOption[]` | Available options, ready for ``. | | `setTimeline` | `function` | Setter for the current timeline. | #### Example ```tsx function DashboardControls() { const { timeline, options, setTimeline } = useDashboardTimeRange() const { valuePhs } = useSiteHashrate({ timeline }) return ( <> {valuePhs?.toFixed(2)} PH/s ) } ``` ## Chart data ### `useConsumptionChartData` TanStack Query hook returning raw consumption tail-log samples. Most dashboards should use the higher-level [`useSiteConsumptionChartData`](#usesiteconsumptionchartdata), which wraps this hook and returns a ``-ready payload. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix, e.g. `'1m'`, `'5m'`. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `tag` | Optional | `string` | `'t-miner'` | Thing tag. Use `'t-powermeter'` for transformer-level consumption. | | `powerAttribute` | Optional | `string` | `'power_w_sum_aggr'` | Aggregate field name to read. | | `refetchInterval` | Optional | `number` | `60000` | Polling interval in ms. Pass `0` to disable. | #### Returns A TanStack `UseQueryResult` — raw tail-log matrix before projection. ### `useHashrateChartData` TanStack Query hook combining the site tail-log hashrate series with the per-pool hashrate history into a single `ChartCardData` payload for ``. Handles unit conversion from both MH/s (tail-log) and raw H/s (pool API) into PH/s for display. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix, e.g. `'5m'`. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `refetchInterval` | Optional | `number` | none | Polling interval in ms. | #### Returns A TanStack `UseQueryResult` whose `data` is `ChartCardData` — ready for ``. ### `usePowerModeTimelineData` TanStack Query hook returning power-mode and status samples shaped for ``. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `timeline` | Required | `string` | none | **Required.** Stat key suffix, e.g. `'1m'`. | | `start` | Optional | `number` | none | Lower time bound (ms epoch). | | `end` | Optional | `number` | none | Upper time bound (ms epoch). | | `tag` | Optional | `string` | none | Thing tag override. | | `refetchInterval` | Optional | `number` | none | Polling interval in ms. | #### Returns A TanStack `UseQueryResult`. ## Auth and token ### `useAuthToken` Reads `?authToken=…` from `window.location.search`, persists it into the headless `authStore`, and strips the parameter from the URL via `history.replaceState` so the token never lingers in the address bar. Router-agnostic by design. Returns the current token from the store so callers can gate navigation on authentication. ```tsx ``` #### Returns | Type | Description | |------|-------------| | `string \| null` | Current auth token from the `authStore`, or `null` when no token is present. | #### Example ```tsx function ProtectedRoute() { const token = useAuthToken() return token ? : } ``` ### `useTokenPolling` Polls the backend token-refresh endpoint at a fixed interval (default 250 s) and writes the new token back into the `authStore`. Fires the optional `onSessionEnded` callback on a 401 or 500, which MDK UI Shell uses to redirect back to `/signin`. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `intervalMs` | Optional | `number` | `250000` | Polling interval in ms. Backend token TTL defaults to 5 min (300 s); 250 s gives comfortable headroom. | | `enabled` | Optional | `boolean` | `true` when token present | Pass `false` to pause polling (e.g. on the sign-in page). | | `onSessionEnded` | Optional | `function` | none | Called on 401 or 500; use to navigate to the sign-in page. | #### Example ```tsx function App() { const navigate = useNavigate() useTokenPolling({ onSessionEnded: () => navigate('/signin') }) return } ``` ## Incidents ### `useActiveIncidents` TanStack Query hook returning the list of currently-firing alerts, shaped for ``. Queries devices that have a non-null `last.alerts` field and maps them via the `mapDevicesToIncidents` utility. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | `20000` | Polling interval in ms. Matches Moria's production cadence. Pass `0` to disable. | | `formatDate` | Optional | `function` | ISO string | Date formatter applied to the row body timestamp. | #### Returns A TanStack `UseQueryResult`. #### Example ```tsx function IncidentsFeed() { const { data: items = [], isLoading } = useActiveIncidents({ refetchInterval: 20_000 }) return } ``` ## Alerts Data hooks that back the full alerts surface: `useCurrentAlertDevices` feeds the `` / `` table with raw device rows; `useHistoricalAlerts` fetches and shapes the historical-alerts log for ``. Both require [``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) in the tree. See also [`useActiveIncidents`](#useactiveincidents) in the Incidents section, which hits the same `list-things` endpoint but maps results to the dashboard card's `IncidentRow[]` shape. ### `useCurrentAlertDevices` TanStack Query hook returning the raw devices that currently carry one or more alerts, as the nested `ListThingsDevice[][]` envelope the devkit `` / `` table expects. Unlike `useActiveIncidents`, this hook leaves the payload unshaped so the table can derive its own filter tokens and per-row status. Both hit `/auth/list-things`; this hook requests a wider field set and uses a distinct cache key. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `refetchInterval` | Optional | `number` | `20000` | Polling interval in ms. Matches the default production polling cadence. Pass `0` to disable. | | `filterTags` | Optional | `string[]` | none | Alerts search chips. Folded into the backend `list-things` selector — triggers a re-fetch that narrows the dataset server-side. | #### Returns A TanStack `UseQueryResult`. #### Example ```tsx function AlertsTable({ filterTags }) { const { data, isLoading } = useCurrentAlertDevices({ filterTags }) return } ``` ### `useHistoricalAlerts` TanStack Query hook for the historical-alerts log. Fetches the `[start, end]` range as successive `history-log` windows, merges results by `uuid`, and shapes rows for the devkit `` table via `mapHistoryLogToAlerts`. Range changes abort the in-flight chunk loop through the query's `AbortSignal`. By default the entire range is fetched in a single request. Pass a smaller `intervalMs` (e.g. `ONE_DAY_MS`) only for wide ranges where the backend would otherwise cap or slow a single query — that splits the fetch into sequential 24-hour windows. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `start` | Required | `number` | none | Lower bound of the look-back window (ms epoch). | | `end` | Required | `number` | none | Upper bound of the look-back window (ms epoch). | | `intervalMs` | Optional | `number` | whole range | Per-request window size in ms. Defaults to the whole range in one request; set a smaller value to chunk wide ranges into sequential fetches. | | `enabled` | Optional | `boolean` | `true` when range valid | Pass `false` to force-disable the query. Defaults to enabled when `start` and `end` are finite and `end > start`. | #### Returns A TanStack `UseQueryResult`. #### Example ```tsx function AlertHistory({ start, end, filterTags, localFilters, onDateRangeChange }) { const { data: alerts = [], isLoading } = useHistoricalAlerts({ start, end }) return ( ) } ``` #### Behavior notes - Wide ranges fan out into many requests. The MDK UI Shell page caps the default window at 14 days; pass a tighter `[start, end]` or set `intervalMs` to limit per-request payload size. - The hook removes duplicate rows by `uuid` after merging chunks, before passing them to `mapHistoryLogToAlerts`. # State hooks (/reference/app-toolkit/hooks/state) @tetherto/mdk-react-adapter State hooks bind the framework-agnostic [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) Zustand stores into React. Each hook subscribes the component to its store and re-renders only when the selected slice changes. Use these when you want headless state with your own components. The [Developer entry points](/concepts/stack/app-toolkit#developer-entry-points) table compares adoption layers. ## Prerequisites - [Wrap your app in ``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx useActions, useAuth, useDevices, useNotifications, useTimezone, } from '@tetherto/mdk-react-adapter' ``` ## `useAuth` @tetherto/mdk-react-adapter React-bound view of the headless [`authStore`](/reference/app-toolkit/ui-foundation). Exposes `token` and `permissions`; equivalent to `useStore(authStore)` with React subscription semantics. ```tsx ``` ### Example ```tsx function SessionStatus() { const { token } = useAuth() if (!token) return

return

Active session

} ``` ## `useDevices` @tetherto/mdk-react-adapter React-bound view of the headless [`devicesStore`](/reference/app-toolkit/ui-foundation). Exposes the device list, the currently selected devices, and helpers to mutate selection. ```tsx ``` ### Example ```tsx function DeviceToolbar() { const { selectedDevices, setSelectedDevices } = useDevices() return (

Selected: {selectedDevices.length}

) } ``` ## `useTimezone` @tetherto/mdk-react-adapter React-bound view of the headless [`timezoneStore`](/reference/app-toolkit/ui-foundation). Read or update the operator's timezone preference (IANA identifier). Use [`useTimezoneFormatter`](/reference/app-toolkit/hooks/utilities#usetimezoneformatter) when you also need date-formatting helpers. ```tsx ``` ### Example ```tsx function TimezonePicker() { const { timezone, setTimezone } = useTimezone() return ( ) } ``` ## `useNotifications` @tetherto/mdk-react-adapter React-bound view of the headless [`notificationStore`](/reference/app-toolkit/ui-foundation). Exposes the unread counter (`count`) plus `increment`, `decrement`, and `reset`. For the user-facing toast surface use [`useNotification`](/reference/app-toolkit/hooks/components#usenotification) from foundation. ```tsx ``` ### Example ```tsx function UnreadBadge() { const { count } = useNotifications() return } ``` ## `useActions` @tetherto/mdk-react-adapter React-bound view of the headless [`actionsStore`](/reference/app-toolkit/ui-foundation). Exposes the pending operator submission queue plus helpers like `setAddPendingSubmissionAction` and `removePendingSubmissionAction`. ```tsx ``` ### Example ```tsx function SubmissionTracker() { const { pendingSubmissions, setAddPendingSubmissionAction } = useActions() return (

{pendingSubmissions.length} pending submissions

) } ``` # Utility hooks (/reference/app-toolkit/hooks/utilities) @tetherto/mdk-react-adapter + @tetherto/mdk-react-devkit/foundation Generic React helpers, mining-domain transforms, permission checks, device/IP utilities, and a curated set of TanStack Query re-exports. Use these alongside [State hooks](/reference/app-toolkit/hooks/state) to wire app concerns (permissions, devices, viewport, formatting) without depending on MDK styled components. ## At a glance | Sub-group | Hooks | |---|---| | [Permissions](#permissions) | `useCheckPerm`, `useHasPerms`, `useIsFeatureEditingEnabled` | | [Generic React](#generic-react) | `useLocalStorage`, `useKeyDown`, `useWindowSize`, `usePlatform`, `useDeviceResolution`, `useBeepSound`, `usePagination`, `useSubtractedTime`, `useTimezoneFormatter` | | [Device and IP](#device-and-ip) | `usePduViewer` | | [Domain transforms](#domain-transforms) | `useCostSummary`, `useHashBalance`, `useSubsidyFees`, `useUpdateExistedActions` | | [TanStack Query re-exports](#tanstack-query-re-exports) | `useQuery`, `useMutation`, `useQueries`, `useInfiniteQuery`, `useIsFetching`, `useIsMutating`, `useQueryClient` | ## Prerequisites - [Wrap your app in ``](/quickstart/wire-react#wrap-your-app-in-mdkprovider) - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ## Import ```tsx useBeepSound, useCheckPerm, useDeviceResolution, useHasPerms, useIsFeatureEditingEnabled, useKeyDown, useLocalStorage, usePagination, usePduViewer, usePlatform, useSubtractedTime, useTimezoneFormatter, useWindowSize, } from '@tetherto/mdk-react-adapter' useCostSummary, useHashBalance, useSubsidyFees, useUpdateExistedActions, } from '@tetherto/mdk-react-devkit/foundation' ``` ## Permissions ### `useCheckPerm` @tetherto/mdk-react-adapter Check if the current user has a specific permission. Reads `permissions` from the adapter [`authStore`](/reference/app-toolkit/hooks/state#useauth). Prefer this over `useHasPerms` for single-permission gates. ```tsx ``` #### Example ```tsx function EditDevicesButton() { const canEdit = useCheckPerm('devices:edit') return canEdit ? : null } ``` ### `useHasPerms` @tetherto/mdk-react-adapter Returns a callable that accepts a permission request — a string, a string array (first match wins), or a check object. Reads from the adapter [`authStore`](/reference/app-toolkit/hooks/state#useauth). ```tsx ``` #### Example ```tsx function ContextMenu({ device }) { const hasPerms = useHasPerms() return ( {hasPerms(['devices:edit', 'devices:admin']) && Edit} {hasPerms('devices:delete') && Delete} ) } ``` ### `useIsFeatureEditingEnabled` @tetherto/mdk-react-adapter Returns whether the current user has the `features` capability to edit feature flags. ```tsx ``` #### Example ```tsx function FeatureFlagRow({ flag }) { const canEdit = useIsFeatureEditingEnabled() return } ``` ## Generic React ### `useLocalStorage` @tetherto/mdk-react-adapter Type-safe `localStorage` access with cross-tab synchronization. Returns `[value, setValue, removeValue]` and stays in sync across browser tabs via the `storage` event. ```tsx ``` #### Example ```tsx function ThemeToggle() { const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('app:theme', 'light') return } ``` ### `useKeyDown` @tetherto/mdk-react-adapter Track whether a specific keyboard key is currently pressed. Attaches global `keydown`/`keyup` listeners. Useful for modifier-key interactions like shift-click multi-select. ```tsx ``` #### Example ```tsx function MinerGrid({ miners }) { const shiftHeld = useKeyDown('Shift') return miners.map((m) => ( select(m, { range: shiftHeld })} /> )) } ``` ### `useWindowSize` @tetherto/mdk-react-adapter Track window width and height, refreshing on `resize`. Returns `{ windowWidth, windowHeight }`. Use [`useDeviceResolution`](#usedeviceresolution) when you only need a device-class branch rather than raw pixels. ```tsx ``` #### Example ```tsx function ResponsiveChart() { const { windowWidth } = useWindowSize() return } ``` ### `usePlatform` @tetherto/mdk-react-adapter Detect the host platform (iOS, Android, Mac, Windows, Linux) from the user agent. Returns the value matching the exported `OS_TYPES` constant; pair with `detectPlatform` for one-off checks outside React. ```tsx ``` #### Example ```tsx function PlatformBadge() { const platform = usePlatform() return Running on {platform} } ``` ### `useDeviceResolution` @tetherto/mdk-react-adapter Map window width to a device class (`mobile`, `tablet`, `desktop`) using the shared `BREAKPOINTS` constant. Cheaper than re-reading pixels in every render. ```tsx ``` #### Example ```tsx function Layout({ children }) { const device = useDeviceResolution() return device === 'mobile' ? {children} : {children} } ``` ### `useBeepSound` @tetherto/mdk-react-adapter Play a repeating beep when `isAllowed` is true. Configurable volume and interval (`delayMs`). The alarm is synthesised via the Web Audio API — no audio asset is bundled or fetched. Designed for audible critical alerts (overheating containers, equipment failure). ```tsx ``` #### Example ```tsx function CriticalAlertChime({ active }) { useBeepSound({ isAllowed: active, volume: 0.6, delayMs: 1500 }) return null } ``` ### `usePagination` @tetherto/mdk-react-adapter Manage pagination state and produce `{ limit, offset }` query arguments for API calls. Returns state shaped for the devkit `` component plus helpers to change page, page size, and total count. ```tsx ``` #### Options | Option | Status | Type | Default | Description | |--------|--------|------|---------|-------------| | `current` | Optional | `number` | `1` | Initial 1-indexed page | | `pageSize` | Optional | `number` | `20` | Initial rows per page | | `total` | Optional | `number` | none | Initial total row count | | `showSizeChanger` | Optional | `boolean` | `true` | Whether the UI exposes a page-size selector | #### Returns | Member | Type | Description | |--------|------|-------------| | `pagination` | `PaginationState` | `{ current, pageSize, showSizeChanger, total }` — spread onto `` | | `queryArgs` | `{ limit, offset }` | Query arguments for API calls | | `handleChange` | `function` | `(page, pageSize) => void` — pass to `` | | `setPagination` | `function` | Imperative pagination state update | | `reset` | `function` | Reset to initial state | | `setTotal` | `function` | Update total row count | | `hideNextPage` | `function` | Hide next page when the current page has fewer rows than `pageSize` | #### Example ```tsx function MinerList() { const { pagination, queryArgs, handleChange } = usePagination({ current: 1, pageSize: 25 }) const { data } = useQuery(['miners', queryArgs], () => fetchMiners(queryArgs)) return ( <> ) } ``` ### `useSubtractedTime` @tetherto/mdk-react-adapter Returns `Date.now() - diff`, refreshing on a fixed interval (default 5s). Useful for "synced N seconds ago" labels without forcing tree-wide re-renders. ```tsx ``` #### Example ```tsx function LastSyncedLabel({ lastSyncOffsetMs }) { const now = useSubtractedTime(lastSyncOffsetMs) return Synced {formatDistanceToNow(now)} ago } ``` ### `useTimezoneFormatter` @tetherto/mdk-react-adapter Read the app timezone from the adapter [`timezoneStore`](/reference/app-toolkit/hooks/state#usetimezone) and format dates for display. Use when foundation components or app code need timestamps in the operator-selected timezone (alerts, pool manager, dashboard widgets). ```tsx ``` #### Example ```tsx function AlertTimestamp({ raisedAt }) { const { getFormattedDate } = useTimezoneFormatter() return {getFormattedDate(raisedAt)} } ``` ## Device and IP ### `usePduViewer` @tetherto/mdk-react-adapter Pan/zoom controller for the PDU floor-plan viewer. Wraps `react-zoom-pan-pinch` with viewport-aware reset logic and a debounced "back to content" indicator that appears when the user pans the layout off-screen. ```tsx ``` #### Example ```tsx function PduFloorPlan() { const { onViewerInit, showBackToContent, handleBackToContent } = usePduViewer() return ( <> {/* …diagram… */} {showBackToContent && } ) } ``` ## Domain transforms ### `useCostSummary` @tetherto/mdk-react-devkit/foundation Base hook for the cost-summary reporting page (single-site mode). ```tsx ``` #### Example ```tsx // Wire your query result in; consume queryParams to drive the fetch function CostSummaryPage({ query }) { const { datePicker, queryParams, isLoading, error } = useCostSummary({ query }) // Pass queryParams to your data-fetching layer whenever the date range changes // e.g. useGetCostSummaryQuery(queryParams, { skip: !queryParams }) return (

{datePicker} {isLoading &&

Loading…

} {error &&

Failed to load cost data

}

) } ``` ### `useHashBalance` @tetherto/mdk-react-devkit/foundation Derives hash-balance metrics and chart datasets from finance log entries for the active date range, currency, and timeframe type. Used by hash balance panels. ```tsx ``` #### Example ```tsx function HashBalancePanel({ data, log, currency, dateRange }) { const { siteHashRevenueChartData, networkHashpriceChartData, combinedCostChartData, } = useHashBalance({ data, log, currency, dateRange }) return (

{/* Pass chart datasets to your BarChart components */}

{JSON.stringify(siteHashRevenueChartData?.labels, null, 2)}

{JSON.stringify(networkHashpriceChartData?.labels, null, 2)}

{JSON.stringify(combinedCostChartData?.labels, null, 2)}

) } ``` ### `useSubsidyFees` @tetherto/mdk-react-devkit/foundation Aggregates raw subsidy-fee log entries into chart-ready datasets keyed by the active period type (day / week / month / year) and surfaces a summary for the matching reporting widgets. Used by `Subsid… ```tsx ``` #### Example ```tsx function SubsidyFeesPanel({ data, dateRange }) { const { summary, subsidyFeesChartData, averageFeesChartData, isEmpty } = useSubsidyFees({ data, dateRange, }) if (isEmpty) return

No subsidy fee data for this period.

return (

Total fees: {(summary as any)?.total ?? '—'}

{/* Pass chart datasets to your BarChart components */}

{JSON.stringify(subsidyFeesChartData?.labels, null, 2)}

{JSON.stringify(averageFeesChartData?.labels, null, 2)}

) } ``` ### `useUpdateExistedActions` @tetherto/mdk-react-devkit/foundation Mutation hook that updates only the changed fields of an existing action record. ```tsx ``` #### Example ```tsx function DeviceActionBar({ actionType, pendingSubmissions, selectedDevices }) { const { updateExistedActions } = useUpdateExistedActions() const handleApply = () => { updateExistedActions({ actionType, pendingSubmissions, selectedDevices }) } return ( ) } ``` ## TanStack Query re-exports The adapter re-exports a curated set of [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) hooks so you can import data-fetching primitives from a single package alongside MDK helpers. The re-exports are unmodified — refer to the upstream TanStack Query documentation for full API details. | Hook | TanStack docs | | --- | --- | | `useQuery` | [TanStack `useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) | | `useMutation` | [TanStack `useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) | | `useQueries` | [TanStack `useQueries`](https://tanstack.com/query/latest/docs/framework/react/reference/useQueries) | | `useInfiniteQuery` | [TanStack `useInfiniteQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery) | | `useIsFetching` | [TanStack `useIsFetching`](https://tanstack.com/query/latest/docs/framework/react/reference/useIsFetching) | | `useIsMutating` | [TanStack `useIsMutating`](https://tanstack.com/query/latest/docs/framework/react/reference/useIsMutating) | | `useQueryClient` | [TanStack `useQueryClient`](https://tanstack.com/query/latest/docs/framework/react/reference/useQueryClient) | # UI CLI reference (/reference/app-toolkit/ui-cli) The **UI CLI** (`mdk-ui`, package `@tetherto/mdk-ui-cli`) is the command surface your AI agent uses to build with MDK. You usually never run it yourself, your agent does, after you [wire your IDE](/quickstart/connect-agents). This page documents the commands for when you want to drive or inspect the tooling by hand. Every command runs locally and prints JSON by default. Add `--format table` for human-readable output. There are no network or model calls: each command is a lookup against files MDK ships. ## At a glance | Bucket | Section | What it covers | |--------|---------|----------------| | Set up | [Set up a project](#set-up-a-project) | Wire your IDE with `init` | | Discover | [Discover what to use](#discover-what-to-use) | `suggest`, `hooks`, `stores`, `find` | | Read | [Read a component contract](#read-a-component-contract) | `docs`, `example` | | Recipes | [Follow a recipe](#follow-a-recipe) | `blueprints`, `blueprint` | | Scaffold | [Scaffold and verify](#scaffold-and-verify) | `add page`, `check`, `sync` | | Inspect | [Inspect the UI CLI itself](#inspect-the-ui-cli-itself) | `--json-help` | ## All commands | Command | Summary | |---------|---------| | [`init`](#init) | Bootstrap `.mdk/context.md` and IDE rules | | [`suggest`](#suggest) | Ranked shortlist from free-text intent | | [`hooks`](#hooks) | List adapter hooks (optional `--category`) | | [`stores`](#stores) | List Zustand stores and query helpers | | [`find`](#find) | Filter components by domain and capability | | [`docs`](#docs) | Print a component's `USAGE.md` | | [`example`](#example) | Print a runnable `*.example.tsx` | | [`blueprints`](#blueprints) | List curated intent-to-component recipes | | [`blueprint`](#blueprint) | Show one recipe in detail | | [`add page`](#add-page) | Scaffold a page with chosen components | | [`check`](#check) | Type-check a file against real APIs | | [`sync`](#sync) | Refresh `.mdk/context.md` | | [`--json-help`](#json-help) | Machine-readable CLI surface | ## The agent's decision flow Given an intent, the deterministic path a session follows is: ```mermaid flowchart TD intent["Plain-language intent"] suggest["mdk-ui suggest"] state{"State or hooks needed?"} hooks["mdk-ui hooks / stores"] blueprints["mdk-ui blueprints"] match{"Matching blueprint?"} blueprint["mdk-ui blueprint"] find["mdk-ui find"] docs["mdk-ui docs / example"] add["mdk-ui add page"] check["mdk-ui check"] intent --> suggest suggest --> state state -->|yes| hooks state -->|no| blueprints hooks --> add blueprints --> match match -->|yes| blueprint match -->|no| find blueprint --> docs find --> docs docs --> add add --> check ``` ## Set up a project ### init Bootstraps the current project with an agent-context file and an IDE rule so every AI session is wired automatically: ```bash npx @tetherto/mdk-ui-cli init --ide cursor # .mdk/context.md + .cursor/rules/mdk.mdc npx @tetherto/mdk-ui-cli init --ide claude # .mdk/context.md + CLAUDE.md ``` ## Discover what to use ### suggest Turns free text into a ranked shortlist across components, hooks, blueprints, and stores: ```bash mdk-ui suggest "show hashrate for a pool" ``` ### hooks Lists every hook exported from `@tetherto/mdk-react-adapter`, grouped by category (`store`, `utility`, `permission`, `ui`, `external`): ```bash mdk-ui hooks --format table # all adapter hooks mdk-ui hooks --category store --format table # store-binding hooks only ``` ### stores Describes the Zustand stores and TanStack Query helpers from `@tetherto/mdk-ui-foundation`: ```bash mdk-ui stores --format table # stores and query helpers mdk-ui stores --category devices --format table ``` ### find Filters the component library by domain and capability: ```bash mdk-ui find --domain mining-operations --capability hashrate-monitoring ``` ## Read a component contract ### docs Prints a component's usage notes: ```bash mdk-ui docs LineChartCard ``` ### example Prints a runnable example: ```bash mdk-ui example LineChartCard ``` ## Follow a recipe Blueprints are curated recipes that map a high-level intent to a concrete set of components and hooks. ### blueprints Lists available recipes: ```bash mdk-ui blueprints ``` ### blueprint Shows one recipe in detail: ```bash mdk-ui blueprint device-management ``` ## Scaffold and verify ### add page Scaffolds a page with the components you name: ```bash mdk-ui add page Dashboard --component LineChartCard ``` ### check Confirms a file compiles against the real component APIs: ```bash mdk-ui check src/pages/Dashboard.tsx ``` ### sync Keeps the `.mdk/context.md` agent-context file current as MDK updates: ```bash mdk-ui sync ``` ## Inspect the UI CLI itself ### json-help `--json-help` prints the full command surface, useful for meta-tooling that wants to discover commands without running them: ```bash mdk-ui --json-help ``` ## Next steps - [Build dashboards with your AI agent](/quickstart/connect-agents): the two-step flow most developers use - [UI Devkit](/reference/ui): the component library these commands draw from - [MDK repositories](/support/resources/repositories): source for the UI CLI and the agent-ready contract # UI Devkit (/reference/app-toolkit/ui-devkit) The UI Devkit is the frontend tools half of the [MDK App Toolkit](/concepts/stack/app-toolkit). This reference documents its constants, React hooks, TypeScript types, and helper utilities. ## Browse by topic | Topic | What's there | |-------|--------------| | [Constants](/reference/app-toolkit/ui-devkit/constants) | Colors, units, currency, chart configs and permissions, roles, header preferences| | [Hooks](/reference/app-toolkit/ui-devkit/hooks) | Discover hooks for monitoring and UI patterns; full reference at [Hooks](/reference/app-toolkit/hooks) | | [Types](/reference/app-toolkit/ui-devkit/types) | TypeScript type exports. UI primitives and domain models like `Device`, `Alert` | | [Utilities](/reference/app-toolkit/ui-devkit/utilities) | Helper functions for formatting, validation, conversions, and settings persistence | ## Browse by package If you're working with a specific package, use these per-package shortcuts: ### `@tetherto/mdk-react-devkit/core` - [Constants](/reference/app-toolkit/ui-devkit/constants#core-constants) - [Types](/reference/app-toolkit/ui-devkit/types#core-types) - [Utilities](/reference/app-toolkit/ui-devkit/utilities#core-utilities) ### `@tetherto/mdk-react-devkit/foundation` - [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants) - [Types](/reference/app-toolkit/ui-devkit/types#foundation-types) - [Utilities](/reference/app-toolkit/ui-devkit/utilities#foundation-utilities) - [Hooks](/reference/app-toolkit/hooks) — every App Toolkit hook (state, components, utilities) lives on a single overview page now. ### `@tetherto/mdk-ui-foundation` - [Alert utilities](/reference/app-toolkit/ui-devkit/utilities#ui-foundation-alert-utilities) — alert query-parameter builders and time-range chunking helpers # Constants (/reference/app-toolkit/ui-devkit/constants) This page documents constants exported by the MDK packages. Constants live in two distinct domains: - [Core constants](#core-constants) ships UI primitives: colors, units, currency symbols, chart defaults - [Foundation constants](#foundation-constants) ships mining-domain values: permissions, roles, header preferences, error codes ## Core constants UI primitive constants exported by `@tetherto/mdk-react-devkit/core` — colors, units, currency symbols, and chart defaults. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx COLOR, UNITS, CURRENCY, CHART_COLORS, TABLE_COLORS, HASHRATE_LABEL_DIVISOR, } from '@tetherto/mdk-react-devkit/core' ``` ### Color constants #### `COLOR` @tetherto/mdk-react-devkit/core Comprehensive color palette with 80+ named colors. ```tsx COLOR.GREEN // '#72F59E' COLOR.RED // '#EF4444' COLOR.COLD_ORANGE // '#F7931A' ``` ##### Base colors | Constant | Value | Description | |----------|-------|-------------| | `WHITE` | `#FFFFFF` | Pure white | | `BLACK` | `#17130F` | Standard black | | `DARK_BACK` | `#1A1815` | Dark background | | `EBONY` | `#0f0f0f` | Chart background | | `TRANSPARENT` | `transparent` | Transparent | ##### Status colors | Constant | Value | Description | |----------|-------|-------------| | `GREEN` | `#72F59E` | Success/online | | `RED` | `#EF4444` | Error/danger | | `YELLOW` | `#FFC107` | Warning | | `BRIGHT_YELLOW` | `#EAB308` | Bright warning | | `LIGHT_BLUE` | `#22AFFF` | Info | | `SLEEP_BLUE` | `#3B82F6` | Sleep/standby | ##### Brand colors | Constant | Value | Description | |----------|-------|-------------| | `COLD_ORANGE` | `#F7931A` | Bitcoin orange | | `ORANGE` | `#FF6A00` | Primary orange | | `EMERALD` | `#009393` | Teal accent | | `INDIGO` | `#5B5FFB` | Purple accent | #### `TABLE_COLORS` @tetherto/mdk-react-devkit/core Colors for table styling. ```tsx TABLE_COLORS.HEADER_BG TABLE_COLORS.ROW_HOVER ``` #### `HEATMAP` @tetherto/mdk-react-devkit/core `HEATMAP` color scale for temperature and intensity displays. ```tsx ``` #### `CHART_COLORS` @tetherto/mdk-react-devkit/core Default chart color palette. ```tsx ``` #### `PIE_CHART_COLORS` @tetherto/mdk-react-devkit/core Color palette for pie and doughnut charts. ```tsx ``` #### `CATEGORICAL_COLORS` @tetherto/mdk-react-devkit/core 25-color categorical palette for multi-series charts. ```tsx CATEGORICAL_COLORS[0] // First color CATEGORICAL_COLORS[24] // Last color ``` #### `TEMPERATURE_COLORS` @tetherto/mdk-react-devkit/core Color scale for temperature displays. ```tsx ``` #### `SOCKET_BORDER_COLOR` @tetherto/mdk-react-devkit/core Colors for socket status indicators. ```tsx ``` ### Unit constants #### `UNITS` @tetherto/mdk-react-devkit/core Physical and measurement units. ```tsx UNITS.POWER_W // 'W' UNITS.POWER_KW // 'kW' UNITS.ENERGY_MWH // 'MWh' UNITS.TEMPERATURE_C // '°C' UNITS.HASHRATE_TH_S // 'TH/s' ``` | Constant | Value | Description | |----------|-------|-------------| | `POWER_W` | `W` | Watts | | `POWER_KW` | `kW` | Kilowatts | | `ENERGY_WH` | `Wh` | Watt-hours | | `ENERGY_KWH` | `kWh` | Kilowatt-hours | | `ENERGY_MW` | `MW` | Megawatts | | `ENERGY_MWH` | `MWh` | Megawatt-hours | | `ENERGY_GWH` | `GWh` | Gigawatt-hours | | `TEMPERATURE_C` | `°C` | Celsius | | `VOLTAGE_V` | `V` | Volts | | `AMPERE` | `A` | Amperes | | `PERCENT` | `%` | Percentage | | `PRESSURE_BAR` | `bar` | Pressure (bar) | | `HASHRATE_MH_S` | `MH/s` | Megahash/second | | `HASHRATE_TH_S` | `TH/s` | Terahash/second | | `HASHRATE_PH_S` | `PH/s` | Petahash/second | | `HASHRATE_EH_S` | `EH/s` | Exahash/second | | `FREQUENCY_MHZ` | `MHz` | Megahertz | | `FREQUENCY_HERTZ` | `Hz` | Hertz | | `HUMIDITY_PERCENT` | `%RH` | Relative humidity | | `EFFICIENCY_W_PER_TH` | `W/TH` | Watts per terahash | | `FLOW_M3H` | `m3/h` | Flow rate | | `SATS` | `Sats` | Satoshis | | `VBYTE` | `vByte` | Virtual bytes | #### `CURRENCY` @tetherto/mdk-react-devkit/core Currency symbols and labels. ```tsx CURRENCY.BTC // '₿' CURRENCY.USD // '$' CURRENCY.EUR // '€' CURRENCY.SATS // 'Sats' CURRENCY.BTC_LABEL // 'BTC' CURRENCY.USD_LABEL // 'USD' ``` #### `MAX_UNIT_VALUE` @tetherto/mdk-react-devkit/core Maximum values for certain units. ```tsx MAX_UNIT_VALUE.HUMIDITY_PERCENT // 100 MAX_UNIT_VALUE.TEMPERATURE_PERCENT // 100 ``` #### `HASHRATE_LABEL_DIVISOR` @tetherto/mdk-react-devkit/core Divisors for converting hashrate units. ```tsx HASHRATE_LABEL_DIVISOR['TH/s'] // 1e6 HASHRATE_LABEL_DIVISOR['PH/s'] // 1e9 HASHRATE_LABEL_DIVISOR['EH/s'] // 1e12 ``` ### Chart constants #### `defaultChartColors` @tetherto/mdk-react-devkit/core Default color array for chart datasets. ```tsx ``` #### `defaultChartOptions` @tetherto/mdk-react-devkit/core Default [Chart.js](https://www.chartjs.org/) options. ```tsx ``` #### `CHART_LEGEND_OPACITY` @tetherto/mdk-react-devkit/core Opacity values for chart legends. ```tsx ``` #### `CHART_PERFORMANCE` @tetherto/mdk-react-devkit/core Performance threshold constants for charts. ```tsx ``` #### `getChartAnimationConfig` @tetherto/mdk-react-devkit/core Get animation configuration based on data count. ```tsx const animConfig = getChartAnimationConfig(dataPointCount) ``` #### `getDataDecimationConfig` @tetherto/mdk-react-devkit/core Get data decimation configuration for large datasets. ```tsx const decimationConfig = getDataDecimationConfig(dataPointCount) ``` ### Type exports The constants module also exports TypeScript types: ```tsx UnitKey, UnitValue, CurrencyKey, CurrencyValue, } from '@tetherto/mdk-react-devkit/core' ``` ## Foundation constants Constants exported by `@tetherto/mdk-react-devkit/foundation`: app identity, dialog flows, header preferences, permissions, roles, and error codes. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx WEBAPP_NAME, WEBAPP_SHORT_NAME, WEBAPP_DISPLAY_NAME, POSITION_CHANGE_DIALOG_FLOWS, HEADER_ITEMS, DEFAULT_HEADER_PREFERENCES, AUTH_PERMISSIONS, AUTH_LEVELS, USER_ROLE, USER_ROLES, PERM_LEVEL_LABELS, getRoleBadgeColors, } from '@tetherto/mdk-react-devkit/foundation' ``` ### App identity Brand strings the foundation UI uses to label the running web app in header rows, chart legends, settings export errors, and confirmation copy. The kit ships placeholder defaults; consumers read them via the named imports. #### `WEBAPP_NAME` @tetherto/mdk-react-devkit/foundation Inline name used in confirmations and the `parseSettingsFile` import-error message. ```tsx WEBAPP_NAME // 'Appl.' ``` #### `WEBAPP_SHORT_NAME` @tetherto/mdk-react-devkit/foundation Compact label embedded in [`HEADER_ITEMS`](#header_items) for the in-app miner and hashrate header rows. ```tsx WEBAPP_SHORT_NAME // 'APP' ``` #### `WEBAPP_DISPLAY_NAME` @tetherto/mdk-react-devkit/foundation Display name used in chart legends, including the hash-rate line chart series label. ```tsx WEBAPP_DISPLAY_NAME // 'Application' ``` ### Dialog flows #### `POSITION_CHANGE_DIALOG_FLOWS` @tetherto/mdk-react-devkit/foundation Flow keys consumed by [`PositionChangeDialog`](/reference/ui/react/foundation/operations/details-view/fleet-management#positionchangedialog) and its sibling dialogs to route between step-specific surfaces. ```tsx POSITION_CHANGE_DIALOG_FLOWS.MAINTENANCE // 'maintenance' POSITION_CHANGE_DIALOG_FLOWS.REPLACE_MINER // 'replaceMiner' ``` | Constant | Value | Description | |----------|-------|-------------| | `CONFIRM_REMOVE` | `remove` | Render the remove-miner confirmation surface | | `CHANGE_INFO` | `changeInfo` | Edit info for an existing miner | | `MAINTENANCE` | `maintenance` | Move a miner to (or back from) the maintenance container | | `REPLACE_MINER` | `replaceMiner` | Replace the miner currently occupying a socket | | `CONFIRM_CHANGE_POSITION` | `confirmChange` | Confirm a position change between sockets | | `CONTAINER_SELECTION` | `containerSelection` | Pick a destination container and socket | #### `PositionChangeDialogFlowKey` type @tetherto/mdk-react-devkit/foundation ```tsx type PositionChangeDialogFlowKey = keyof typeof POSITION_CHANGE_DIALOG_FLOWS ``` #### `PositionChangeDialogFlowValue` type @tetherto/mdk-react-devkit/foundation ```tsx type PositionChangeDialogFlowValue = (typeof POSITION_CHANGE_DIALOG_FLOWS)[PositionChangeDialogFlowKey] ``` ### Header controls #### `HEADER_ITEMS` @tetherto/mdk-react-devkit/foundation Array of header metric options for the [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls) component. ```tsx ``` | Key | Label | |-----|-------| | `poolMiners` | `Pool Miners` | | `miners` | `` `${WEBAPP_SHORT_NAME} Miners` `` | | `poolHashrate` | `Pool Hashrate` | | `hashrate` | `` `${WEBAPP_SHORT_NAME} Hashrate` `` | | `consumption` | `Consumption` | | `efficiency` | `Efficiency` | The two in-app rows compose their labels from [`WEBAPP_SHORT_NAME`](#webapp_short_name); with the shipped default that renders as `APP Miners` and `APP Hashrate`. #### `DEFAULT_HEADER_PREFERENCES` @tetherto/mdk-react-devkit/foundation Default visibility state for all header items (all `true`). ```tsx DEFAULT_HEADER_PREFERENCES.poolMiners // true DEFAULT_HEADER_PREFERENCES.consumption // true ``` #### `HeaderPreferences` type @tetherto/mdk-react-devkit/foundation ```tsx type HeaderPreferences = { poolMiners: boolean miners: boolean poolHashrate: boolean hashrate: boolean consumption: boolean efficiency: boolean } ``` ### Permissions #### `AUTH_PERMISSIONS` @tetherto/mdk-react-devkit/foundation Permission resource identifiers. ```tsx AUTH_PERMISSIONS.USERS // 'users' AUTH_PERMISSIONS.SETTINGS // 'settings' AUTH_PERMISSIONS.MINER // 'miner' ``` | Constant | Value | Description | |----------|-------|-------------| | `USERS` | `users` | User management | | `SETTINGS` | `settings` | Application settings | | `MINER` | `miner` | Miner operations | | `ALERTS` | `alerts` | Alert management | | `ACTIONS` | `actions` | Action execution | | `EXPLORER` | `explorer` | Device explorer | | `INVENTORY` | `inventory` | Inventory management | | `CONTAINER` | `container` | Container management | | `PRODUCTION` | `production` | Production data | | `REPORTING` | `reporting` | Reports | #### `AUTH_LEVELS` @tetherto/mdk-react-devkit/foundation Permission access levels. ```tsx AUTH_LEVELS.READ // 'r' AUTH_LEVELS.WRITE // 'w' ``` #### `USER_ROLE` @tetherto/mdk-react-devkit/foundation User role identifiers. ```tsx USER_ROLE.ADMIN // 'admin' USER_ROLE.SITE_MANAGER // 'site_manager' USER_ROLE.READ_ONLY // 'read_only_user' ``` | Constant | Value | |----------|-------| | `ADMIN` | `admin` | | `SITE_MANAGER` | `site_manager` | | `SITE_OPERATOR` | `site_operator` | | `FIELD_OPERATOR` | `field_operator` | | `REPAIR_TECHNICIAN` | `repair_technician` | | `REPORTING_TOOL_MANAGER` | `reporting_tool_manager` | | `READ_ONLY` | `read_only_user` | ### Settings #### `USER_ROLES` @tetherto/mdk-react-devkit/foundation Array of role options for select dropdowns. ```tsx // [{ label: 'Admin', value: 'admin' }, ...] ``` #### `PERM_LEVEL_LABELS` @tetherto/mdk-react-devkit/foundation Human-readable labels for permission levels. ```tsx PERM_LEVEL_LABELS.rw // 'Read & Write' PERM_LEVEL_LABELS.r // 'Read Only' PERM_LEVEL_LABELS.none // 'No Access' ``` #### `SETTINGS_ERROR_CODES` @tetherto/mdk-react-devkit/foundation Error code to message mapping. ```tsx SETTINGS_ERROR_CODES.ERR_USER_EXISTS // 'User already exists' SETTINGS_ERROR_CODES.DEFAULT // 'An error occurred' ``` ### Role styling #### `getRoleBadgeColors` @tetherto/mdk-react-devkit/foundation Get badge colors for a role. ```tsx const { color, bgColor } = getRoleBadgeColors('admin') // { color: '#e8833a', bgColor: 'rgba(232, 131, 58, 0.1)' } ``` | Role | Color | Background | |------|-------|------------| | `admin` | `#e8833a` | Orange tint | | `site_manager` | `#52c41a` | Green tint | | `site_operator` | `#faad14` | Yellow tint | | `read_only_user` | `#8c8c8c` | Gray tint | # Hooks (/reference/app-toolkit/ui-devkit/hooks) Hooks shipped by `@tetherto/mdk-react-devkit`. For the full catalog — including adapter data hooks and state hooks from `@tetherto/mdk-react-adapter` — see the [Hooks reference](/reference/app-toolkit/hooks). Use the groups below to browse by concern; each hook name links to its entry in that reference. ## Available hooks | Group | Hooks | |---|---| | [Monitoring](/reference/app-toolkit/hooks) | [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck), [`useBeepSound`](/reference/app-toolkit/hooks/utilities#usebeepsound), [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite), [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | | [UI](/reference/app-toolkit/hooks) | [`useNotification`](/reference/app-toolkit/hooks/components#usenotification), [`useHeaderControls`](/reference/app-toolkit/hooks/components#useheadercontrols), [`useSidebarExpandedState`](/reference/app-toolkit/hooks/components#usesidebarexpandedstate), [`useSidebarSectionState`](/reference/app-toolkit/hooks/components#usesidebarsectionstate), [`useHasPerms`](/reference/app-toolkit/hooks/utilities#usehasperms), [`useCheckPerm`](/reference/app-toolkit/hooks/utilities#usecheckperm), [`useLocalStorage`](/reference/app-toolkit/hooks/utilities#uselocalstorage), [`usePagination`](/reference/app-toolkit/hooks/utilities#usepagination), [`useIsFeatureEditingEnabled`](/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) | # Types (/reference/app-toolkit/ui-devkit/types) This page documents the TypeScript types exported by the MDK packages. The two packages cover different territory: - [Core types](#core-types) ships **UI primitive types**: sizes, variants, colors, status, common API and chart shapes. These are the building blocks consumed by core components and re-used in your own component prop types. - [Foundation types](#foundation-types) ships **mining-domain models**: `Device`, `Container`, `Alert`, `MinerStats`, settings shapes. These describe the data flowing through foundation components and the API responses they consume. ## Core types UI primitive types exported by `@tetherto/mdk-react-devkit/core` — sizes, variants, colors, status, and common API and chart shapes. These are the building blocks consumed by core components and re-used in your own component prop types. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx ComponentSize, ButtonVariant, ColorVariant, Status, ApiResponse, } from '@tetherto/mdk-react-devkit/core' ``` ### Common types #### `ComponentSize` @tetherto/mdk-react-devkit/core Standard size variants used across multiple components. ```tsx type ComponentSize = 'sm' | 'md' | 'lg' ``` Used by: `Button`, `Badge`, `Checkbox`, `Switch`, `Radio`, `Spinner`, `Indicator`, `EmptyState`, `Pagination`. #### `ButtonSize` @tetherto/mdk-react-devkit/core Extends `ComponentSize` with an icon-only variant. ```tsx type ButtonSize = ComponentSize | 'icon' ``` #### `BorderRadius` @tetherto/mdk-react-devkit/core Border radius variants for form components. ```tsx type BorderRadius = 'none' | 'small' | 'medium' | 'large' | 'full' ``` Used by: `Checkbox`, `Switch`, `Radio`. #### `ColorVariant` @tetherto/mdk-react-devkit/core Comprehensive color variants for components. ```tsx type ColorVariant = | 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' ``` #### `StatusVariant` @tetherto/mdk-react-devkit/core Status variants for state indication. ```tsx type StatusVariant = 'success' | 'processing' | 'error' | 'warning' | 'default' | 'idle' ``` Used by: badges, notifications, status indicators. #### `ComponentColor` @tetherto/mdk-react-devkit/core Color options for form components. ```tsx type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error' ``` Used by: `Checkbox`, `Switch`, `Radio`, `Typography`. #### `Position` @tetherto/mdk-react-devkit/core Position/side options for UI elements. ```tsx type Position = 'top' | 'right' | 'bottom' | 'left' ``` Used by: `Tooltip`, `Popover`, chart legends. #### `TextAlign` @tetherto/mdk-react-devkit/core Text alignment options. ```tsx type TextAlign = 'left' | 'center' | 'right' | 'justify' ``` #### `FlexAlign` @tetherto/mdk-react-devkit/core Flex/grid alignment options. ```tsx type FlexAlign = 'start' | 'center' | 'end' ``` ### Component types #### `ButtonVariant` @tetherto/mdk-react-devkit/core Button visual variants. ```tsx type ButtonVariant = | 'primary' | 'secondary' | 'danger' | 'tertiary' | 'link' | 'icon' | 'outline' | 'ghost' ``` #### `ButtonIconPosition` @tetherto/mdk-react-devkit/core Where icons appear in buttons. ```tsx type ButtonIconPosition = 'left' | 'right' ``` #### `NotificationVariant` @tetherto/mdk-react-devkit/core Toast/notification variants. ```tsx type NotificationVariant = 'success' | 'error' | 'warning' | 'info' ``` #### `BadgeStatus` @tetherto/mdk-react-devkit/core Badge status options. ```tsx type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default' ``` #### `TypographyColor` @tetherto/mdk-react-devkit/core Typography color options including muted. ```tsx type TypographyColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'muted' ``` ### Utility types #### `UnknownRecord` @tetherto/mdk-react-devkit/core Generic type for objects with unknown structure. ```tsx type UnknownRecord = Record ``` #### `Nullable` / `Optional` / `Maybe` @tetherto/mdk-react-devkit/core Null/undefined wrapper types. ```tsx type Nullable = T | null type Optional = T | undefined type Maybe = T | null | undefined ``` #### `Status` @tetherto/mdk-react-devkit/core Async operation status. ```tsx type Status = 'idle' | 'loading' | 'success' | 'error' ``` ### API types #### `PaginationParams` @tetherto/mdk-react-devkit/core Pagination request parameters. ```tsx type PaginationParams = { limit?: number offset?: number page?: number } ``` #### `PaginatedResponse` @tetherto/mdk-react-devkit/core Paginated response wrapper. ```tsx type PaginatedResponse = { data: T[] page: number total: number totalPages: number } ``` #### `ApiResponse` @tetherto/mdk-react-devkit/core API response wrapper. ```tsx type ApiResponse = { data: T message?: string status: number } ``` #### `ApiError` @tetherto/mdk-react-devkit/core API error response structure. ```tsx type ApiError = { error: string message: string status: number data?: { message?: string } } ``` ### Data table types @tetherto/mdk-react-devkit/core Re-exported from TanStack Table for convenience. ```tsx DataTableColumnDef, DataTableExpandedState, DataTablePaginationState, DataTableRow, DataTableRowSelectionState, DataTableSortingState, } from '@tetherto/mdk-react-devkit/core' ``` ### Value types #### `ValueUnit` @tetherto/mdk-react-devkit/core A value paired with a unit, used for display formatting. ```tsx type ValueUnit = { value: number | string | null unit: string realValue: number } ``` #### `HashrateUnit` / `CurrencyUnit` @tetherto/mdk-react-devkit/core Specialized value-unit aliases. ```tsx type HashrateUnit = ValueUnit type CurrencyUnit = ValueUnit ``` #### `UnitLabel` @tetherto/mdk-react-devkit/core SI-prefix unit labels. ```tsx type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P' ``` ### Time types #### `TimeRangeFormatted` @tetherto/mdk-react-devkit/core A formatted time range. ```tsx type TimeRangeFormatted = { start: string end: string formatted: string } ``` #### `TimeInterval` @tetherto/mdk-react-devkit/core A time interval with start/end timestamps. ```tsx type TimeInterval = { start: number end: number } ``` ### Chart types #### `ChartLegendPosition` @tetherto/mdk-react-devkit/core Chart legend position options. ```tsx type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea' ``` #### `WeightedAverageResult` @tetherto/mdk-react-devkit/core Result from weighted average calculation. ```tsx type WeightedAverageResult = { avg: number totalWeight: number weightedValue: number } ``` #### `ErrorWithTimestamp` @tetherto/mdk-react-devkit/core An error with optional timestamp. ```tsx type ErrorWithTimestamp = { msg?: string message?: string timestamp?: number | string } ``` ## Foundation types Foundation types describe the shape of devices, containers, alerts, site configuration, and settings data flowing through `@tetherto/mdk-react-devkit/foundation` components and API responses. They are organized into barrels including `alerts`, `config`, `device`, and `settings.types`. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx Alert, Device, DeviceLast, DeviceInfo, ContainerSnap, ContainerStats, MinerStats, MinerConfig, SettingsUser, PermLevel, GlobalConfig, TimelineChartDataPoint, TimelineChartDataset, TimelineChartData, ChartRange, AxisTitleText, MetricsEfficiencyLogEntry, } from '@tetherto/mdk-react-devkit/foundation' ``` ### Alert types #### `Alert` @tetherto/mdk-react-devkit/foundation Raw alert record as it appears on a device's `alerts` array. ```tsx type Alert = { id?: string severity: string createdAt: number | string name: string description: string message?: string uuid?: string code?: string | number [key: string]: unknown } ``` The `severity` field uses string values like `critical`, `high`, `medium`, `low`. The open `[key: string]: unknown` index signature allows vendor-specific fields without breaking the type contract. #### `LogFormattedAlertData` @tetherto/mdk-react-devkit/foundation Alert reshaped for log display components (e.g., `AlertsLog`). ```tsx type LogFormattedAlertData = { title: string subtitle: string status: string severityLevel: number creationDate: number | string body: string id: string uuid?: string [key: string]: unknown } ``` ### Device types The `Device` family models everything that appears on the device explorer: miners, containers, power meters, temperature sensors, and cabinets. The shape is intentionally permissive (open index signatures, optional fields) because devices come from a live API that adds vendor-specific fields over time. #### `Device` @tetherto/mdk-react-devkit/foundation The root device record. Used pervasively in the [operations centre](/reference/ui/react/foundation/operations) components. ```tsx type Device = { id: string type: string tags?: string[] rack?: string last?: DeviceLast username?: string info?: DeviceInfo containerId?: string address?: string | null code?: string alerts?: Alert[] | null powerMeters?: Device[] tempSensors?: Device[] transformerTempSensor?: Device rootTempSensor?: Device [key: string]: unknown } ``` The `type` string discriminates devices by category (such as miner or container) and by vendor. The `last` field carries the latest snapshot from the device. #### `DeviceLast` @tetherto/mdk-react-devkit/foundation The latest reading wrapper that lives on `Device.last`. ```tsx type DeviceLast = { err?: string | null type?: string snap?: ContainerSnap alerts?: Alert[] | null [key: string]: unknown } ``` `err` is a connection or upstream error string when the device is unreachable. `snap` carries the actual stats and config payload. #### `DeviceInfo` @tetherto/mdk-react-devkit/foundation Identification and placement metadata that lives on `Device.info`. ```tsx type DeviceInfo = { container?: string pos?: string poolConfig?: string serialNum?: string macAddress?: string | null posHistory?: Partial [key: string]: unknown } ``` #### `PosHistoryEntry` @tetherto/mdk-react-devkit/foundation A single past placement of a miner. ```tsx type PosHistoryEntry = { container: string pos: string removedAt: number } ``` #### `DeviceData` @tetherto/mdk-react-devkit/foundation A flattened version of `Device` with a guaranteed (non-optional) `snap` field, returned by the `getDeviceData` helper. ```tsx type DeviceData = { id: string type: string tags?: string[] rack?: string snap: ContainerSnap alerts?: Alert[] username?: string info?: DeviceInfo containerId?: string address?: string err?: string [key: string]: unknown } ``` ### Container types #### `Container` @tetherto/mdk-react-devkit/foundation A `Device` specialized for containers, with container-specific `info` and `last` shapes. ```tsx type Container = { info?: Partial last?: Partial } & Device ``` #### `ContainerInfo` @tetherto/mdk-react-devkit/foundation Cooling, supply, and pressure metadata for a container. ```tsx type ContainerInfo = { container: string cooling_system: Record cdu: Record primary_supply_temp: number second_supply_temp1: number second_supply_temp2: number supply_liquid_temp: number supply_liquid_set_temp: number supply_liquid_pressure: number return_liquid_pressure: number } ``` #### `ContainerPosInfo` @tetherto/mdk-react-devkit/foundation Position descriptor for a device inside a container (PDU/socket coordinates). ```tsx type ContainerPosInfo = { containerInfo: Partial<{ container: string; type: string }> pdu: string | number socket: string | number pos: string [key: string]: unknown } ``` #### `ContainerLast` @tetherto/mdk-react-devkit/foundation Last-snapshot wrapper for a container. ```tsx type ContainerLast = { snap: { stats?: Partial } alerts: unknown[] | null err: string | null } ``` #### `ContainerSnap` @tetherto/mdk-react-devkit/foundation The `snap` payload found on `DeviceLast.snap` for both miners and containers. `stats` is what most components read. ```tsx type ContainerSnap = { stats?: Partial config?: Record } ``` #### `ContainerStats` @tetherto/mdk-react-devkit/foundation The big stats blob produced by every container snapshot. ```tsx type ContainerStats = { status: string ambient_temp_c: number humidity_percent: number power_w: number container_specific: Partial distribution_box1_power_w: number distribution_box2_power_w: number stats: Record temperature_c: Partial frequency_mhz: Partial miner_specific: Partial [key: string]: unknown } ``` `status` is one of `running`, `offline`, `stopped` (see `CONTAINER_STATUS` in [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants)). #### `ContainerSpecific` @tetherto/mdk-react-devkit/foundation Container-specific stats (currently the PDU array). ```tsx type ContainerSpecific = { pdu_data: Partial[] [key: string]: unknown } ``` #### `ContainerPduData` @tetherto/mdk-react-devkit/foundation Per-PDU power and status reading. ```tsx type ContainerPduData = { power_w: number status: number } ``` #### `StatsTemperatureC` @tetherto/mdk-react-devkit/foundation Temperature stats with per-chip detail. ```tsx type StatsTemperatureC = { avg: number min: number max: number chips: TempChipData[] [key: string]: unknown } ``` #### `StatsFrequencyMhz` @tetherto/mdk-react-devkit/foundation Frequency stats with per-chip detail. ```tsx type StatsFrequencyMhz = { avg: number chips: ChipData[] [key: string]: unknown } ``` #### `ChipData` / `TempChipData` @tetherto/mdk-react-devkit/foundation Per-chip readings. ```tsx type ChipData = { index: number current: number } type TempChipData = { index: number max?: number min?: number avg?: number } ``` #### `MinerSpecificStats` @tetherto/mdk-react-devkit/foundation Miner-specific stats blob. ```tsx type MinerSpecificStats = { upfreq_speed: number [key: string]: unknown } ``` ### Miner types #### `MinerStats` @tetherto/mdk-react-devkit/foundation Per-miner stats reported on each snapshot. ```tsx type MinerStats = { status?: string uptime_ms?: number power_w?: number hashrate_mhs?: MinerHashrateMhs poolHashrate?: string temperature_c?: { max?: number } } ``` #### `MinerHashrateMhs` @tetherto/mdk-react-devkit/foundation Hashrate readings, currently just the rolling 5-minute window. ```tsx type MinerHashrateMhs = { t_5m?: number } ``` #### `MinerInfo` @tetherto/mdk-react-devkit/foundation Identifying info for a miner (used by miner record cards). ```tsx type MinerInfo = { container?: string pos?: string macAddress?: string serialNum?: string } ``` #### `MinerConfig` @tetherto/mdk-react-devkit/foundation Mutable miner configuration. ```tsx type MinerConfig = { firmware_ver?: string power_mode?: string led_status?: boolean } ``` `power_mode` values come from `MINER_POWER_MODE` (`sleep`, `low`, `normal`, `high`). #### `MinerDeviceSnapshot` @tetherto/mdk-react-devkit/foundation Lightweight snapshot wrapper holding only `MinerConfig`. ```tsx type MinerDeviceSnapshot = { last?: { snap?: { config?: MinerConfig } } } ``` #### `MinerRecord` @tetherto/mdk-react-devkit/foundation Combined miner record used by list/table views. ```tsx type MinerRecord = { id?: string shortCode?: string info?: MinerInfo address?: string type?: string alerts?: unknown[] stats?: MinerStats config?: MinerConfig device?: MinerDeviceSnapshot error?: string err?: string isPoolStatsEnabled?: boolean } ``` ### Power and cabinet types #### `PowerMeter` @tetherto/mdk-react-devkit/foundation Minimal power meter reading shape. ```tsx type PowerMeter = { last?: { snap?: { stats?: { power_w?: number } } } } ``` #### `LvCabinetRecord` @tetherto/mdk-react-devkit/foundation LV cabinet record carrying its associated power meters. ```tsx type LvCabinetRecord = { id: string powerMeters?: PowerMeter[] } ``` ### Config types #### `GlobalConfig` @tetherto/mdk-react-devkit/foundation Site-wide configuration from your API or store, including nominal targets for reporting dashboards. Load this shape in your app from your API or store and pass it into foundation reporting UI as needed. ```tsx type GlobalConfig = { nominalSiteHashrate_MHS?: number nominalAvailablePowerMWh?: number nominalPowerConsumption_MW?: number nominalWeightedAvgEfficiency_WThs?: number nominalMinerCapacity?: number isAutoSleepAllowed?: boolean siteEnergyDataThresholdMWh?: number [key: string]: unknown } ``` | Field | Type | Description | |-------|------|-------------| | `nominalSiteHashrate_MHS` | `number` | Nominal site hashrate (MH/s) | | `nominalAvailablePowerMWh` | `number` | Nominal available power (MWh on the wire) | | `nominalPowerConsumption_MW` | `number` | Nominal power consumption (MW) | | `nominalWeightedAvgEfficiency_WThs` | `number` | Nominal weighted average efficiency (W/TH) | | `nominalMinerCapacity` | `number` | Nominal miner capacity | | `isAutoSleepAllowed` | `boolean` | Whether auto-sleep is permitted for the site | | `siteEnergyDataThresholdMWh` | `number` | Energy data threshold (MWh) | | `[key: string]` | `unknown` | Additional API fields without breaking the type | ### Timeline chart types Types for [`TimelineChart`](/reference/ui/react/foundation/dashboard/charts#timelinechart) in `@tetherto/mdk-react-devkit/foundation`. Each segment uses `x: [startMs, endMs]` and `y` matching a row in `labels`. #### `TimelineChartDataPoint` @tetherto/mdk-react-devkit/foundation One horizontal segment on a timeline row. ```tsx type TimelineChartDataPoint = { x: [number, number] y: string | undefined } ``` | Field | Type | Description | |-------|------|-------------| | `x` | `[number, number]` | Segment start and end (epoch ms) | | `y` | `string \| undefined` | Row label; must match an entry in `TimelineChartData.labels` | #### `TimelineChartDataset` @tetherto/mdk-react-devkit/foundation A named group of segments (legend entry). ```tsx type TimelineChartDataset = { label: string data: TimelineChartDataPoint[] borderColor?: string[] backgroundColor?: string[] color?: string } ``` #### `TimelineChartData` @tetherto/mdk-react-devkit/foundation Full payload for `initialData` and `newData`. ```tsx type TimelineChartData = { labels: string[] datasets: TimelineChartDataset[] } ``` | Field | Type | Description | |-------|------|-------------| | `labels` | `string[]` | Row names (Y axis) | | `datasets` | `TimelineChartDataset[]` | Segment groups keyed by `label` | #### `ChartRange` @tetherto/mdk-react-devkit/foundation Visible time window for the `range` prop. ```tsx type ChartRange = { min: Date | number max: Date | number } ``` #### `AxisTitleText` @tetherto/mdk-react-devkit/foundation Axis title strings for `axisTitleText`. ```tsx type AxisTitleText = { x: string y: string } ``` ### Metrics efficiency types Types for **`/auth/metrics/efficiency`**, used by the site view tab on [`OperationsEfficiency`](/reference/ui/react/foundation/reporting/operations-efficiency). #### `MetricsEfficiencyLogEntry` @tetherto/mdk-react-devkit/foundation One point on the site efficiency time series. ```tsx type MetricsEfficiencyLogEntry = { ts: number efficiencyWThs: number } ``` | Field | Type | Description | |-------|------|-------------| | `ts` | `number` | Timestamp (epoch ms) | | `efficiencyWThs` | `number` | Site efficiency (W/TH) at `ts` | #### `MetricsEfficiencySummary` @tetherto/mdk-react-devkit/foundation Summary block returned with the efficiency metrics response. ```tsx type MetricsEfficiencySummary = { avgEfficiencyWThs: number | null } ``` #### `MetricsEfficiencyResponse` @tetherto/mdk-react-devkit/foundation Wrapper for the efficiency metrics endpoint (`log` entries plus summary), using the shared `MetricsResponse` shape from `@tetherto/mdk-react-devkit/foundation`. ### Settings types #### `SettingsUser` @tetherto/mdk-react-devkit/foundation A user record as it appears in user-management lists. ```tsx type SettingsUser = { id: string name?: string email: string role: string last_login?: string lastActive?: string [key: string]: unknown } ``` #### `RoleOption` @tetherto/mdk-react-devkit/foundation Role option for select dropdowns. Also exported as the array `USER_ROLES` in [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants). ```tsx type RoleOption = { label: string value: string } ``` #### `PermLevel` @tetherto/mdk-react-devkit/foundation Permission level values. ```tsx type PermLevel = 'rw' | 'r' | false ``` #### `RolesPermissionsData` @tetherto/mdk-react-devkit/foundation The shape consumed by [`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control). ```tsx type RolesPermissionsData = { permissions: Record> labels: Record } ``` #### `SettingsExportData` @tetherto/mdk-react-devkit/foundation The export envelope produced and consumed by [`ImportExportSettings`](/reference/ui/react/foundation/settings/import-export). Generic `TExtra` lets you attach app-specific extras. ```tsx type SettingsExportData = Record> = { headerControls?: Record featureFlags?: Record timestamp?: string version?: string } & TExtra ``` #### `ImportResult` @tetherto/mdk-react-devkit/foundation Result returned from settings import operations. ```tsx type ImportResult = { success: boolean applied?: string[] errors?: string[] message?: string } ``` # Utilities (/reference/app-toolkit/ui-devkit/utilities) This page documents helper functions exported by the MDK packages. - [Core utilities](#core-utilities) ships **15 utility modules** with functions for formatting, dates, validation, conversions, class-name merging, and more - [Foundation utilities](#foundation-utilities) currently ships a single public utility module (`settings-utils`) for parsing, validating, and exporting settings JSON - [UI Foundation alert utilities](#ui-foundation-alert-utilities) ships query-parameter builders and time-range chunking helpers for the Alerts feature ## Core utilities Helper functions exported by `@tetherto/mdk-react-devkit/core` for formatting, dates, validation, conversions, and class-name merging. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ### Import @tetherto/mdk-react-devkit/core ```tsx formatNumber, formatHashrate, formatDate, formatRelativeTime, cn, isEmpty, isValidEmail, } from '@tetherto/mdk-react-devkit/core' ``` ### Formatting utilities #### `formatNumber` @tetherto/mdk-react-devkit/core Format numbers with locale formatting and configurable options. ```tsx formatNumber(1234.567) // "1,234.57" formatNumber(null) // "-" formatNumber(1234, { minimumFractionDigits: 2 }) // "1,234.00" formatNumber(undefined, {}, 'N/A') // "N/A" ``` #### `formatHashrate` @tetherto/mdk-react-devkit/core Format hashrate values with rounding. ```tsx formatHashrate(150.456) // "150.46" formatHashrate(null) // "-" ``` #### `formatCurrency` @tetherto/mdk-react-devkit/core Format currency values. ```tsx formatCurrency(1234.56, 'USD') // "$1,234.56" formatCurrency(0.00012345, 'BTC') // "₿0.00012345" ``` #### `getPercentFormattedNumber` @tetherto/mdk-react-devkit/core Format numbers as percentages. ```tsx getPercentFormattedNumber(0.75) // "75%" getPercentFormattedNumber(0.1234, 1) // "12.3%" ``` #### `formatValueUnit` @tetherto/mdk-react-devkit/core Format value-unit objects. ```tsx formatValueUnit(150, 'TH/s') // "150 TH/s" ``` ### Date utilities #### `formatDate` @tetherto/mdk-react-devkit/core Format dates with customizable patterns. ```tsx formatDate(new Date()) // "Jan 15, 2025" formatDate(1705334400000, { format: 'yyyy-MM-dd' }) // "2025-01-15" ``` #### `formatRelativeTime` @tetherto/mdk-react-devkit/core Format dates as relative time strings. ```tsx formatRelativeTime(new Date(Date.now() - 3600000)) // "1h ago" formatRelativeTime(new Date(Date.now() - 86400000)) // "1d ago" ``` #### `formatChartDate` @tetherto/mdk-react-devkit/core Format timestamps for chart display. ```tsx formatChartDate(1705334400) // "Jan 15" formatChartDate(1705334400, true) // "Jan 15, 2025" ``` #### `isValidTimestamp` @tetherto/mdk-react-devkit/core Check if a timestamp is valid. ```tsx isValidTimestamp(1705334400000) // true isValidTimestamp('invalid') // false ``` #### `parseMonthLabelToDate` @tetherto/mdk-react-devkit/core Parse month labels to `Date` objects. ```tsx parseMonthLabelToDate('01-26') // Date(2026, 0, 1) parseMonthLabelToDate('03-2025') // Date(2025, 2, 1) ``` #### `getPastDateFromDate` @tetherto/mdk-react-devkit/core Get a date in the past. ```tsx getPastDateFromDate({ dateTs: Date.now(), days: 7 }) // 7 days ago ``` ### Validation utilities #### `isEmpty` @tetherto/mdk-react-devkit/core Check if a value is empty. ```tsx isEmpty(null) // true isEmpty('') // true isEmpty([]) // true isEmpty({}) // true isEmpty('hello') // false isEmpty([1, 2, 3]) // false ``` #### `isValidEmail` @tetherto/mdk-react-devkit/core Validate email addresses. ```tsx isValidEmail('user@example.com') // true isValidEmail('invalid') // false ``` #### `isValidUrl` @tetherto/mdk-react-devkit/core Validate URLs. ```tsx isValidUrl('https://example.com') // true isValidUrl('not-a-url') // false ``` #### `isNil` @tetherto/mdk-react-devkit/core Check if value is `null` or `undefined`. ```tsx isNil(null) // true isNil(undefined) // true isNil(0) // false isNil('') // false ``` #### `isPlainObject` @tetherto/mdk-react-devkit/core Check if value is a plain object. ```tsx isPlainObject({}) // true isPlainObject({ a: 1 }) // true isPlainObject([]) // false isPlainObject(new Date()) // false ``` ### Class name utilities #### `cn` @tetherto/mdk-react-devkit/core Merge class names using [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge). ```tsx cn('px-4', 'py-2') // "px-4 py-2" cn('text-red', isError && 'bg-red') // conditional classes cn('p-4', { 'hidden': !visible }) // object syntax ``` ### Conversion utilities #### `toMW` / `toMWh` @tetherto/mdk-react-devkit/core Convert watts to megawatts. ```tsx toMW(1000000) // 1 toMWh(1000000) // 1 ``` #### `toPHS` @tetherto/mdk-react-devkit/core Convert raw hashrate to `PH/s`. ```tsx toPHS(1000000000000000) // 1 ``` #### `convertMpaToBar` @tetherto/mdk-react-devkit/core Convert pressure units. ```tsx convertMpaToBar(0.1) // 1 ``` #### `unitToKilo` @tetherto/mdk-react-devkit/core Convert to kilo units. ```tsx unitToKilo(1000) // 1 ``` ### Number utilities #### `percentage` @tetherto/mdk-react-devkit/core Calculate percentage. ```tsx percentage(25, 100) // 25 percentage(1, 4) // 25 ``` #### `getPercentChange` @tetherto/mdk-react-devkit/core Calculate percentage change. ```tsx getPercentChange(110, 100) // 10 getPercentChange(90, 100) // -10 ``` #### `convertUnits` @tetherto/mdk-react-devkit/core Convert between SI-prefix units. ```tsx convertUnits(1, 'k', 'M') // 0.001 convertUnits(1000, 'decimal', 'k') // 1 ``` #### `safeNumber` @tetherto/mdk-react-devkit/core Safely convert to number. ```tsx safeNumber('123') // 123 safeNumber('invalid') // 0 safeNumber(null) // 0 ``` ### String utilities #### `toTitleCase` @tetherto/mdk-react-devkit/core Convert string to Title Case. ```tsx toTitleCase('hello world') // "Hello World" ``` #### `formatMacAddress` @tetherto/mdk-react-devkit/core Format MAC addresses. ```tsx formatMacAddress('aa:bb:cc:dd:ee:ff') // "AA:BB:CC:DD:EE:FF" ``` #### `safeString` @tetherto/mdk-react-devkit/core Safely convert to string. ```tsx safeString(123) // "123" safeString(null) // "" ``` ### Time utilities #### `secondsToMs` @tetherto/mdk-react-devkit/core Convert seconds to milliseconds. ```tsx secondsToMs(60) // 60000 ``` #### `breakTimeIntoIntervals` @tetherto/mdk-react-devkit/core Split `[start, end]` into consecutive windows of `intervalMs`. Re-exported from `@tetherto/mdk-ui-foundation`. ```tsx breakTimeIntoIntervals(start, end, 3_600_000) // Array of 1-hour { start, end } windows ``` #### `timeRangeWalker` @tetherto/mdk-react-devkit/core Generator for iterating through time ranges. ```tsx for (const interval of timeRangeWalker(start, end, duration)) { // Process each interval } ``` ### Color utilities #### `hexToRgba` @tetherto/mdk-react-devkit/core Convert hex color to rgba. ```tsx hexToRgba('#72F59E', 0.5) // "rgba(114, 245, 158, 0.5)" ``` ### Array utilities #### `getNestedValue` @tetherto/mdk-react-devkit/core Get nested value by dot-path. ```tsx getNestedValue({ a: { b: 1 } }, 'a.b') // 1 ``` #### `getWeightedAverage` @tetherto/mdk-react-devkit/core Calculate weighted average. ```tsx getWeightedAverage(items, 'value', 'weight') ``` #### `circularArrayAccess` @tetherto/mdk-react-devkit/core Create infinite cycling generator. ```tsx const colors = circularArrayAccess(['red', 'green', 'blue']) colors.next().value // 'red' colors.next().value // 'green' colors.next().value // 'blue' colors.next().value // 'red' (cycles) ``` ## Foundation utilities Helpers exported by `@tetherto/mdk-react-devkit/foundation` for filtering, formatting, validating, parsing, and exporting settings data. ### Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites) ### Import @tetherto/mdk-react-devkit/foundation ```tsx filterUsers, formatRoleLabel, formatLastActive, validateSettingsJson, parseSettingsFile, exportSettingsToFile, } from '@tetherto/mdk-react-devkit/foundation' ``` ### Settings utilities #### `filterUsers` @tetherto/mdk-react-devkit/foundation Filter a `SettingsUser[]` list by email substring (case-insensitive) and exact role match. Used by the user-management table search. ```tsx filterUsers({ users, email: 'alice', // partial, case-insensitive match on user.email role: 'admin', // exact match on user.role; pass null to skip }) ``` | Parameter | Type | Description | |-----------|------|-------------| | `users` | `SettingsUser[]` | Source list | | `email` | `string \| null \| undefined` | Substring filter on `email` (case-insensitive). Skipped when falsy. | | `role` | `string \| null \| undefined` | Exact role match. Skipped when falsy. | #### `formatRoleLabel` @tetherto/mdk-react-devkit/foundation Convert a snake case role identifier to a human-readable Title Case label. ```tsx formatRoleLabel('site_manager') // "Site Manager" formatRoleLabel('reporting_tool_manager') // "Reporting Tool Manager" formatRoleLabel('admin') // "Admin" ``` #### `formatLastActive` @tetherto/mdk-react-devkit/foundation Format a timestamp string as `MM/DD/YYYY - HH:MM`. Returns `'-'` when the input is missing or invalid. ```tsx formatLastActive('2025-01-15T14:30:00Z') // "01/15/2025 - 14:30" formatLastActive(undefined) // "-" formatLastActive('not-a-date') // "-" ``` #### `validateSettingsJson` @tetherto/mdk-react-devkit/foundation Type-guard that checks whether an unknown value is a valid `SettingsExportData`. Returns `true` if the value is an object that contains at least one of `headerControls`, `featureFlags`, or `timestamp`. ```tsx if (validateSettingsJson(parsed)) { // parsed is now narrowed to SettingsExportData } ``` #### `parseSettingsFile` @tetherto/mdk-react-devkit/foundation Read a `File` containing settings JSON, validate it, and resolve to `SettingsExportData`. Rejects on invalid JSON, an invalid format, or a file read error. ```tsx try { const settings = await parseSettingsFile(file) applySettings(settings) } catch (err) { notifyError('Could not import settings', err.message) } ``` | Throws | Reason | |--------|--------| | `` `Invalid settings file format. Please ensure the file is a valid ${WEBAPP_NAME} settings export.` `` | The JSON parsed but didn't match the `SettingsExportData` shape. The literal interpolates [`WEBAPP_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_name). | | `Failed to parse JSON file. Please ensure the file is valid JSON.` | The file contents weren't valid JSON. | | `Failed to read file.` | The browser couldn't read the file. | #### `exportSettingsToFile` @tetherto/mdk-react-devkit/foundation Serialize `SettingsExportData` to JSON, package it as a downloadable Blob, and trigger a browser download. Returns the generated filename (e.g., `mdk-settings-2025-01-15T14-30-00-000Z.json`). The filename prefix is fixed in the foundation kit and does not interpolate [`WEBAPP_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_name). ```tsx const filename = exportSettingsToFile({ headerControls: { poolMiners: true, consumption: false }, featureFlags: { betaCharts: true }, timestamp: new Date().toISOString(), version: '1.0.0', }) ``` ## UI Foundation alert utilities `@tetherto/mdk-ui-foundation` ships two utility modules for the Alerts feature: query-parameter builders (`alert-queries`) and time-range chunking helpers (`historical-log-chunks`). These are the source consumed directly by the `useCurrentAlertDevices` and `useHistoricalAlerts` adapter hooks. ### Prerequisites - Complete the [@tetherto/mdk-ui-foundation installation](/reference/app-toolkit/ui-foundation) ### Import @tetherto/mdk-ui-foundation ```tsx ONE_DAY_MS, DEFAULT_HISTORICAL_WINDOW_MS, getDefaultHistoricalAlertsRange, buildCurrentAlertDevicesParams, buildHistoricalAlertsParams, breakTimeIntoIntervals, mergeAlertsByUuid, fetchHistoricalAlertsInChunks, } from '@tetherto/mdk-ui-foundation' ``` ### Alert query builders #### `ONE_DAY_MS` @tetherto/mdk-ui-foundation One day in milliseconds (`86_400_000`). The fetch-window size used by the historical-alerts data path. ```tsx ONE_DAY_MS // 86400000 ``` #### `DEFAULT_HISTORICAL_WINDOW_MS` @tetherto/mdk-ui-foundation Default historical-alerts look-back window — 14 days (`14 * ONE_DAY_MS`). Matches the devkit [``](/reference/ui/react/foundation/alerts) feature default; wider ranges fan out into more 24-hour requests. ```tsx DEFAULT_HISTORICAL_WINDOW_MS // 1209600000 (14 days in ms) ``` #### `getDefaultHistoricalAlertsRange` @tetherto/mdk-ui-foundation Returns the default historical-alerts range: the last `DEFAULT_HISTORICAL_WINDOW_MS` ending now. Used by the devkit [``](/reference/ui/react/foundation/alerts) feature and the shell Alerts page to seed their range state. Pass `now` to fix the upper bound in tests. ```tsx const range = getDefaultHistoricalAlertsRange() // { start: <14 days ago>, end: } // Injectable for tests getDefaultHistoricalAlertsRange(1_700_000_000_000) // { start: 1_700_000_000_000 - DEFAULT_HISTORICAL_WINDOW_MS, end: 1_700_000_000_000 } ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `now` | Optional | `number` | `Date.now()` | Upper bound of the window (ms epoch). | #### `buildCurrentAlertDevicesParams` @tetherto/mdk-ui-foundation Builds the `list-things` query params for the current-alerts table: every device that currently carries one or more alerts, with a 1 000 device limit. Consumed by `useCurrentAlertDevices`. `filterTags` widen the server-side selector so the fetch narrows with the active search chips (`ip-`, `sn-`, `mac-`, `firmware-`) instead of relying on client-side filtering alone. ```tsx // All devices with active alerts const params = buildCurrentAlertDevicesParams() // Narrowed to devices matching the active search chips const filtered = buildCurrentAlertDevicesParams(['ip-192.168.1.1', 'sn-ABC123']) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `filterTags` | Optional | `string[]` | `[]` | Active alert search chips to narrow the selector server-side. | #### `buildHistoricalAlertsParams` @tetherto/mdk-ui-foundation Builds the `history-log` query params for a single alerts window (`logType: 'alerts'`). Called once per 24-hour sub-window by the chunked fetch. ```tsx const params = buildHistoricalAlertsParams({ start: range.start, end: range.end }) // { logType: 'alerts', start: ..., end: ... } ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `range` | Required | `HistoricalAlertsRange` | none | `{ start: number; end: number }` — ms epoch bounds for the window. | ### Historical alert chunking #### `breakTimeIntoIntervals` @tetherto/mdk-ui-foundation Splits `[start, end]` into consecutive windows of `intervalMs` (default `ONE_DAY_MS`); the final window is clamped to `end`. Returns an empty array for an empty or inverted range. ```tsx // 24-hour windows (default) const windows = breakTimeIntoIntervals(start, end) // Custom window size const hourly = breakTimeIntoIntervals(start, end, 3_600_000) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `start` | Required | `number` | none | Range start (ms epoch). | | `end` | Required | `number` | none | Range end (ms epoch). | | `intervalMs` | Optional | `number` | `ONE_DAY_MS` | Window size in ms. | Returns `TimeInterval[]` where each element is `{ start: number; end: number }`. #### `mergeAlertsByUuid` @tetherto/mdk-ui-foundation Concatenates `next` onto `prev`, replacing any row that shares a `uuid` (later windows win) and appending the rest. Rows without a `uuid` are always appended. ```tsx const merged = mergeAlertsByUuid(previousAlerts, newAlerts) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `prev` | Required | `T[]` | none | Existing alert rows. | | `next` | Required | `T[]` | none | Rows from the latest window fetch. | Returns `T[]` where `T extends { uuid?: string }`. #### `fetchHistoricalAlertsInChunks` @tetherto/mdk-ui-foundation Fetches a historical-alerts range as successive 24-hour windows (oldest to newest), merging results by `uuid`. Individual window failures are swallowed so one bad request does not drop the whole range. The loop bails out early when `options.signal` is aborted. ```tsx fetchHistoricalAlertsInChunks, buildHistoricalAlertsParams, } from '@tetherto/mdk-ui-foundation' const alerts = await fetchHistoricalAlertsInChunks( { start: range.start, end: range.end }, async (window) => { const result = await myApi.historyLog(buildHistoricalAlertsParams(window)) return result.data }, { signal: abortController.signal }, ) ``` | Parameter | Status | Type | Default | Description | |-----------|--------|------|---------|-------------| | `range` | Required | `{ start: number; end: number }` | none | Full date range to paginate over (ms epoch). | | `fetchWindow` | Required | `function` | none | Called once per 24-hour window, oldest first. Receives a `TimeInterval` and returns `Promise`. | | `options.intervalMs` | Optional | `number` | `ONE_DAY_MS` | Window size in ms. | | `options.signal` | Optional | `AbortSignal` | none | Checked between windows — aborts the loop early on range changes. | # UI Foundation (/reference/app-toolkit/ui-foundation) @tetherto/mdk-ui-foundation If you are building a React app with the MDK kit, start with the [React adapter](/tutorials/ui/react) instead. `` and adapter hooks such as `useAuth` and `useDevices` wrap this package so most React code never imports `@tetherto/mdk-ui-foundation` directly. Use this reference when you need headless store access outside React (logging, websocket setup, test helpers) or when authoring a future framework adapter. `@tetherto/mdk-ui-foundation` is the framework-agnostic headless layer of the [MDK App Toolkit](/concepts/stack/app-toolkit). It ships Zustand vanilla stores and a TanStack Query Core `QueryClient` factory. There are **no React imports** in this package. ## Subpath exports | Subpath | Purpose | |---------|---------| | `.` | Top-level barrel | | `./store` | Zustand vanilla stores | | `./query` | `QueryClient` factory, query keys, and query/mutation factories | | `./types` | Shared type contracts | | `./stores.json` | Machine-readable store manifest (generated at build time) | ## Stores Each store is a Zustand vanilla singleton. In a React app, read and update state through the matching adapter hook instead of importing stores directly. | Store | Summary | Adapter hook | |-------|---------|--------------| | `authStore` | Session token and permission payload | [`useAuth`](/reference/app-toolkit/hooks/state#useauth) | | `devicesStore` | Fleet device list and current selection | [`useDevices`](/reference/app-toolkit/hooks/state#usedevices) | | `timezoneStore` | Active operator timezone | [`useTimezone`](/reference/app-toolkit/hooks/state#usetimezone) | | `notificationStore` | Unread notification counter (`count`, `increment`, `decrement`, `reset`) | [`useNotifications`](/reference/app-toolkit/hooks/state#usenotifications) | | `actionsStore` | Pending device and pool action submissions | [`useActions`](/reference/app-toolkit/hooks/state#useactions) | Import from `@tetherto/mdk-ui-foundation/store` (or the top-level barrel). ## QueryClient factory `createMdkQueryClient` builds a TanStack Query Core client with environment-aware Gateway base URL resolution: 1. Explicit override (typically from ``) 2. Build-time env: `VITE_MDK_API_URL` (Vite) or `MDK_API_URL` (Node) 3. Default: `http://localhost:3000` The `./query` subpath also exports query key helpers and factories (`authQuery`, `devicesQuery`, `deviceQuery`, `telemetryQuery`). See [TanStack Query](https://tanstack.com/query/latest) for general usage. ## Headless read outside React Utility code can subscribe to a store without React: ```ts const token = authStore.getState().token const unsubscribe = authStore.subscribe((state) => { console.log('token changed', state.token) }) // later: unsubscribe() ``` `` wires these singleton stores into React and creates the shared `QueryClient` for adapter hooks. ## What's not here yet Throttled telemetry subscriptions, stale detection, and history ring buffers are not yet present. They will be added alongside the consuming code that requires them. ## Next steps - [React get started](/tutorials/ui/react): three-package install and `` - [Wire a React app](/tutorials/ui/react/tutorial): full adapter wiring walkthrough - [MDK App Toolkit](/concepts/stack/app-toolkit): where UI Foundation fits in the frontend stack # Glossary (/reference/glossary) This page provides explanations for terms that new users may not be familiar with. - [Stack](#stack-and-hardware-terms) - [HRPC](#hyperswarm-rpc) ## Stack and hardware terms This section explains the terms you need to familiarize yourself with, using an Antminer rack as an example. | Term | What it is | Lives at | | --- | --- | --- | | **Kernel** (Orchestration Kernel) | The pull-only kernel that owns the device registry, routes commands, and aggregates telemetry. | [`backend/core/kernel/index.js`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js) | | **Gateway** | The developer-owned entry point between non-Node clients (UI, AI agents) and Kernel. Mandatory whenever a non-Node consumer reaches the kernel; not used in the in-process Antminer-rack example below. | [`backend/core/gateway/`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) | | **Worker** | A device-family translator. Speaks the MDK Protocol upward to Kernel and the vendor's native API downward to one device family (one miner brand, one container type, one pool API). | [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) | | **Manager class** | The JavaScript class a Worker exports, one per supported device model. Instances drive a single rack of devices. | e.g. `AM_S19XP`, `AM_S21` in [`backend/workers/miners/antminer/index.js`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/index.js) | | **Thing** | One registered device instance. Created by calling `manager.registerThing({ info, opts })`. Identified by a generated `deviceId`. | runtime, in `manager.mem.things` | ### How they compose, for an Antminer rack ```mermaid flowchart TB subgraph clientLayer ["Your code"] Client["your script (e.g., client.js)"] end subgraph kernel ["Kernel"] Kernel["Kernel
device registry · command routing · telemetry pull"] end subgraph workerLayer ["Antminer Worker"] AntminerWorker["e.g., AM_S21PRO"] end subgraph devices ["Antminer devices (real or mock)"] Miners["Antminers (HTTP / digest auth)"] end Client -->|"HRPC"| Kernel Kernel -->|"HRPC"| AntminerWorker AntminerWorker --> Miners ``` The same shape repeats for every other device family (Whatsminer, container vendors, pool APIs). For a multi-Worker view, parallel Workers, and multi-site deployments, see [`architecture.md#scaling`](/concepts/architecture#scaling). ## Hyperswarm RPC MDK uses [`@hyperswarm/rpc`](https://github.com/holepunchto/rpc) as its runtime transport. Hyperswarm RPC (HRPC) is not an HTTP-based RPC system. It is an RPC layer that rides on Hyperswarm peer-to-peer connectivity. The library is a simple RPC over the Hyperswarm DHT, backed by `Protomux`. Think of it as a peer-to-peer remote function call system built on a DHT and an encrypted connection layer. **Mental model** — Hyperswarm finds peers and establishes connections; `Protomux` divides the connection into named channels; RPC defines the conversation — a caller names a method and receives a reply. A useful analogy is a phone call between peers — Hyperswarm helps the phones find each other and connect; `Protomux` splits the line into channels; RPC defines how one side asks for a method and the other side responds. **Practical implications:** - You work with services, methods, requests, and responses — not URLs and routes - The RPC-shaped API is identical across same-process, same-host, and distributed deployments; only the discovery mechanism changes (same-process registration, shared directory, or DHT topic) - Peers discover and communicate without a central HTTP server ### HRPC on the same host MDK uses HRPC as the single transport across all deployment shapes — same-process, same-host, and distributed. Every component is addressed by its public key, not by a socket path or hostname. The Gateway, a standalone Node.js script, and a remote service all connect the same way: ```js createMdkClient({ hrpc: { key } }) ``` The Noise handshake that HRPC performs on every connection authenticates by key, so Kernel's allowlist works identically whether the caller is on the same machine or a remote host. This is consistent with the broader Holepunch ecosystem philosophy — everything is a peer addressed by public key. When the peer is on the same machine it routes locally over the local network interface; the application code sees no difference. ## Next steps - You are ready to run the example in [Run the stack](/tutorials/backend-stack/run) - Learn more about: - Multi-process discovery across machines: [Worker discovery](/concepts/stack/workers) - Gateway implementation details (HTTP routing, JWT auth, RBAC) — see [`backend/core/gateway/worker.js`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) - Building your own Worker for a new device family: see [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) - Per-device contract details (telemetry units, command shapes, error codes): those live in each Worker's `mdk-contract.json`, e.g. [`backend/workers/miners/antminer/mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/mdk-contract.json) # Kernel reference (/reference/kernel) `@tetherto/mdk-ork` is the orchestration kernel of the MDK stack. This subsection holds the canonical specs for its internal modules. For the architectural narrative explaining how these modules fit together, see [Kernel](/concepts/stack/kernel). ## What's documented - **[Modules](/reference/kernel/modules)**: per-module responsibility, interfaces, state machines, transition rules, crash-recovery procedures, and scaling characteristics. # Kernel modules (/reference/kernel/modules) `@tetherto/mdk-ork`'s coordination splits across single-purpose modules. Each owns its own state machine, persistence boundary, and scaling characteristics. Six modules ship in v0.0.1; two more (Fault Supervisor, Concurrency Manager) are deferred to a later release. For the architectural overview that explains how these modules connect, see [Kernel](/concepts/stack/kernel). This page is the per-module spec. ## How to read this page Each accordion below covers one module: - **Responsibility**: what the module owns and the example commands or events it handles. - **Interfaces**: input and output channels, plus the public function names callers depend on. - **State machine**: the canonical diagram for the module's internal lifecycle. - **Crash recovery**: behavior on a fresh start, including how state is reconstructed. - **Scalability**: where the module can be extracted, sharded, or replicated. ## Modules **Responsibility**: validates incoming commands against the generic MDK schema, checks permissions, and resolves the correct Worker based on the `deviceId`. *Example*: when an Gateway sends a `reboot` command for `wm001`, the Dispatcher verifies that `wm001` exists, that `reboot` is a valid capability for it, then passes the request to the State Machine. **Interfaces**: - *Input*: receives generic commands via Holepunch RPC (HRPC) and the MDK Protocol from the Gateway or MCP Handler. - *Output*: hands off validated commands to the Command State Machine. - *Functions*: `dispatchCommand(deviceId, action, payload)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Validating Validating --> RoutingAction : Valid Validating --> Rejected : Invalid RoutingAction --> Enqueued Enqueued --> [*] ``` **Crash recovery**: none needed. In-flight requests fail and must be retried by the client. **Scalability**: extracted easily; can run independently to offload validation. **Responsibility**: tracks the execution lifecycle of every single command in the system. Receives execution results directly via the synchronous HRPC response. If the connection drops or a response is delayed, it relies on the Scheduler to fetch the latest status via `state.pull` so commands cannot hang. *Example*: once the `reboot` command is dispatched it transitions to `EXECUTING`. If the HRPC response returns OK it transitions to `SUCCESS`. If the response hangs, the next `state.pull` fetches the true status from the Worker. **Interfaces**: - *Input*: receives validated commands from the Dispatcher; status updates from HRPC responses or Scheduler ticks. - *Output*: invokes the Worker HRPC execution layer; emits terminal state results to the caller. - *Functions*: `enqueue(command)`, `syncState(commandId)`, `cancel(commandId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> QUEUED QUEUED --> DISPATCHED DISPATCHED --> EXECUTING : HRPC sent EXECUTING --> SUCCESS : state.pull (response) EXECUTING --> FAILED : state.pull (error) EXECUTING --> TIMEOUT TIMEOUT --> QUEUED : Retry allowed TIMEOUT --> FAILED : Max retries SUCCESS --> [*] FAILED --> [*] ``` **Crash recovery**: on startup, performs a recovery sweep of pending commands. `DISPATCHED` and `EXECUTING` commands are forced to `TIMEOUT` (and re-queued if retries are available); `QUEUED` commands are left untouched. **Scalability**: requires state sharding (for example, by device or rack). **Responsibility**: the phonebook for the entire `@tetherto/mdk-ork` ecosystem. Maps which physical device IDs belong to which connected Worker channels and stores their declared capabilities. *Example*: a `whatsminer-worker` connects and declares it manages `wm001` and `wm002`. The Registry saves this topology so the Dispatcher knows exactly where to route a command for `wm001`. **Interfaces**: - *Input*: `identity.register` requests from Workers. - *Output*: internal events triggering full state lifecycle binding. - *Functions*: `resolveWorkerState(target)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Unregistered Unregistered --> Discovered : DHT peer detected Discovered --> IdentitySaved : identity pulled IdentitySaved --> Ready : capabilities pulled Ready --> Terminated : eviction Terminated --> [*] ``` **Crash recovery**: rebuilt from state, which serves as a baseline to detect Workers that were registered but failed to reconnect. **Scalability**: read-heavy by nature; can be extracted into a read-replica architecture or partitioned by region or rack. **Responsibility**: a lightweight proxy and routing layer between the upper system (UI / AI) and the downstream Workers. Rather than `@tetherto/mdk-ork` performing heavy time-series aggregations, the *Worker* is responsible for storing and aggregating data for the specific devices it controls. The Collector simply provides an interface to query this data and proxies the response up to the UI (via Gateway) or the AI Agent. **Worker data handling (telemetry context)**: - *Compaction*: the Worker handles compaction of metrics over large time frames. - *Local storage*: Workers should save telemetry data in a local Hyper DB. - *As-requested serving*: the Worker serves data strictly when `@tetherto/mdk-ork` asks for it, precisely as dictated by the telemetry schemas in `mdk-contract.json`. - *Internal scheduling*: to achieve this without blocking `@tetherto/mdk-ork`, the Worker may run its own internal scheduler for device polling. **Interfaces**: - *Input*: client or AI telemetry queries (for example, "fetch metrics for device wm001"). - *Output*: normalized telemetry payloads passed straight through from the Worker to the requesting layer. - *Functions*: `proxyTelemetryFetch(deviceId, queryArgs)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Idle Idle --> Proxying : Request received Proxying --> RoutingToClient : Worker returns data Proxying --> Timeout : Worker unresponsive RoutingToClient --> Idle ``` **Scalability**: because the heavy lifting of data storage and aggregation is pushed down into the isolated Worker processes, the Collector remains stateless and highly scalable as a pure asynchronous router. **Responsibility**: the system metronome. Triggers repetitive tasks without holding any domain-specific logic itself. *Example*: emits an internal `tick` event every 5 seconds that the Health Monitor listens to, prompting it to ping all Workers. **Interfaces**: - *Input*: system clock and configured task intervals. - *Output*: injects intents (for example, `telemetry.pull`, `health.ping`) into the Dispatcher or Collector. - *Functions*: `addJob(interval, intent)`, `removeJob(jobId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Waiting Waiting --> Triggered : Interval elapsed Triggered --> Waiting ``` **Crash recovery**: timers re-initialize from zero on startup. Tasks are strictly idempotent. **Scalability**: scales trivially. Requires basic distributed locking to avoid duplicate ticks in multi-process `@tetherto/mdk-ork` deployments. **Responsibility**: continuously evaluates the liveness and readiness of every registered Worker to prevent routing messages to dead nodes. *Example*: if `health.ping` to a Worker fails three times in a row, the Health Monitor marks the Worker's status as `SICK` and tells the Registry to halt routing new commands there. **Interfaces**: - *Input*: executes `health.ping` sequentially based on Scheduler ticks. - *Output*: pushes status updates to the Registry. - *Functions*: `pingWorker(workerId)`, `getHealth(workerId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> UNKNOWN UNKNOWN --> HEALTHY : Ping success HEALTHY --> SICK : Ping failed (1) SICK --> DEAD : Ping failed (threshold) SICK --> HEALTHY : Ping success DEAD --> HEALTHY : Reconnected ``` **Crash recovery**: blank slate on startup; re-evaluates all known Workers immediately via ping. **Scalability**: operates locally per `@tetherto/mdk-ork` kernel, or via independent lightweight ping agents. **Idea**: implements circuit-breaker patterns to protect the overall system from cascading failures caused by bad hardware or software bugs (for example, rejecting commands during a cooling period after repeated errors). **Status**: deferred for the first cut to keep the core orchestrator simple. If the use case arises (such as complex retry backoffs or cluster destabilization), it will be reintroduced. **Idea**: provides guaranteed lock management and queue limits to ensure mutually exclusive commands do not overlap on physical devices. **Status**: deferred for the first cut. The system relies solely on the basic command queue. If explicit global locks or backpressure limits become necessary, this module will be built out. # Protocol reference (/reference/protocol) The MDK Protocol is the contract that crosses every layer of the stack: Workers, `@tetherto/mdk-ork`, and the Gateway all exchange the same envelope. This subsection holds the canonical specs. For the architectural narrative explaining how the protocol fits together, see [Architecture](/concepts/architecture#the-mdk-protocol). ## What's documented - **[Messages](/reference/protocol/messages)**: envelope schema, request/response examples, the full action catalogue, and the base command set. # Protocol messages (/reference/protocol/messages) Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page is the canonical spec for that envelope, the full set of protocol actions, and the base command set every Worker must support. For the architectural narrative explaining when each action fires, see [Architecture](/concepts/architecture#the-mdk-protocol). ## Envelope ```json { "id": "uuid-v4", "version": "0.1.0", "type": "request | response | event", "action": "", "sender": "", "target": " | null", "deviceId": "string | null", "timestamp": 1711640000000, "payload": {} } ``` External consumers (UI or AI agents) only provide `deviceId`; the `target` Worker identity is internally resolved by `@tetherto/mdk-ork`. A concrete request and response pair, end to end: ```json // request: Gateway asks @tetherto/mdk-ork to reboot device wm001 { "id": "8d1c-e3a4", "version": "0.1.0", "type": "request", "action": "command.request", "sender": "appNode:fleet-api:1", "target": null, "deviceId": "wm001", "timestamp": 1711640000000, "payload": { "command": "reboot" } } // response: @tetherto/mdk-ork relays the worker's terminal result { "id": "1f9b-77c2", "version": "0.1.0", "type": "response", "action": "command.result", "sender": "ork:kernel:tx-1", "target": "appNode:fleet-api:1", "deviceId": "wm001", "timestamp": 1711640002145, "payload": { "status": "SUCCESS", "elapsedMs": 2145 } } ``` ## Actions | Action | Type | Direction | Purpose | |---|---|---|---| | *(DHT presence)* | passive | Worker to DHT topic | Worker joins a known Hyperswarm topic; `@tetherto/mdk-ork` detects its peer connection automatically | | `identity.request` | request | `@tetherto/mdk-ork` to Worker | Requests the Worker's identity and managed devices | | `capability.request` | request | `@tetherto/mdk-ork` to Worker | Asks the Worker to declare its full capability schema | | `state.pull` | request | `@tetherto/mdk-ork` to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) | | `telemetry.pull` | request | `@tetherto/mdk-ork` to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) | | `command.request` | request | `@tetherto/mdk-ork` to Worker | Resolves the Worker by `deviceId` and dispatches the command for execution | | `health.ping` | request | `@tetherto/mdk-ork` to Worker | Liveness probe (high cadence tick, e.g., 5s) | ## Base command set The protocol standardizes a Base Command Set supported by every Worker: - `getConfig`: retrieve current device configuration - `setConfig`: update device configuration parameters - `health`: fetch detailed diagnostic health status from the device # Supported hardware (/reference/supported-hardware) ## Overview MDK integrates field hardware through Workers. Each Worker declares what it supports in its `mdk-contract.json`, and that contract is the single source of truth for coverage. Use this page to discover what Workers are supported. ## What MDK supports - **Miners**: For example, Bitmain Antminer, MicroBT Whatsminer - **Containers**: For example, Bitmain Antspace, Bitdeer - **Power meters**: For example, ABB, Satec - **Sensors**: For example, Seneca - **Mining pools**: Protocol integrations such as Ocean, F2Pool For the exact model lists, Worker packages, and per-Worker docs, see the generated catalogue: - [Full supported-hardware catalogue](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/supported-hardware.md) — generated from every `backend/workers/**/mdk-contract.json` ## Next steps - New to the moving parts? Read [terminology](/reference/glossary) (Kernel, Worker, manager, thing, mock) - Decide how to run the Worker service — [Deployment topologies](/concepts/deployment-topologies) - Run a miner Worker — [Run a miner Worker](/guides/miners) # UI Devkit (/reference/ui) ## TL;Dr Today the published React path is complete; other frameworks are on the [roadmap](/support/resources/roadmap) and will reuse the same headless core. The MDK React UI Devkit is a [three-layer stack](#how-the-layers-fit-together): - [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation): headless Zustand stores and TanStack Query client factory (framework-agnostic) - [`@tetherto/mdk-react-adapter`](/quickstart/wire-react#wrap-your-app-in-mdkprovider): `` and store hooks; binds the core into your UI runtime (React today) - [`@tetherto/mdk-react-devkit`](/tutorials/ui/react): [`/core`](/reference/ui/react/core) primitives and [`/foundation`](/reference/ui/react/foundation) mining-domain components ## Framework quickstarts } title={React} href="/tutorials/ui/react" description={ Get started with the React MDK UI Devkit } /> Vue} href="/support/resources/roadmap" description={ <> Reactive hooks for Vue via @tetherto/mdk-vue Learn about the release schedule → } /> Svelte} href="/support/resources/roadmap" description={ <> Reactive hooks for Svelte via @tetherto/mdk-svelte Learn about the release schedule → } /> Web Components} href="/support/resources/roadmap" description={ <> Framework-agnostic Web Components via @tetherto/wc Learn about the release schedule → } /> ## How the layers fit together The MDK React UI Devkit and subsequent frameworks will share a similar architecture: ```mermaid graph TB subgraph headless [Layer 1: Headless] uiCore([mdk-ui-foundation
Zustand stores · Query client factory
Framework-agnostic]) end subgraph adapter [Layer 2: Framework adapter] reactAdapter([mdk-react-adapter
MdkProvider · store hooks
React today]) end subgraph uiLib [Layer 3: Framework UI library] reactDevkit([mdk-react-devkit
/core + /foundation
Primitives and mining-domain UI]) end uiCore --> reactAdapter reactAdapter --> reactDevkit style headless fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style adapter fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style uiLib fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A ``` ## Next steps - [Quickstart](/quickstart/wire-react): integrate the three packages into your React app - [Explore the demo](/tutorials/ui/explore-the-demo): run the demo app in your browser # @tetherto/mdk-react-devkit (/reference/ui/react/core) [The core entrypoint](/support/resources/repositories) (`@tetherto/mdk-react-devkit/core`) provides the foundational **React** UI components, utilities, and theme system for the MDK React UI Devkit. This is the `/core` subpath of the devkit package, not the framework-agnostic [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) headless package. Mining-domain components, hooks, and settings live on the [`/foundation`](/reference/ui/react/foundation) entrypoint. Both subpaths are exported from `@tetherto/mdk-react-devkit`. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. ## What's included ### Components Production-ready React components organized by category: | Category | Description | |----------|-------------| | [Forms](/reference/ui/react/core/components/forms) | Input and form control components | | [Overlays](/reference/ui/react/core/components/overlays) | Dialogs, popovers, tooltips, and toasts | | [Data display](/reference/ui/react/core/components/data-display) | Cards, tables, tags, and data presentation | | [Charts](/reference/ui/react/core/components/charts) | Data visualization components | | [Navigation](/reference/ui/react/core/components/navigation) | Sidebar, tabs, and breadcrumbs | | [Loading](/reference/ui/react/core/components/loading) | Spinners, loaders, and progress indicators | | [Errors](/reference/ui/react/core/components/errors) | Error boundaries, error cards, and alerts | | [Logs](/reference/ui/react/core/components/logs) | Log display components | See the [Components reference](/reference/ui/react/core/components) for the full list with demo links. ### Icons 70+ purpose-built icons for Bitcoin mining applications: - Navigation icons (Dashboard, Farms, Inventory, etc.) - Status icons (Mining, Offline, Error, etc.) - Weather icons (Sunny, Cloudy, Rainy, etc.) - Alarm icons (Temperature, Pressure, Fluid, etc.) ### Utilities Helper functions for common operations: - [`formatNumber`](/reference/app-toolkit/ui-devkit/utilities#formatnumber), [`formatHashrate`](/reference/app-toolkit/ui-devkit/utilities#formathashrate), [`formatCurrency`](/reference/app-toolkit/ui-devkit/utilities#formatcurrency): Number formatting - [`formatDate`](/reference/app-toolkit/ui-devkit/utilities#formatdate), [`formatRelativeTime`](/reference/app-toolkit/ui-devkit/utilities#formatrelativetime): Date formatting - [`cn`](/reference/app-toolkit/ui-devkit/utilities#cn): Class name merging ([clsx](https://github.com/lukeed/clsx) wrapper) - Conversion utilities for energy, hashrate, and units - Validation utilities for email, URL, and empty checks ### Theme system CSS custom properties and utilities for consistent styling: - Color tokens (primary, gray scales) - Spacing scale - Border radius scale - Font size scale - Light/dark mode support ### Types TypeScript types for type-safe development: - [`ComponentSize`](/reference/app-toolkit/ui-devkit/types#componentsize), [`ButtonVariant`](/reference/app-toolkit/ui-devkit/types#buttonvariant), [`ColorVariant`](/reference/app-toolkit/ui-devkit/types#colorvariant) - [`Status`](/reference/app-toolkit/ui-devkit/types#status), [`PaginationParams`](/reference/app-toolkit/ui-devkit/types#paginationparams), [`ApiResponse`](/reference/app-toolkit/ui-devkit/types#apiresponse) - Chart types, table types, and utility types ## Reference Detailed reference material lives in the unified [Reference section](/reference). Core (`/core`) slices are: - [Constants](/reference/app-toolkit/ui-devkit/constants#core-constants): colors, units, currency, chart configs - [Types](/reference/app-toolkit/ui-devkit/types#core-types): UI primitives, API shapes, value-unit types - [Utilities](/reference/app-toolkit/ui-devkit/utilities#core-utilities): formatting, validation, conversions, `cn` and friends ## Import examples ```tsx // Import components // Import utilities // Import types // Import icons // Import styles (required for component styling) ``` # Components (/reference/ui/react/core/components) The `@tetherto/mdk-react-devkit/core` package provides production-ready React components. All components are built with accessibility in mind and support both light and dark themes. ## Import ### Prerequisites - Complete the [installation](/quickstart/wire-react) ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Import the core styles in your app's entry point: ```tsx ``` ### Import named components Declare the components you require: ```tsx ``` ## Supported components ## Styling Components use BEM-style CSS classes (e.g., `.mdk-button`, `.mdk-card__header`) for styling consistency and easy customization. ## Class name forwarding Every component forwards `className` to its root element, so you can apply layout or override styles without ejecting. This is assumed throughout and not repeated in every props table. Components with multiple styleable parts also expose **named** hooks (for example `contentClassName`, `indicatorClassName`, `dropdownClassName`) — those *are* listed in the relevant component's props table. ## Component design principles - **Composable**: Components are designed to work together - **Accessible**: Built with ARIA attributes and keyboard navigation - **Themeable**: Support light/dark modes via CSS custom properties - **Type-safe**: Full TypeScript support with exported prop types # Chart components (/reference/ui/react/core/components/charts) Chart components for visualizing time-series data, metrics, and statistics. Built on [Chart.js](https://www.chartjs.org/) and [Lightweight Charts](https://tradingview.github.io/lightweight-charts/), supporting: - Chart types: components that render datasets (`AreaChart`, `BarChart`, `DoughnutChart`, `GaugeChart`, `LineChart`) - Domain chart wrappers: opinionated chart components with preset layouts and series config (`AverageDowntimeChart`, `ThresholdLineChart`, `OperationsEnergyCostChart`) - [Composition elements](/reference/ui/react/core/components/charts/composition): layout chrome, legends, stats rows, and chart utilities (`ChartContainer`, `ChartStatsFooter`, `DetailLegend`, `MinMaxAvg`, helpers) ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## All chart type components ## `AreaChart` Presentational Chart.js area chart (line series with fill). Data and options follow the same Chart.js model as [`LineChart`](#linechart), without a separate MDK data wrapper type. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `ChartData` | none | [Chart.js](https://www.chartjs.org/) line chart `data` (datasets typically use `fill: true` for an area look) | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) options (merged with defaults) | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip config; when set, replaces the default Chart.js tooltip | | `height` | Optional | `number` | `300` | Chart height in pixels | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx const data = { labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'], datasets: [ { label: 'Revenue', data: [100, 120, 115, 134, 168], fill: true, backgroundColor: 'rgba(114, 245, 158, 0.2)', borderColor: '#72F59E', }, ], } ``` ## `BarChart` The `BarChart` component renders Chart.js bar or column series. It manages: 1. **Data** (`data`): labels and datasets passed to Chart.js. 2. **Chart options** (`options`): merged with MDK defaults. 3. **Formatting** (`formatYLabel`, `formatDataLabel`, `tooltip`): axis labels, data labels, and HTML tooltips. 4. **Presentation** (`isStacked`, `isHorizontal`, `showLegend`, `legendPosition`, `legendAlign`, `showDataLabels`): layout and legend. 5. **Size** (`height`): chart height in pixels. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `ChartData` | none | [Chart.js](https://www.chartjs.org/) data object | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) options (merged with defaults) | | `formatYLabel` | Optional | `function` | none | Format Y-axis tick labels | | `formatDataLabel` | Optional | `function` | none | Format data label values | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip config | | `isStacked` | Optional | `boolean` | `false` | Stack bars on top of each other | | `isHorizontal` | Optional | `boolean` | `false` | Render bars horizontally | | `showLegend` | Optional | `boolean` | `true` | Show [Chart.js](https://www.chartjs.org/) legend | | `legendPosition` | Optional | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Legend position | | `legendAlign` | Optional | `'start' \| 'center' \| 'end'` | `'start'` | Legend alignment | | `showDataLabels` | Optional | `boolean` | `false` | Show values above bars | | `height` | Optional | `number` | `300` | Chart height in pixels | ### Basic usage ```tsx const data = { labels: ['Jan', 'Feb', 'Mar', 'Apr'], datasets: [ { label: 'Hashrate (TH/s)', data: [120, 150, 180, 200], backgroundColor: '#72F59E', }, ], } ``` ### Data from hooks Hand-built Chart.js `data` (above) is valid. When app hooks return `{ labels, series }` declarative input, convert with [`buildBarChartData`](/reference/ui/react/core/components/charts/composition#hook-shaped-bar-data) in [chart utilities](/reference/ui/react/core/components/charts/composition#chart-utilities), optionally merge per-series `datalabels`, then pass the result to `data`. ### Stacked bar chart ```tsx const data = { labels: ['Site A', 'Site B', 'Site C'], datasets: [ { label: 'Online', data: [100, 80, 120], backgroundColor: '#72F59E' }, { label: 'Offline', data: [10, 20, 5], backgroundColor: '#FF6B6B' }, ], } ``` ### Horizontal bar chart ```tsx `${value} TH/s`} /> ``` ### With data labels ```tsx `${value.toFixed(1)}%`} /> ``` ## `DoughnutChart` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `DoughnutChartDataset[]` | none | Array of `{ label, value, color? }` slices (see [data shape](#data-shape-for-doughnut-charts)) | | `unit` | Optional | `string` | `''` | Unit suffix shown in the default tooltip | | `options` | Optional | `ChartOptions` | none | [Chart.js](https://www.chartjs.org/) doughnut options (merged with defaults) | | `cutout` | Optional | `string` | `'75%'` | Inner radius cutout (doughnut ring thickness) | | `borderWidth` | Optional | `number` | `4` | Border width between segments | | `height` | Optional | `number` | `260` | Chart height in pixels | | `legendPosition` | Optional | `string` | `'top'` | Where to place the custom legend relative to the chart | | `tooltip` | Optional | `ChartTooltipConfig` | none | Custom HTML tooltip; when set, replaces the default doughnut tooltip | | `formatValue` | Optional | `(value: number) => string` | none | Formats slice values in the built-in legend and default tooltip (default: raw number) | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for doughnut charts Pass `data` as an array of `{ label, value, color? }`. The chart maps this into Chart.js internally (`labels`, single dataset, segment colors). Omit `color` to use the default palette rotation. ### Basic usage ```tsx const data = [ { label: 'Online', value: 85, color: '#72F59E' }, { label: 'Offline', value: 10, color: '#FF6B6B' }, { label: 'Maintenance', value: 5, color: '#FFD700' }, ] ``` ## `GaugeChart` Speedometer-style presentational arc gauge for displaying a single normalized value, providing: 1. **Percent** (`percent`): fill level from `0` to `1` (values outside that range are clamped). 2. **Arc appearance** (`colors`, `arcWidth`, `nrOfLevels`): segment colors, relative thickness, and segment count. 3. **Center label** (`hideText`): percentage text in the center of the gauge (hidden when `hideText` is `true`). 4. **Accessibility** (`id`): stable id wired into SVG labels (defaults to `mdk-gauge-chart`). 5. **Layout** (`height`, `maxWidth`, `className`): container height, max width, and host root class. The `GaugeChart` is SVG-based; strokes and labels may paint past the host element’s layout bounds. For a hard edge, wrap the gauge in an element with **`overflow: hidden`**, or add vertical spacing. [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) does **not** set overflow clipping on the chart slot—it is for title, loading/empty, and footer chrome like other charts (see [Composition](/reference/ui/react/core/components/charts/composition)); it may add spacing that makes overlap less visible, but it is not a substitute for clipping when you need it. ### Import ```tsx ``` The gauge is driven by a **normalized** `percent` in the range **0–1** (for example `0.75` is 75%). It is not a `value` / `max` API, and it does not accept `label` or `unit` props (see [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) for layout notes). ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `percent` | Required | `number` | none | Fill level from `0` to `1` (clamped) | | `colors` | Optional | `string[]` | green → soft green → red (theme) | Arc segment colors as HEX strings | | `arcWidth` | Optional | `number` | `0.2` | Arc thickness as a fraction of the gauge radius (`0`–`1`) | | `nrOfLevels` | Optional | `number` | `3` | Number of colored segments on the arc | | `hideText` | Optional | `boolean` | `false` | Hide the percentage text in the center | | `id` | Optional | `string` | `'mdk-gauge-chart'` | Stable id for SVG accessibility labels | | `height` | Optional | `number` \| `string` | `200` | Container height (pixels or CSS length, e.g. `'50%'`) | | `maxWidth` | Optional | `number` | `500` | Maximum width in pixels | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ### In a chart card (same shell as other charts) [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) adds title, loading, and empty chrome; it does **not** apply `overflow: hidden` to the chart body. When you still see bleed next to siblings or footers, wrap `GaugeChart` in an extra element with **`overflow: hidden`**. ```tsx

``` ### Custom colors and arc ```tsx ``` ## `LineChart` The `LineChart` component renders time-series lines. It manages: 1. **Series data** (`data`): `LineChartData` with millisecond `x` values (see [data shape](#data-shape-for-line-charts)). 2. **Context** (`timeline`, `unit`): timeline identifier and unit label for tooltips. 3. **Formatting** (`yTicksFormatter`, `priceFormatter`, `customLabel`): tick and tooltip text. 4. **Presentation** (`backgroundColor`, `beginAtZero`, `showPointMarkers`, `showDateInTooltip`, `uniformDistribution`): axis and marker behavior. 5. **Size** (`height`): chart height in pixels. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Required | `LineChartData` | none | Object with a `datasets` array (see [data shape](#data-shape-for-line-charts)) | | `timeline` | Optional | `string` | none | Timeline identifier | | `yTicksFormatter` | Optional | `function` | none | Format Y-axis ticks | | `priceFormatter` | Optional | `function` | none | Format tooltip values | | `customLabel` | Optional | `string` | none | Custom tooltip label | | `unit` | Optional | `string` | `''` | Unit label for values | | `backgroundColor` | Optional | `string` | none | Chart background color | | `beginAtZero` | Optional | `boolean` | `false` | Start Y-axis at zero | | `showPointMarkers` | Optional | `boolean` | `false` | Show data point markers | | `showDateInTooltip` | Optional | `boolean` | `false` | Show date in tooltip | | `uniformDistribution` | Optional | `boolean` | `false` | Uniform time distribution | | `height` | Optional | `number` | `240` | Chart height in pixels | #### Data shape for line charts `LineChartData` is `{ datasets: LineDataset[] }`. Each `LineDataset` has `label`, `borderColor`, optional `visible` / `borderWidth` / `extraTooltipData`, and `data: { x, y }[]` where `x` is a time value in **milliseconds** (for example from `Date.prototype.valueOf()`) and `y` is the series value (number, or `null` / `undefined` for gaps). ### Basic usage ```tsx const data = { datasets: [ { label: 'Hashrate', borderColor: '#72F59E', data: [ { x: 1704067200000, y: 150 }, { x: 1704153600000, y: 155 }, { x: 1704240000000, y: 160 }, ], }, ], } ``` ### Multiple lines ```tsx const hashrateData = [ { x: 1704067200000, y: 150 }, { x: 1704153600000, y: 155 }, ] const targetData = [ { x: 1704067200000, y: 140 }, { x: 1704153600000, y: 145 }, ] const data = { datasets: [ { label: 'Hashrate', borderColor: '#72F59E', data: hashrateData, }, { label: 'Target', borderColor: '#FFD700', data: targetData, }, ], } ``` ## `AverageDowntimeChart` Stacked bar chart showing monthly average downtime broken into **Curtailment** and **Op. Issues** series. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`BarChart`](#barchart). It manages: 1. **Data** (`data`): period labels and per-series rate arrays (values are fractions 0–1). 2. **Formatting** (`yTicksFormatter`): formats Y-axis ticks, tooltips, and optional bar data labels. 3. **Presentation** (`showDataLabels`, `title`, `unit`): bar data labels and header text. 4. **Layout** (`height`, `barWidth`): chart height and bar width in pixels. 5. **State** (`isLoading`, `emptyMessage`): loading overlay and empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `AverageDowntimeChartData` | none | Period labels and downtime rate arrays (see [data shape](#data-shape-for-averagedowntimechart)) | | `yTicksFormatter` | Optional | `function` | `defaultAverageDowntimeRateFormatter` | Formats Y-axis ticks, tooltips, and data labels; input values are 0–1 rates | | `showDataLabels` | Optional | `boolean` | `false` | Show formatted rate values above each bar segment | | `title` | Optional | `string` | `'Monthly Average Downtime'` | Header title | | `unit` | Optional | `string` | `'%'` | Unit label shown beneath the title | | `height` | Optional | `number` | `280` | Chart height in pixels | | `barWidth` | Optional | `number` | `38` | Bar width in pixels | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows a loading overlay | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `AverageDowntimeChart` Pass `data` as an `AverageDowntimeChartData` object: | Field | Type | Description | |-------|------|-------------| | `labels` | `string[]` | Period labels (e.g. month names) | | `curtailment` | `number[]` | Curtailment downtime rates (0–1) per period | | `operationalIssues` | `number[]` | Operational issue downtime rates (0–1) per period | Both series arrays are optional; absent series are omitted from the chart. ### Basic usage ```tsx ``` ### Custom formatter `yTicksFormatter` receives raw 0–1 rate values and must return a display string. The default, `defaultAverageDowntimeRateFormatter`, multiplies by 100 and appends `%`: ```tsx AverageDowntimeChart, defaultAverageDowntimeRateFormatter, } from '@tetherto/mdk-react-devkit/core' // Override: show one decimal place `${(rate * 100).toFixed(1)}%`} showDataLabels /> ``` ### Exported helpers | Export | Role | |--------|------| | `buildAverageDowntimeBarChartData` | Converts `AverageDowntimeChartData` into Chart.js `data` | | `buildAverageDowntimeTooltip` | Builds the HTML tooltip config for the stacked bars | | `defaultAverageDowntimeRateFormatter` | Default Y-axis / label formatter (rate × 100, `%` suffix) | | `hasAverageDowntimeData` | Returns `true` when `data` has at least one non-empty series | ## `ThresholdLineChart` Time-series line chart with optional horizontal threshold bands. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`LineChart`](#linechart). It manages: 1. **Data** (`data`): one or more line series plus optional threshold lines. 2. **Formatting** (`yTicksFormatter`): formats Y-axis ticks. 3. **Presentation** (`title`, `unit`, `isTall`, `isLegendVisible`): header, height variant, and legend toggle. 4. **Layout** (`height`): explicit chart height in pixels (overrides `isTall`). 5. **State** (`emptyMessage`): empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `ThresholdLineChartData` | none | Series and optional thresholds (see [data shape](#data-shape-for-thresholdlinechart)) | | `yTicksFormatter` | Optional | `function` | unit-aware default | Formats Y-axis tick labels; defaults to `"${value} ${unit}"` when `unit` is set, otherwise `String(value)` | | `title` | Optional | `string` | none | Header title; rendered as `"${title} (${unit})"` when both are set | | `unit` | Optional | `string` | none | Unit appended to the title and used by the default tick formatter | | `isTall` | Optional | `boolean` | `false` | When `true`, uses a taller default height of `360px` instead of `280px` | | `isLegendVisible` | Optional | `boolean` | `true` | Show the interactive legend with dataset visibility toggles | | `height` | Optional | `number` | `280` (`360` when `isTall`) | Chart height in pixels; explicit value overrides `isTall` | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `ThresholdLineChart` `ThresholdLineChartData` holds series and optional threshold lines: | Field | Type | Description | |-------|------|-------------| | `series` | `ThresholdLineChartSeries[]` | Line series to render | | `thresholds` | `ThresholdLineChartThreshold[]` | Optional horizontal reference lines | Each `ThresholdLineChartSeries`: | Field | Type | Description | |-------|------|-------------| | `label` | `string` | Series label shown in the legend | | `points` | `ThresholdLineChartPoint[]` | Data points (`{ timestamp: string \| number, value: number }`) | | `color` | `string` | Optional line color | | `fill` | `boolean` | Optional area fill below the line | Each `ThresholdLineChartThreshold`: | Field | Type | Description | |-------|------|-------------| | `label` | `string` | Label shown in the legend | | `value` | `number` | Y-axis value at which the horizontal line is drawn | | `color` | `string` | Optional line color | ### Basic usage ```tsx ``` ### Tall variant ```tsx ``` ### Exported helpers | Export | Role | |--------|------| | `toThresholdLineChartData` | Converts `ThresholdLineChartData` into `LineChartData` for the underlying `LineChart` | | `hasNonZeroData` | Returns `true` when `data` contains at least one series with a non-zero value | ## `OperationsEnergyCostChart` Doughnut chart comparing operational costs against energy costs in USD per MWh. Wraps [`ChartContainer`](/reference/ui/react/core/components/charts/composition#chartcontainer) and [`DoughnutChart`](#doughnutchart). It manages: 1. **Data** (`data`): operational and energy cost values in USD. 2. **Presentation** (`title`, `unit`): header text and unit label. 3. **Layout** (`height`): chart height in pixels. 4. **State** (`isLoading`, `emptyMessage`): loading overlay and empty-state copy. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `data` | Optional | `OperationsEnergyCostChartData` | none | Cost values in USD (see [data shape](#data-shape-for-operationsenergycostchart)) | | `title` | Optional | `string` | `'Operations vs Energy Cost'` | Header title | | `unit` | Optional | `string` | `'$/MWh'` | Unit label shown beneath the title | | `height` | Optional | `number` | `200` | Chart height in pixels | | `isLoading` | Optional | `boolean` | `false` | When `true`, shows a loading overlay | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty state | | `className` | Optional | `string` | none | Root class name from the host app | #### Data shape for `OperationsEnergyCostChart` `OperationsEnergyCostChartData` has two optional numeric fields: | Field | Type | Description | |-------|------|-------------| | `operationalCostsUSD` | `number` | Operational costs in USD | | `energyCostsUSD` | `number` | Energy costs in USD | Both fields are optional. Slices with a zero or absent value are omitted from the doughnut. ### Basic usage ```tsx ``` ### Exported helpers | Export | Role | |--------|------| | `buildOperationsEnergyCostSlices` | Converts `OperationsEnergyCostChartData` into `DoughnutChartDataset[]` slices, omitting zero-value entries | | `buildOperationsEnergyCostTooltip` | Builds the HTML tooltip config with two-decimal formatting | | `hasOperationsEnergyCostData` | Returns `true` when at least one cost field is a positive number | # Chart composition (/reference/ui/react/core/components/charts/composition) Compose chart types from [Chart components](/reference/ui/react/core/components) with wrappers and helpers. `ChartContainer` adds title, loading, and empty states; `ChartStatsFooter` and `DetailLegend` add summary rows and rich legends (for example [`LineChartCard`](/reference/ui/react/foundation/dashboard/charts#linechartcard)). ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## Components ## `ChartContainer` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `children` | Required | `ReactNode` | none | Chart body (for example a `BarChart` or `LineChart`) | | `title` | Optional | `string` | none | Title text | | `titleExtra` | Optional | `ReactNode` | none | Node rendered immediately after the title text (e.g. an info tooltip); only shown when `title` is set and `header` is not | | `header` | Optional | `ReactNode` | none | Custom header node | | `headerAction` | Optional | `ReactNode` | none | Action rendered on the right side of the header row (e.g. an expand toggle); sits alongside the range selector when both are present | | `legendData` | Optional | `LegendItem[]` | none | Legend entries rendered in the container chrome | | `highlightedValue` | Optional | `object` | none | Highlighted metric (`value`, `unit`, `className`, `style`); highlight chrome renders only when this prop is set and the chart body is visible (not `loading` / not `empty`) | | `rangeSelector` | Optional | `object` | none | Range selector props (`options`, `value`, `onChange`, `className`, `style`, `buttonClassName`) | | `loading` | Optional | `boolean` | none | When `true`, shows a centered `Loader` overlay over the chart area | | `empty` | Optional | `boolean` | none | When `true`, shows empty state | | `emptyMessage` | Optional | `string` | `'No data available'` | Copy shown in the empty overlay when `empty` is `true` and `loading` is not `true` | | `minMaxAvg` | Optional | `object` | none | Min / max / avg strings for the summary row | | `timeRange` | Optional | `string` | none | Time range label | | `footer` | Optional | `ReactNode` | none | Footer slot | | `footerClassName` | Optional | `string` | none | Class name on the footer wrapper | | `onToggleDataset` | Optional | `function` | none | Called with dataset index when legend toggles visibility | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ## `ChartStatsFooter` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `minMaxAvg` | Optional | `object` | none | Min, max, and average strings shown in the primary row when provided | | `stats` | Optional | `ChartStatsFooterItem[]` | none | Additional stat rows (`label`, `value`) in a columnar grid | | `statsPerColumn` | Optional | `number` | `1` | Number of stat items per column when `stats` is set | | `secondaryLabel` | Optional | `object` | none | Secondary block with `title` and `value` when provided | | `className` | Optional | `string` | none | Root class name from the host app | The component renders **nothing** when `minMaxAvg`, `stats`, and `secondaryLabel` are all absent or empty. ### Basic usage ```tsx ``` ## `DetailLegend` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `items` | Required | `DetailLegendItem[]` | none | Legend rows (`label`, `color`, optional `icon`, `currentValue`, `percentChange`, `hidden`) | | `onToggle` | Optional | `function` | none | Called with `label` and index when a row is toggled | | `className` | Optional | `string` | none | Root class name from the host app | ### Basic usage ```tsx ``` ## `MinMaxAvg` Compact summary row displaying min, max, and average values with consistent MDK label and value styling. Rendered automatically by [`ChartContainer`](#chartcontainer) when its `minMaxAvg` prop is set, and by [`ChartStatsFooter`](#chartstatsfooter) in the same way. Use it directly when you need the summary row outside of a `ChartContainer` or `ChartStatsFooter`. The component renders **nothing** when all three values are absent or empty strings. ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `min` | Optional | `string` | none | Minimum value label (for example `'65 TH/s'`) | | `max` | Optional | `string` | none | Maximum value label | | `avg` | Optional | `string` | none | Average value label | | `className` | Optional | `string` | none | Root class name from the host app | ### `MinMaxAvgValues` type ```tsx type MinMaxAvgValues = Partial<{ min: string max: string avg: string }> ``` `MinMaxAvgValues` is the shape accepted by the `minMaxAvg` prop on both `ChartContainer` and `ChartStatsFooter`. ### Basic usage ```tsx ``` ### Usage with `ChartContainer` ```tsx const stats = computeStats(values) ``` ## Chart utilities Pure functions for building Chart.js data and options. Import from the package root alongside components. ```tsx defaultChartOptions, defaultChartColors, buildBarChartData, buildBarChartOptions, buildChartTooltip, computeStats, } from '@tetherto/mdk-react-devkit/core' ``` | Export | Role | |--------|------| | `defaultChartOptions` | Shared Chart.js defaults used by MDK chart components | | `defaultChartColors` | Default dataset color palette | | `buildBarChartData` | Map MDK bar input into Chart.js `data` | | `buildBarChartOptions` | Build bar chart options (stacking, axes, formatters) | | `buildChartTooltip` | HTML tooltip config for Chart.js | | `computeStats` | Min, max, and average for a numeric array | Types `BarChartInput`, `BarChartSeries`, `BarChartLine`, and `BarChartConstant` are exported from the same package for hook-shaped bar data. ### Hook-shaped bar data App and reporting hooks often return declarative bar input instead of Chart.js `data`. `buildBarChartData` converts that shape into `{ labels, datasets }` for [`BarChart`](/reference/ui/react/core/components/charts#barchart). The pipeline: 1. **Input** (`BarChartInput`): optional `labels`, required `series`, optional `lines` and `constants` for mixed bar/line overlays. 2. **Build** (`buildBarChartData`): returns Chart.js `data` with MDK gradient styling and layout defaults (`barWidth`, `categoryPercentage`, `barPercentage` are optional on the input). 3. **Data labels** (optional): per-series overrides on the input (`formatter`, `anchor`, `align`, `offset`, `font`, `padding`, `display`, `clamp`, `clip`) map to each built dataset’s Chart.js `datalabels` by series index. 4. **Render** (``): pass the built object to the component; pair with `buildBarChartOptions` when you need stacking, axes, or formatters. `BarChartInput` shape | Field | Status | Type | Description | |-------|--------|------|-------------| | `series` | Required | `BarChartSeries[]` | Bar datasets (`label`, `values`, optional `color`, `stack`, `gradient`, bar layout props) | | `labels` | Optional | `string[]` | Category labels; omitted labels are derived from series `values` keys or indices | | `lines` | Optional | `BarChartLine[]` | Line overlays on the same chart | | `constants` | Optional | `BarChartConstant[]` | Horizontal reference lines | Each `BarChartSeries` uses `values` as either `number[]` (positional) or `Record` (keyed by category label). #### Example Hook output to `BarChart` example: ```tsx BarChart, buildBarChartData, ChartContainer, } from '@tetherto/mdk-react-devkit/core' // Typical shape returned by app/reporting data hooks const hookOutput = { labels: ['Q1', 'Q2', 'Q3'], series: [ { label: 'Revenue', values: [4.2, 3.8, 5.1], color: '#72F59E', dataLabels: { formatter: (v: number) => `${v.toFixed(1)}M`, anchor: 'end', align: 'top', }, }, { label: 'OpEx', values: [1.8, 2.0, 1.6], color: '#FFD700', }, ], } const cleanSeries = hookOutput.series.map(({ dataLabels: _dl, ...s }) => s) const base = buildBarChartData({ labels: hookOutput.labels, series: cleanSeries }) const chartData = { labels: base.labels, datasets: base.datasets.map((dataset, i) => { const overrides = hookOutput.series[i]?.dataLabels return overrides ? { ...dataset, datalabels: overrides } : dataset }), } const isEmpty = !hookOutput.series.length || hookOutput.series.every((s) => { const vals = Array.isArray(s.values) ? s.values : Object.values(s.values) return !vals.length || vals.every((v) => v === 0) }) ``` #### Empty and all-zero series Treat bar data as empty when any of the following is true: - `series` is missing or has length `0` - Every series has empty `values` (array or record) - Every numeric value across all series is `0` Prefer `ChartContainer` `empty` or a placeholder instead of rendering a flat chart. After building Chart.js `data`, you can also use [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck) from `@tetherto/mdk-react-devkit/foundation` with `{ data: chartData }`. # Data display (/reference/ui/react/core/components/data-display) Components for displaying data in cards, tables, badges, tags, and other visual formats. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `DataTable` ### Import ```tsx // Types for column definitions DataTableColumnDef, DataTableSortingState, DataTablePaginationState, DataTableRowSelectionState, } from '@tetherto/mdk-react-devkit/core' ``` ### Basic usage ```tsx type Miner = { id: string name: string hashrate: number status: string } const columns: DataTableColumnDef[] = [ { accessorKey: 'name', header: 'Name', }, { accessorKey: 'hashrate', header: 'Hashrate', cell: ({ row }) => `${row.original.hashrate} TH/s`, }, { accessorKey: 'status', header: 'Status', }, ] function MinersTable() { return } ``` ### With sorting and pagination ```tsx const [sorting, setSorting] = useState([]) const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10, }) ``` ### With row selection ```tsx const [rowSelection, setRowSelection] = useState({}) ``` ### Styling - `.mdk-data-table`: Root container - `.mdk-data-table__header`: Header row - `.mdk-data-table__body`: Table body - `.mdk-data-table__row`: Data row - `.mdk-data-table__cell`: Table cell ## `Card` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `className` | Optional | `string` | none | Additional CSS class | | `onClick` | Optional | `function` | none | Click handler (adds clickable styling) | | `children` | Optional | `ReactNode` | none | Card content | ### Basic usage ```tsx Title Content goes here Actions ``` Default children are automatically wrapped in the body slot: ```tsx Title This content goes to the body automatically ``` ### Clickable card ```tsx navigate('/details')}> Click me Navigates on click ``` ### Styling - `.mdk-card`: Root container - `.mdk-card--clickable`: Applied when `onClick` is provided - `.mdk-card__header`: Header slot - `.mdk-card__body`: Body slot - `.mdk-card__footer`: Footer slot ## `LabeledCard` A generic card container with a header label, an optional navigation link on the label, and a set of layout modifiers. Useful for compact stat or metadata blocks. ### Import ```tsx ``` ### Props All props are optional. | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `ReactNode` | none | Header content shown above the card body | | `children` | Optional | `ReactNode` | none | Card body content | | `getNavigateOptions` | Optional | `(label: string) => { href?: string; target?: string }` | none | Returns a link `href`/`target` for the label; only activates when `label` is a plain string | | `isDark` | Optional | `boolean` | `false` | Applies a dark background modifier | | `isFullWidth` | Optional | `boolean` | `false` | Stretches the card to full container width | | `isFullHeight` | Optional | `boolean` | `false` | Stretches the card to full container height | | `isRelative` | Optional | `boolean` | `false` | Sets `position: relative` on the container | | `isScrollable` | Optional | `boolean` | `false` | Enables vertical scroll on the card body | | `hasNoWrap` | Optional | `boolean` | `false` | Prevents content from wrapping | | `hasNoMargin` | Optional | `boolean` | `false` | Removes default margin | | `hasNoBorder` | Optional | `boolean` | `false` | Removes the card border | | `className` | Optional | `string` | none | Additional class for the root element | ### Basic usage ```tsx

Content goes here.

``` ### With a navigation link on the label ```tsx ({ href: '/miners?filter=error' })} > ``` When `label` is the string `'Miners with error'`, an informational tooltip is added automatically, explaining that minor errors not affecting hashrate are excluded. ## `Accordion` ### Import ```tsx Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from '@tetherto/mdk-react-devkit/core' ``` ### `Accordion` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `title` | Optional | `string` | `''` | Accordion header title | | `isOpened` | Optional | `boolean` | `false` | Initially expanded | | `isRow` | Optional | `boolean` | `false` | Row layout for content | | `unpadded` | Optional | `boolean` | `false` | Remove content padding | | `noBorder` | Optional | `boolean` | `false` | Remove trigger border | | `solidBackground` | Optional | `boolean` | `false` | Solid background color | | `showToggleIcon` | Optional | `boolean` | `true` | Show expand/collapse icon | | `toggleIconPosition` | Optional | `'left' \| 'right'` | `'left'` | Icon position | | `customLabel` | Optional | `ReactNode` | none | Custom label next to title | | `onValueChange` | Optional | `function` | none | Callback when state changes | ### Basic usage ```tsx

This content can be expanded or collapsed.

``` ### With custom label ```tsx Active} showToggleIcon={false} >

All systems operational.

``` ### Multiple items ```tsx Section 1 Content 1 Section 2 Content 2 ``` ### Styling - `.mdk-accordion`: Root container - `.mdk-accordion--solid-background`: Solid background variant - `.mdk-accordion__item`: Individual item - `.mdk-accordion__trigger`: Clickable header - `.mdk-accordion__content`: Collapsible content area ## `Badge` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `count` | Optional | `number` | `0` | Number to display | | `overflowCount` | Optional | `number` | `99` | Max count before showing "99+" | | `showZero` | Optional | `boolean` | `false` | Show badge when count is 0 | | `dot` | Optional | `boolean` | `false` | Show as dot instead of number | | `text` | Optional | `string` | none | Custom text content | | `color` | Optional | [`ColorVariant`](/reference/app-toolkit/ui-devkit/types#colorvariant) | `'primary'` | Badge color | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge size | | `status` | Optional | `'success' \| 'processing' \| 'error' \| 'warning' \| 'default'` | none | Status variant | | `square` | Optional | `boolean` | `false` | Square badge (no border-radius) | | `offset` | Optional | `[number, number]` | `[0, 0]` | Position offset [x, y] | ### Basic usage ```tsx // Number badge on content // Overflow // Shows "99+" ``` ### Dot badge ```tsx ``` ### Status badge ```tsx ``` ### Standalone badge ```tsx ``` ### Styling - `.mdk-badge`: Badge element - `.mdk-badge--{color}`: Color variant - `.mdk-badge--{size}`: Size variant - `.mdk-badge--dot`: Dot variant - `.mdk-badge--status`: Status variant - `.mdk-badge-wrapper`: Wrapper when wrapping content ## `Pagination` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `current` | Optional | `number` | `1` | Current page number | | `total` | Optional | `number` | `0` | Total number of items | | `pageSize` | Optional | `number` | `20` | Items per page | | `pageSizeOptions` | Optional | `number[]` | `[10, 20, 50, 100]` | Page size options | | `showSizeChanger` | Optional | `boolean` | `true` | Show page size dropdown | | `showTotal` | Optional | `boolean` | `false` | Show total count text | | `disabled` | Optional | `boolean` | `false` | Disable pagination | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant | | `onChange` | Optional | `(page: number, pageSize: number) => void` | none | Callback when the page number or page size changes | | `onSizeChange` | Optional | `(current: number, size: number) => void` | none | Callback when the page size changes | ### Basic usage ```tsx const [page, setPage] = useState(1) const [pageSize, setPageSize] = useState(20) { setPage(newPage) setPageSize(newSize) }} /> ``` ### With total display ```tsx // Shows "1-20 of 100" ``` ### Styling - `.mdk-pagination`: Root container - `.mdk-pagination__pages`: Page buttons container - `.mdk-pagination__button`: Navigation button - `.mdk-pagination__button--active`: Active page - `.mdk-pagination__total`: Total count text - `.mdk-pagination__size-changer`: Page size select ## `Tag` ### Import ```tsx ``` ### Basic usage ```tsx Default Tag Primary Success handleRemove()}>Removable ``` ## `Avatar` ### Import ```tsx ``` ### Basic usage ```tsx JD ``` ## `SkeletonBlock` ### Import ```tsx ``` ### Basic usage ```tsx // Text skeleton // Circle skeleton // Card skeleton ``` ## `EmptyState` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `description` | Optional | `ReactNode` | none | **Required.** Description text | | `image` | Optional | `'default' \| 'simple' \| ReactNode` | `'default'` | Image/icon to display | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant | ### Basic usage ```tsx ``` ### Custom image ```tsx } /> ``` ### Styling - `.mdk-empty-state`: Root container - `.mdk-empty-state--{size}`: Size variant - `.mdk-empty-state__image`: Image container - `.mdk-empty-state__description`: Description text ## `BtcAveragePrice` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `price` | Optional | `number \| null` | none | BTC price in USD; formatted with grouping and no decimal places. Shows `-` when `null`, `undefined`, non-finite, or negative | | `label` | Optional | `string` | `'BTC Average Price'` | Label shown before the price | ### Basic usage ```tsx ``` ## `Typography` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `variant` | Optional | `'heading1' \| 'heading2' \| 'heading3' \| 'body' \| 'secondary' \| 'caption'` | none | Typography variant | | `size` | Optional | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | none | Text size | | `weight` | Optional | `'light' \| 'normal' \| 'medium' \| 'semibold' \| 'bold'` | none | Font weight | | `align` | Optional | `TextAlign` | none | Text alignment | | `color` | Optional | `'default' \| 'muted' \| 'primary' \| 'success' \| 'warning' \| 'error'` | none | Text color variant | | `truncate` | Optional | `boolean` | `false` | Truncate text with ellipsis | | `className` | Optional | `string` | none | Custom class name | ### Basic usage ```tsx Operations dashboard Sites Primary site operations are running within expected parameters. Last refreshed 12 seconds ago. Updated 2 minutes ago Site #1 ``` ## `Indicator` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `color` | Optional | `'gray' \| 'slate' \| 'red' \| 'amber' \| 'yellow' \| 'green' \| 'blue' \| 'purple'` | none | Color variant of the indicator dot | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Size variant of the indicator | | `vertical` | Optional | `boolean` | `false` | When `true`, adds extra spacing between child elements and stacks them vertically | | `onClick` | Optional | `function` | none | Click handler | | `children` | Optional | `ReactNode` | none | Label content (text, icons, or multiple elements) | | `className` | Optional | `string` | none | Custom class name | ### Basic usage ```tsx Online Offline Maintenance Running Running 142 ``` ## `CurrencyToggler` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `currencies` | Required | `(string \| CurrencyItem)[]` | none | Currencies to toggle between, as codes or `CurrencyItem` objects | | `value` | Required | `string` | none | Currently selected currency code | | `onChange` | Required | `(currency: string) => void` | none | Called with the newly selected currency code | | `className` | Optional | `string` | none | Custom class name for the root element | ### Basic usage ```tsx ``` ## `ListViewFilter` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `CascaderOption[]` | none | Cascader options for filtering | | `onChange` | Required | `(selections: CascaderValue[]) => void` | none | Callback when filters change | | `localFilters` | Optional | `LocalFilters` | none | Current filter values as key-value pairs (e.g. `{ status: ['active'] }`) | | `filterKey` | Optional | `string` | none | Key to force re-mounting the Cascader when filters change (resets its internal state) | | `className` | Optional | `string` | none | Custom class name for the filter button | ### Basic usage ```tsx const FILTER_OPTIONS = [ { value: 'type', label: 'Type', children: [ { value: 'Antminer S19XP', label: 'Antminer S19XP' }, { value: 'Avalon A1346', label: 'Avalon A1346' }, ], }, { value: 'status', label: 'Status', children: [ { value: 'active', label: 'Active' }, { value: 'offline', label: 'Offline' }, ], }, ] const [filters, setFilters] = useState({}) setFilters(selectionToFilters(selections))} /> ``` ## `Mosaic` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `template` | Required | `string[] \| string[][]` | none | Grid layout template — area names per row that map child `MosaicItem`s to grid regions | | `children` | Required | `ReactNode` | none | `MosaicItem` elements placed into the named grid areas | | `columns` | Optional | `string \| string[]` | none | Column track sizes (e.g. `'1fr 2fr 1fr'`); defaults to equal columns derived from the template | | `gap` | Optional | `string` | `'12px'` | Gap between grid cells (any CSS length) | | `rowHeight` | Optional | `string` | `'auto'` | Height applied to each grid row (any CSS length) | | `className` | Optional | `string` | none | Custom class name for the root element | ### Basic usage ```tsx Hashrate Active miners Power usage ``` # Errors (/reference/ui/react/core/components/errors) Components for displaying errors, alerts, and handling error states. ## Prerequisites - Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites) ## `CoreAlert` ### Import ```tsx ``` The component is authored as `Alert` in `@tetherto/mdk-react-devkit/core` but re-exported as `CoreAlert` at the package barrel to avoid collisions with other `Alert` primitives (for example Radix `AlertDialog`). ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `type` | Optional | `'success' \| 'info' \| 'warning' \| 'error'` | `'info'` | Alert type | | `title` | Optional | `ReactNode` | none | Main message | | `description` | Optional | `ReactNode` | none | Additional description | | `showIcon` | Optional | `boolean` | `false` | Show type icon | | `icon` | Optional | `ReactNode` | none | Custom icon | | `closable` | Optional | `boolean` | `false` | Show close button | | `onClose` | Optional | `function` | none | Close callback | | `banner` | Optional | `boolean` | `false` | Full-width banner style | | `action` | Optional | `ReactNode` | none | Action element | ### Basic usage ```tsx ``` ### With action ```tsx View Details} /> ``` ### Banner style ```tsx ``` ### Styling - `.mdk-alert`: Root container - `.mdk-alert--{type}`: Type variant - `.mdk-alert--banner`: Banner variant - `.mdk-alert__icon`: Icon container - `.mdk-alert__content`: Content wrapper - `.mdk-alert__title`: Title text - `.mdk-alert__description`: Description text - `.mdk-alert__action`: Action container - `.mdk-alert__close`: Close button ## `ErrorBoundary` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `fallback` | Optional | `ReactNode` | none | Custom fallback UI | | `componentName` | Optional | `string` | none | Component name for error display | | `onError` | Optional | `function` | none | Error callback | | `children` | Required | `ReactNode` | none | Children to wrap | ### Basic usage ```tsx Something went wrong}> ``` ### With component name ```tsx console.error(error)} > ``` ### Higher-order component ```tsx const SafeChart = withErrorBoundary( Chart, 'Chart', (error) => logError(error) ) ``` #### Styling - `.mdk-error-boundary`: Root container - `.mdk-error-boundary__title`: Error title - `.mdk-error-boundary__message`: Error message - `.mdk-error-boundary__details`: Expandable details - `.mdk-error-boundary__stack`: Stack trace ## `ErrorCard` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `error` | Required | `string` | none | Error message (supports `\n` for line breaks) | | `title` | Optional | `string` | `'Errors'` | Title displayed above the error message | | `variant` | Optional | `'card' \| 'inline'` | `'card'` | Display variant — `card` shows a bordered container, `inline` shows flat text | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx ``` ### Styling - `.mdk-error-card`: Root container - `.mdk-error-card--{variant}`: Variant modifier (`card` / `inline`) - `.mdk-error-card__title`: Title text - `.mdk-error-card__message`: Message text ## `NotFoundPage` ### Import ```tsx ``` ### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `onGoHome` | Optional | `VoidFunction` | none | Callback fired when the "Go Home" button is clicked (button only renders when provided) | | `title` | Optional | `string` | none | Page title | | `message` | Optional | `string` | none | Message displayed below the title | | `className` | Optional | `string` | none | Additional CSS class | ### Basic usage ```tsx navigate('/')} /> navigate('/')} /> ``` ### Styling - `.mdk-not-found-page`: Root container - `.mdk-not-found-page__title`: Title text - `.mdk-not-found-page__message`: Message text - `.mdk-not-found-page__button`: Go Home button # Form components (/reference/ui/react/core/components/forms) Form components handle user input and form submission. All components are built with accessibility in mind and support keyboard navigation. The category splits into three groups: - [Controls](#controls): raw inputs you can drop in standalone or compose inside `` - [Composition](/reference/ui/react/core/components/forms/composition): the `` provider and the low-level building blocks (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`) - [Prebuilt fields](/reference/ui/react/core/components/forms/fields): one-tag wrappers that bind a control to React hook form ## Prerequisites Before using these components, complete the [@tetherto/mdk-react-devkit installation](/reference/ui/react/core#prerequisites). ## Controls Standalone form controls. Manage `value` and `onChange`, or compose them inside [``](/reference/ui/react/core/components/forms/composition#form) with [`FormField`](/reference/ui/react/core/components/forms/composition#formfield). ### `ActionButton` Triggers an action after **confirmation** in either an inline **popover** (default) or a modal **dialog**. Set **variant** so the trigger [`Button`](#button) matches severity (for example `danger` for destructive flows). After the user confirms, run your side effects there. Consider showing feedback with [`Toast`](/reference/ui/react/core/components/overlays#toast) and **`Toaster`** from the same Toast setup as in [`overlays`](/reference/ui/react/core/components/overlays). This is the pattern the [demo app(../quickstart) applies. #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Trigger button label | | `variant` | Optional | `'primary' \| 'secondary' \| 'danger'` | `'secondary'` | Visual variant of the trigger [`Button`](#button) | | `loading` | Optional | `boolean` | `false` | Loading state on the trigger | | `disabled` | Optional | `boolean` | `false` | Disable the trigger | | `className` | Optional | `string` | none | Class on the trigger | | `mode` | Optional | `'popover' \| 'dialog'` | `'popover'` | **`popover`**: confirmation UI in an anchored popover. **`dialog`**: confirmation UI in a modal [`Dialog`](/reference/ui/react/core/components/overlays#dialog). | | `confirmation` | Required | `ActionButtonConfirmation` | none | title, body copy, and confirm/cancel handlers. See [Confirmation object](#confirmation-object). | #### Confirmation object Nested inside `confirmation`: | Field | Type | Description | |-------|------|-------------| | `title` | `string` | Heading shown in the confirmation UI | | `description` | `ReactNode` | Optional body (text or JSX) | | `onConfirm` | `() => void` | Called when the user confirms | | `onCancel` | `() => void` | Called when the user cancels | | `confirmLabel` | `string` | Optional confirm button label (defaults vary by `mode`) | | `cancelLabel` | `string` | Optional cancel button label (defaults to **Cancel**) | | `icon` | `ReactNode` | Optional icon in **popover** header (popover mode only; dialog layout uses title and body) | #### Basic usage (popover) Default `mode` is **`popover`**: compact confirmation next to the trigger. ```tsx { void restartService() }, }} /> ``` #### Dialog mode Set **`mode="dialog"`** when you want a full modal confirmation (for example irreversible or high-impact actions). ```tsx { void factoryReset() }, }} /> ``` ### `Button` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `variant` | Optional | `'primary' \| 'secondary' \| 'danger' \| 'tertiary' \| 'link' \| 'icon' \| 'outline' \| 'ghost'` | `'secondary'` | Visual variant | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Button size | | `loading` | Optional | `boolean` | `false` | Show loading spinner | | `fullWidth` | Optional | `boolean` | `false` | Expand to container width | | `icon` | Optional | `ReactNode` | none | Icon element | | `iconPosition` | Optional | `'left' \| 'right'` | `'left'` | Icon placement | | `contentClassName` | Optional | `string` | none | Class names applied to the inner content wrapper | | `disabled` | Optional | `boolean` | `false` | Disable interaction | #### Basic usage ```tsx ``` #### With icon ```tsx ``` #### Loading state ```tsx ``` #### Styling - `.mdk-button`: Root element - `.mdk-button--variant-{variant}`: Variant modifier - `.mdk-button--size-{size}`: Size modifier - `.mdk-button--full-width`: Full width modifier - `.mdk-button--loading`: Loading state ### `Cascader` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `CascaderOption[]` | none | Hierarchical options; parent options with children render in the left panel | | `value` | Optional | `CascaderValue \| CascaderValue[]` | none | Current selected value(s) | | `onChange` | Optional | `(value: CascaderValue \| CascaderValue[] \| null) => void` | none | Callback when the selection changes | | `multiple` | Optional | `boolean` | `false` | Enable multiple selection (shows checkboxes; selected items render as tags) | | `placeholder` | Optional | `string` | none | Placeholder text shown when no selections are made | | `disabled` | Optional | `boolean` | `false` | Disable the entire cascader | | `dropdownClassName` | Optional | `string` | none | Custom class name for the dropdown panels container | | `className` | Optional | `string` | none | Custom class name for the root element | #### Basic usage ```tsx ``` ### `Checkbox` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Checkbox size | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'primary'` | Color when checked | | `radius` | Optional | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius | | `checked` | Optional | `boolean \| 'indeterminate'` | none | Checked state (controlled) | | `onCheckedChange` | Optional | `function` | none | Change callback | #### Basic usage ```tsx I agree to the terms ``` #### Sizes and colors ```tsx ``` #### Styling - `.mdk-checkbox`: Root element - `.mdk-checkbox--{size}`: Size modifier - `.mdk-checkbox--{color}`: Color modifier - `.mdk-checkbox__indicator`: Check mark container ### `DatePicker` #### Import ```tsx ``` #### Basic usage ```tsx ``` ### `DateRangePicker` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `selected` | Optional | `DateRange` | none | Selected `{ from, to }` range (controlled) | | `onSelect` | Optional | `(range: DateRange \| undefined) => void` | none | Called when the user applies a range | | `placeholder` | Optional | `string` | `'Pick a date range'` | Trigger text when no range is selected | | `dateFormat` | Optional | `string` | `'MM/dd/yyyy'` | `date-fns` format used in the trigger label | | `disabled` | Optional | `boolean` | `false` | Disable interaction | | `showPresets` | Optional | `boolean` | `true` | Show the default preset buttons for the last 7, 14, 30, and 90 days | | `presets` | Optional | `PresetItem[]` | none | Override the default preset list | | `allowFutureDates` | Optional | `boolean` | `false` | When `false`, dates after today are disabled | | `triggerClassName` | Optional | `string` | none | Extra classes for the trigger button | | `calendarClassName` | Optional | `string` | none | Extra classes for the calendar | | `modalClassName` | Optional | `string` | none | Extra classes for the popover modal | Any other [`react-day-picker` props](https://daypicker.dev/) (excluding `mode` and `selected`) are forwarded to the underlying calendar. #### Basic usage ```tsx const [range, setRange] = useState() ``` #### Custom presets ```tsx const presets: PresetItem[] = [ { label: 'This week', value: { from: startOfWeek(new Date()), to: new Date() } }, { label: 'This month', value: { from: startOfMonth(new Date()), to: new Date() } }, ] ``` #### Allowing future dates ```tsx ``` #### Styling - `.mdk-date-picker__trigger`: Trigger button - `.mdk-date-picker__modal`: Popover modal container - `.mdk-date-picker__calendar`: Calendar grid - `.mdk-date-picker__summary`: Selected-range summary block - `.mdk-date-picker__presets`: Preset button row ### `Input` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Visible label for the field | | `variant` | Optional | `'default' \| 'search'` | `'default'` | Input variant | | `size` | Optional | `'default' \| 'medium'` | `'default'` | Input size | | `error` | Optional | `string` | none | Error message (shows red border) | | `prefix` | Optional | `ReactNode` | none | Element before input | | `suffix` | Optional | `ReactNode` | none | Element after input | | `wrapperClassName` | Optional | `string` | none | Wrapper element class | #### Basic usage ```tsx ``` #### With prefix/suffix ```tsx } placeholder="Username" /> ``` #### Error state ```tsx setMac(e.target.value)} /> ``` #### Styling - `.mdk-input`: Input element - `.mdk-input__wrapper`: Wrapper container - `.mdk-input__wrapper--error`: Error state - `.mdk-input__label`: Label element - `.mdk-input__prefix`: Prefix element - `.mdk-input__suffix`: Suffix element - `.mdk-input__error`: Error message ### `Label` #### Import ```tsx ``` #### Basic usage ```tsx Email Password ``` ### `MultiSelect` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `options` | Required | `MultiSelectOption[]` | none | Selectable options (`{ value, label }`) | | `value` | Optional | `string[]` | none | Controlled selected values; omit to use `defaultValue` for uncontrolled mode | | `defaultValue` | Optional | `string[]` | none | Initial values for uncontrolled mode; ignored when `value` is provided | | `onValueChange` | Optional | `(next: string[]) => void` | none | Called with the updated selection | | `placeholder` | Optional | `ReactNode` | none | Trigger placeholder shown when nothing is selected | | `emptyMessage` | Optional | `ReactNode` | none | Rendered inside the popover when `options` is empty | | `maxSelectedDisplay` | Optional | `number` | none | Max selected chips shown in the trigger before collapsing the rest into a "+N more" badge | | `disabled` | Optional | `boolean` | `false` | Disable the control | | `size` | Optional | `MultiSelectSize` | none | Size variant | | `variant` | Optional | `MultiSelectVariant` | none | Visual variant | | `aria-label` | Optional | `string` | none | Accessible label applied to the trigger button | | `className` | Optional | `string` | none | Custom class name for the root element | | `contentClassName` | Optional | `string` | none | Custom class name for the popover content panel | #### Basic usage ```tsx const MINER_TYPES: MultiSelectOption[] = [ { value: 'miner-am-s19xp', label: 'Antminer S19XP' }, { value: 'miner-wm-m56s', label: 'WhatsMiner M56S' }, { value: 'miner-av-a1346', label: 'Avalon A1346' }, ] function MinerTypeFilter() { const [selected, setSelected] = useState([]) return ( ) } ``` ### `Radio` #### Radio composition parts | Part | Role | |------|------| | `RadioGroup` | Root that holds the selected value and calls `onValueChange` when it changes. | | `Radio` | Default circular radio item; use `label` or children for visible text. | | `RadioCard` | Card-styled option for horizontal or compact layouts; uses the same item primitive as `Radio`. | #### Import ```tsx ``` #### `Radio` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `label` | Optional | `string` | none | Label text (or use children for custom content) | | `size` | Optional | `'sm' \| 'md' \| 'lg'` | none | Size variant of the radio | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | none | Color variant when checked | | `radius` | Optional | `BorderRadius` | none | Border radius variant (`full` makes it circular) | | `children` | Optional | `ReactNode` | none | Custom content (takes precedence over `label`) | | `indicatorClassName` | Optional | `string` | none | Custom class name for the indicator element | | `className` | Optional | `string` | none | Custom class name for the root element | #### Basic usage ```tsx Small Medium Large ``` **RadioCard** suits card-style, horizontal groups: ```tsx ``` ### `Select` #### Import ```tsx Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, } from '@tetherto/mdk-react-devkit/core' ``` #### `Select` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `allowClear` | Optional | `boolean` | `false` | Show a clear button when a value is selected | #### `SelectTrigger` props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'lg'` | Trigger size | | `variant` | Optional | `'default' \| 'colored'` | `'default'` | Visual variant | | `color` | Optional | `string` | none | Custom color for colored variant (hex) | #### Basic usage ```tsx ``` #### With groups ```tsx ``` #### Colored variant ```tsx ``` #### Styling - `.mdk-select__trigger`: Trigger button - `.mdk-select__trigger--{size}`: Size modifier - `.mdk-select__trigger--colored`: Colored variant - `.mdk-select__content`: Dropdown content - `.mdk-select__item`: Option item ### `Switch` #### Import ```tsx ``` #### Props | Prop | Status | Type | Default | Description | |------|--------|------|---------|-------------| | `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch size | | `color` | Optional | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error'` | `'default'` | Color when checked | | `radius` | Optional | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'none'` | Border radius | | `checked` | Required | `boolean` | none | Checked state (controlled) | | `onCheckedChange` | Required | `function` | none | Change callback | #### Basic usage ```tsx Dark Mode ``` #### Sizes and colors ```tsx ``` #### Styling - `.mdk-switch`: Root element - `.mdk-switch--{size}`: Size modifier - `.mdk-switch--{color}`: Color modifier - `.mdk-switch__thumb`: Toggle thumb ### `TagInput` #### Import ```tsx ``` #### Basic usage ```tsx ``` ### `TextArea` #### Import ```tsx ``` #### Basic usage ```tsx

setValue(e.target.value)}
/>
```

## Composition

The `<Form>` provider plus the low-level compound components for assembling custom form fields. Use these when no [prebuilt field](/reference/ui/react/core/components/forms/fields) fits, or when you need full control over the field's layout.

See the [Composition page](/reference/ui/react/core/components/forms/composition) for `<Form>`, the seven compound parts, and built-in validators.

## Prebuilt fields

Form-bound fields pre-wired to React hook form. Each combines `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, and `FormMessage` so you can render a labelled, validated field from a single component.

See the [Prebuilt fields page](/reference/ui/react/core/components/forms/fields) for the full prop reference and component-specific examples.

# Form composition (/reference/ui/react/core/components/forms/composition)

The `<Form>` provider plus the seven compound parts (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`) are the building blocks for any form. Use them when no [prebuilt field](/reference/ui/react/core/components/forms/fields) fits, or when you need full control over a field's layout.

For standalone inputs that you can drop in without `<Form>`, see [Controls](/reference/ui/react/core/components/forms#controls).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)
- Familiarity with [React hook form](https://react-hook-form.com/)

## Components

## `Form`

The package includes a complete form system built on [React hook form](https://react-hook-form.com/). `<Form>` is the context provider; the other six components on this page are the building blocks you compose inside it. See [Prebuilt fields](/reference/ui/react/core/components/forms/fields) for ready-made wrappers that render a labelled, validated field in a single tag.

### Import

```tsx
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormDescription,
  FormMessage,
  useFormField,
} from '@tetherto/mdk-react-devkit/core'
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `form` | Required | `UseFormReturn` | none | The instance returned by `useForm()` |
| `children` | Required | `ReactNode` | none | Form content |
| `onSubmit` | Required | `function` | none | Submit handler. Wrap with `form.handleSubmit(...)` to get parsed values |

Any other standard `<form>` element attribute (`id`, `action`, `noValidate`, `onReset`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element.

### Basic usage

```tsx

function MyForm() {
  const form = useForm({
    defaultValues: { email: '' },
  })

const onSubmit = (values) => {
    console.log(values)
  }

return (
    <Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
      <FormField
        control={form.control}
        name="email"
        render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input placeholder="email@example.com" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )}
      />
      <Button type="submit">Submit</Button>
    </Form>
  )
}
```

### Built-in validators

The package re-exports common Zod schemas and validator helpers so you can wire `useForm` to a resolver without rolling your own.

```tsx
```

### Styling

- `.mdk-form`: Root `<form>` element

## `FormField`

### Import

```tsx
```

### Props

`FormField` is a thin wrapper over [React hook form's `Controller`](https://react-hook-form.com/docs/usecontroller/controller) and accepts the same props (`control`, `name`, `defaultValue`, `rules`, `render`, etc.). It additionally provides field context to descendants like `FormLabel` and `FormControl` so they can wire up ARIA attributes automatically.

### Basic usage

```tsx
<FormField
  control={form.control}
  name="username"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Username</FormLabel>
      <FormControl>
        <Input {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

## `FormItem`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `className` | Optional | `string` | none | Extra classes merged onto the wrapper |

Any other standard `<div>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element.

### Basic usage

```tsx
<FormField
  control={form.control}
  name="bio"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Bio</FormLabel>
      <FormControl>
        <TextArea {...field} />
      </FormControl>
      <FormDescription>Max 200 characters</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

### Styling

- `.mdk-form-item`: Root element

## `FormLabel`

### Import

```tsx
```

### Props

Accepts every prop the underlying [`FormLabel`](#formlabel) accepts. The `htmlFor` attribute is set automatically from the `FormItem` context, and an error modifier class is applied when the field has a validation error.

### Basic usage

```tsx
<FormItem>
  <FormLabel>Email address</FormLabel>
  <FormControl>
    <Input type="email" {...field} />
  </FormControl>
</FormItem>
```

### Styling

- `.mdk-form-label`: Root element
- `.mdk-form-label--error`: Applied when the field has a validation error

## `FormControl`

### Import

```tsx
```

### Props

`FormControl` uses [Radix `Slot`](https://www.radix-ui.com/primitives/docs/utilities/slot) to merge its props onto its single child without adding an extra DOM node. It autoinjects `id`, `aria-describedby`, and `aria-invalid` based on the surrounding `FormItem`/`FormField` context.

### Basic usage

```tsx
<FormItem>
  <FormLabel>Phone</FormLabel>
  <FormControl>
    <Input type="tel" {...field} />
  </FormControl>
  <FormMessage />
</FormItem>
```

`FormControl` must wrap exactly one child element.

## `FormDescription`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `className` | Optional | `string` | none | Extra classes merged onto the wrapper |

Any other standard `<p>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element.

### Basic usage

```tsx
<FormItem>
  <FormLabel>Password</FormLabel>
  <FormControl>
    <Input type="password" {...field} />
  </FormControl>
  <FormDescription>Must be at least 8 characters</FormDescription>
  <FormMessage />
</FormItem>
```

### Styling

- `.mdk-form-description`: Root element

## `FormMessage`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `children` | Required | `ReactNode` | none | Fallback content shown when the field has no validation error |
| `className` | Optional | `string` | none | Extra classes merged onto the wrapper |

Any other standard `<p>` attribute (`id`, `ref`, `data-*`, `aria-*`, etc.) is forwarded to the underlying DOM element.

`FormMessage` always renders to prevent layout shift. When an error is present it shows the validation message and applies `role="alert"`; otherwise it shows `children` (or a non-breaking space placeholder) and adds the `--empty` modifier class.

### Basic usage

```tsx
<FormItem>
  <FormLabel>Email</FormLabel>
  <FormControl>
    <Input type="email" {...field} />
  </FormControl>
  <FormMessage />
</FormItem>
```

### Styling

- `.mdk-form-message`: Root element
- `.mdk-form-message--empty`: Applied when no error and no children are present

# Prebuilt form fields (/reference/ui/react/core/components/forms/fields)

Form-bound fields pre-wired to React hook form. Each combines [`FormField`](/reference/ui/react/core/components/forms/composition#formfield), [`FormItem`](/reference/ui/react/core/components/forms/composition#formitem), [`FormLabel`](/reference/ui/react/core/components/forms/composition#formlabel), [`FormControl`](/reference/ui/react/core/components/forms/composition#formcontrol), [`FormDescription`](/reference/ui/react/core/components/forms/composition#formdescription), and [`FormMessage`](/reference/ui/react/core/components/forms/composition#formmessage) so you can render a labelled, validated field from a single component.

For raw inputs without form binding, see [Controls](/reference/ui/react/core/components/forms#controls). To assemble a custom field from the building blocks, see [Composition](/reference/ui/react/core/components/forms/composition).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)
- Wrap your form in [`<Form>`](/reference/ui/react/core/components/forms/composition#form) and pass `form.control` to each field

## Components

## Common props

Every prebuilt field accepts the [`Controller`](https://react-hook-form.com/docs/usecontroller/controller) props from React hook form (`control`, `name`, `defaultValue`, `rules`, `shouldUnregister`, `disabled`) plus three presentation props:

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Optional | `string` | none | Label displayed above the field |
| `description` | Optional | `string` | none | Helper text below the field |
| `placeholder` | Optional | `string` | none | Placeholder text (ignored by `FormCheckbox` and `FormSwitch`) |

Component-specific props are listed under each field below.

## `FormCascader`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `options` | Required | `CascaderOption[]` | none | Hierarchical options tree |
| `multiple` | Optional | `boolean` | `false` | Allow multiple selection |
| `cascaderProps` | Required | `object` | none | Pass-through props for the underlying `Cascader` |

### Basic usage

```tsx
<FormCascader
  control={form.control}
  name="category"
  label="Category"
  placeholder="Select category..."
  options={[
    {
      value: 'electronics',
      label: 'Electronics',
      children: [
        { value: 'phones', label: 'Phones' },
        { value: 'laptops', label: 'Laptops' },
      ],
    },
  ]}
  description="Choose a category and subcategory"
/>
```

### Multiple selection

```tsx
<FormCascader
  control={form.control}
  name="categories"
  label="Categories"
  placeholder="Select categories..."
  options={categoryOptions}
  multiple
  description="Select multiple categories"
/>
```

## `FormCheckbox`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `layout` | Optional | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the checkbox or above it |
| `checkboxProps` | Required | `object` | none | Pass-through props for the underlying `Checkbox` |

### Basic usage

```tsx
<FormCheckbox
  control={form.control}
  name="terms"
  label="Accept terms and conditions"
  description="You must agree to continue"
/>
```

## `FormDatePicker`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `datePickerProps` | Required | `object` | none | Pass-through props for the underlying `DatePicker` (excluding `selected` and `onSelect`, which are bound to the form) |

### Basic usage

```tsx
<FormDatePicker
  control={form.control}
  name="startDate"
  label="Start Date"
  placeholder="Pick a date"
  description="When should this take effect?"
/>
```

## `FormInput`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `type` | Optional | `'text' \| 'email' \| 'password' \| 'number' \| ...` | `'text'` | HTML input type |
| `variant` | Optional | `'default' \| 'search'` | `'default'` | Input variant |
| `inputProps` | Required | `object` | none | Pass-through props for the underlying `Input` (excluding `type` and `variant`) |

### Basic usage

```tsx
<FormInput
  control={form.control}
  name="email"
  label="Email"
  type="email"
  placeholder="user@example.com"
  description="We'll never share your email"
/>
```

## `FormRadioGroup`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `options` | Required | `FormRadioOption[]` | none | Array of `{ value, label, disabled? }` items |
| `orientation` | Optional | `'horizontal' \| 'vertical'` | `'vertical'` | Radio layout direction |
| `radioGroupProps` | Required | `object` | none | Pass-through props for the underlying `RadioGroup` |

### Basic usage

```tsx
<FormRadioGroup
  control={form.control}
  name="priority"
  label="Priority"
  options={[
    { value: 'low', label: 'Low' },
    { value: 'medium', label: 'Medium' },
    { value: 'high', label: 'High' },
  ]}
  orientation="horizontal"
/>
```

## `FormSelect`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `options` | Required | `FormSelectOption[]` | none | Array of `{ value, label, disabled? }` items |
| `selectProps` | Required | `object` | none | Pass-through props for the underlying `Select` (excluding `onValueChange` and `defaultValue`, which are bound to the form) |

### Basic usage

```tsx
<FormSelect
  control={form.control}
  name="role"
  label="Role"
  placeholder="Select a role"
  options={[
    { value: 'admin', label: 'Admin' },
    { value: 'user', label: 'User' },
  ]}
  description="Your access level"
/>
```

## `FormSwitch`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `layout` | Optional | `'row' \| 'column'` | `'row'` | Whether the label sits inline with the switch or above it |
| `switchProps` | Required | `object` | none | Pass-through props for the underlying `Switch` (excluding `checked` and `onCheckedChange`) |

### Basic usage

```tsx
<FormSwitch
  control={form.control}
  name="notifications"
  label="Enable notifications"
  description="Receive alerts when miners go offline"
/>
```

## `FormTagInput`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `options` | Required | `TagInputOption[]` | none | Suggested tags offered as autocomplete options |
| `allowCustomTags` | Optional | `boolean` | `true` | Let users type tags not present in `options` |
| `variant` | Optional | `'default' \| 'search'` | `'search'` | Visual variant |
| `tagInputProps` | Required | `object` | none | Pass-through props for the underlying `TagInput` |

### Basic usage

```tsx
<FormTagInput
  control={form.control}
  name="tags"
  label="Tags"
  placeholder="Add tags..."
  options={['React', 'TypeScript', 'Node.js']}
  description="Select or type tags"
/>
```

## `FormTextArea`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `textAreaProps` | Required | `object` | none | Pass-through props for the underlying `TextArea` |

### Basic usage

```tsx
<FormTextArea
  control={form.control}
  name="bio"
  label="Bio"
  placeholder="Tell us about yourself"
  description="Max 200 characters"
/>
```

# Loading (/reference/ui/react/core/components/loading)

Components for indicating loading and progress states.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## `Spinner`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `size` | Optional | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size |
| `color` | Optional | `'primary' \| 'secondary'` | none | Color variant of the spinner |
| `type` | Optional | `'circle' \| 'square'` | none | Type of spinner animation |
| `speed` | Optional | `'slow' \| 'normal' \| 'fast'` | none | Speed of the animation |
| `label` | Optional | `string` | none | Optional label text displayed below the spinner |
| `fullScreen` | Optional | `boolean` | `false` | Display in fullscreen mode |
| `className` | Optional | `string` | none | Additional CSS class |

### Basic usage

```tsx
<Spinner />
<Spinner size="sm" />
<Spinner size="lg" />
<Spinner type="circle" speed="fast" />
<Spinner label="Loading miners..." />
```

### With content

```tsx
<Button disabled>
  <Spinner size="sm" /> Loading...
</Button>
```

### Styling

- `.mdk-spinner`: Root element
- `.mdk-spinner--{size}`: Size modifier

## `Loader`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `count` | Optional | `3 \| 5 \| 7` | `5` | Number of dots to display |
| `color` | Optional | `'red' \| 'gray' \| 'blue' \| 'amber' \| 'orange'` | `'orange'` | Color variant of the loader |
| `size` | Optional | `number` | `10` | Size of each dot in pixels |
| `className` | Optional | `string` | none | Additional CSS class |

### Basic usage

```tsx
<Loader />
<Loader color="blue" />
<Loader count={3} size={8} color="amber" />
<Loader count={7} size={12} color="red" />
```

### In a container

```tsx
<div className="relative min-h-[200px]">
  {isLoading && <Loader />}
  {data && <DataDisplay data={data} />}
</div>
```

### Styling

- `.mdk-loader`: Root container
- `.mdk-loader__dot`: Individual dot
- `.mdk-loader__dot--{color}`: Dot color modifier

# Log components (/reference/ui/react/core/components/logs)

Components for displaying log entries, activity feeds, and event histories.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## `LogsCard`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `logsData` | Required | `LogData[]` | `[]` | Array of log entries |
| `type` | Required | `string` | none | Log type identifier |
| `label` | Required | `string` | none | Card label |
| `isLoading` | Required | `boolean` | `false` | Show loading skeleton |
| `isDark` | Required | `boolean` | `false` | Dark theme variant |
| `emptyMessage` | Required | `string` | `'No incidents'` | Empty state message |
| `skeletonRows` | Required | `number` | `5` | Number of skeleton rows |
| `pagination` | Required | `LogPagination` | none | Pagination configuration |
| `onLogClicked` | Required | `function` | none | Log click callback |

### `LogData` type

```tsx
type LogData = {
  uuid: string
  body: string
  title: string
  status: string
  subtitle: string
}
```

### `LogPagination` type

```tsx
type LogPagination = {
  current: number
  total: number
  pageSize: number
  handlePaginationChange: (page: number) => void
}
```

### Basic usage

```tsx
const logs = [
  {
    uuid: '1',
    title: 'Miner Offline',
    subtitle: 'Site A - Rack 12',
    body: 'Miner 001 went offline at 14:32',
    status: 'error',
  },
  {
    uuid: '2',
    title: 'Hashrate Drop',
    subtitle: 'Site B - Rack 5',
    body: 'Hashrate dropped below threshold',
    status: 'warning',
  },
]

<LogsCard
  label="Recent Incidents"
  logsData={logs}
  type="incident"
  onLogClicked={(uuid) => handleLogClick(uuid)}
/>
```

### With pagination

```tsx
const [page, setPage] = useState(1)

<LogsCard
  label="Activity Log"
  logsData={logs}
  type="activity"
  pagination={{
    current: page,
    total: 100,
    pageSize: 10,
    handlePaginationChange: setPage,
  }}
/>
```

### Loading state

```tsx
<LogsCard
  label="Loading..."
  isLoading
  skeletonRows={5}
/>
```

### Styling

- `.mdk-logs-card`: Root container
- `.mdk-logs-card__inner-container`: Content wrapper
- `.mdk-logs-card__list-container`: Log list container
- `.mdk-logs-card__pagination`: Pagination area
- `.mdk-logs-card__empty`: Empty state container

## `LogRow`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `log` | Required | `LogData` | none | Log entry data |
| `type` | Required | `string` | none | Log type identifier |
| `style` | Optional | `CSSProperties` | none | Custom styles |
| `onLogClicked` | Optional | `function` | none | Click callback |

### Basic usage

```tsx
<LogRow
  log={{
    uuid: '1',
    title: 'System Alert',
    subtitle: 'High temperature detected',
    body: 'Rack 5 temperature exceeded 80°C',
    status: 'warning',
  }}
  type="alert"
  onLogClicked={(uuid) => viewDetails(uuid)}
/>
```

## `LogItem`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `LogData` | none | Log entry data |
| `onLogClicked` | Optional | `function` | none | Click callback |

### Basic usage

```tsx
<LogItem
  data={{
    uuid: '1',
    title: 'Configuration Change',
    subtitle: 'Pool settings updated',
    body: 'Primary pool changed to us-east',
    status: 'info',
  }}
/>
```

## `LogDot`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `type` | Required | `string` | none | Log type identifier |
| `status` | Required | `string` | none | Status value |

### Basic usage

```tsx
<LogDot type="incident" status="error" />
<LogDot type="activity" status="success" />
<LogDot type="alert" status="warning" />
```

## `LogActivityIcon`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `status` | Required | `string` | none | Status value |

### Basic usage

```tsx
<LogActivityIcon status="online" />
<LogActivityIcon status="offline" />
<LogActivityIcon status="warning" />
```

## Status values

Log components support the following status values:

| Status | Color | Use case |
|--------|-------|----------|
| `success` | Green | Successful operations |
| `error` | Red | Errors, failures |
| `warning` | Yellow | Warnings, alerts |
| `info` | Blue | Informational |
| `default` | Gray | Neutral/unknown |

# Navigation (/reference/ui/react/core/components/navigation)

Components for navigating between views and organizing content.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## `AppHeader`

### Import

```tsx
```

### Props

`AppHeader` is a three-slot top-bar shell.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `logo` | Optional | `ReactNode` | none | Left-most slot — typically the app's brand lockup / logo |
| `start` | Optional | `ReactNode` | none | Left-edge content — e.g. a sidebar collapse toggle button |
| `children` | Optional | `ReactNode` | none | Middle slot — typically the dashboard's stats strip |
| `actions` | Optional | `ReactNode` | none | Right-edge action cluster — e.g. alarms bell, profile menu |
| `sticky` | Optional | `boolean` | `true` | Render the header sticky to the top of its scroll container |
| `className` | Optional | `string` | none | Class hook for the outer `<header>` element |

### Basic usage

```tsx
<AppHeader
  start={<strong>MDK</strong>}
  actions={<Button size="sm">Sign out</Button>}
>
  <div>Header content</div>
</AppHeader>
```

## `Sidebar`

### Import

```tsx
  Sidebar,
  useSidebarExpandedState,
  useSidebarSectionState,
  clearSidebarState,
} from '@tetherto/mdk-react-devkit/core'
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `items` | Required | `SidebarMenuItem[]` | none | **Required.** Menu items array |
| `activeId` | Required | `string` | none | Currently active item ID |
| `expanded` | Required | `boolean` | none | Controlled expanded state |
| `defaultExpanded` | Optional | `boolean` | `false` | Initial expanded state |
| `visible` | Optional | `boolean` | `true` | Sidebar visibility |
| `overlay` | Optional | `boolean` | `false` | Overlay mode (mobile) |
| `header` | Optional | `ReactNode` | none | Header content |
| `onItemClick` | Required | `function` | none | Item click callback |
| `onExpandedChange` | Required | `function` | none | Expand state callback |
| `onClose` | Required | `function` | none | Close callback (overlay mode) |

### `SidebarMenuItem` type

```tsx
type SidebarMenuItem = {
  id: string
  label: string
  icon?: ReactNode
  href?: string
  children?: SidebarMenuItem[]
  disabled?: boolean
}
```

### Basic usage

```tsx
const items = [
  { id: 'dashboard', label: 'Dashboard', icon: <DashboardIcon /> },
  { id: 'settings', label: 'Settings', icon: <SettingsIcon /> },
  {
    id: 'reports',
    label: 'Reports',
    icon: <ReportsIcon />,
    children: [
      { id: 'daily', label: 'Daily' },
      { id: 'weekly', label: 'Weekly' },
    ],
  },
]

<Sidebar
  items={items}
  activeId="dashboard"
  onItemClick={(item) => navigate(item.href)}
/>
```

### With persisted state

```tsx
function App() {
  const [expanded, setExpanded] = useSidebarExpandedState(true)
  
  return (
    <Sidebar
      items={items}
      expanded={expanded}
      onExpandedChange={setExpanded}
    />
  )
}
```

### Styling

- `.mdk-sidebar`: Root container
- `.mdk-sidebar--expanded`: Expanded state
- `.mdk-sidebar--hidden`: Hidden state
- `.mdk-sidebar--overlay`: Overlay mode
- `.mdk-sidebar__toggle`: Expand/collapse button
- `.mdk-sidebar__menu`: Menu container
- `.mdk-sidebar__backdrop`: Overlay backdrop

## `Tabs`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `defaultValue` | Optional | `string` | none | Initially active tab |
| `value` | Optional | `string` | none | Controlled active tab |
| `onValueChange` | Optional | `function` | none | Tab change callback |
| `variant` | Optional | `'default' \| 'side'` | `'default'` | Tab layout variant |

### Basic usage

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
    <TabsTrigger value="logs" disabled>Logs</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">
    Overview content here
  </TabsContent>
  <TabsContent value="settings">
    Settings content here
  </TabsContent>
</Tabs>
```

### Side variant

```tsx
<Tabs defaultValue="tab1" variant="side">
  <TabsList variant="side">
    <TabsTrigger value="tab1" variant="side">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2" variant="side">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content 1</TabsContent>
  <TabsContent value="tab2">Content 2</TabsContent>
</Tabs>
```

### Styling

- `.mdk_tabs`: Root container
- `.mdk_tabs__list`: Tab button container
- `.mdk_tabs__list--side`: Side variant list
- `.mdk_tabs__trigger`: Individual tab button
- `.mdk_tabs__content`: Tab panel content

## `LazyTabWrapper`

### Import

```tsx
```

### Usage

```tsx
<TabsContent value="heavy-content">
  <LazyTabWrapper>
    <ExpensiveComponent />
  </LazyTabWrapper>
</TabsContent>
```

## `Breadcrumbs`

### Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `items` | Required | `BreadcrumbItem[]` | none | Breadcrumb entries to render; each item is `{ label, href?, onClick? }` |
| `showBack` | Optional | `boolean` | `false` | Render a back button before the breadcrumb trail |
| `backLabel` | Optional | `string` | `'Back'` | Accessible label / text for the back button |
| `onBackClick` | Optional | `VoidFunction` | none | Callback fired when the back button is clicked |
| `separator` | Optional | `ReactNode` | `'/'` | Custom node rendered between items |
| `itemClassName` | Optional | `string` | none | Custom class name applied to each breadcrumb item |
| `backClassName` | Optional | `string` | none | Custom class name applied to the back button |
| `className` | Optional | `string` | none | Custom class name for the root element |

### Basic usage

```tsx
const items: BreadcrumbItem[] = [
  { label: 'Home', href: '/' },
  { label: 'Miners', href: '/miners' },
  { label: 'Details' },
]

<Breadcrumbs items={items} />
```

### Styling

- `.mdk-breadcrumbs`: Root container
- `.mdk-breadcrumbs__item`: Individual item
- `.mdk-breadcrumbs__separator`: Separator between items

# Overlays (/reference/ui/react/core/components/overlays)

Overlay components display content above the main interface. All components are built on [Radix UI](https://www.radix-ui.com/) primitives for accessibility.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## `Dialog`

### Import

```tsx
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose,
} from '@tetherto/mdk-react-devkit/core'
```

## `DialogContent` props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Optional | `string` | none | Dialog title |
| `description` | Optional | `string` | none | Dialog description |
| `closable` | Optional | `boolean` | `false` | Show close button |
| `onClose` | Optional | `function` | none | Close callback |
| `closeOnClickOutside` | Optional | `boolean` | `true` | Close when clicking outside |
| `closeOnEscape` | Optional | `boolean` | `true` | Close on Escape key |
| `bare` | Optional | `boolean` | `false` | Minimal header styling |

## Basic usage

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent title="Confirm Action" closable onClose={() => {}}>
    <p>Are you sure you want to proceed?</p>
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="secondary">Cancel</Button>
      </DialogClose>
      <Button>Confirm</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Styling

- `.mdk-dialog__overlay`: Background overlay
- `.mdk-dialog__content`: Dialog container
- `.mdk-dialog__header`: Header area
- `.mdk-dialog__title`: Title text
- `.mdk-dialog__description`: Description text
- `.mdk-dialog__footer`: Footer area

## `DropdownMenu`

### Import

```tsx
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuLabel,
  DropdownMenuGroup,
} from '@tetherto/mdk-react-devkit/core'
```

### Basic usage

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button>Options</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuLabel>Actions</DropdownMenuLabel>
    <DropdownMenuItem onClick={() => {}}>Edit</DropdownMenuItem>
    <DropdownMenuItem onClick={() => {}}>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem onClick={() => {}} className="text-red-500">
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

### Styling

- `.mdk-dropdown-menu__content`: Menu container
- `.mdk-dropdown-menu__item`: Menu item
- `.mdk-dropdown-menu__label`: Label text
- `.mdk-dropdown-menu__separator`: Divider line

## `Popover`

### Import

```tsx
  Popover,
  PopoverTrigger,
  PopoverContent,
} from '@tetherto/mdk-react-devkit/core'
```

#### Basic usage

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button>Show Details</Button>
  </PopoverTrigger>
  <PopoverContent>
    <p>Additional information goes here.</p>
  </PopoverContent>
</Popover>
```

### Styling

- `.mdk-popover__content`: Popover container

## `Toast`

### Import

```tsx
```

### `Toast` props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `string` | none | **Required.** Toast title |
| `description` | Optional | `string` | none | Additional description |
| `variant` | Optional | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | Toast variant |
| `icon` | Optional | `ReactElement` | none | Custom icon |

### `ToastViewport` props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `position` | Optional | `ToastPosition` | `'bottom-right'` | Toast position |

Available positions: `'top-left'`, `'top-center'`, `'top-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`

### Setup

```tsx

function App() {
  return (
    <ToastProvider>
      {/* Your app content */}
      <ToastViewport position="bottom-right" />
    </ToastProvider>
  )
}
```

### Basic usage

```tsx

function MyComponent() {
  const [open, setOpen] = useState(false)

return (
    <>
      <Button onClick={() => setOpen(true)}>Show Toast</Button>
      <Toast
        open={open}
        onOpenChange={setOpen}
        title="Success!"
        description="Your changes have been saved."
        variant="success"
      />
    </>
  )
}
```

### Styling

- `.mdk_toast`: Toast container
- `.mdk_toast__header`: Header section
- `.mdk_toast__title`: Title text
- `.mdk_toast__description`: Description text
- `.mdk_toast__close`: Close button

## `Tooltip`

### Import

```tsx
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from '@tetherto/mdk-react-devkit/core'
```

### Basic usage

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="icon">
        <InfoIcon />
      </Button>
    </TooltipTrigger>
    <TooltipContent>
      Additional information
    </TooltipContent>
  </Tooltip>
</TooltipProvider>
```

### Styling

- `.mdk-tooltip__content`: Tooltip container

# Icons (/reference/ui/react/core/icons)

The `@tetherto/mdk-react-devkit/core` package includes **70+ icons** to simplify development of Bitcoin mining applications.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## Import

```tsx
// Import individual icons

// Import the factory function

// Import types
```

### Icon props

All icons accept the `IconProps` interface:

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `size` | Optional | `number \| string` | `24` | Sets both width and height |
| `color` | Optional | `string` | `'currentColor'` | Icon color (single-color icons only) |
| `width` | Optional | `number \| string` | none | Override width |
| `height` | Optional | `number \| string` | none | Override height |
| `className` | Optional | `string` | none | CSS class |
| `style` | Optional | `CSSProperties` | none | Inline styles |

### Basic usage

```tsx

// Default size (24px)
<DashboardNavIcon />

// Custom size
<HashrateStatIcon size={32} />

// Custom color
<MiningStatusIcon color="#72F59E" />

// With className
<SettingsNavIcon className="sidebar-icon" />
```

## Available icons

### Navigation icons

Icons for sidebar and navigation menus:

| Icon | Name | Description |
|------|------|-------------|
| ![dashboard-nav-icon](/images/ui-kit/icons/dashboard-nav-icon.svg) | `DashboardNavIcon` | Dashboard/home |
| <DocIcon src="/images/ui-kit/icons/farms-nav-icon.svg" scale={75} /> | `FarmsNavIcon` | Mining farms |
| ![financials-nav-icon](/images/ui-kit/icons/financials-nav-icon.svg) | `FinancialsNavIcon` | Financial reports |
| ![inventory-nav-icon](/images/ui-kit/icons/inventory-nav-icon.svg) | `InventoryNavIcon` | Equipment inventory |
| ![miners-overview-nav-icon](/images/ui-kit/icons/miners-overview-nav-icon.svg) | `MinersOverviewNavIcon` | Miner overview |
| ![operations-nav-icon](/images/ui-kit/icons/operations-nav-icon.svg) | `OperationsNavIcon` | Operations |
| ![pool-manager-nav-icon](/images/ui-kit/icons/pool-manager-nav-icon.svg) | `PoolManagerNavIcon` | Pool Manager |
| ![reporting-nav-icon](/images/ui-kit/icons/reporting-nav-icon.svg) | `ReportingNavIcon` | Reporting |
| ![settings-nav-icon](/images/ui-kit/icons/settings-nav-icon.svg) | `SettingsNavIcon` | Settings |
| ![user-management-nav-icon](/images/ui-kit/icons/user-management-nav-icon.svg) | `UserManagementNavIcon` | User management |
| ![explorer-nav-icon](/images/ui-kit/icons/explorer-nav-icon.svg) | `ExplorerNavIcon` | Explorer |
| ![alerts-nav-icon](/images/ui-kit/icons/alerts-nav-icon.svg) | `AlertsNavIcon` | Alerts |
| ![cabinet-widget-nav-icon](/images/ui-kit/icons/cabinet-widget-nav-icon.svg) | `CabinetWidgetNavIcon` | Cabinet widgets |
| ![container-widgets-nav-icon](/images/ui-kit/icons/container-widgets-nav-icon.svg) | `ContainerWidgetsNavIcon` | Container widgets |

### Status icons

Icons for displaying operational status:

| Icon | Name | Description |
|------|------|-------------|
| ![mining-status-icon](/images/ui-kit/icons/mining-status-icon.svg) | `MiningStatusIcon` | Active mining |
| ![offline-status-icon](/images/ui-kit/icons/offline-status-icon.svg) | `OfflineStatusIcon` | Offline |
| ![sleep-status-icon](/images/ui-kit/icons/sleep-status-icon.svg) | `SleepStatusIcon` | Sleep/standby mode |
| <DocIcon src="/images/ui-kit/icons/error-status-icon.svg" scale={50} /> | `ErrorStatusIcon` | Error state |
| ![live-icon](/images/ui-kit/icons/live-icon.svg) | `LiveIcon` | Live/active |

{/* OfflineIcon source file exists but isn't exported from @tetherto/mdk-react-devkit/core (upstream barrel gap) — pending fix
| ![offline-icon](/images/ui-kit/icons/offline-icon.svg) | `OfflineIcon` | Offline indicator |
*/}

### Alarm icons

Icons for alerts and alarms:

| Icon | Name | Description |
|------|------|-------------|
| ![temperature-alarm-icon](/images/ui-kit/icons/temperature-alarm-icon.svg) | `TemperatureAlarmIcon` | Temperature alarm |
| ![pressure-alarm-icon](/images/ui-kit/icons/pressure-alarm-icon.svg) | `PressureAlarmIcon` | Pressure alarm |
| ![fluid-alarm-icon](/images/ui-kit/icons/fluid-alarm-icon.svg) | `FluidAlarmIcon` | Fluid/coolant alarm |
| ![offline-alarm-icon](/images/ui-kit/icons/offline-alarm-icon.svg) | `OfflineAlarmIcon` | Offline alarm |
| ![other-alarm-icon](/images/ui-kit/icons/other-alarm-icon.svg) | `OtherAlarmIcon` | Generic alarm |
| ![alert-triangle-icon](/images/ui-kit/icons/alert-triangle-icon.svg) | `AlertTriangleIcon` | Warning triangle |

### Weather icons

Icons for environmental conditions:

{/*CloudyIcon SVG is identical to SunnyIcon (upstream bug) - using emoji placeholder
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/cloudy-icon.svg" alt="cloudy-icon" /></span> | `CloudyIcon` | Cloudy |
*/}

| Icon | Name | Description |
|------|------|-------------|
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/sunny-icon.svg" alt="sunny-icon" /></span> | `SunnyIcon` | Sunny/clear |
| ⛅ | `CloudyIcon` | Cloudy |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/rainy-icon.svg" alt="rainy-icon" /></span> | `RainyIcon` | Rain |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/snowy-icon.svg" alt="snowy-icon" /></span> | `SnowyIcon` | Snow |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/partly-cloudy-icon.svg" alt="partly-cloudy-icon" /></span> | `PartlyCloudyIcon` | Partly cloudy |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/rain-thunder-icon.svg" alt="rain-thunder-icon" /></span> | `RainThunderIcon` | Thunderstorm |

### Mining/stats icons

Icons for mining metrics and statistics:

| Icon | Name | Description |
|------|------|-------------|
| ![hashrate-card-icon](/images/ui-kit/icons/hashrate-card-icon.svg) | `HashrateCardIcon` | Hashrate display |
| ![hashrate-stat-icon](/images/ui-kit/icons/hashrate-stat-icon.svg) | `HashrateStatIcon` | Hashrate statistic |
| ![miners-stat-icon](/images/ui-kit/icons/miners-stat-icon.svg) | `MinersStatIcon` | Miner count |
| ![farm-star-icon](/images/ui-kit/icons/farm-star-icon.svg) | `FarmStarIcon` | Farm highlight |
| ![farm-alert-icon](/images/ui-kit/icons/farm-alert-icon.svg) | `FarmAlertIcon` | Farm alert |
| ![miner-overview-icon](/images/ui-kit/icons/miner-overview-icon.svg) | `MinerOverviewIcon` | Miner overview |
| ![miner-explorer-icon](/images/ui-kit/icons/miner-explorer-icon.svg) | `MinerExplorerIcon` | Miner explorer |
| ![pools-icon](/images/ui-kit/icons/pools-icon.svg) | `PoolsIcon` | Mining pools |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/production-data-icon.svg" alt="production-data-icon" /></span> | `ProductionDataIcon` | Production data |

### Measurement icons

Icons for measurements and readings:

| Icon | Name | Description |
|------|------|-------------|
| ![power-icon](/images/ui-kit/icons/power-icon.svg) | `PowerIcon` | Power consumption |
| ![fan-icon](/images/ui-kit/icons/fan-icon.svg) | `FanIcon` | Fan/cooling |
| ![frequency-icon](/images/ui-kit/icons/frequency-icon.svg) | `FrequencyIcon` | Frequency |
| ![efficiency-icon](/images/ui-kit/icons/efficiency-icon.svg) | `EfficiencyIcon` | Efficiency |
| ![consumption-icon](/images/ui-kit/icons/consumption-icon.svg) | `ConsumptionIcon` | Consumption |
| ![temperature-celsius-icon](/images/ui-kit/icons/temperature-celsius-icon.svg) | `TemperatureCelsiusIcon` | Temperature (°C) |
| ![temperature-indicator-icon](/images/ui-kit/icons/temperature-indicator-icon.svg) | `TemperatureIndicatorIcon` | Temperature indicator |
| <span className="doc-icon doc-icon-tall" style={{'--icon-scale': 0.75}}><img src="/images/ui-kit/icons/temperature-weather-icon.svg" alt="temperature-weather-icon" /></span> | `TemperatureWeatherIcon` | Temperature/weather |
| ![cooling-drop-icon](/images/ui-kit/icons/cooling-drop-icon.svg) | `CoolingDropIcon` | Cooling/liquid |

### UI icons

General UI icons:

| Icon | Name | Description |
|------|------|-------------|
| ![arrow-icon](/images/ui-kit/icons/arrow-icon.svg) | `ArrowIcon` | Arrow (direction) |
| ![right-arrow-icon](/images/ui-kit/icons/right-arrow-icon.svg) | `RightArrowIcon` | Right arrow |
| ![right-navigate-icon](/images/ui-kit/icons/right-navigate-icon.svg) | `RightNavigateIcon` | Navigate right |
| <DocIcon src="/images/ui-kit/icons/pin-icon.svg" scale={50} /> | `PinIcon` | Pin/favorite |
| <DocIcon src="/images/ui-kit/icons/unpin-icon.svg" scale={50} /> | `UnPinIcon` | Unpin |
| ![menu-icon](/images/ui-kit/icons/menu-icon.svg) | `MenuIcon` | Menu hamburger |
| ![export-icon](/images/ui-kit/icons/export-icon.svg) | `ExportIcon` | Export data |
| ![google-icon](/images/ui-kit/icons/google-icon.svg) | `GoogleIcon` | Google logo |
| ![notification-bell-icon](/images/ui-kit/icons/notification-bell-icon.svg) | `NotificationBellIcon` | Notifications |
| ![settings-header-icon](/images/ui-kit/icons/settings-header-icon.svg) | `SettingsHeaderIcon` | Settings gear |
| ![sign-out-icon](/images/ui-kit/icons/sign-out-icon.svg) | `SignOutIcon` | Sign out |
| ![user-avatar-icon](/images/ui-kit/icons/user-avatar-icon.svg) | `UserAvatarIcon` | User avatar |
| ![volume-on-icon](/images/ui-kit/icons/volume-on-icon.svg) | `VolumeOnIcon` | Volume on |
| ![volume-off-icon](/images/ui-kit/icons/volume-off-icon.svg) | `VolumeOffIcon` | Volume off |
| ![comment-icon](/images/ui-kit/icons/comment-icon.svg) | `CommentIcon` | Comment |
| ![comment-icon-common](/images/ui-kit/icons/comment-icon-common.svg) | `CommentIconCommon` | Comment (common variant) |
| ![increase-icon](/images/ui-kit/icons/increase-icon.svg) | `IncreaseIcon` | Increase/up |
| ![decrease-icon](/images/ui-kit/icons/decrease-icon.svg) | `DecreaseIcon` | Decrease/down |
| ![profit-arrow-icon](/images/ui-kit/icons/profit-arrow-icon.svg) | `ProfitArrowIcon` | Profit indicator |
| ![btc-card-icon](/images/ui-kit/icons/btc-card-icon.svg) | `BtcCardIcon` | Bitcoin card |
| ![mode-icon](/images/ui-kit/icons/mode-icon.svg) | `ModeIcon` | Mode toggle |
| ![scale-control-icon](/images/ui-kit/icons/scale-control-icon.svg) | `ScaleControlIcon` | Scale control |
| ![site-overview-icon](/images/ui-kit/icons/site-overview-icon.svg) | `SiteOverviewIcon` | Site overview |
| ![actions-tick-icon](/images/ui-kit/icons/actions-tick-icon.svg) | `ActionsTickIcon` | Action complete |

## Create custom icons

Use `createIcon` to create custom icons following the same pattern:

```tsx

displayName: 'MyCustomIcon',
  viewBox: '0 0 24 24',
  defaultWidth: 24,
  defaultHeight: 24,
  path: (
    <path
      d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"
      stroke="currentColor"
      strokeWidth={2}
      strokeLinecap="round"
      strokeLinejoin="round"
    />
  ),
})
```

### `CreateIconOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `displayName` | `string` | none | **Required:** Component display name |
| `viewBox` | `string` | none | **Required:** SVG `viewBox` |
| `defaultWidth` | `number` | `24` | Default width |
| `defaultHeight` | `number` | `24` | Default height |
| `multiColor` | `boolean` | `false` | Multi-color icon flag |
| `path` | `ReactNode \| function` | none | **Required:** SVG path content |

### Dynamic color icons

For icons that need dynamic colors:

```tsx
  displayName: 'DynamicColorIcon',
  viewBox: '0 0 24 24',
  path: ({ color }) => (
    <circle cx="12" cy="12" r="10" fill={color} />
  ),
})
```

# Theme (/reference/ui/react/core/theme)

The `@tetherto/mdk-react-devkit/core` package provides a theme system with design tokens and utilities for consistent styling across your application.

Import `@tetherto/mdk-react-devkit/styles.css` once in your app entry (before your own CSS). The compiled stylesheet declares `@layer base`, `mdk`, `app` — so unlayered or `@layer app` styles in your application always win against devkit component styles. MDK ships with `--mdk-color-primary: #f7931a`; override tokens in `:root` only when reskinning.

```css
/* app.css — imported AFTER @tetherto/mdk-react-devkit/styles.css */
:root {
  --mdk-color-primary: #f7931a;
  --mdk-radius: 6px;
}

@layer app {
  .mdk-button--variant-primary { letter-spacing: 0.04em; }
}
```

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/core#prerequisites)

## Import

```tsx
// Import tokens

// Import utilities
  getSystemTheme,
  applyTheme,
  getStoredTheme,
  setStoredTheme,
} from '@tetherto/mdk-react-devkit/core'

// Import types
```

## Design tokens

### Colors

Primary and gray color scales with 10 shades each (50-900).

```tsx

colors.primary[500]  // 'hsl(222, 47%, 50%)'
colors.gray[900]     // 'hsl(222, 47%, 11%)'
```

#### Primary scale

| Token | Value | Usage |
|-------|-------|-------|
| `primary.50` | `hsl(222, 47%, 95%)` | Lightest background |
| `primary.100` | `hsl(222, 47%, 90%)` | Light background |
| `primary.200` | `hsl(222, 47%, 80%)` | Hover states |
| `primary.300` | `hsl(222, 47%, 70%)` | Borders |
| `primary.400` | `hsl(222, 47%, 60%)` | Secondary text |
| `primary.500` | `hsl(222, 47%, 50%)` | Primary color |
| `primary.600` | `hsl(222, 47%, 40%)` | Hover on primary |
| `primary.700` | `hsl(222, 47%, 30%)` | Active states |
| `primary.800` | `hsl(222, 47%, 20%)` | Dark backgrounds |
| `primary.900` | `hsl(222, 47%, 11.2%)` | Darkest |

#### Gray scale

| Token | Value | Usage |
|-------|-------|-------|
| `gray.50` | `hsl(210, 40%, 98%)` | Page background |
| `gray.100` | `hsl(210, 40%, 96.1%)` | Card background |
| `gray.200` | `hsl(214, 32%, 91.4%)` | Borders |
| `gray.300` | `hsl(213, 27%, 84.1%)` | Dividers |
| `gray.400` | `hsl(215, 20%, 65.1%)` | Placeholder text |
| `gray.500` | `hsl(215, 16%, 47%)` | Secondary text |
| `gray.600` | `hsl(215, 19%, 35%)` | Body text |
| `gray.700` | `hsl(215, 25%, 27%)` | Headings |
| `gray.800` | `hsl(217, 33%, 17%)` | Dark mode card |
| `gray.900` | `hsl(222, 47%, 11%)` | Dark mode `bg` |

### Spacing

Consistent spacing scale for margins, padding, and gaps.

```tsx

spacing[4]   // '1rem' (16px)
spacing[8]   // '2rem' (32px)
```

| Token | Value | Pixels |
|-------|-------|--------|
| `0` | `0` | 0px |
| `1` | `0.25rem` | 4px |
| `2` | `0.5rem` | 8px |
| `3` | `0.75rem` | 12px |
| `4` | `1rem` | 16px |
| `5` | `1.25rem` | 20px |
| `6` | `1.5rem` | 24px |
| `8` | `2rem` | 32px |
| `10` | `2.5rem` | 40px |
| `12` | `3rem` | 48px |
| `16` | `4rem` | 64px |
| `20` | `5rem` | 80px |
| `24` | `6rem` | 96px |

### Border radius

Border radius scale for rounded corners.

```tsx

borderRadius.md    // '0.375rem'
borderRadius.full  // '9999px'
```

| Token | Value |
|-------|-------|
| `none` | `0` |
| `sm` | `0.125rem` |
| `DEFAULT` | `0.25rem` |
| `md` | `0.375rem` |
| `lg` | `0.5rem` |
| `xl` | `0.75rem` |
| `2xl` | `1rem` |
| `full` | `9999px` |

### Font size

Font size scale for typography.

```tsx

fontSize.base  // '1rem'
fontSize.lg    // '1.125rem'
```

| Token | Value |
|-------|-------|
| `xs` | `0.75rem` |
| `sm` | `0.875rem` |
| `base` | `1rem` |
| `lg` | `1.125rem` |
| `xl` | `1.25rem` |
| `2xl` | `1.5rem` |
| `3xl` | `1.875rem` |
| `4xl` | `2.25rem` |
| `5xl` | `3rem` |

## Theme utilities

### Theme type

```tsx
type Theme = 'light' | 'dark' | 'system'
```

### `getSystemTheme`

Get the user's system theme preference.

```tsx

const systemTheme = getSystemTheme()  // 'light' or 'dark'
```

### `applyTheme`

Apply a theme to the document root.

```tsx

applyTheme('dark')   // Sets dark mode
applyTheme('light')  // Sets light mode
applyTheme('system') // Uses system preference
```

This function:
- Removes existing `light`/`dark` classes from `<html>`
- Adds the resolved theme class
- Sets the `color-scheme` CSS property

### `getStoredTheme`

Get the stored theme from `localStorage`.

```tsx

const storedTheme = getStoredTheme()  // Theme | null
const customKey = getStoredTheme('my-theme-key')
```

### `setStoredTheme`

Store the theme in `localStorage`.

```tsx

setStoredTheme('dark')
setStoredTheme('light', 'my-theme-key')  // Custom storage key
```

## Usage example

```tsx
  applyTheme,
  getStoredTheme,
  setStoredTheme,
  getSystemTheme,
} from '@tetherto/mdk-react-devkit/core'

function ThemeProvider({ children }) {
  const [theme, setTheme] = useState<Theme>(() => {
    return getStoredTheme() || 'system'
  })

useEffect(() => {
    applyTheme(theme)
    setStoredTheme(theme)
  }, [theme])

return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}
```

## CSS custom properties

The theme system uses CSS custom properties that can be overridden:

```css
:root {
  --mdk-color-primary: #f7931a;
  --mdk-color-background: hsl(210, 40%, 98%);
  --mdk-color-foreground: hsl(222, 47%, 11%);
  /* ... more properties */
}

.dark {
  --mdk-color-background: hsl(222, 47%, 11%);
  --mdk-color-foreground: hsl(210, 40%, 98%);
}
```

# @tetherto/mdk-react-devkit (/reference/ui/react/foundation)

The [foundation entrypoint](/support/resources/repositories) (`@tetherto/mdk-react-devkit/foundation`) provides **domain-specific React components, 
hooks, and constants** assembled from [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core). These are higher-level blocks for common 
Bitcoin mining application use cases.

<Callout type="info">
Generic primitives (buttons, tables, charts) import from [`/core`](/reference/ui/react/core). Both subpaths ship from `@tetherto/mdk-react-devkit`. 
Connected foundation components expect `<MdkProvider>` from [`@tetherto/mdk-react-adapter`](/tutorials/ui/react) and adapter store hooks.
</Callout>

## Prerequisites

- Complete the installation

<Accordions>
  <Accordion title="Show steps">
    ```bash
# Clone the MDK UI monorepo (adjust the URL to your fork if needed)
git clone https://github.com/tetherto/mdk.git
cd mdk/ui

# Install dependencies and build packages (npm workspaces)
npm install
npm run build
```

</Accordion>
</Accordions>

- Add the dependency to your app's `package.json`

```json
{
  "dependencies": {
    "@tetherto/mdk-react-devkit": "*",
    "@tetherto/mdk-react-adapter": "*",
    "@tetherto/mdk-ui-foundation": "*"
  }
}
```

</Tab>
  <Tab value="npm" label="🚧 Registry install">

> **Coming soon** — npm packages are not yet published. Use the monorepo setup for now.

```bash
npm install \
  @tetherto/mdk-react-devkit \
  @tetherto/mdk-react-adapter \
  @tetherto/mdk-ui-foundation
```

</Tab>
</Tabs>

Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages.

## What's included

| Feature | Description |
|---------|-------------|
| [Operations centre](/reference/ui/react/foundation/operations) | Bitcoin mining operations monitoring and management components |
| [Reporting tool](/reference/ui/react/foundation/reporting) | Operational reporting surfaces |
| [Settings](/reference/ui/react/foundation/settings) | Administrative settings views |
| [Hooks](#hooks) | Reusable React hooks |
| [Constants](#constants) | Shared constants and configurations |

### Operations centre

Domain-specific components for Bitcoin mining operations monitoring and management, including device explorers, vendor container UIs, dashboard widgets, 
charts, pool management, and data export.

See the [operations centre reference](/reference/ui/react/foundation/operations) for the full component list with demo links.

### Settings

Pre-built settings UI for common administrative tasks:

- [`SettingsDashboard`](/reference/ui/react/foundation/settings): main settings container with accordion sections
- [`FeatureFlagsSettings`](/reference/ui/react/foundation/settings/feature-flags): toggle feature flags on/off
- [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls): configure header display options
- [`ImportExportSettings`](/reference/ui/react/foundation/settings/import-export): import/export configuration data
- [`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control): role-based access control settings
- [User management modals](/reference/ui/react/foundation/settings/user-management): add, manage, and confirm user changes

### Hooks

Reusable React hooks for [notifications and shell layout](/reference/app-toolkit/hooks/components#notifications) and 
[chart/dashboard transforms](/reference/app-toolkit/hooks/components#charts) — see the full [Hooks reference](/reference/app-toolkit/hooks).

### Constants

Shared [constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants) for consistency across your application: permission definitions, 
role configurations, settings defaults, and error codes.

## Import examples

```tsx
// Import components

// Import from domain subpath when you only need settings-domain exports
```

## Next steps

Consider the detailed [reference material](/reference) for the foundation entrypoint:

- [Constants](/reference/app-toolkit/ui-devkit/constants#foundation-constants): permissions, roles, header controls, settings error codes
- [Hooks: Components](/reference/app-toolkit/hooks/components) and [Hooks: Utilities > Domain transforms](/reference/app-toolkit/hooks/utilities#domain-transforms)
- [Types](/reference/app-toolkit/ui-devkit/types#foundation-types): [`Device`](/reference/app-toolkit/ui-devkit/types#device), [`Container`](/reference/app-toolkit/ui-devkit/types#container), [`Alert`](/reference/app-toolkit/ui-devkit/types#alert), [`MinerStats`](/reference/app-toolkit/ui-devkit/types#minerstats), settings shapes
- [Utilities](/reference/app-toolkit/ui-devkit/utilities#foundation-utilities): `settings-utils` (filtering, formatting, import/export)

# Alerts (/reference/ui/react/foundation/alerts)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Alerts components cover the full alarm surface: `AlarmsBellButton` in the app header, the `Alerts` feature composite 
(current and historical tabs), and the standalone `HistoricalAlerts` table. Pair with the [dashboard](/reference/ui/react/foundation/dashboard) 
for live context.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- Wrap your app in `<MdkProvider>` — see [foundation prerequisites](/reference/ui/react/foundation#prerequisites)

## Components

### `AlarmsBellButton`

Header bell button that renders severity-bucketed alarm counts in a stacked badge. Typically placed in the [`AppHeader`](/reference/ui/react/core/components/navigation#appheader) actions cluster.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `counts` | Optional | `AlarmsBellButtonCounts` | none | Severity-bucketed alarm counts rendered in the stacked badge |
| `onClick` | Optional | `(event: React.MouseEvent<HTMLButtonElement>) => void` | none | Click handler — typically opens an alerts panel or routes to `/alerts` |
| `onSeverityClick` | Optional | `(severity: AlarmSeverity, event: React.MouseEvent<HTMLButtonElement>) => void` | none | Click handler for an individual severity count; when provided, each badge row becomes its own button |
| `label` | Optional | `string` | `'Active alarms'` | Accessible label |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Basic usage

```tsx
<AlarmsBellButton counts={{ critical: 171, high: 72, medium: 322 }} />

<AlarmsBellButton
  counts={{ critical: 2, high: 5 }}
  onSeverityClick={(severity) => router.push(`/alerts?severity=${severity}`)}
/>
```

### `Alerts`

Full-page alerts surface that wraps [`CurrentAlerts`](#currentalerts) and (when `isHistoricalAlertsEnabled`) [`HistoricalAlerts`](#historicalalerts), coordinating their shared filter state, date range, and alert click handling. It manages:

1. **Current alerts** (`devices`, `isCurrentAlertsLoading`): raw devices payload and loading flag passed to `CurrentAlerts`.
2. **Historical alerts** (`historicalAlerts`, `isHistoricalAlertsLoading`, `isHistoricalAlertsEnabled`): log data and visibility toggle.
3. **Filtering** (`selectedAlertId`, `initialSeverity`, `typeFiltersForSite`): deep-link focus, severity pre-selection, and site type filters.
4. **Callbacks** (`onAlertClick`, `onDateRangeChange`): row navigation and date range updates.
5. **Sound** (`isSoundEnabled`, `isDemoMode`): critical-alert beep toggle and demo/preview mode.
6. **Layout** (`header`, `className`): optional header slot and root class.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `devices` | Optional | `Device[][]` | none | Raw devices payload for current alerts (see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices)) |
| `isCurrentAlertsLoading` | Optional | `boolean` | `false` | When `true`, shows the loading state in `CurrentAlerts` |
| `historicalAlerts` | Optional | `Alert[]` | none | Pre-fetched historical alerts (see [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts)) |
| `isHistoricalAlertsLoading` | Optional | `boolean` | `false` | When `true`, shows the loading state in `HistoricalAlerts` |
| `isHistoricalAlertsEnabled` | Optional | `boolean` | `false` | When `true`, renders the historical alerts log section |
| `selectedAlertId` | Optional | `string` | none | Focuses the table on a single alert (deep-link from URL) |
| `initialSeverity` | Optional | `string` | none | Pre-selects a severity filter (typically from a `?severity=` URL param) |
| `onAlertClick` | Optional | `function` | none | Called with device `id` and alert `uuid` when the user opens an alert row |
| `onDateRangeChange` | Optional | `function` | none | Called when the user picks a new date range in the historical log |
| `dateRange` | Optional | `HistoricalAlertsRange` | last 14 days | Controlled date range (`{ start: number, end: number }` in ms) |
| `isSoundEnabled` | Optional | `boolean` | `false` | Enables the critical-alert audible beep when a critical alert is present |
| `isDemoMode` | Optional | `boolean` | `false` | When `true`, skips sound notifications (safe for preview environments) |
| `typeFiltersForSite` | Optional | `CascaderOption[]` | none | Site-specific overrides for the `TagFilterBar` type filter |
| `header` | Optional | `ReactNode` | none | Optional header (e.g. breadcrumbs) rendered above the alerts tables |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Hook integration

Wire `Alerts` with the MDK adapter hooks for live data (see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts)):

```tsx

function AlertsPage() {
  const { filterTags } = useDevices()
  const devices = useCurrentAlertDevices({ filterTags })
  const [range, setRange] = useState(() => getDefaultHistoricalAlertsRange())
  const historical = useHistoricalAlerts(range)

return (
    <Alerts
      devices={devices.data}
      isCurrentAlertsLoading={devices.isLoading}
      historicalAlerts={historical.data}
      isHistoricalAlertsLoading={historical.isLoading}
      isHistoricalAlertsEnabled
      dateRange={range}
      onDateRangeChange={setRange}
      onAlertClick={(id, uuid) => router.push(`/alerts/${uuid}`)}
    />
  )
}
```

<Callout type="tip">See [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts) for hook options.</Callout>

### `CurrentAlerts`

Sortable, searchable data table of active alerts derived from a raw devices payload. Plays an audible beep when a 
critical alert is present and sound notifications are enabled — after the user confirms 
via [`AlertConfirmationModal`](#alertconfirmationmodal). The [`Alerts`](#alerts) feature wrapper manages all 
state for most use cases; use `CurrentAlerts` directly when you need a standalone current-alerts table.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `localFilters` | Required | `AlertLocalFilters` | none | Controlled filter state shared with other alerts components (see [type](#alertlocalfilters-type)) |
| `onLocalFiltersChange` | Required | `function` | none | Called with the updated `AlertLocalFilters` when filters change |
| `filterTags` | Required | `string[]` | none | Active search tags; mirrors the devices-store tag slice |
| `onFilterTagsChange` | Required | `function` | none | Called with updated tags when the user adds or removes a search chip |
| `devices` | Optional | `Device[][]` | none | Raw devices payload; drives alert row derivation |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows the table loading state |
| `selectedAlertId` | Optional | `string` | none | Focuses the table on a single alert |
| `onAlertClick` | Optional | `function` | none | Called with device `id` and alert `uuid` when the user opens an alert row |
| `isSoundEnabled` | Optional | `boolean` | `false` | Enables the critical-alert audible beep |
| `isDemoMode` | Optional | `boolean` | `false` | When `true`, skips sound notifications |
| `typeFiltersForSite` | Optional | `CascaderOption[]` | none | Site-specific overrides for the type filter in `TagFilterBar` |
| `className` | Optional | `string` | none | Root class name from the host app |

#### `AlertLocalFilters` type

```tsx
type AlertLocalFilters = {
  severity?: string[] | string
  status?: string[]
  type?: string[]
  id?: string[]
  thing?: { id?: string }
  [key: string]: unknown
}
```

#### Basic usage

```tsx

function AlertsView({ devices, isLoading }) {
  const [localFilters, setLocalFilters] = useState<AlertLocalFilters>({})
  const [filterTags, setFilterTags] = useState<string[]>([])

return (
    <CurrentAlerts
      devices={devices}
      isLoading={isLoading}
      localFilters={localFilters}
      onLocalFiltersChange={setLocalFilters}
      filterTags={filterTags}
      onFilterTagsChange={setFilterTags}
      onAlertClick={(id, uuid) => console.log('Alert clicked', id, uuid)}
    />
  )
}
```

### `HistoricalAlerts`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `alerts` | Optional | `Alert[]` | `[]` | Pre-fetched historical alert entries |
| `isLoading` | Optional | `boolean` | `false` | Show table loading state |
| `localFilters` | Required | `AlertLocalFilters` | none | Filters and search state shared with `CurrentAlerts` |
| `filterTags` | Required | `string[]` | none | Active filter tags |
| `dateRange` | Required | `HistoricalAlertsRange` | none | Controlled start/end timestamps (ms) |
| `onDateRangeChange` | Required | `function` | none | Fires when the user picks a new range |
| `onAlertClick` | Optional | `function` | none | Row click handler |
| `className` | Optional | `string` | none | Additional CSS class |

#### `HistoricalAlertsRange` type

```tsx
type HistoricalAlertsRange = {
  start: number
  end: number
}
```

#### Basic usage

```tsx
<HistoricalAlerts
  alerts={historicalAlerts}
  localFilters={localFilters}
  filterTags={filterTags}
  dateRange={{ start: rangeStart, end: rangeEnd }}
  onDateRangeChange={({ start, end }) => setRange({ start, end })}
  onAlertClick={(id, uuid) => console.log('Alert clicked', id, uuid)}
/>
```

#### Loading state

```tsx
<HistoricalAlerts
  alerts={[]}
  isLoading
  localFilters={localFilters}
  filterTags={filterTags}
  dateRange={dateRange}
  onDateRangeChange={onDateRangeChange}
/>
```

#### Behavior notes

- The component wires a `DateRangePicker` into the table title via `AlertsTableTitle`, so date range changes 
come back through `onDateRangeChange`.
- Rows are sorted by severity (descending) then creation date (descending) by default
- Timestamps are formatted through `useTimezoneFormatter()`'s `getFormattedDate`

### `TagFilterBar`

Strip of removable filter chips and a tag-input search field for narrowing the alerts table by severity, status, 
type, and device tags. Used as the subtitle slot of [`AlertsTableTitle`](#alertstabletitle) inside [`CurrentAlerts`](#currentalerts).

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `filterTags` | Required | `string[]` | none | Active search tag chips |
| `localFilters` | Required | `AlertLocalFilters` | none | Controlled filter state (severity, status, type) |
| `onSearchTagsChange` | Required | `function` | none | Called with updated tags when the user adds or removes a chip |
| `onLocalFiltersChange` | Required | `function` | none | Called with updated `AlertLocalFilters` when a cascader selection changes |
| `typeFiltersForSite` | Optional | `CascaderOption[]` | default filter list | Site-specific overrides for the "Type" cascader children |
| `placeholder` | Optional | `string` | none | Placeholder text for the tag-input field |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Basic usage

```tsx

<TagFilterBar
  filterTags={filterTags}
  localFilters={localFilters}
  onSearchTagsChange={setFilterTags}
  onLocalFiltersChange={setLocalFilters}
/>
```

### `AlertsTableTitle`

Heading strip for an alerts table — renders the section title and an optional subtitle slot (typically used 
for `TagFilterBar` or `DateRangePicker`). Used internally by [`CurrentAlerts`](#currentalerts) and 
[`HistoricalAlerts`](#historicalalerts).

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `ReactNode` | none | Section heading content |
| `subtitle` | Optional | `ReactNode` | none | Optional content rendered below the title (e.g. `TagFilterBar` or `DateRangePicker`) |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Basic usage

```tsx

<AlertsTableTitle
  title="Current Alerts"
  subtitle={
    <TagFilterBar
      filterTags={filterTags}
      localFilters={localFilters}
      onSearchTagsChange={setFilterTags}
      onLocalFiltersChange={setLocalFilters}
    />
  }
/>
```

### `AlertConfirmationModal`

One-time consent dialog that appears before critical-alert sound notifications are activated. 
Renders a non-dismissible `Dialog` with an "Understood" button. Once confirmed (tracked in `sessionStorage`), `CurrentAlerts` 
begins playing the beep.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isOpen` | Required | `boolean` | none | Controls modal visibility |
| `onOk` | Required | `function` | none | Called when the user clicks "Understood" |

#### Basic usage

```tsx

<AlertConfirmationModal
  isOpen={showConfirmation}
  onOk={() => setShowConfirmation(false)}
/>
```

### `AlarmContents`

Building block of the alarm card — renders the body region with the alert details and recommended next actions. Compose it inside your own card chrome when you need a custom alarm layout.

#### Import

```tsx
```

### `AlarmRow`

Building block of the alarm feed — a single row with a severity dot, timestamp, source device, and the alert message. Map your alert list to a stack of `AlarmRow`s for a custom feed.

#### Import

```tsx
```

## Next steps

- For live incident context, see [`ActiveIncidentsCard`](/reference/ui/react/foundation/dashboard/feeds#activeincidentscard) on the 
dashboard Feeds page
- For alert data hooks, see [`useCurrentAlertDevices`](/reference/app-toolkit/hooks/data#usecurrentalertdevices) 
and [`useHistoricalAlerts`](/reference/app-toolkit/hooks/data#usehistoricalalerts)

# Dashboard (/reference/ui/react/foundation/dashboard)

The dashboard is the top-level operations surface. It composes live feeds, summary widgets, and chart cards into a single overview of fleet health, pool context, and power trends.

The docs group these components into three intuitive buckets:

- [Feeds](/reference/ui/react/foundation/dashboard/feeds): active incidents and activity logs
- [Stats](/reference/ui/react/foundation/dashboard/stats): at-a-glance summary cards for containers, pool details, and export controls
- [Charts](/reference/ui/react/foundation/dashboard/charts): line, timeline, and multi-series chart cards

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## All dashboard components

## Next steps

For past alerts paired with the dashboard's active-incidents view, see [`HistoricalAlerts`(../alerts#historicalalerts).

# Charts (/reference/ui/react/foundation/dashboard/charts)

Chart components specialized for Bitcoin mining operations data visualization, including hashrate trends, power consumption, power mode timelines, 
and multi-container comparisons.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

### `ChartWrapper`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `children` | Optional | `ReactNode` | none | Chart content rendered when data is present |
| `data` | Optional | `object \| array` | none | Chart data for LineChart-style datasets; used by `useChartDataCheck` |
| `dataset` | Optional | `object \| array` | none | Chart dataset for BarChart-style data; used by `useChartDataCheck` |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows the loading overlay with default `<Loader />` (animated dots) or `customLoader`, and hides chart children |
| `showNoDataPlaceholder` | Optional | `boolean` | `true` | When `true`, shows empty placeholder when data/dataset has no values |
| `customLoader` | Optional | `ReactNode` | `<Loader />` | Node shown in the loading overlay (default core `Loader`) |
| `customNoDataMessage` | Optional | `string \| ReactNode` | none | Custom empty state message or component |
| `minHeight` | Optional | `number` | `400` | Minimum height in pixels for empty state |
| `loadingMinHeight` | Optional | `number` | `minHeight` | Minimum height in pixels for the loading overlay (default `<Loader />` or `customLoader`) |
| `className` | Optional | `string` | none | Root class name from the host app |

Chart children (`LineChart`, `BarChart`) come from `@tetherto/mdk-react-devkit/core`.

```tsx

const CustomSpinner = () => <div className="my-spinner" aria-hidden />
```

#### Basic usage

```tsx
<ChartWrapper
  data={chartData}
  isLoading={isLoading}
  minHeight={400}
>
  <LineChart data={chartData} />
</ChartWrapper>
```

#### With custom loader

```tsx
<ChartWrapper
  data={chartData}
  isLoading={isLoading}
  customLoader={<CustomSpinner />}
  minHeight={300}
>
  <LineChart data={chartData} />
</ChartWrapper>
```

#### With custom empty message

Pass an empty dataset so `ChartWrapper` shows the empty placeholder instead of the chart. With non-empty `dataset`, children render and the custom 
message is not shown.

```tsx

const emptyBarData = { labels: [], datasets: [] }

<ChartWrapper
  dataset={emptyBarData}
  isLoading={false}
  customNoDataMessage="No hashrate data available for this period"
  minHeight={300}
>
  <BarChart data={emptyBarData} />
</ChartWrapper>
```

#### States

The component handles three states automatically. Chart **children** are hidden while `isLoading` is `true` or when `data` / `dataset` is empty (and `showNoDataPlaceholder` is `true`):

1. **Loading**: Shows default `<Loader />` (animated dots) or `customLoader`
2. **No data**: Shows `EmptyState` placeholder (or `customNoDataMessage`)
3. **Has data**: Shows chart content

#### Styling

- `.mdk-chart-wrapper`: Root element
- `.mdk-chart-wrapper__content`: Chart content container
- `.mdk-chart-wrapper__content--hidden`: Hidden content state
- `.mdk-chart-wrapper__empty`: Empty state container
- `.mdk-chart-wrapper__loading`: Loading state container

### `ContainerCharts`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `featureEnabled` | Optional | `boolean` | `true` | When `false`, shows `disabledMessage` instead of charts |
| `combinations` | Required | \{ value: string; label: string \}[] | none | Select options (`value` / `label` pairs) |
| `chartRawData` | Optional | `ChartEntry[]` | `null` | Raw time-series rows; shape depends on selected container type |
| `selectedCombination` | Optional | `string \| null` | none | Controlled selected `combinations[].value` |
| `defaultSelectedCombination` | Optional | `string \| null` | `null` | Initial selection when uncontrolled |
| `onSelectedCombinationChange` | Optional | `function` | none | Called with the new combination `value` (or `null`) when the user changes selection |
| `isLoadingCombinations` | Optional | `boolean` | `false` | When `true`, shows loading state on the combination selector |
| `isLoadingCharts` | Optional | `boolean` | `false` | When `true`, shows loading state on the chart grid |
| `disabledMessage` | Optional | `string` | `'Container Charts feature is not enabled'` | Message when `featureEnabled` is `false` |
| `title` | Optional | `string` | `'Container Charts'` | Section heading |
| `getDatasetBorderColor` | Optional | `function` | none | Resolver for dataset border colors; receives dataset metadata from the builder |

#### `ChartEntry` type

```tsx
type EntryData = {
  [key: string]: number | null | undefined
}

type ChartEntry = {
  ts: number | string
  container_specific_stats_group_aggr: Record<string, EntryData | null | undefined>
}
```

Each row’s `container_specific_stats_group_aggr` keys use complete container type ids (for example `container-bd-d40-m30`, `container-as-hk3`). Stat field names inside each entry depend on the container family.

**Bitdeer** (`container-bd-…` keys) — field names per chart block:

| Chart block | Stat field pattern |
|-------------|-------------------|
| Liquid Temp H | `hot_temp_c_w_{n}_group` |
| Liquid Temp L | `cold_temp_c_w_{n}_group` |
| Oil Temp | `cold_temp_c_{n}_group` (no `_w_`) |
| Pressure | `tank{n}_bar_group` |

**Hydro** (`container-as-hk3`): `supply_liquid_temp_group`, `supply_liquid_pressure_group`.

Combination `value` strings must contain the real prefix patterns the component detects (`bd-…`, `as-hk3…`, `as-immersion…`, `mbt-…`). Values such as `bitmain_hydro_b2` (underscores) do not match `isAntspaceHydro()` and show the wrong chart blocks.

```tsx
const chartData: ChartEntry[] = [
  {
    ts: 1700000000,
    container_specific_stats_group_aggr: {
      'container-bd-d40-m30': {
        hot_temp_c_w_1_group: 52,
        hot_temp_c_w_2_group: 54,
        cold_temp_c_w_1_group: 38,
        cold_temp_c_w_2_group: 39,
        cold_temp_c_1_group: 36,
        cold_temp_c_2_group: 37,
        tank1_bar_group: 2.4,
        tank2_bar_group: 2.5,
      },
      'container-as-hk3': {
        supply_liquid_temp_group: 44,
        supply_liquid_pressure_group: 2.8,
      },
    },
  },
]
```

#### Basic usage

```tsx
<ContainerCharts
  combinations={[
    { value: 'bd-d40-m30_wm-m30sp', label: 'Bitdeer M30SP' },
    { value: 'as-hk3_am-s19xp_h', label: 'Bitmain Hydro S19XP' },
  ]}
  defaultSelectedCombination="bd-d40-m30_wm-m30sp"
  chartRawData={chartData}
  onSelectedCombinationChange={setSelected}
/>
```

#### Container type charts

Charts displayed vary by container type:
- **Bitdeer**: Liquid Temp H, Liquid Temp L, Oil Temp, Pressure
- **Bitmain Hydro**: Liquid Temp L, Pressure
- **Bitmain Immersion**: Liquid Temp L, Oil Temp
- **MicroBT**: Liquid Temp L, Pressure

#### Styling

- `.mdk-container-charts`: Root element
- `.mdk-container-charts__title`: Section title
- `.mdk-container-charts__select-row`: Combination selector row
- `.mdk-container-charts__select-label`: Selector label
- `.mdk-container-charts__select`: Select dropdown
- `.mdk-container-charts__layout`: Charts grid layout
- `.mdk-container-charts__chart-block`: Individual chart container
- `.mdk-container-charts__chart-title`: Chart block title
- `.mdk-container-charts__loading`: Loading state container

### `LineChartCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `LineChartCardData` | none | Pre-processed chart payload passed to the inner line chart |
| `rawData` | Optional | `unknown` | none | Raw API payload; use with `dataAdapter` instead of `data` |
| `dataAdapter` | Optional | `function` | none | Maps `rawData` to `LineChartCardData` |
| `timelineOptions` | Optional | `TimelineOption[]` | none | Timeline range buttons |
| `timeline` | Optional | `string` | none | Controlled active timeline value |
| `defaultTimeline` | Optional | `string` | `'5m'` | Initial timeline when uncontrolled |
| `onTimelineChange` | Optional | `function` | none | Called when the user selects a new timeline range |
| `title` | Optional | `string` | none | Chart title in the card header |
| `titleExtra` | Optional | `ReactNode` | none | Node rendered inline beside the title — use for a secondary label or unit badge |
| `headerAction` | Optional | `ReactNode` | none | Node rendered at the trailing edge of the header row — use for action buttons such as an expand toggle |
| `detailLegends` | Optional | `boolean` | `false` | When `true`, shows detailed legends below the title |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state |
| `shouldResetZoom` | Optional | `boolean` | `true` | When `true`, resets chart zoom when the timeline changes |
| `minHeight` | Optional | `number` | `350` | Minimum chart body height in pixels |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Basic usage

```tsx
<LineChartCard
  title="Temperature"
  data={chartData}
  timelineOptions={[
    { label: '5m', value: '5m' },
    { label: '1h', value: '1h' },
    { label: '24h', value: '24h' },
  ]}
  defaultTimeline="1h"
/>
```

#### With data adapter

```tsx
<LineChartCard
  title="Power Consumption"
  rawData={rawStats}
  dataAdapter={(raw) => processStatsToChartData(raw)}
  timelineOptions={timelineOptions}
  defaultTimeline="24h"
  isLoading={isLoading}
/>
```

#### Styling

- `.mdk-line-chart-card`: Root element
- `.mdk-line-chart-card__legends`: Detail legends container

### `PowerModeTimelineChart`

Mining-specific wrapper around [`TimelineChart`](#timelinechart). Use `TimelineChart` directly when you supply custom row labels and segment data.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `PowerModeTimelineEntry[]` | `[]` | Historical power mode segments for `TimelineChart` |
| `dataUpdates` | Optional | `PowerModeTimelineEntry[]` | `[]` | New segments merged into the chart when updates arrive |
| `timezone` | Optional | `string` | `'UTC'` | IANA timezone for segment timestamps |
| `title` | Optional | `string` | `'Power Mode Timeline'` | Chart title passed to the inner timeline |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state inside the chart card |

#### `PowerModeTimelineEntry` type

```tsx
type PowerModeTimelineEntry = {
  ts?: number
  power_mode_group_aggr?: Record<string, string>
  status_group_aggr?: Record<string, string>
}
```

#### Basic usage

```tsx
<PowerModeTimelineChart
  data={powerModeHistory}
  timezone="America/New_York"
  isLoading={isLoading}
/>
```

#### With real-time updates

```tsx
<PowerModeTimelineChart
  data={powerModeHistory}
  dataUpdates={realtimeUpdates}
  timezone={userTimezone}
/>
```

### `TimelineChart`

Gantt-like timeline for multiple rows. `labels` lists row names (Y axis). Each dataset groups colored segments; each segment's `y` must 
match one of `labels`, and `x` is `[startMs, endMs]`.

#### Import

```tsx
```

#### Empty initial state

Use `emptyTimelineChartData` (`{ labels: [], datasets: [] }`) for the first render before live timeline data arrives. Pair with `isLoading` while fetching if needed.

```tsx
<TimelineChart
  initialData={emptyTimelineChartData}
  title="Miner state"
  isLoading={isLoading}
/>
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `initialData` | Required | `TimelineChartData` | none | Row labels and segment datasets shown on first render |
| `newData` | Optional | `TimelineChartData` | none | Extra labels and datasets merged when `skipUpdates` is false |
| `skipUpdates` | Optional | `boolean` | `false` | When `true`, ignores `newData` |
| `range` | Optional | `ChartRange` | none | Visible time window (`min` / `max` as `Date` or epoch ms) |
| `axisTitleText` | Optional | `AxisTitleText` | `{ x: 'Time', y: '' }` | Axis title strings |
| `isLoading` | Optional | `boolean` | `false` | Shows loading state inside `ChartContainer` |
| `title` | Optional | `string` | none | Chart title passed to `ChartContainer` |
| `height` | Optional | `number \| string` | none | Root height (CSS length or pixels) |

#### `TimelineChartData` type

See also [Timeline chart types](/reference/app-toolkit/ui-devkit/types#timeline-chart-types).

```tsx
type TimelineChartDataPoint = {
  x: [number, number] // segment start and end (epoch ms)
  y: string | undefined // must match an entry in labels
}

type TimelineChartDataset = {
  label: string
  data: TimelineChartDataPoint[]
  borderColor?: string[]
  backgroundColor?: string[]
  color?: string
}

type TimelineChartData = {
  labels: string[]
  datasets: TimelineChartDataset[]
}

type ChartRange = {
  min: Date | number
  max: Date | number
}
```

#### Basic usage

```tsx
const start = Date.now() - 2 * 60 * 60 * 1000

<TimelineChart
  initialData={{
    labels: ['Task A', 'Task B', 'Task C'],
    datasets: [
      {
        label: 'In Progress',
        color: '#22afff',
        data: [
          { x: [start, start + 30 * 60 * 1000], y: 'Task A' },
          { x: [start + 20 * 60 * 1000, start + 50 * 60 * 1000], y: 'Task B' },
        ],
      },
      {
        label: 'Completed',
        color: '#72f59e',
        data: [{ x: [start + 30 * 60 * 1000, start + 60 * 60 * 1000], y: 'Task A' }],
      },
    ],
  }}
  title="Project timeline"
  axisTitleText={{ x: 'Time', y: 'Tasks' }}
/>
```

#### With `newData` updates

```tsx
<TimelineChart
  initialData={baseline}
  newData={streamingUpdate}
  skipUpdates={false}
/>
```

When `newData` arrives, labels are unioned and datasets are appended. Set `skipUpdates` to keep only `initialData`.

#### Styling

- `.mdk-timeline-chart`: Root element
- `.mdk-timeline-chart__loading`: Loading container
- `.mdk-timeline-chart__legend`, `.mdk-timeline-chart__legend-item`, `.mdk-timeline-chart__legend-color`, `.mdk-timeline-chart__legend-label`: Legend row
- `.mdk-timeline-chart__visualization`: Scrollable chart body

### `WidgetTopRow`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `string` | none | Widget title shown in the header row |
| `power` | Optional | `number` | none | Power consumption value; formatted with `unit` when set |
| `unit` | Optional | `string` | none | Unit suffix for `power` (for example `kW`) |
| `statsErrorMessage` | Optional | `string \| ErrorWithTimestamp[]` | none | Replaces the power readout with `-` and a `formatErrors` tooltip |
| `alarms` | Optional | `object` | none | Map keyed by `liquidAlarms`, `leakageAlarms`, `pressureAlarms`, `otherAlarms`; values are [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) arrays |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Composition

`WidgetTopRow` renders the title, then four fixed alarm slots in order (liquid, leakage, pressure, other), then the power readout. Each slot reads the matching `alarms` key from the table below; when the array is missing or empty, that slot is not shown. Tooltip text lists each [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) with timestamp and description.

| Slot label | `alarms` key | Icon role |
|------------|--------------|-----------|
| Liquid | `liquidAlarms` | Temperature / liquid alarm |
| Leakage | `leakageAlarms` | Fluid / leakage alarm |
| Pressure | `pressureAlarms` | Pressure alarm |
| Other | `otherAlarms` | Other alarm |

When `power` and `unit` are set and `statsErrorMessage` is unset, the power label shows `formatNumber(unitToKilo(power))` followed by the unit in a nested `<span>`.

#### Basic usage

```tsx
<WidgetTopRow
  title="Container A1"
  power={125000}
  unit="kW"
/>
```

#### More examples

Each `alarms` key must match the table above (`liquidAlarms`, `leakageAlarms`, `pressureAlarms`, `otherAlarms`), not generic names like `temperature`. Items use the [`Alert`](/reference/app-toolkit/ui-devkit/types#alert) shape.

```tsx
<WidgetTopRow
  title="Container A1"
  power={125000}
  unit="kW"
  alarms={{
    liquidAlarms: [
      {
        severity: 'critical',
        createdAt: Date.now(),
        name: 'Al.Liq.#1',
        description: '1st Liquid Alarm',
      },
    ],
    leakageAlarms: [
      {
        severity: 'high',
        createdAt: Date.now(),
        name: 'Al.Lkg.#1',
        description: '1st Leakage Alarm',
      },
    ],
    pressureAlarms: [
      {
        severity: 'medium',
        createdAt: Date.now(),
        name: 'Al.Prs.#1',
        description: '1st Pressure Alarm',
      },
    ],
    otherAlarms: [
      {
        severity: 'low',
        createdAt: Date.now(),
        name: 'Al.Oth.#1',
        description: '1st Other Alarm',
      },
    ],
  }}
/>
```

</Accordion>
  <Accordion title="With stats error">

When `statsErrorMessage` is set, the power label is hidden and `-` is shown with a tooltip built from `formatErrors` (string or [`ErrorWithTimestamp`](/reference/app-toolkit/ui-devkit/types#errorwithtimestamp) array).

```tsx
<WidgetTopRow title="Container A1" statsErrorMessage="Example Error Message" />
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-widget-top-row`: Root element
- `.mdk-widget-top-row__inner`: Inner container
- `.mdk-widget-top-row__title`: Title text
- `.mdk-widget-top-row__alarm-info-icon`: Alarm slot icon (tooltip trigger)
- `.mdk-widget-top-row__alarm-info-title`: Alarm tooltip heading (`{slot} issues`)
- `.mdk-widget-top-row__power`: Power display or error placeholder

## Related hooks

The following adapter and component hooks supply data to the chart components on this page.

| Hook | Supplies |
|------|---------|
| [`useHashrateChartData`](/reference/app-toolkit/hooks/data#usehashratechartdata) | `ChartCardData` combining site and per-pool hashrate series for `<LineChartCard />` |
| [`useSiteConsumptionChartData`](/reference/app-toolkit/hooks/data#usesiteconsumptionchartdata) | Consumption `ChartCardData` in MW for `<LineChartCard />` |
| [`usePowerModeTimelineData`](/reference/app-toolkit/hooks/data#usepowermodetimelinedata) | `PowerModeTimelineEntry[]` for `<PowerModeTimelineChart />` |
| [`useChartDataCheck`](/reference/app-toolkit/hooks/components#usechartdatacheck) | Empty-state guard used by `<ChartWrapper />` to decide when to render the no-data placeholder |

# Feeds (/reference/ui/react/foundation/dashboard/feeds)

Feeds surface streams of operational events on the dashboard. `ActiveIncidentsCard` renders the current alerts feed; `LogsCard` (from `@tetherto/mdk-react-devkit/core`) renders activity and event logs.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

### `ActiveIncidentsCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Optional | `string` | `'Active Alerts'` | Card header label |
| `items` | Optional | `TIncidentRowProps[]` | `[]` | Array of incident items to display |
| `isLoading` | Optional | `boolean` | `false` | Show skeleton loading state |
| `skeletonRows` | Optional | `number` | `4` | Number of skeleton rows when loading |
| `emptyMessage` | Required | `string` | none | Message when no incidents |
| `onItemClick` | Required | `function` | none | Callback when an incident row is clicked |
| `className` | Optional | `string` | none | Additional CSS class |

#### `TIncidentRowProps`

Each incident item requires these properties:

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `id` | Optional | `string` | none | Unique incident identifier |
| `title` | Required | `string` | none | Incident title |
| `subtitle` | Required | `string` | none | Secondary text (e.g., timestamp or source) |
| `body` | Required | `string` | none | Incident description |
| `severity` | Required | `'critical' \| none | 'high' \| 'medium'` | Severity level |

#### Basic usage

```tsx
<ActiveIncidentsCard
  label="Active Alerts"
  items={[
    {
      id: '1',
      title: 'High Temperature Alert',
      subtitle: 'Miner #A2341',
      body: 'Temperature exceeded 85°C threshold',
      severity: 'critical',
    },
    {
      id: '2',
      title: 'Network Connection Lost',
      subtitle: 'Pool: pool.example.com',
      body: 'Connection timeout after 30 seconds',
      severity: 'high',
    },
  ]}
  onItemClick={(id) => console.log('Clicked:', id)}
/>
```

#### Loading state

```tsx
<ActiveIncidentsCard label="Active Alerts" isLoading skeletonRows={4} />
```

#### Empty state

```tsx
<ActiveIncidentsCard
  label="Active Alerts"
  items={[]}
  emptyMessage="No active incidents"
/>
```

#### Styling

- `.mdk-active-incidents-card`: Root element
- `.mdk-active-incidents-card__header`: Header container
- `.mdk-active-incidents-card__label`: Header label text
- `.mdk-active-incidents-card__list`: Incidents list container
- `.mdk-active-incidents-card__row`: Individual incident row
- `.mdk-active-incidents-card__row--clickable`: Clickable row modifier
- `.mdk-active-incidents-card__row-title`: Incident title
- `.mdk-active-incidents-card__row-subtitle`: Incident subtitle
- `.mdk-active-incidents-card__row-body`: Incident body text
- `.mdk-active-incidents-card__empty`: Empty state container
- `.mdk-active-incidents-card__skeleton-container`: Loading skeleton container

### `LogsCard`

[`LogsCard`](/reference/ui/react/core/components/logs#logscard) is a `@tetherto/mdk-react-devkit/core` component used on the dashboard to render paginated activity and event log feeds..

Import from `@tetherto/mdk-react-devkit/core`:

```tsx
```

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useActiveIncidents`](/reference/app-toolkit/hooks/data#useactiveincidents) | Returns `IncidentRow[]` ready for `<ActiveIncidentsCard items={...} />` |

## Next steps

For past alerts to pair with the active incidents feed, see [`HistoricalAlerts`](/reference/ui/react/foundation/alerts#historicalalerts).

# Stats (/reference/ui/react/foundation/dashboard/stats)

Stat widgets are the compact, at-a-glance cards that line the dashboard. They summarize container health, pool configuration, liquid supply, tanks, miner roll-ups, and export controls.

For the persistent app header bar components (HeaderStatsBar, HeaderConsumptionBox, etc.) see [Settings › Header controls › Header items](/reference/ui/react/foundation/settings/header-controls/header-items).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- Most widgets expect a container [`Device`](/reference/app-toolkit/ui-devkit/types#device) record; read the individual Props sections for field shapes
- In TypeScript, import the type from the foundation barrel: `import type { Device } from '@tetherto/mdk-react-devkit/foundation'`. Snippet fixtures may be plain objects that satisfy `Device` without an import

## Supported widgets

| Scope | Components |
|-------|------------|
| All vendors | [`MinersSummaryBox`](./generic-widgets#minerssummarybox), [`PoolDetailsCard`](./generic-widgets#pooldetailscard), [`PoolDetailsPopover`](./generic-widgets#pooldetailspopover), [`StatsExport`](./generic-widgets#statsexport), [`SupplyLiquidBox`](./generic-widgets#supplyliquidbox), [`TanksBox`](./generic-widgets#tanksbox) |
| Bitmain Immersion | [`BitMainImmersionSummaryBox`](./bitmain#bitmainimmersionsummarybox) |
| MicroBT | [`MicroBTWidgetBox`](./microbt#microbtwidgetbox) |

## Widget groups

- [Generic widgets](./generic-widgets): vendor-agnostic summary cards for containers, pool details, and data export
- [Bitmain](./bitmain): summary widget for Bitmain Immersion containers
- [MicroBT](./microbt): summary widget for MicroBT containers

## All stat components

# Bitmain (/reference/ui/react/foundation/dashboard/stats/bitmain)

Summary widget for Bitmain Immersion containers. For other vendor widgets see [MicroBT](/reference/ui/react/foundation/dashboard/stats/microbt). For vendor-agnostic cards see [Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A [`Device`](/reference/app-toolkit/ui-devkit/types#device) record of type `bitmain-immersion`

## Components

### `BitMainImmersionSummaryBox`

{/*Returns `null` when `data` is not provided. Reads pump flags (`second_pump1`, `second_pump2`, `one_pump`) and temperature fields from
`container_specific_stats`.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `Device` | none | Bitmain immersion container device record; returns `null` when omitted |
| `containerSettings` | Optional | `BitMainImmersionSummaryBoxContainerSettings \| null` | `null` | Custom temperature thresholds passed to immersion color helpers |

#### `BitMainImmersionSummaryBoxContainerSettings` type

```tsx
type BitMainImmersionSummaryBoxContainerSettings = {
  thresholds?: Record<string, unknown>
}
```

```tsx

const immersionContainer: Device = {
  id: 'bitmain-immersion-1',
  type: 'bitmain-immersion',
  last: {
    snap: {
      stats: {
        status: 'running',
        container_specific: {
          second_supply_temp1: 40,
          second_supply_temp2: 41,
          primary_supply_temp: 42,
          second_pump1: true,
          second_pump2: true,
          second_pump1_fault: false,
          second_pump2_fault: false,
          one_pump: true,
        },
      },
    },
  },
}

const customThresholds = {
  oilTemperature: {
    COLD: 30,
    LIGHT_WARM: 34,
    WARM: 38,
    HOT: 42,
    SUPERHOT: 45,
  },
}
```

#### Basic usage

```tsx
<BitMainImmersionSummaryBox data={immersionContainer} />
```

#### More examples

```tsx
<BitMainImmersionSummaryBox
  data={immersionContainer}
  containerSettings={{ thresholds: customThresholds }}
/>
```

</Accordion>
  <Accordion title="Oil pump fault">

When `second_pump1_fault` is `true`, oil pump #1 shows an `Error` indicator while pump #2 can remain `Running`.

```tsx

const immersionWithPump1Fault: Device = {
  id: 'bitmain-immersion-1',
  type: 'bitmain-immersion',
  last: {
    snap: {
      stats: {
        status: 'running',
        container_specific: {
          second_pump1: true,
          second_pump2: true,
          second_pump1_fault: true,
          one_pump: true,
          primary_supply_temp: 42,
          second_supply_temp1: 40,
          second_supply_temp2: 41,
        },
      },
    },
  },
}

<BitMainImmersionSummaryBox data={immersionWithPump1Fault} />
```

</Accordion>
</Accordions>

#### Composition

- Oil pump #1 and oil pump #2 indicators derived from `second_pump1` / `second_pump2` and their `_fault` flags
- Water pump indicator derived from `one_pump`
- Three `SingleStatCard`s for primary supply temp, secondary supply Temp1, and secondary supply Temp2, each colored and flashed via `getImmersionTemperatureColor` and `shouldImmersionTemperatureFlash`

#### Styling

- `.mining-sdk-bitmain-immersion-summary-box`: Root element
- `.mining-sdk-bitmain-immersion-summary-box__pumps`: Pumps row
- `.mining-sdk-bitmain-immersion-summary-box__pump`: Single pump cell
- `.mining-sdk-bitmain-immersion-summary-box__pump-title`: Pump label text
- `.mining-sdk-bitmain-immersion-summary-box__liquid-stats`: Liquid stat cards row

# Generic widgets (/reference/ui/react/foundation/dashboard/stats/generic-widgets)

Widgets that work with any container vendor and pool configuration. For header bar controls see [Header items](/reference/ui/react/foundation/settings/header-controls/header-items). For vendor-specific summary boxes see [Bitmain](/reference/ui/react/foundation/dashboard/stats/bitmain) and [MicroBT](/reference/ui/react/foundation/dashboard/stats/microbt).

## Prerequisites

## Components

### `MinersSummaryBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `params` | Required | `MinersSummaryParam[]` | none | Label-value pairs rendered in a two-column grid |
| `className` | Optional | `string` | none | Additional CSS class |

#### `MinersSummaryParam` type

```tsx
type MinersSummaryParam = {
  label: string   // Parameter name
  value: string   // Pre-formatted display value (including units)
}
```

#### Basic usage

```tsx
<MinersSummaryBox
  params={[
    { label: 'Efficiency', value: '32.5 W/TH/S' },
    { label: 'Hash Rate', value: '1.24 PH/s' },
    { label: 'Max Temp', value: '72 °C' },
    { label: 'Avg Temp', value: '65 °C' },
  ]}
/>
```

#### Notes

- Values must be pre-formatted strings (the component does not format data)
- Text size automatically adjusts for long values (>12 or >15 characters)

#### Styling

- `.mdk-miners-summary-box`: Root element
- `.mdk-miners-summary-box__param`: Individual parameter row
- `.mdk-miners-summary-box__label`: Parameter label
- `.mdk-miners-summary-box__label--small`: Smaller text for long values
- `.mdk-miners-summary-box__label--tiny`: Tiny text for very long values
- `.mdk-miners-summary-box__value`: Parameter value

### `PoolDetailsCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `details` | Required | `PoolDetailItem[]` | none | Pool metadata rows; an empty array shows "No data available" |
| `label` | Optional | `string` | none | Card header label |
| `underline` | Optional | `boolean` | `false` | Underline the header |
| `className` | Optional | `string` | none | Additional CSS class |

#### `PoolDetailItem` type

```tsx
type PoolDetailItem = {
  title: string
  value?: string | number
}
```

#### Basic usage

```tsx
<PoolDetailsCard
  label="Pool Configuration"
  details={[
    { title: 'Pool URL', value: 'stratum+tcp://pool.example.com:3333' },
    { title: 'Worker', value: 'worker001' },
    { title: 'Algorithm', value: 'SHA-256' },
  ]}
/>
```

#### More examples

```tsx
<PoolDetailsCard
  label="Primary Pool"
  underline
  details={[
    { title: 'URL', value: 'stratum://pool1.example.com:3333' },
    { title: 'Status', value: 'Active' },
    { title: 'Hashrate', value: '95.2 TH/s' },
    { title: 'Accepted', value: 12847 },
    { title: 'Rejected', value: 23 },
  ]}
/>
```

</Accordion>
  <Accordion title="Empty state">

When `details` is an empty array, displays "No data available":

```tsx
<PoolDetailsCard
  label="Backup Pool"
  details={[]}
/>
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-pool-details-card`: Root element
- `.mdk-pool-details-card__header`: Header container
- `.mdk-pool-details-card__header--underline`: Underlined header modifier
- `.mdk-pool-details-card__label`: Header label text
- `.mdk-pool-details-card__list`: Details list container
- `.mdk-pool-details-card__item`: Individual detail row
- `.mdk-pool-details-card__item-title`: Detail title
- `.mdk-pool-details-card__item-value`: Detail value
- `.mdk-pool-details-card__empty`: Empty state container

### `PoolDetailsPopover`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `details` | Required | `PoolDetailItem[]` | none | Rows rendered inside the dialog via `PoolDetailsCard` |
| `title` | Optional | `string` | none | Dialog title |
| `description` | Optional | `string` | none | Dialog description |
| `triggerLabel` | Optional | `string` | none | Trigger button label |
| `disabled` | Optional | `boolean` | `false` | Disable the trigger button |
| `className` | Optional | `string` | none | Additional CSS class |

#### Basic usage

```tsx
<PoolDetailsPopover
  triggerLabel="View Pool Details"
  title="Primary Pool"
  details={[
    { title: 'URL', value: 'stratum://pool.example.com:3333' },
    { title: 'Worker', value: 'worker001' },
    { title: 'Status', value: 'Active' },
  ]}
/>
```

#### More examples

```tsx
<PoolDetailsPopover
  triggerLabel="Pool Info"
  title="Pool Configuration"
  description="Current mining pool settings"
  details={poolDetails}
/>
```

</Accordion>
  <Accordion title="Disabled state">

```tsx
<PoolDetailsPopover
  triggerLabel="View Details"
  details={[]}
  disabled={!hasPoolData}
/>
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-pool-details-popover`: Root element
- `.mdk-pool-details-popover__body`: Dialog body container

### `StatsExport`

{/*Demo nav lists this as "Stats Export Dropdown"; the code export is `StatsExport`.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `onCsvExport` | Required | `function` | none | Called when CSV is selected; awaited while a spinner is shown |
| `onJsonExport` | Required | `function` | none | Called when JSON is selected; awaited while a spinner is shown |
| `disabled` | Optional | `boolean` | `false` | Disable the trigger button |
| `showLabel` | Optional | `boolean` | `false` | When `false` (default), shows the "Export" text label next to the icon; when `true`, hides the label (icon-only trigger) |

`fetchStats`, `downloadCsv`, and `downloadJson` are **app-level** helpers—you implement them (or call your API) inside `onCsvExport` and `onJsonExport`. They are not exported from `@tetherto/mdk-react-devkit`.

#### Basic usage

```tsx
<StatsExport
  onCsvExport={async () => {
    const data = await yourApp.fetchDashboardStats()
    yourApp.downloadCsv(data, 'mining-stats.csv')
  }}
  onJsonExport={async () => {
    const data = await yourApp.fetchDashboardStats()
    yourApp.downloadJson(data, 'mining-stats.json')
  }}
/>
```

#### More examples

```tsx
<StatsExport
  disabled={!hasData}
  onCsvExport={handleCsvExport}
  onJsonExport={handleJsonExport}
/>
```

</Accordion>
  <Accordion title="With loading state">

The component automatically shows a loading spinner during export operations:

```tsx
<StatsExport
  onCsvExport={async () => {
    await generateAndDownloadCsv()
  }}
  onJsonExport={async () => {
    await generateAndDownloadJson()
  }}
/>
```

</Accordion>
  <Accordion title="Export formats">

The dropdown provides two export options:

1. **CSV**: Comma-separated values for spreadsheet applications
2. **JSON**: JavaScript Object Notation for programmatic use

</Accordion>
</Accordions>

#### Styling

- `.stats-export__button`: Trigger button
- `.stats-export__button--disabled`: Disabled state
- `.stats-export__label`: Button label text
- `.stats-export__divider`: Divider between icon and arrow
- `.stats-export__dropdown`: Dropdown menu container
- `.stats-export__item`: Dropdown menu item
- `.stats-export__item--bordered`: Item with bottom border

### `SupplyLiquidBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `Device` | none | Container device record with supply liquid snap stats |
| `containerSettings` | Optional | `SupplyLiquidBoxContainerSettings \| null` | `null` | Hydro threshold overrides (`waterTemperature`, `supplyLiquidPressure`) for color and flash |

#### `SupplyLiquidBoxContainerSettings` type

```tsx
type SupplyLiquidBoxContainerSettings = {
  thresholds?: Record<string, Record<string, number>>
}
```

Use hydro keys under `thresholds` (not snap stat names such as `supply_liquid_temp`).

```tsx

const containerDevice: Device = {
  id: 'bitmain-hydro-1',
  type: 'bitmain-hydro',
  last: {
    snap: {
      stats: {
        status: 'running',
        supply_liquid_temp: 35,
        supply_liquid_set_temp: 32,
        supply_liquid_pressure: 2.5,
      },
    },
  },
}
```

#### Basic usage

```tsx
<SupplyLiquidBox data={containerDevice} />
```

#### More examples

`containerSettings.thresholds` uses hydro keys `waterTemperature` and `supplyLiquidPressure`. Snap fields such as `supply_liquid_temp` on the device record are separate and are not threshold config keys.

```tsx
<SupplyLiquidBox
  data={containerDevice}
  containerSettings={{
    thresholds: {
      waterTemperature: {
        criticalLow: 21,
        alarmLow: 21,
        normal: 30,
        alarmHigh: 37,
        criticalHigh: 40,
      },
      supplyLiquidPressure: {
        criticalLow: 2,
        alarmLow: 2,
        normal: 2.3,
        alarmHigh: 3.5,
        criticalHigh: 4,
      },
    },
  }}
/>
```

</Accordion>
</Accordions>

#### Features

The component displays three `SingleStatCard` items:
- **Supply Liquid** / subtitle **Temp**: current liquid temperature
- **Supply Liquid** / subtitle **Set Temp**: target set temperature
- **Supply Liquid** / subtitle **Pressure**: current pressure

Each stat automatically shows color and flash indicators based on threshold settings.

#### Styling

- `.mdk-supply-liquid-box`: Root element
- `.mdk-supply-liquid-box__stats`: Stats container

### `TanksBox`

For the per-row primitive and standalone usage, see [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) on the containers page.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `TanksBoxData` | none | Oil pump, water pump, and pressure tank readings; renders nothing when omitted |

#### `TanksBoxData` type

```tsx
type Tank = {
  cold_temp_c: number
  enabled: boolean
  color?: string      // Visual indicator color
  flash?: boolean     // Enable flash animation
  tooltip?: string    // Tooltip text
}

type TanksBoxData = {
  oil_pump: Tank[]
  water_pump: { enabled: boolean }[]
  pressure: { value?: number; flash?: boolean; color?: string; tooltip?: string }[]
}
```

#### Composition

`TanksBox` maps each `oil_pump` entry to one [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) by array index:

```tsx
// Per-row mapping (index i):
oil_pump[i].enabled       -> oilPumpEnabled
oil_pump[i].cold_temp_c   -> temperature (always Celsius)
water_pump[i]?.enabled    -> waterPumpEnabled
pressure[i] ?? {}         -> pressure
oil_pump[i].{color,flash,tooltip} -> temperature cell hints
```

#### Basic usage

```tsx
<TanksBox
  data={{
    oil_pump: [
      { cold_temp_c: 45, enabled: true },
      { cold_temp_c: 42, enabled: true },
    ],
    water_pump: [
      { enabled: true },
      { enabled: false },
    ],
    pressure: [
      { value: 1.2 },
      { value: 1.1 },
    ],
  }}
/>
```

#### More examples

```tsx
<TanksBox
  data={{
    oil_pump: [
      { cold_temp_c: 85, enabled: true, color: 'red', flash: true, tooltip: 'High temp!' },
    ],
    water_pump: [{ enabled: true }],
    pressure: [{ value: 2.5, color: 'orange', flash: true }],
  }}
/>
```

</Accordion>
  <Accordion title="Multiple tanks">

```tsx
<TanksBox
  data={{
    oil_pump: [
      { cold_temp_c: 42, enabled: true },
      { cold_temp_c: 44, enabled: true },
      { cold_temp_c: 41, enabled: false },
    ],
    water_pump: [{ enabled: true }, { enabled: false }, { enabled: true }],
    pressure: [{ value: 1.1 }, { value: 1.3 }, {}],
  }}
/>
```

</Accordion>
  <Accordion title="With custom tooltips">

```tsx
<TanksBox
  data={{
    oil_pump: [
      { cold_temp_c: 42, enabled: true, tooltip: 'Within normal range' },
      {
        cold_temp_c: 55,
        enabled: true,
        tooltip: 'Approaching threshold – consider cooling',
      },
    ],
    water_pump: [{ enabled: true }, { enabled: true }],
    pressure: [{ value: 1.2 }, { value: 1.4, tooltip: 'Pressure slightly elevated' }],
  }}
/>
```

</Accordion>
  <Accordion title="Mixed pump states">

```tsx
<TanksBox
  data={{
    oil_pump: [
      { cold_temp_c: 43, enabled: true },
      { cold_temp_c: 44, enabled: false },
      { cold_temp_c: 42, enabled: true },
    ],
    water_pump: [{ enabled: false }, { enabled: true }, { enabled: false }],
    pressure: [{ value: 1.1 }, { value: 1.2 }, { value: 1.0 }],
  }}
/>
```

</Accordion>
  <Accordion title="No data">

When `data` is omitted, `TanksBox` returns `null` and renders nothing:

```tsx
<TanksBox />
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-tanks-box`: Root element
- Uses [`TankRow`](/reference/ui/react/foundation/operations/containers#tankrow) internally for each tank display

## Related hooks

The following adapter data hooks supply the live values consumed by the widgets on this page.

| Hook | Supplies |
|------|---------|
| [`useSiteHashrate`](/reference/app-toolkit/hooks/data#usesitehashrate) | Aggregate hashrate in PH/s for hashrate stat boxes |
| [`useSiteMinerCounts`](/reference/app-toolkit/hooks/data#usesiteminercounts) | Online, offline, and error miner counts |
| [`useSiteMinerStats`](/reference/app-toolkit/hooks/data#usesiteminerstats) | Live MOS total and realtime miner breakdown (stat-rtd) |
| [`useSiteEfficiency`](/reference/app-toolkit/hooks/data#usesiteefficiency) | W/TH/s efficiency value |
| [`useSiteConsumption`](/reference/app-toolkit/hooks/data#usesiteconsumption) | Latest site power consumption in MW |
| [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate pool worker counts and hashrate for pool summary cards |
| [`useHashrateChartData`](/reference/app-toolkit/hooks/data#usehashratechartdata) | Site + per-pool hashrate time-series for chart widgets |

# MicroBT (/reference/ui/react/foundation/dashboard/stats/microbt)

Summary widget for MicroBT containers. For other vendor widgets see [Bitmain](/reference/ui/react/foundation/dashboard/stats/bitmain). For vendor-agnostic cards see [Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets).

## Prerequisites

## Components

### `MicroBTWidgetBox`

{/*Returns `null` when `data` is not provided. The first tile is labelled `"Cicle Pump"` in the source (typo for `"Cycle Pump"`); the label is
intentionally mirrored here to match the rendered UI.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `Device` | none | MicroBT container device record; returns `null` when omitted |

```tsx

const microbtContainer: Device = {
  id: 'microbt-1',
  type: 'microbt',
  last: {
    snap: {
      stats: {
        status: 'running',
        container_specific: {
          cdu: {
            circulation_pump_running_status: 'running',
            cooling_fan_control: true,
          },
        },
      },
    },
  },
}
```

#### Basic usage

```tsx
<MicroBTWidgetBox data={microbtContainer} />
```

#### Indicators rendered

{/* Maintainer note: `Cicle Pump` is a known typo in foundation source (`micro-bt-widget-box.tsx`); docs mirror the UI string until product fixes the label. */}

The label **`Cicle Pump`** matches the rendered UI and foundation source (typo for "Cycle Pump"); keep documentation aligned until the component string is corrected in code.

- `Cicle Pump`: green `Running` when `cdu.circulation_pump_running_status` equals `CONTAINER_STATUS.RUNNING`, gray `Off` otherwise
- `Cooling Fan`: green `Running` when `cdu.cooling_fan_control` is truthy, red `Error` otherwise

#### Styling

- `.mdk-micro-bt-widget-box`: Root grid element
- `.mdk-micro-bt-widget-box__item`: Single indicator cell
- `.mdk-micro-bt-widget-box__title`: Indicator label text

# Inventory (/reference/ui/react/foundation/inventory)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Inventory components display historical device movement details. Pair with the [Operations centre](/reference/ui/react/foundation/operations) for full device-management context.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Components

### `MovementDetailsModal`

Modal showing the details of a historical device movement — the device summary plus the origin → destination transition of location and status. All three props are optional (the component renders `null` when `movement` is absent), so you can gate the modal on a selection without separate conditional rendering:

1. **Device details** (`movement.device`): code, type, site, container, serial number, MAC address.
2. **Movement preview**: side-by-side origin and destination panels showing location and status with colour-coded badges.
3. **Comments** (`movement.comments`): optional free-text or node rendered below the movement panels.

The component does no data fetching — the parent is responsible for passing the selected movement.

#### Import

```tsx
  MovementDetailsModalProps,
  MovementData,
  MovementDevice,
} from '@tetherto/mdk-react-devkit/foundation'
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isOpen` | Optional | `boolean` | `false` | When `true`, the modal is visible |
| `onClose` | Optional | `function` | none | Called when the user dismisses the modal |
| `movement` | Optional | `MovementData` | none | Movement record to display; modal renders `null` when absent |

#### `MovementData` type

```tsx
type MovementData = {
  origin: string
  destination: string
  previousStatus: string
  newStatus: string
  device?: MovementDevice
  comments?: ReactNode
}
```

#### `MovementDevice` type

```tsx
type MovementDevice = Partial<{
  code: string
  tags: string[]
  type: string
  info: Partial<{
    subType: string
    site: string
    container: string
    serialNum: string
    macAddress: string
  }>
}>
```

#### Basic usage

```tsx

function InventoryTable({ movements }) {
  const [selected, setSelected] = useState<MovementData | null>(null)

return (
    <>
      {/* … table that calls setSelected(row.movement) on row click … */}

<MovementDetailsModal
        isOpen={selected !== null}
        movement={selected ?? undefined}
        onClose={() => setSelected(null)}
      />
    </>
  )
}
```

#### Behavior notes

- `movement` is the primary gate: when it is absent the component returns `null` and nothing is mounted, regardless of `isOpen`. `isOpen` only controls visibility once a `movement` is provided
- Location and status badge colours come from the MDK design-token maps (`MINER_LOCATION_*`, `MINER_STATUS_*`)
- The modal title is fixed: **"Historical Device Update"**

## Next steps

- For device-level details, see the [Operations centre](/reference/ui/react/foundation/operations) pages

# Operations centre (/reference/ui/react/foundation/operations)

Domain-specific components for Bitcoin mining operations monitoring and management.

## Next steps

- **[@tetherto/mdk-react-devkit/core components](/reference/ui/react/core/components)**: Base components used by the operations centre (Cards, Charts, Tables)
- **[Settings](/reference/ui/react/foundation/settings)**: Administrative settings UI for feature flags, user management, and configuration
- **[Hooks](/reference/app-toolkit/hooks/components#charts)**: React hooks for real-time monitoring data

# Container components (/reference/ui/react/foundation/operations/containers)

Components for viewing, navigating, and controlling Bitcoin mining containers, racks, and associated hardware.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Container subpages

Dedicated pages for the socket primitive and vendor-specific UI:

- [Socket](/reference/ui/react/foundation/operations/containers/socket) — PDU socket tile primitive
- [Bitdeer](/reference/ui/react/foundation/operations/containers/bitdeer)
- [Bitmain](/reference/ui/react/foundation/operations/containers/bitmain)
- [Bitmain Immersion](/reference/ui/react/foundation/operations/containers/bitmain-immersion)
- [MicroBT](/reference/ui/react/foundation/operations/containers/microbt)

## All container components

Every component in this category, including shared chrome and vendor-specific widgets.

## Shared components

Container-authoring primitives that work with any container device record. Use these as building blocks inside the vendor-specific pages above, or 
when composing your own container view. For the PDU socket tile, see the dedicated [Socket](/reference/ui/react/foundation/operations/containers/socket) page.

### `EnabledDisableToggle`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `value` | Required | `unknown` | none | Current toggle value; boolean enables switch display |
| `tankNumber` | Optional | `number \| string` | required | Tank identifier; empty falls back to "Air Exhaust System" |
| `isButtonDisabled` | Required | `boolean` | none | Disables both Enable and Disable buttons |
| `isOffline` | Required | `boolean` | none | Marks container offline and disables controls |
| `onToggle` | Required | `function` | none | Fires when user clicks Enable or Disable |

#### Basic usage

```tsx
<EnabledDisableToggle
  value={tank.circulationEnabled}
  tankNumber={1}
  isButtonDisabled={false}
  isOffline={false}
  onToggle={({ tankNumber, isOn }) => submitToggle(tankNumber, isOn)}
/>
```

#### More examples

```tsx
<EnabledDisableToggle
  value={exhaustEnabled}
  tankNumber=""
  isButtonDisabled={false}
  isOffline={false}
  onToggle={({ isOn }) => setExhaust(isOn)}
/>
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-enabled-disable-toggle`: Root element
- `.mdk-enabled-disable-toggle__toggle`: Label and `Switch` row shown when `value` is boolean

### `GenericDataBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `DataItem[]` | `[]` | Rows to render as label, value, and units |
| `fallbackValue` | Optional | `unknown` | none | Value used when a row's `value` is undefined |

#### `DataItem` type

```tsx
type DataItem = {
  label?: string
  value?: unknown
  units?: string
  unit?: string          // Alternative unit field
  isHighlighted?: boolean
  color?: string
  flash?: boolean
}
```

#### Basic usage

```tsx
<GenericDataBox
  data={[
    { label: 'Temperature', value: 45, units: '°C' },
    { label: 'Pressure', value: 2.5, units: 'bar', isHighlighted: true },
    { label: 'Status', value: 'Running', color: 'green' },
  ]}
/>
```

#### Styling

- `.mdk-generic-data-box`: Root element
- Renders each row through `DataRow`

### `TankRow`

`TankRow` is composed by [`TanksBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#tanksbox) for dashboard tank status; use `TankRow` 
directly when building custom container layouts.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Required | `string` | none | Row label shown on the left |
| `temperature` | Required | `number` | none | Temperature reading displayed in the row |
| `unit` | Required | `string` | none | Unit suffix appended to the temperature |
| `oilPumpEnabled` | Required | `boolean` | none | Drives the oil pump indicator state |
| `waterPumpEnabled` | Required | `boolean` | none | Drives the water pump indicator state |
| `color` | Required | `string` | none | Text color for temperature and pressure cells; empty string uses default theme colors |
| `pressure` | Required | `TankRowPressure` | none | [`Pressure readout object`](#tankrowpressure-type); block not rendered when `value` is omitted |
| `flash` | Optional | `boolean` | none | Enables flash animation on the temp cell |
| `tooltip` | Optional | `string` | none | Overrides the default temperature tooltip |

#### `TankRowPressure` type

```tsx
type TankRowPressure = Partial<{
  value: number
  flash: boolean
  color: string
  tooltip: string
}>
```

#### Basic usage

```tsx
<TankRow
  label="Tank 1"
  temperature={45}
  unit="°C"
  oilPumpEnabled
  waterPumpEnabled={false}
  color=""
  pressure={{ value: 1.2 }}
/>
```

#### More examples

```tsx
<TankRow
  label="Tank 1"
  temperature={42}
  unit="°C"
  oilPumpEnabled
  waterPumpEnabled
  color=""
  pressure={{}}
/>
```

</Accordion>
  <Accordion title="With alert state">

```tsx
<TankRow
  label="Tank 2"
  temperature={82}
  unit="°C"
  oilPumpEnabled
  waterPumpEnabled
  color="red"
  flash
  tooltip="Oil temperature above threshold"
  pressure={{ value: 2.4, color: 'orange', flash: true }}
/>
```

</Accordion>
</Accordions>

#### Styling

- `.mdk-tanks-box__row`: Root row element
- `.mdk-tanks-box__params`: Temperature and pressure group
- `.mdk-tanks-box__param` / `__param-label` / `__param-value`: Individual readouts
- `.mdk-tanks-box__pump-statuses`: Pump indicator group
- `.mdk-tanks-box__pump-status` / `__pump-status-title`: Per-pump indicator

### `ContainerFanLegend`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `index` | Optional | `number \| null` | none | Fan number shown in the badge |
| `enabled` | Optional | `boolean` | `false` | Renders on/off styling and icon color |
| `className` | Optional | `string` | none | Additional CSS class on the root element |

#### Basic usage

```tsx
<ContainerFanLegend index={1} enabled />
<ContainerFanLegend index={2} enabled={false} />
```

#### Styling

- `.mdk-container-fan-legend`: Root element
- `.mdk-container-fan-legend--on` / `--off`: On/off state modifier
- `.mdk-container-fan-legend__number`: Fan number badge
- `.mdk-container-fan-legend__icon` / `--on` / `--off`: Fan icon container

### `ContainerFansCard`

{/*`fansData` items reuse the `PumpItem` type from `PumpBox`. The component renders `fan.index + 1`, so pass zero-based indexes.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `fansData` | Required | `PumpItem[]` | none | Fan entries; returns `null` when omitted |

#### `PumpItem` type

```tsx
type PumpItem = {
  enabled?: boolean
  index: number
}
```

#### Basic usage

```tsx
<ContainerFansCard
  fansData={[
    { enabled: true, index: 0 },
    { enabled: false, index: 1 },
    { enabled: true, index: 2 },
  ]}
/>
```

#### Styling

- `.mdk-container-fans-card`: Root grid element
- Renders one `ContainerFanLegend` per entry

### `DryCooler`

{/*`data` is typed as `UnknownRecord`. The component reads `container_specific_stats.cooling_system.{dry_cooler, oil_pump, water_pump}` internally.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `UnknownRecord` | none | Container device record with cooling system stats |

```tsx
const containerDevice = {
  container_specific_stats: {
    cooling_system: {
      dry_cooler: [{ index: 0, enabled: true, fans: [{ enabled: true, index: 0 }] }],
      oil_pump: [{ enabled: true, index: 0 }],
      water_pump: [{ enabled: true, index: 0 }],
    },
  },
}
```

#### Basic usage

```tsx
<DryCooler data={containerDevice} />
```

#### Expected data shape

The component reads the following path from `data`:

```tsx
// data.container_specific_stats.cooling_system
{
  dry_cooler: [
    { index: 0, enabled: true, fans: [{ enabled: true, index: 0 }] },
    { index: 1, enabled: false, fans: [] },
  ],
  oil_pump:   [{ enabled: true, index: 0 }, { enabled: false, index: 1 }],
  water_pump: [{ enabled: true, index: 0 }, { enabled: true,  index: 1 }],
}
```

#### Styling

- `.mdk-dry-cooler`: Root element
- `.mdk-dry-cooler__segment`: Per-cooler group
- `.mdk-dry-cooler__card`: Cooler card with status and fans
- `.mdk-dry-cooler__status`: Title and indicator row
- `.mdk-dry-cooler__title`: Cooler title
- `.mdk-dry-cooler__pumps`: Oil and water pump column

### `PumpBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `pumpTitle` | Required | `string` | none | Pump label prefix (e.g. `"Oil"`, `"Water"`) |
| `pumpItem` | Required | `PumpItem` | none | Pump entry; returns `null` without a boolean `enabled` |

#### `PumpItem` type

```tsx
type PumpItem = {
  enabled?: boolean
  index: number        // zero-based; shown as index + 1
}
```

#### Basic usage

```tsx
<PumpBox pumpTitle="Oil" pumpItem={{ enabled: true, index: 0 }} />
<PumpBox pumpTitle="Water" pumpItem={{ enabled: false, index: 1 }} />
```

#### Styling

- `.mdk-pump-box`: Root element
- `.mdk-pump-box__status`: Title and indicator row
- `.mdk-pump-box__title`: Pump title text

## Next steps

- For browsing containers, racks, and miners, see the [device explorer](/reference/ui/react/foundation/operations/device-explorer).
- For container-level controls, see [`ContainerControlsBox`](/reference/ui/react/foundation/operations/details-view/controls#containercontrolsbox) 
on the Controls page.
- For container summary widgets that surface on the dashboard, see [`TanksBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#tanksbox), 
[`SupplyLiquidBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#supplyliquidbox), and 
[`MinersSummaryBox`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#minerssummarybox).

# Bitdeer container components (/reference/ui/react/foundation/operations/containers/bitdeer)

UI for Bitdeer containers. These components consume Bitdeer-shaped device records and render pump state, exhaust fan status, tank charts, and settings.

For primitives shared across all container vendors (`EnabledDisableToggle`, `DryCooler`, etc.), see the [Containers overview](/reference/ui/react/foundation/operations). The PDU socket tile has its own [Socket](/reference/ui/react/foundation/operations/containers/socket) page.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A Bitdeer container device record. The charts and pumps components read from `container_specific_stats.cooling_system`.

## Components

### `BitdeerPumps`

{/*Despite the plural name, this renders a single exhaust-fan status pulled from `getBitdeerCoolingSystemData(data)`. Returns `null` if `exhaustFanEnabled` is not a boolean.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Bitdeer container record; must contain exhaust fan status |

#### Basic usage

```tsx
<BitdeerPumps data={bitdeerContainer} />
```

#### Styling

- `.mdk-bitdeer-pumps`: Root element
- `.mdk-bitdeer-pumps__status`: Title and indicator row
- `.mdk-bitdeer-pumps__title`: Label text (`"Exhaust Fan"`)

### `BitdeerSettings`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `UnknownRecord` | `{}` | Bitdeer container device record |

#### Basic usage

```tsx
<BitdeerSettings data={bitdeerContainer} />
```

#### Composition

- Renders `ContainerParamsSettings` with container identity data
- Renders `EditableThresholdForm` wired with Bitdeer-specific color, flash, and superflash helpers for oil temperature and tank pressure

#### Styling

- `.mdk-bitdeer-settings`: Root element
- `.mdk-bitdeer-settings__params`: Container params section
- `.mdk-bitdeer-settings__thresholds`: Editable threshold section

### `BitdeerTankPressureCharts`

{/*Thin wrapper around `ContainerChartsBuilder` with a fixed Tank1/Tank2 pressure payload. Accepts `ContainerChartsBuilderProps`; `chartDataPayload` is internal and cannot be overridden.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Tank Pressure'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range (e.g. `'5m'`, `'3h'`, `'1D'`) |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |

#### Basic usage

```tsx
<BitdeerTankPressureCharts
  tag="container1"
  data={pressureData}
  timeline="24h"
/>
```

#### Lines rendered

- **Tank1 Pressure**: yellow, backend attribute `tank1_bar_group`
- **Tank2 Pressure**: violet, backend attribute `tank2_bar_group`
- Values are shown in `bar` with 1 decimal place

### `BitdeerTankTempCharts`

{/*Extends `ContainerChartsBuilderProps` with a `tankNumber` prop. Chart title is derived from `CHART_TITLES.TANK_OIL_TEMP` using `tankNumber`; `chartDataPayload` is internal.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `tankNumber` | Optional | `number \| string` | `1` | Tank index used to build backend attributes |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |

#### Basic usage

```tsx
<BitdeerTankTempCharts
  tag="container1"
  tankNumber={1}
  data={tempData}
  timeline="24h"
/>
```

#### Lines rendered

- `Tank{n} Oil TempL`: yellow (4px), backend attribute `cold_temp_c_{n}_group`
- `Tank{n} Oil TempH`: violet, `hot_temp_c_{n}_group`
- `Tank{n} Water TempL`: blue, `cold_temp_c_w_{n}_group`
- `Tank{n} Water TempH`: sky blue, `hot_temp_c_w_{n}_group`
- Values are shown in `°C`

# Bitmain container components (/reference/ui/react/foundation/operations/containers/bitmain)

UI for Bitmain hydro containers. These components read from Bitmain-shaped device records and render cooling-system status, power and positioning, liquid-flow charts, and hydro settings.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A Bitmain container device record. Most components read from `container_specific_stats` and `container_specific_stats_group_aggr` on the device.

## Components

### `BitMainBasicSettings`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | Bitmain container device record |

#### Basic usage

```tsx
<BitMainBasicSettings data={bitmainContainer} />
```

#### Composition

- Renders `BitMainCoolingSystem` with pump and fan indicators
- Renders a `"Power & Positioning"` section containing `BitMainPowerAndPositioning`

#### Styling

- `.mdk-bitmain-basic-settings`: Root element
- `.mdk-bitmain-basic-settings__section`: Section wrapper
- `.mdk-bitmain-basic-settings__title`: Section heading

### `BitMainCoolingSystem`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | Bitmain container device record |

#### Basic usage

```tsx
<BitMainCoolingSystem data={bitmainContainer} />
```

#### Indicators rendered

- `Circulating pump`: `circulating_pump`, fault from `circulating_pump_fault`
- `Fluid Infusion pump`: `fluid_infusion_pump`, fault from `fluid_infusion_pump_fault`
- `Fan #1`, `Fan #2`: `fan1`, `fan2`, faults from `fan1_fault`, `fan2_fault`
- `Cooling tower fan #1..#3`: `cooling_tower_fan1..3` with matching `_fault` attributes
- Indicator color is red on fault, green when running, gray otherwise

#### Styling

- `.mdk-bitmain-cooling-system`: Root element
- `.mdk-bitmain-cooling-system__wrapper`: Indicator grid wrapper
- `.mdk-bitmain-cooling-system__row`: Row of indicators
- `.mdk-bitmain-cooling-system__item`: Indicator cell
- `.mdk-bitmain-cooling-system__label`: Label text

### `BitMainHydroLiquidTemperatureCharts`

{/*Thin wrapper around `ContainerChartsBuilder` with a fixed secondary supply temperature payload. Accepts `ContainerChartsBuilderProps`; `chartDataPayload` is internal and cannot be overridden.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Hydro Liquid Temperature'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range (e.g. `'5m'`, `'3h'`, `'1D'`) |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |
| `showLegend` | Optional | `boolean` | `true` | Shows the series legend |
| `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector |
| `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart |

#### Basic usage

```tsx
<BitMainHydroLiquidTemperatureCharts
  tag="container1"
  data={tempData}
  timeline="24h"
/>
```

#### Lines rendered

- **Sec. Liquid supply Temp1**: sky blue, backend attribute `second_supply_temp1_group`
- **Sec. Liquid supply Temp2**: violet, backend attribute `second_supply_temp2_group`
- Values are shown in `°C` with 1 decimal place

### `BitMainHydroSettings`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | Bitmain Hydro container device record |

#### Basic usage

```tsx
<BitMainHydroSettings data={bitmainContainer} />
```

#### Composition

- Renders `BitMainBasicSettings` for cooling, power, and positioning
- Renders `HydroEditableThresholdForm` wired with Bitmain-specific color, flash, and superflash helpers for supply liquid temperature and pressure

#### Styling

- `.mdk-bitmain-hydro-settings`: Root element
- `.mdk-bitmain-hydro-settings__params`: Basic settings section
- `.mdk-bitmain-hydro-settings__thresholds`: Editable threshold section

### `BitMainLiquidPressureCharts`

{/*Thin wrapper around `ContainerChartsBuilder` with a fixed supply/return liquid pressure payload. Values are converted from MPa to bar; `chartDataPayload` is internal and cannot be overridden.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Liquid Pressure'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |
| `showLegend` | Optional | `boolean` | `true` | Shows the series legend |
| `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector |
| `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart |

#### Basic usage

```tsx
<BitMainLiquidPressureCharts
  tag="container1"
  data={pressureData}
  timeline="24h"
/>
```

#### Lines rendered

- **Supply Liquid Pressure**: sky blue, backend attribute `supply_liquid_pressure_group`
- **Return Liquid Pressure**: violet, backend attribute `return_liquid_pressure_group`
- Values are shown in `bar` with 3 decimal places; source MPa values are autoconverted with [`convertMpaToBar`](/reference/app-toolkit/ui-devkit/utilities#convertmpatobar).

### `BitMainLiquidTempCharts`

{/*Thin wrapper around `ContainerChartsBuilder` with a fixed supply/return liquid temperature payload. `chartDataPayload` is internal and cannot be overridden.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Liquid Temperature'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |
| `showLegend` | Optional | `boolean` | `true` | Shows the series legend |
| `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector |
| `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart |

#### Basic usage

```tsx
<BitMainLiquidTempCharts
  tag="container1"
  data={tempData}
  timeline="24h"
/>
```

#### Lines rendered

- **Supply Liquid Temp**: sky blue, backend attribute `supply_liquid_temp_group`
- **Return Liquid Temp**: violet, backend attribute `return_liquid_temp_group`
- Values are shown in `°C` with 1 decimal place

### `BitMainPowerAndPositioning`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | Bitmain container device record |

#### Basic usage

```tsx
<BitMainPowerAndPositioning data={bitmainContainer} />
```

#### Composition

- Renders a `Power` `ContentBox` with distribution box #1 and #2 kW values (read from `distribution_box1_power_w`, `distribution_box2_power_w`)
- Renders a `Location` `ContentBox` with latitude, longitude, and their direction fields

#### Styling

- `.mdk-bitmain-power-positioning`: Root element
- `.mdk-bitmain-power-positioning__panel`: Power or Location panel
- `.mdk-bitmain-power-positioning__section`: Section body
- `.mdk-bitmain-power-positioning__power-item`: Distribution box row
- `.mdk-bitmain-power-positioning__location-grid`: Latitude and longitude grid
- `.mdk-bitmain-power-positioning__location-item`: Coordinate cell
- `.mdk-bitmain-power-positioning__location-details`: Coordinate details
- `.mdk-bitmain-power-positioning__subtitle`: Panel subtitle
- `.mdk-bitmain-power-positioning__value`: Power value text

### `BitMainPowerCharts`

{/*Wraps `ContainerChartsBuilder` with a fixed power payload and preprocesses `container_specific_stats_group_aggr` to add a computed `total_power_computed` field (box1 + box2). `chartDataPayload` is internal.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Power Consumption'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |
| `showLegend` | Optional | `boolean` | `true` | Shows the series legend |
| `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector |
| `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart |

#### Basic usage

```tsx
<BitMainPowerCharts
  tag="container1"
  data={powerData}
  timeline="24h"
/>
```

#### Lines rendered

- **Total Power**: sky blue (3px), computed attribute `total_power_computed` (sum of boxes)
- **Dist. Box 1 Power**: violet, backend attribute `distribution_box1_power_group`
- **Dist. Box 2 Power**: red, backend attribute `distribution_box2_power_group`
- Values are shown in `W` (stored kW is converted with `convertKwToW`) with 2 decimal places

### `BitMainSupplyLiquidFlowCharts`

{/*Thin wrapper around `ContainerChartsBuilder` with a single supply liquid flow series. `showLegend` defaults to `false` because only one line is drawn; `chartDataPayload` is internal.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `tag` | Required | `string` | none | Container tag used to scope chart data |
| `chartTitle` | Optional | `string` | `'Supply Liquid Flow'` | Chart header title |
| `data` | Required | `UnknownRecord[]` | none | Time-series entries to plot |
| `timeline` | Optional | `string` | `'24h'` | Initial time range |
| `dateRange` | Optional | \{ start?: number; end?: number \} | none | Explicit start/end window in ms |
| `fixedTimezone` | Required | `string` | none | Forces a timezone for axis labels |
| `height` | Required | `number` | none | Chart height in pixels |
| `showLegend` | Optional | `boolean` | `false` | Shows the series legend |
| `showRangeSelector` | Optional | `boolean` | `true` | Shows the timeline range selector |
| `footer` | Optional | `ReactNode` | none | Custom footer rendered below the chart |

#### Basic usage

```tsx
<BitMainSupplyLiquidFlowCharts
  tag="container1"
  data={flowData}
  timeline="24h"
/>
```

#### Lines rendered

- **Supply Liquid Flow**: sky blue (2px), backend attribute `supply_liquid_flow_group`
- Values are shown in `m³/h` with 2 decimal places

### `StatusItem`

{/*Generic-looking name, but classified under the Bitmain subcategory because that is the only vendor that consumes it today.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Required | `string` | none | Label text shown next to the indicator |
| `status` | Optional | `'normal' \| 'warning' \| 'fault' \| 'unavailable'` | `'unavailable'` | Status type; selects color and label |

#### Status mapping

- `normal`: green indicator, label `Normal`
- `warning`: amber indicator, label `Warning`
- `fault`: red indicator, label `Fault`
- `unavailable`: gray indicator, label `Unavailable`

#### Basic usage

```tsx
<StatusItem label="Temperature" status="normal" />
<StatusItem label="Pressure" status="warning" />
<StatusItem label="Flow" status="fault" />
```

#### Styling

- `.mdk-status-item`: Root element
- `.mdk-status-item__content`: Label and indicator row
- `.mdk-status-item__label`: Label text

# Bitmain Immersion container components (/reference/ui/react/foundation/operations/containers/bitmain-immersion)

UI for Bitmain Immersion containers. These components render unit control boxes, pump-station status, immersion settings, and system-status views on top of Bitmain immersion-shaped device records.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A Bitmain Immersion container device record. Most components read pump and temperature fields from `container_specific_stats`.

## Components

### `BitMainControlsTab`

{/*File is named `bitmain-immersion-controls-tab.tsx`, but the exported component is `BitMainControlsTab`. Import path is unchanged.*/}

#### Import

```tsx
```

#### Props

#### Basic usage

```tsx
<BitMainControlsTab data={immersionContainer} />
```

#### Composition

- Container fan indicator from `container_fan` and `fan_fault` (red on fault, green running, gray off)
- Tank levels for Tank A to Tank D read from `tank_a_level` to `tank_d_level` in cm
- GPS latitude and longitude with direction fields

#### Styling

- `.mdk-bitmain-controls-tab`: Root element
- `.mdk-bitmain-controls-tab__section`: Section wrapper
- `.mdk-bitmain-controls-tab__section-header`: Fan status row
- `.mdk-bitmain-controls-tab__section-label`: Fan label text
- `.mdk-bitmain-controls-tab__title`: Section heading
- `.mdk-bitmain-controls-tab__grid`: Tank or GPS grid
- `.mdk-bitmain-controls-tab__item`: Tank cell
- `.mdk-bitmain-controls-tab__label`: Tank label
- `.mdk-bitmain-controls-tab__value`: Tank value
- `.mdk-bitmain-controls-tab__location`: GPS cell
- `.mdk-bitmain-controls-tab__location-label`: GPS axis label
- `.mdk-bitmain-controls-tab__location-value`: GPS coordinate value
- `.mdk-bitmain-controls-tab__location-dir`: GPS direction text

### `BitMainImmersionControlBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `string` | none | Box title shown above the left column |
| `leftContent` | Required | `ReactNode` | none | Content for the left column |
| `rightContent` | Required | `ReactNode` | none | Content for the right column |
| `bottomContent` | Optional | `ReactNode` | none | Optional content for the bottom row |
| `secondary` | Optional | `boolean` | `false` | Borderless variant |
| `className` | Optional | `string` | none | Additional class name on the root |

#### Basic usage

```tsx
<BitMainImmersionControlBox
  title="Power Status"
  leftContent={<div>Current: 35°C</div>}
  rightContent={<div>Target: 30°C</div>}
  bottomContent={<div>Additional info</div>}
/>
```

#### Styling

- `.mdk-bitmain-immersion-control-box`: Root element
- `.mdk-bitmain-immersion-control-box--secondary`: Borderless variant modifier
- `.mdk-bitmain-immersion-control-box__top`: Two-column wrapper
- `.mdk-bitmain-immersion-control-box__left`: Left column
- `.mdk-bitmain-immersion-control-box__right`: Right column
- `.mdk-bitmain-immersion-control-box__title`: Title text
- `.mdk-bitmain-immersion-control-box__bottom`: Bottom row

### `BitMainImmersionPumpStationControlBox`

{/*A state row (`ready`, `operation`, `start`) is hidden when its prop is `undefined`. When provided as `false`, the label is prefixed with `Not`.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `string` | none | Box title |
| `alarmStatus` | Optional | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise |
| `ready` | Required | `boolean` | none | Ready state; row hidden when omitted |
| `operation` | Required | `boolean` | none | Operating state; row hidden when omitted |
| `start` | Required | `boolean` | none | Started state; row hidden when omitted |
| `className` | Optional | `string` | none | Additional class name on the root |

#### Basic usage

```tsx
<BitMainImmersionPumpStationControlBox
  title="Pump Station #1"
  alarmStatus={false}
  ready={true}
  operation={true}
  start={true}
/>
```

#### Styling

- `.mdk-bitmain-immersion-pump-station-control-box`: Root element
- `.mdk-bitmain-immersion-pump-station-control-box__title`: Title text
- `.mdk-bitmain-immersion-pump-station-control-box__content`: Tag and states row
- `.mdk-bitmain-immersion-pump-station-control-box__status`: Alarm tag wrapper
- `.mdk-bitmain-immersion-pump-station-control-box__state`: State label
- `.mdk-bitmain-immersion-pump-station-control-box__state--on`: Active state modifier
- `.mdk-bitmain-immersion-pump-station-control-box__state--off`: Inactive state modifier

### `BitMainImmersionSettings`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | Bitmain immersion container device record |
| `containerSettings` | Optional | `object \| null` | `null` | Optional custom oil temperature thresholds. Shape: `{ thresholds?: Record<string, unknown> }` |

#### Basic usage

```tsx
<BitMainImmersionSettings data={immersionContainer} />
```

#### With custom thresholds

```tsx
<BitMainImmersionSettings
  data={immersionContainer}
  containerSettings={{ thresholds: customThresholds }}
/>
```

#### Composition

- Renders `ImmersionEditableThresholdForm` wired with Bitmain immersion color, flash, and superflash helpers for oil temperature
- When `status` is missing on `data`, it defaults to `'active'`

### `BitMainImmersionSystemStatus`

{/*The `Server Start` row only renders when `server_on` is truthy; the `Connection` row always renders and flips between `Connected` and `Disconnected` based on `disconnect`.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | Bitmain immersion container device record |

#### Basic usage

```tsx
<BitMainImmersionSystemStatus data={immersionContainer} />
```

#### Styling

- `.mdk-bitmain-immersion-system-status`: Root element
- `.mdk-bitmain-immersion-system-status__header`: Header row
- `.mdk-bitmain-immersion-system-status__title`: Title text
- `.mdk-bitmain-immersion-system-status__content`: Status rows wrapper
- `.mdk-bitmain-immersion-system-status__item`: Single status row
- `.mdk-bitmain-immersion-system-status__label`: Row label text

### `BitMainImmersionUnitControlBox`

{/*Built on top of `BitMainImmersionControlBox`. When `isDryCooler` is true, the status label is forced to `"Dry Cooler"` regardless of `title`. Frequency row is hidden when `frequency` is nullish.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `title` | Required | `string` | none | Box title shown above the left column |
| `alarmStatus` | Optional | `boolean` | `false` | Shows `Fault` tag when true, `Normal` otherwise |
| `frequency` | Required | `number` | none | Frequency value in Hz; row hidden when omitted |
| `isDryCooler` | Optional | `boolean` | `false` | Forces status label to `"Dry Cooler"` |
| `running` | Optional | `boolean` | `false` | Shows a running or off indicator |
| `showFrequencyInLeftColumn` | Optional | `boolean` | `false` | Renders the frequency row in the left column instead of the right |
| `secondary` | Optional | `boolean` | `false` | Borderless variant |
| `className` | Optional | `string` | none | Additional class name on the root |

#### Basic usage

```tsx
<BitMainImmersionUnitControlBox
  title="Unit #1"
  alarmStatus={false}
  running={true}
  frequency={50}
/>
```

#### Dry cooler variant

```tsx
<BitMainImmersionUnitControlBox
  isDryCooler
  running
  frequency={45}
  showFrequencyInLeftColumn
/>
```

#### Styling

- `.mdk-bitmain-immersion-unit-control-box`: Root element
- `.mdk-bitmain-immersion-unit-control-box__item`: Label and value row (status or frequency)
- `.mdk-bitmain-immersion-unit-control-box__item-label`: Row label text
- `.mdk-bitmain-immersion-unit-control-box__item-value`: Row value text

# MicroBT container components (/reference/ui/react/foundation/operations/containers/microbt)

UI for MicroBT containers. These components read from MicroBT-shaped device records and render cooling status, fire and water sensors, power meters, and a gauge chart used for temperature readouts.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A MicroBT container device record. Cooling components read from `container_specific_stats.cdu`; `PowerMeters` reads from `container_specific_stats.power_meters`.

## Components

### `GaugeChartComponent`

{/*Generic-looking name, but classified under the MicroBT subcategory because that is the only vendor that consumes it today. Thin wrapper around `GaugeChart` from `@tetherto/mdk-react-devkit/core` that adds a title and a value/unit readout.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `max` | Required | `number` | none | Maximum value for the gauge |
| `value` | Required | `number` | none | Current value |
| `unit` | Required | `string` | none | Unit of measurement |
| `label` | Optional | `string` | `''` | Title shown above the gauge |
| `chartStyle` | Optional | `React.CSSProperties` | `{}` | Inline style on the chart wrapper |
| `colors` | Optional | `string[]` | `[COLOR.EMERALD, COLOR.SOFT_TEAL]` | Arc colors in HEX |
| `hideText` | Optional | `boolean` | `true` | Hides the built-in percentage text |
| `height` | Optional | `number` | `200` | Chart height in pixels |
| `className` | Optional | `string` | none | Additional class name on the root |

#### Basic usage

```tsx
<GaugeChartComponent
  max={100}
  value={75.5}
  label="Temperature"
  unit="°C"
/>
```

#### Styling

- `.mdk-gauge-chart-component`: Root element
- `.mdk-gauge-chart-component__title`: Gauge title
- `.mdk-gauge-chart-component__chart`: Chart wrapper
- `.mdk-gauge-chart-component__value`: Value readout row
- `.mdk-gauge-chart-component__value-number`: Numeric value text
- `.mdk-gauge-chart-component__value-unit`: Unit text

### `MicroBTCooling`

{/*Returns `null` when `data` is not provided. Reads cooling status from the `cdu` object on `container_specific_stats`. Pump speed is shown in `%` for Kehua units (`isMicroBTKehua`) and in `Hz` otherwise.*/}

#### Import

```tsx
```

#### Props

#### Basic usage

```tsx
<MicroBTCooling data={microbtContainer} />
```

#### Composition

- `Cycle Pump` indicator from `cdu.cycle_pump_control` (green `Running`, gray `Off`)
- `Main Circulation Pump` panel: status from `circulation_pump_running_status`, switch from `circulation_pump_switch`, speed from `circulation_pump_speed` in `%` or `Hz`
- `Cooling Fan` panel: status from `cooling_fan_control`, Kehua-only speed from `cooling_system_status`, switch from `cooling_fan_switch`
- `Make Up Pump` panel: status is red on `makeup_water_pump_fault`, green on `makeup_water_pump_control`, gray otherwise; switch from `makeup_water_pump_switch`.

#### Styling

- `.mdk-micro-bt-cooling`: Root element
- `.mdk-micro-bt-cooling__section`: Section wrapper
- `.mdk-micro-bt-cooling__section-title`: Section heading
- `.mdk-micro-bt-cooling__divider`: Horizontal divider between sections
- `.mdk-micro-bt-cooling__row`: Row of items inside a section
- `.mdk-micro-bt-cooling__item-row`: Single-row layout (cycle pump)
- `.mdk-micro-bt-cooling__item`: Item cell
- `.mdk-micro-bt-cooling__label`: Item label text
- `.mdk-micro-bt-cooling__value`: Item value text

### `MicroBTSettings`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | MicroBT container device record |
| `containerSettings` | Optional | `object \| null` | `null` | Optional custom inlet temperature thresholds. Shape: `{ thresholds?: Record<string, unknown> }` |

#### Basic usage

```tsx
<MicroBTSettings data={microbtContainer} />
```

#### With custom thresholds

```tsx
<MicroBTSettings
  data={microbtContainer}
  containerSettings={{ thresholds: customThresholds }}
/>
```

#### Composition

- Renders `ContainerParamsSettings` for the common container parameters block
- Renders `MicroBTEditableThresholdForm` wired with MicroBT-specific color, flash, and superflash helpers (`getMicroBtInletTempColor`, `shouldMicroBtTemperatureFlash`, `shouldMicroBtTemperatureSuperflash`) for inlet water temperature

#### Styling

- `.mdk-micro-bt-settings`: Root element
- `.mdk-micro-bt-settings__divider`: Spacer between the params and threshold sections

### `PowerMeters`

{/*Returns `null` when `data` is not provided or when `container_specific_stats.power_meters` is empty. Renders one `ContentBox` per meter titled `Power Meter {n}`, starting at `1`.*/}

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `Device` | none | MicroBT container device record |

#### Basic usage

```tsx
<PowerMeters data={microbtContainer} />
```

#### Rows rendered

- `Communication Status`: green `Normal` when `status === 1`, red `Error` otherwise
- `Voltage A-B`, `Voltage B-C`, `Voltage C-A`: `voltage_ab`, `voltage_bc`, `voltage_ca` in `V`
- `Total Power Factor`: `total_power_factor`, unitless
- `Frequency`: `freq` in `Hz`
- `Total Active Power`: `total_active_power` in `kW`
- `Total Apparent Power`: `total_apparent_power` in `kVA`
- `Total Active Energy`: `total_active_energy` in `kWh`

#### Styling

- `.mdk-power-meters`: Root element
- `.mdk-power-meters__panel`: Single power-meter panel wrapper

# Socket (/reference/ui/react/foundation/operations/containers/socket)

`Socket` renders a single PDU socket cell used inside container floor plans and detail views. It pairs socket identity with live power and current readouts, reflects miner mount state, and supports an add-miner flow in edit mode.

For the container vendors that compose sockets into larger layouts, see the [Containers overview](/reference/ui/react/foundation/operations).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A socket payload: index, enabled flag, optional `power_w` / `current_a`,
- (Optional) a mounted [`Miner`](/reference/app-toolkit/ui-devkit/types#device)

### `Socket`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `socket` | Optional | `number \| null` | `null` | Socket index shown in the cell |
| `enabled` | Optional | `boolean` | `false` | Whether the socket is powered |
| `selected` | Optional | `boolean` | `false` | Applies selected visual state |
| `current_a` | Optional | `number \| null` | `null` | Current draw in amperes |
| `power_w` | Optional | `number \| null` | `null` | Power draw in watts |
| `miner` | Optional | `Miner \| null` | `null` | Miner mounted in the socket |
| `heatmap` | Optional | `Heatmap \| null` | `null` | Heatmap configuration; see type below |
| `cooling` | Optional | `boolean \| undefined` | `undefined` | Shows cooling fan state when set |
| `isEditFlow` | Optional | `boolean` | `false` | Renders the add-miner flow UI |
| `clickDisabled` | Optional | `boolean` | `false` | Disables socket click interactions |
| `isEmptyPowerDashed` | Optional | `boolean` | `false` | Shows zero power with dashed border |
| `isContainerControlSupported` | Optional | `boolean` | `false` | Affects tooltip copy for controls |
| `pdu` | Optional | `object` | none | PDU metadata used for `data-pdu-index`. Shape: `{ pdu?: string \| number }` |
| `innerRef` | Optional | `ForwardedRef<HTMLDivElement>` | none | Forwarded ref to the root element |

#### `Heatmap` type

```tsx
type Heatmap = {
  isHeatmapMode?: boolean
  mode?: string       // e.g. 'hashrate' or a temperature field
  ranges?: Record<string, { min?: number; max?: number }>
}
```

#### Basic usage

```tsx
<Socket
  socket={1}
  enabled
  power_w={3250}
  current_a={14.5}
  miner={minerData}
/>
```

#### With heatmap

```tsx
<Socket
  socket={1}
  enabled
  miner={minerData}
  heatmap={{
    isHeatmapMode: true,
    mode: 'chip_avg',
    ranges: { chip_avg: { min: 40, max: 85 } },
  }}
/>
```

#### Styling

- `.mdk-socket`: Root element
- `.mdk-socket--has-cooling`: Cooling fan visible
- `.mdk-socket--heatmap`: Heatmap mode active
- `.mdk-socket--selected`: Selected state
- `.mdk-socket--disabled`: Click disabled
- `.mdk-socket__wrapper`: Content wrapper
- `.mdk-socket__consumption-box`: Power and current readouts
- `.mdk-socket__fan-icon` / `--on`: Cooling fan icon
- `.mdk-socket__value`: Individual power or current cell
- `.mdk-socket__index`: Socket number badge
- `.mdk-socket__add-icon`: Add-miner icon shown in edit flow
- `.mdk-socket__connection-icon`: Clock icon shown while connecting

# Details view (/reference/ui/react/foundation/operations/details-view)

UI for the details view opened from the [device explorer](/reference/ui/react/foundation/operations/device-explorer). These components render device identity, telemetry, hardware state, and operator controls for the currently selected miner, selection of miners, or container.

## Prerequisites

<Accordions>
    <Accordion title="Adapter store hooks used across these components">
      - Several components read the current selection through `useDevices()` (selected devices or containers)
      - They queue operator actions through `useActions()` for power mode, reboot, LED, frequency, and maintenance flows
    </Accordion>
  </Accordions>

- A miner [`Device`](/reference/app-toolkit/ui-devkit/types#device) record (or array of records) shaped per `@tetherto/mdk-react-devkit/foundation`'s `Device` type

<Accordions>
    <Accordion title="Device fields these components read">
      - Identity and metadata fields on the `Device` itself
      - Live telemetry components additionally read `device.last.snap.stats`
      - Config-driven components additionally read `device.last.snap.config`
    </Accordion>
  </Accordions>

## Component groups

The category is split into four subpages plus this index, which hosts the shared identity card:

- [Charts](/reference/ui/react/foundation/operations/details-view/charts): fleet-level activity visualizations
- [Chips](/reference/ui/react/foundation/operations/details-view/chips): per-hashboard ASIC chip telemetry
- [Controls](/reference/ui/react/foundation/operations/details-view/controls): miner power mode, reboot, LEDs, frequency, maintenance flow, plus the batch and per-container controls cards
- [Fleet management](/reference/ui/react/foundation/operations/details-view/fleet-management): dialogs for adding, replacing, moving, and removing miners across containers
- [Stats](/reference/ui/react/foundation/operations/details-view/stats): single and secondary stat cards, aggregated stats, and the combined miner metric card

## All details view components

## Shared identity card

`MinerInfoCard` is the only component in this category without a subgroup. It anchors every details view as the identity header (model, serial, firmware, IP) and is reused in batch and single-selection layouts alike.

### `MinerInfoCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Optional | `string` | `'Miner info'` | Card header label, rendered uppercase |
| `data` | Required | `InfoItem[]` | none | Title and value rows to display |

The `InfoItem` shape is re-exported from `@tetherto/mdk-react-devkit/foundation`:

```tsx
type InfoItem = {
  title?: string
  value?: string | string[] | number
}
```

When `value` is an array, each entry is rendered on its own line under the title.

#### Basic usage

```tsx
<MinerInfoCard
  label="Miner info"
  data={[
    { title: 'Model', value: 'Antminer S19 Pro' },
    { title: 'Serial', value: 'ANT-2024-00142' },
    { title: 'Firmware', value: '2.1.3' },
    { title: 'IP address', value: '192.168.1.42' },
  ]}
/>
```

#### Multi-line values

Pass an array as `value` to stack rows under a single title (useful for pool URLs, worker names, hashboard ids):

```tsx
<MinerInfoCard
  data={[
    {
      title: 'Pools',
      value: ['stratum+tcp://pool1.example.com:3333', 'stratum+tcp://pool2.example.com:3333'],
    },
    { title: 'Workers', value: ['worker-1', 'worker-2', 'worker-3'] },
  ]}
/>
```

#### Composition

`MinerInfoCard` wraps [`DeviceInfo`](/reference/app-toolkit/ui-devkit/types#deviceinfo) (from `@tetherto/mdk-react-devkit/foundation`'s `info-container`) and adds the uppercase header label. If you need the bare row layout without the card chrome, use `DeviceInfo` directly.

#### Styling

- `.mdk-miner-info-card`: root element
- `.mdk-miner-info-card__label`: uppercase header label
- `.mdk-info-container`: nested per-row title and value wrapper
- `.mdk-info-container__title`: row title
- `.mdk-info-container__value`: row value (one inner `<div>` per array entry)

# Charts (/reference/ui/react/foundation/operations/details-view/charts)

Chart components that summarize fleet-wide miner state at a glance.

For single-value and aggregated stat cards, see [Stats](/reference/ui/react/foundation/operations/details-view/stats). For miner identity (`MinerInfoCard`), see the [details view overview](/reference/ui/react/foundation/operations).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A `MinersActivityData` record keyed by status name. Typically derived by grouping a [`Device`](/reference/app-toolkit/ui-devkit/types#device) list by status.

## Components

### `MinersActivityChart`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `MinersActivityData` | `{}` | Counts keyed by status name |
| `large` | Optional | `boolean` | `false` | Switch to large indicator and label sizing |
| `isLoading` | Optional | `boolean` | `false` | Render a spinner instead of the chart |
| `isError` | Optional | `boolean` | `false` | Render `CoreAlert` instead of the chart (unless `isDemoMode`) |
| `error` | Optional | `object \| null` | `null` | Message surfaced inside the error alert. Shape: `{ data?: { message?: string } }` |
| `showLabel` | Optional | `boolean` | `true` | Show the per-status text label under each indicator |
| `isDemoMode` | Optional | `boolean` | `false` | Render zeros on error rather than the alert (for demos) |

`MinersActivityData` is an open record. The component renders one indicator per status key it knows about; unknown keys are ignored.

#### Statuses rendered

The chart fixes the order and color of each indicator:

- **Offline**: gray
- **Error**: red, with a tooltip noting that minor errors not affecting hash rate are excluded
- **Sleep**: power mode
- **Low**: yellow, low power mode
- **Normal**: green, normal power mode
- **High**: purple, high power mode
- **Empty**: socket with no miner connected (rendered as `empty` label)

#### Basic usage

```tsx
<MinersActivityChart
  data={{
    total: 100,
    offline: 4,
    error: 1,
    low: 8,
    normal: 80,
    high: 7,
  }}
/>
```

#### Loading and error states

```tsx
<MinersActivityChart isLoading />

{/* Demo dashboards: render zeros on error instead of the alert */}
<MinersActivityChart isError isDemoMode />
```

#### Styling

- `.mdk-miners-activity-chart__root`: root flex row
- `.mdk-miners-activity-chart__item`: per-status indicator wrapper
- `.mdk-miners-activity-chart__item--large`: large variant
- `.mdk-miners-activity-chart__label`: status label
- `.mdk-miners-activity-chart__label--large`: large label
- `.mdk-miners-activity-chart__spinner`: loading spinner
- `.mdk-miners-activity-chart__spinner--large`: large spinner

# Chips (/reference/ui/react/foundation/operations/details-view/chips)

UI for the per-chip thermal and frequency telemetry that surfaces alongside the rest of the details view. `MinerChipsCard` renders a card with one `MinerChip` tile per ASIC; `MinerChip` is also exported on its own for callers that already have per-chip data and want to render their own grid.

For miner identity, see the [details view overview](/reference/ui/react/foundation/operations). For aggregated stats, see [Stats](/reference/ui/react/foundation/operations/details-view/stats). For fleet activity, see [Charts](/reference/ui/react/foundation/operations/details-view/charts).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- A [`ContainerStats`](/reference/app-toolkit/ui-devkit/types#containerstats) payload with paired `frequency_mhz.chips` and `temperature_c.chips` arrays

<Accordions>
    <Accordion title="How chip entries are matched and filtered">
      - Chips are matched by `index` across the `frequency_mhz.chips` and `temperature_c.chips` arrays
      - Entries missing any of `min`, `max`, or `avg` temperature are skipped
    </Accordion>
  </Accordions>

## Components

### `MinerChipsCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Required | `ContainerStats` | none | Stats payload containing per-chip frequency and temperature arrays |

The component reads `data.frequency_mhz.chips` and `data.temperature_c.chips`. Chips are joined by `index`. The card renders nothing when no chip pair is complete.

#### Expected chip payload

```tsx
type ContainerStats = {
  frequency_mhz?: {
    chips?: { index: number; current: number }[]
  }
  temperature_c?: {
    chips?: { index: number; max: number; min: number; avg: number }[]
  }
}
```

#### Basic usage

```tsx
<MinerChipsCard
  data={{
    frequency_mhz: {
      chips: [
        { index: 0, current: 500 },
        { index: 1, current: 498 },
      ],
    },
    temperature_c: {
      chips: [
        { index: 0, max: 72, min: 65, avg: 68 },
        { index: 1, max: 70, min: 63, avg: 66 },
      ],
    },
  }}
/>
```

#### Composition

`MinerChipsCard` renders one `MinerChip` per joined entry inside a flex layout. Use `MinerChip` directly when you have already-joined per-chip data and want to skip the join step.

#### Styling

- `.mdk-miner-chips-card`: root element
- `.mdk-miner-chips-card__label`: `Chips` header
- `.mdk-miner-chips-card__chips`: flex container holding the chip tiles

### `MinerChip`

`MinerChip` is the tile rendered inside `MinerChipsCard`. It is exported for callers that already have per-chip data and want to render their own grid (for example, custom layouts or test fixtures).

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `index` | Required | `number` | none | Chip index, displayed as the tile title (`Chip {index}`) |
| `frequency` | Required | \{ current: number \} | none | Current frequency in MHz |
| `temperature` | Required | \{ avg: number; min: number; max: number \} | none | Temperature readings in °C |

#### Basic usage

```tsx
<MinerChip
  index={0}
  frequency={{ current: 500 }}
  temperature={{ avg: 68, min: 65, max: 72 }}
/>
```

#### Layout

The tile shows, in order:

- **Title**: `Chip {index}`
- **Temperature**: average value with °C unit
- **Min and max**: small paired values labelled `min (°C)` and `max (°C)`
- **Frequency**: current value with MHz unit

#### Styling

- `.mdk-miner-chip`: root element
- `.mdk-miner-chip__title`: `Chip {index}` header
- `.mdk-miner-chip__property`: `Temperature` and `Frequency` row labels
- `.mdk-miner-chip__value`: numeric value with unit
- `.mdk-miner-chip__minmax`: min and max value row
- `.mdk-miner-chip__value-type`: small label appended to min and max values

# Controls (/reference/ui/react/foundation/operations/details-view/controls)

Operator controls for the currently selected miner or container. These components queue actions through `useActions()` and surface confirmation through the standard notification hooks.

## Prerequisites

<Accordions>
    <Accordion title="Adapter store hooks required by these components">
      - `MinerControlsCard` reads the current device selection from `useDevices()` and pending submissions from `useActions()`, then queues new submissions through `useActions()`
      - `BatchContainerControlsCard` reads the selected containers from `useDevices()`
    </Accordion>
  </Accordions>

- The notification hook [`useNotification`](/reference/app-toolkit/hooks/components#usenotification) (from `@tetherto/mdk-react-devkit/foundation`) wired up; control actions notify on submit.

## Components

### `MinerControlsCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `buttonsStates` | Optional | `Record<string, boolean \| undefined>` | none | Per-action disable flags. Currently consumed: `isSetUpFrequencyButtonDisabled` |
| `isLoading` | Required | `boolean` | none | Renders the loading spinner and disables every action |
| `showPowerModeSelector` | Optional | `boolean` | `true` | Show the embedded `MinerPowerModeSelectionButtons` row |

#### Available controls

The component renders a different control set depending on the selection and maintenance state:

**Standard mode** (any non-maintenance selection):

- **Power mode selector**: embedded `MinerPowerModeSelectionButtons` (toggle via `showPowerModeSelector`)
- **Reboot**: dispatches `ACTION_TYPES.REBOOT` for every selected miner
- **Setup Freq. Settings**: opens the frequency dropdown and dispatches `ACTION_TYPES.SETUP_FREQUENCY_SPEED` with the chosen value
- **LEDs on / LEDs off**: dispatches `ACTION_TYPES.SET_LED` for miners whose LED is not already in the requested state
- **Move to Maintenance**, **Change miner info**, **Change position**: single-device actions that open the matching dialog flow

**Single-miner-in-maintenance mode**:

- **Change Miner Info**: opens the change-info dialog
- **Back from Maintenance**: opens the container-selection dialog (disabled until the device has a MAC address)
- **Remove Miner**: opens the remove-miner dialog

The card returns `null` when more than one miner is selected and every selected miner is already in maintenance.

#### Basic usage

```tsx
<MinerControlsCard
  buttonsStates={{ isSetUpFrequencyButtonDisabled: false }}
  isLoading={false}
/>
```

#### Hide the power mode selector

```tsx
<MinerControlsCard
  buttonsStates={buttonsStates}
  isLoading={isLoading}
  showPowerModeSelector={false}
/>
```

#### Composition

`MinerControlsCard` composes `MinerPowerModeSelectionButtons`, `MinerSetupFrequencyDropdown`, and four dialogs (`ContainerSelectionDialog`, `RemoveMinerDialog`, `AddReplaceMinerDialog`, `PositionChangeDialog`). The dialogs are mounted unconditionally and toggle visibility through internal state; no wiring required from the caller.

#### Styling

- `.mdk-miner-controls`: root element
- `.mdk-miner-controls__label`: `Miner Controls` header
- `.mdk-miner-controls__content`: controls container
- `.mdk-miner-controls__loader`: loading spinner
- `.mdk-miner-controls__grid`: standard mode button grid
- `.mdk-miner-controls__full-width`: full-width button slot
- `.mdk-miner-controls__maintenance-stack`: maintenance mode action stack
- `.mdk-miner-controls__single-device-stack`: single-device action stack

### `MinerPowerModeSelectionButtons`

`MinerPowerModeSelectionButtons` is rendered inside `MinerControlsCard` by default but is exported as a peer for layouts that want the power-mode dropdown without the rest of the control card (for example, an `Alarm` rail or a custom toolbar).

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `selectedDevices` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device)`[]` | `[]` | Miners targeted by the dropdown; used to derive the model groups |
| `setPowerMode` | Required | `function` | none | Callback fired with the matching device subset when a mode is chosen |
| `connectedMiners` | Required | `Device[]` | none | Used to compute the current power mode summary when `powerModesLog` is not provided |
| `powerModesLog` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Pre-computed per-model current power modes (overrides the derived value) |
| `disabled` | Optional | `boolean` | none | Disable every dropdown |
| `hasMargin` | Optional | `boolean` | `false` | Add the `--with-margin` modifier on the root |

The component groups `selectedDevices` by miner model (via `getDeviceModel`) and renders one dropdown per group. When the selection contains a single model, the button reads `Set Power Mode`; with multiple models, the model name is appended (`Set Power Mode (S19 Pro)`).

#### Basic usage

```tsx
<MinerPowerModeSelectionButtons
  selectedDevices={selectedMiners}
  setPowerMode={(devices, mode) => {
    console.log('Set power mode:', mode, 'for', devices.length, 'miners')
  }}
/>
```

#### With pre-computed power modes

```tsx
<MinerPowerModeSelectionButtons
  selectedDevices={selectedMiners}
  powerModesLog={powerModesByModel}
  setPowerMode={handlePowerModeChange}
  disabled={isLoading}
/>
```

#### Styling

- `.mdk-miner-power-mode-selection-buttons`: root element
- `.mdk-miner-power-mode-selection-buttons--with-margin`: margin modifier

### `BatchContainerControlsCard`

`BatchContainerControlsCard` is the container-level counterpart to `MinerControlsCard`. It renders inside the details view when one or more containers are selected and switches between batch and single-container layouts based on selection size.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isBatch` | Optional | `boolean` | `true` | Toggle the title between `Batch Container Controls` and `Container Controls` |
| `isCompact` | Optional | `boolean` | none | Forwarded to `ContainerControlsBox` for the compact layout |
| `connectedMiners` | Optional | `unknown` | none | Forwarded to `ContainerControlsBox` when exactly one container is selected |
| `alarmsDataItems` | Optional | `TimelineItemData[]` | none | Forwarded alarm timeline data |
| `onNavigate` | Optional | `function` | no-op | Forwarded navigation handler |

The card reads the selected containers from `useDevices()` and uses the selection to derive the device record passed into `ContainerControlsBox`. With a single container selected, the full record (plus `connectedMiners`) is forwarded; with multiple containers, only `type` is forwarded, and only when every selected container shares the same model (otherwise `type` is `undefined`, which forces the batch layout).

#### Basic usage

```tsx
<BatchContainerControlsCard
  alarmsDataItems={alarmTimelineItems}
  onNavigate={(path) => router.push(path)}
/>
```

#### Single-container compact layout

```tsx
<BatchContainerControlsCard
  isBatch={false}
  isCompact
  connectedMiners={connectedMinerCount}
  alarmsDataItems={alarmTimelineItems}
  onNavigate={(path) => router.push(path)}
/>
```

#### Composition

`BatchContainerControlsCard` is a thin shell that renders `ContentBox` (with the batch or single title) wrapping `ContainerControlsBox`. Use `ContainerControlsBox` directly if you need to drive the controls from props instead of the adapter store.

#### Styling

- `.mdk-batch-container-controls-card`: root element
- `.mdk-batch-container-controls-card__controls`: controls wrapper inside the content box

### `ContainerControlsBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | Container device data |
| `isBatch` | Optional | `boolean` | `false` | Enable batch operations mode |
| `selectedDevices` | Optional | `Device[]` | `[]` | Selected devices for batch operations |
| `pendingSubmissions` | Optional | `PendingSubmission[]` | `[]` | Pending action submissions |
| `alarmsDataItems` | Optional | `TimelineItemData[]` | `[]` | Active alarms to display |
| `tailLogData` | Optional | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord)`[]` | none | Tail log data for power modes |
| `onNavigate` | Required | `function` | none | Navigation handler |

#### Basic usage

```tsx
<ContainerControlsBox
  data={container}
  onNavigate={(path) => router.push(path)}
/>
```

#### Batch operations

```tsx
<ContainerControlsBox
  isBatch
  selectedDevices={selectedContainers}
  pendingSubmissions={pending}
  alarmsDataItems={alarms}
  onNavigate={handleNavigate}
/>
```

#### Container type features

The component automatically adapts based on container type:

- **Bitdeer**: Start/Stop, Reset Alarm, Tank 1/2 toggles, Air Exhaust toggle, Socket controls
- **Bitmain Hydro**: Start/Stop Cooling, PID Mode display
- **Bitmain Immersion**: Start/Stop Cooling, PID Mode, Running Mode, System Status
- **MicroBT**: Start/Stop Cooling, Socket controls

#### Styling

- `.mdk-container-controls-box`: Root element
- `.mdk-container-controls-box__buttons-row`: Action buttons row
- `.mdk-container-controls-box__toggles-row`: Toggle switches row
- `.mdk-container-controls-box__toggle`: Individual toggle container
- `.mdk-container-controls-box__bulk-row`: Bulk action buttons row

# Fleet management (/reference/ui/react/foundation/operations/details-view/fleet-management)

Dialogs that orchestrate the miner lifecycle launched from the details view: registering a new miner in an empty socket, replacing an existing miner, moving a miner to or from maintenance, changing position between sockets, and permanently removing a miner.

For miner identity, see the [details view overview](/reference/ui/react/foundation/operations). For the buttons that open most of these dialogs, see [Controls](/reference/ui/react/foundation/operations/details-view/controls).

## Prerequisites

<Accordions>
    <Accordion title="Adapter store hooks required by these dialogs">
      - All dialogs queue position, maintenance, and removal updates through `useActions()`
      - Submissions are validated against existing pending entries, so pending submissions from `useActions()` must be readable
      - The host application is responsible for draining the pending queue and submitting the action batch upstream
    </Accordion>
  </Accordions>

- A miner [`Device`](/reference/app-toolkit/ui-devkit/types#device) record (or socket payload containing one) passed in via dialog props

<Accordions>
    <Accordion title="Socket payload shape these dialogs read">
      - `selectedEditSocket` and `selectedSocketToReplace` are socket payloads from the device explorer, each carrying a `miner` (`Device`), a `containerInfo` object holding `container`, plus `pos` and `socket` strings
      - The dialogs read `miner.code`, `miner.tags`, `miner.rack`, `miner.id`, and `miner.info` for short-codes, position text, and the dispatched payload
    </Accordion>
  </Accordions>

- The notification helpers from `@tetherto/mdk-react-devkit/foundation` wired up; submit actions fire info or success notifications

## Components

### `PositionChangeDialog`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Controls dialog visibility |
| `onClose` | Required | `function` | none | Called when the dialog closes; receives the active flow key so callers can decide whether to reset selection state |
| `selectedSocketToReplace` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the destination socket in a position-change or replace flow |
| `selectedEditSocket` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the miner being edited, replaced, or moved |
| `onChangePositionClicked` | Required | `function` | none | Fired when the user picks "Change position" in the default flow |
| `onPositionChangedSuccess` | Required | `function` | none | Fired after a successful confirm-change-position submission |
| `isContainerEmpty` | Optional | `boolean` | `false` | Hint for the container-selection step that the destination container has no occupied sockets |
| `dialogFlow` | Optional | `string` | `''` | Initial flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/reference/app-toolkit/ui-devkit/constants#position_change_dialog_flows); when omitted the default chooser is shown |

#### Internal flows

The dialog routes between step-specific surfaces based on the active `dialogFlow` value:

| Flow key | Surface rendered |
|----------|------------------|
| `confirmChange` | `ConfirmChangePositionDialogContent` |
| `containerSelection` | `ContainerSelectionDialogContent` |
| `replaceMiner`, `changeInfo` | `AddReplaceMinerDialogContent` |
| `confirmRemove` | `RemoveMinerDialogContent` |
| `maintenance` | `MaintenanceDialogContent` |
| _none_ | `DefaultPositionChangeDialogContent` chooser |

When both `selectedSocketToReplace` and `selectedEditSocket` are set, the dialog auto advances to the `confirmChange` flow.

#### Basic usage

```tsx
const [open, setOpen] = useState(false)

<PositionChangeDialog
  open={open}
  onClose={() => setOpen(false)}
  selectedEditSocket={selectedEditSocket}
  dialogFlow={POSITION_CHANGE_DIALOG_FLOWS.CHANGE_INFO}
  onPositionChangedSuccess={() => refetchInventory()}
/>
```

#### Move-to-maintenance flow

```tsx
<PositionChangeDialog
  open={open}
  onClose={handleClose}
  selectedEditSocket={selectedEditSocket}
  dialogFlow={POSITION_CHANGE_DIALOG_FLOWS.MAINTENANCE}
/>
```

#### Styling

- `.mdk-position-change-dialog`: Root dialog element

### `AddReplaceMinerDialog`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Controls dialog visibility |
| `onClose` | Required | `function` | none | Called when the dialog closes |
| `selectedSocketToReplace` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for the empty socket receiving a new miner |
| `selectedEditSocket` | Required | [`UnknownRecord`](/reference/app-toolkit/ui-devkit/types#unknownrecord) | none | Socket payload for an existing miner when running the change-info flow |
| `currentDialogFlow` | Required | `string` | none | Flow key from [`POSITION_CHANGE_DIALOG_FLOWS`](/reference/app-toolkit/ui-devkit/constants#position_change_dialog_flows); typically `replaceMiner` or `changeInfo` |
| `isDirectToMaintenanceMode` | Optional | `boolean` | `false` | Register the new miner straight into the maintenance container instead of the selected socket |
| `minersType` | Required | `string` | none | Restricts the form to a specific miner type (used to gate model-specific validation) |
| `isContainerEmpty` | Optional | `boolean` | none | Forwarded to internal validation when registering into an empty container |

#### Validation

- MAC and serial are validated against pending submissions before dispatch
- `isDirectToMaintenanceMode` skips the position picker and uses the maintenance container as the target

#### Basic usage

```tsx
<AddReplaceMinerDialog
  open={open}
  onClose={() => setOpen(false)}
  selectedSocketToReplace={emptySocket}
  currentDialogFlow={POSITION_CHANGE_DIALOG_FLOWS.REPLACE_MINER}
/>
```

#### Direct-to-maintenance registration

```tsx
<AddReplaceMinerDialog
  open={open}
  onClose={() => setOpen(false)}
  selectedSocketToReplace={emptySocket}
  isDirectToMaintenanceMode
/>
```

### `ContainerSelectionDialog`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Controls dialog visibility |
| `onClose` | Required | `function` | none | Called when the dialog closes |
| `miner` | Required | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | none | The miner being moved out of maintenance |
| `containers` | Optional | [`Device[]`](/reference/app-toolkit/ui-devkit/types#device) | `[]` | Candidate destination containers shown in the picker |
| `isLoading` | Optional | `boolean` | none | Shows a loading state while `containers` is being fetched |

#### Behavior

- Presets the source as the maintenance container and lets the user pick a destination container and socket
- Internally renders `ContainerSelectionDialogContent` with a synthesised `selectedSocketToReplace` of `{ miner, containerInfo: { container: 'maintenance' }, pos: '', socket: '' }`

#### Basic usage

```tsx
<ContainerSelectionDialog
  open={open}
  onClose={() => setOpen(false)}
  miner={minerUnderMaintenance}
  containers={availableContainers}
  isLoading={isContainersLoading}
/>
```

### `MaintenanceDialogContent`

This is a content body intended to be rendered inside [`PositionChangeDialog`](#positionchangedialog) (or any host `Dialog`); it does not render its own dialog chrome.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `selectedEditSocket` | Optional | `object` | none | Socket payload for the miner being moved to maintenance. Shape: `Partial<{ miner: Device, containerInfo: { container?: string } }>` |
| `onCancel` | Required | `function` | none | Called when the user cancels or after a successful submission |

#### Behavior

- Confirms the action with the miner short-code and its current container and position
- On submit, queues an update action through `useActions()` with the maintenance container, an empty `pos`, and an empty `subnet`, preserving the prior position in `posHistory`
- Fires an info notification ("Action added") and calls `onCancel`

#### Basic usage

```tsx
<MaintenanceDialogContent
  selectedEditSocket={selectedEditSocket}
  onCancel={() => setOpen(false)}
/>
```

#### Styling

- `.mdk-maintenance-confirm`: Root container
- `.mdk-maintenance-confirm__warning`: Confirmation copy
- `.mdk-maintenance-confirm__highlight`: Inline miner short-code
- `.mdk-maintenance-confirm__footer`: Cancel and confirm action row

### `RemoveMinerDialog`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `headDevice` | Optional | [`Device`](/reference/app-toolkit/ui-devkit/types#device) | `{}` | The miner being removed; the dialog reads `info.pos` for the confirmation copy |
| `isRemoveMinerFlow` | Required | `boolean` | none | Controls dialog visibility |
| `onCancel` | Required | `function` | none | Called when the user cancels or after a successful submission |

#### Behavior

- Wraps `RemoveMinerDialogContent` inside a `Dialog` with the title "Are you sure to permanently remove miner?"
- On confirm, queues the remove action through `useActions()` for the head device

#### Basic usage

```tsx
<RemoveMinerDialog
  headDevice={selectedMiner}
  isRemoveMinerFlow={isRemoveOpen}
  onCancel={() => setRemoveOpen(false)}
/>
```

# Stats (/reference/ui/react/foundation/operations/details-view/stats)

Single-value and grouped stat cards plus the combined miner metric layout used by the details view.

For miner identity (`MinerInfoCard`), see the [details view overview](/reference/ui/react/foundation/operations). For fleet activity visualizations, see [Charts](/reference/ui/react/foundation/operations/details-view/charts). For per-chip thermal data, see [Chips](/reference/ui/react/foundation/operations/details-view/chips).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- Components on this page read live metrics from `device.last.snap.stats` on a [`Device`](/reference/app-toolkit/ui-devkit/types#device)

<Accordions>
    <Accordion title="Metric fields and adapter store hooks">
      - Hash rate in MH/s, temperature in °C, frequency in MHz, and power in W
      - `StatsGroupCard` additionally requires `useDevices()` so the current device selection is available
    </Accordion>
  </Accordions>

## Components

### `SingleStatCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `name` | Optional | `string` | none | Stat label |
| `subtitle` | Optional | `string` | `''` | Secondary label rendered below the name |
| `value` | Optional | `number \| string \| null` | `null` | Stat value; a tooltip is shown when `value` is set |
| `unit` | Optional | `string` | `''` | Unit suffix; combined with `value` via [`formatValueUnit`](/reference/app-toolkit/ui-devkit/utilities#formatvalueunit) |
| `color` | Optional | `string` | `'inherit'` | CSS color applied via the `--stat-color` custom property |
| `flash` | Optional | `boolean` | `false` | Apply the standard flash animation |
| `superflash` | Optional | `boolean` | `false` | Apply the faster flash animation |
| `tooltipText` | Optional | `string` | `''` | Override for the tooltip label (defaults to `name`) |
| `variant` | Optional | `'primary' \| 'secondary' \| 'tertiary' \| 'highlighted'` | `'primary'` | Layout variant |
| `row` | Optional | `boolean` | `false` | Stack name and value horizontally |

A tooltip is rendered automatically whenever `value` is set; pass `tooltipText` to override the label portion. Values longer than six characters get a `--long-value` modifier for narrower number formatting.

Use `primary` through `tertiary` for explorer and device metrics. Use `highlighted` for financial or reporting summary metric strips (same presentation as OSS **MetricCard** `$isHighlighted`, for example EBITDA sell-scenario tiles: large emphasized value, subdued label).

#### Basic usage

```tsx
<SingleStatCard name="Temperature" value={42} unit="°C" />
<SingleStatCard name="Hash rate" value="95.5" unit="TH/s" />
<SingleStatCard name="Uptime" value="99.7" unit="%" />
```

#### Variants

```tsx
<SingleStatCard name="Temperature" value={42} unit="°C" variant="primary" />
<SingleStatCard name="Fan speed" value={4200} unit="RPM" variant="secondary" />
<SingleStatCard name="Power" value={3250} unit="W" variant="tertiary" />
```

#### Highlighted (reporting metrics)

```tsx
<SingleStatCard name="Revenue" value={4.2} unit="M$" variant="highlighted" />
<SingleStatCard name="OpEx" value={1.8} unit="M$" variant="highlighted" />
<SingleStatCard
  name="(Sell scenario - all BTC sold)"
  value={-123.123}
  unit="$"
  variant="highlighted"
  color="#FF8C42"
/>
<SingleStatCard name="Margin" value={57} unit="%" variant="highlighted" />
```

#### Alerts with flash

```tsx
<SingleStatCard name="Temperature" value={92} unit="°C" color="red" flash />
<SingleStatCard name="Status" value="Overheat" color="#ff0000" superflash />
```

#### Row layout

```tsx
<SingleStatCard name="Efficiency" value="32.5" unit="J/TH" row />
```

#### Styling

- `.mdk-single-stat-card`: root element
- `.mdk-single-stat-card--primary`, `--secondary`, `--tertiary`, `--highlighted`: layout variants (`--highlighted` uses a large bold value via `--stat-color`, muted name and subtitle)
- `.mdk-single-stat-card--flash`, `--superflash`: animation modifiers
- `.mdk-single-stat-card--row`: row layout
- `.mdk-single-stat-card--long-value`: applied automatically when value exceeds 6 characters
- `.mdk-single-stat-card__name`, `__subtitle`, `__value`, `__text`: inner elements

### `SecondaryStatCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `name` | Optional | `string` | `''` | Stat label |
| `value` | Optional | `string \| number` | `''` | Stat value |
| `className` | Optional | `string` | none | Additional class merged onto the root |

#### Basic usage

```tsx
<SecondaryStatCard name="Hash rate" value="95.5 TH/s" />
<SecondaryStatCard name="Uptime" value={99.8} />
<SecondaryStatCard name="Efficiency" value="92%" />
```

#### Styling

- `.mdk-secondary-stat-card`: root element
- `.mdk-secondary-stat-card__name`: stat label
- `.mdk-secondary-stat-card__value`: stat value

### `StatsGroupCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `miners` | Optional | `Device[] \| DeviceData[]` | none | Devices to aggregate for stat values; falls back to the adapter store selection from `useDevices()` when omitted |
| `isMinerMetrics` | Optional | `boolean` | `false` | When `true`, renders `MinerMetricCard` instead of the default `SingleStatCard` grid |

#### Aggregated stats

Primary stats (always rendered):

- **Hash rate**: sum of `snap.stats.hashrate_mhs.t_5m` across the selection, formatted via `getHashrateUnit`
- **Temperature**: max of `snap.stats.temperature_c.max`, in °C
- **Frequency**: average of `snap.stats.frequency_mhz.avg`, in MHz
- **Consumption**: sum of `snap.stats.power_w` (suppressed for miner types where power is not reported)
- **Efficiency**: derived `consumption / hash rate` in J/TH, only when both are present

Secondary stats depend on layout mode:

- **Default grid layout** (`isMinerMetrics={false}`): a second row of `SecondaryStatCard`s when the effective selection (`miners` or the `useDevices()` fallback) has **length 1** (any device type). Values come from the first entry in that set.
- **Miner-metrics layout** (`isMinerMetrics={true}`): secondary stats inside `MinerMetricCard` only when the adapter store selection from `useDevices()` contains **exactly one** device whose `type` satisfies `isMiner` (prefix `miner-`). Passing `miners={…}` alone does not enable the secondary strip. Vendor types such as `antminer-s19` are not counted unless `type` uses the `miner-` prefix.

#### Basic usage

```tsx
<StatsGroupCard miners={selectedMiners} />
```

#### Render with the miner metric layout

```tsx
<StatsGroupCard isMinerMetrics />
```

When `isMinerMetrics` is true, wire device selection through `useDevices()` and use `miner-*` device types if you need the secondary strip; see **Aggregated stats** above.

#### Styling

- `.mdk-stats-group-card`: root element
- `.mdk-stats-group-card__row`: stat row container

### `MinerMetricCard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `primaryStats` | Optional | `StatItem[]` | none | Primary metrics keyed by fixed labels (see below) |
| `secondaryStats` | Optional | `StatItem[]` | none | Free-form stats rendered in the optional secondary grid |
| `showSecondaryStats` | Optional | `boolean` | `true` | When `false`, hides the secondary stats grid |

The `StatItem` type is exported from the same module:

```tsx
type StatItem = {
  name?: string
  value?: number | string
  unit?: string
  tooltipText?: string
}
```

#### Recognised primary stat names

`primaryStats` is read by name. Unknown entries are ignored; only these labels render:

- `Efficiency`: rendered top-right. Hidden if value is undefined or non-numeric.
- `Hash rate`: top-left primary box
- `Temperature`: top-right primary box. Also drives the displayed Frequency value (the source rounds and formats the temperature value as a Frequency stand-in; pass both stats explicitly to keep them aligned).
- `Frequency`: bottom-left primary box (uses the formatted `Temperature` numeric for backwards-compat with upstream callers)
- `Consumption`: bottom-right primary box. Formatted with three decimals; falls back to `kWh` unit when value is `0`.

#### Basic usage

```tsx
<MinerMetricCard
  primaryStats={[
    { name: 'Efficiency', value: 32.5, unit: 'J/TH' },
    { name: 'Hash rate', value: 95.5, unit: 'TH/s' },
    { name: 'Temperature', value: 65, unit: '°C' },
    { name: 'Frequency', value: 500, unit: 'MHz' },
    { name: 'Consumption', value: 3.25, unit: 'kW' },
  ]}
  secondaryStats={[
    { name: 'Fan speed', value: '6000 RPM' },
    { name: 'Uptime', value: '3 days' },
  ]}
/>
```

#### Hide the secondary grid

```tsx
<MinerMetricCard
  primaryStats={primaryStats}
  secondaryStats={[]}
  showSecondaryStats={false}
/>
```

#### Styling

- `.mdk-miner-metric-card`: root element
- `.mdk-miner-metric-card__title`: card title (`Miner Metrics`)
- `.mdk-miner-metric-card__body`: layout wrapper
- `.mdk-miner-metric-card__efficiency`: top-right efficiency block
- `.mdk-miner-metric-card__content`: primary and secondary stat grid
- `.mdk-miner-metric-card__box`: pair of primary stat items
- `.mdk-miner-metric-card__item`: single label/value cell
- `.mdk-miner-metric-card__label`: stat label
- `.mdk-miner-metric-card__value`: stat value
- `.mdk-miner-metric-card__grid-box`: secondary stats grid

# Device explorer (/reference/ui/react/foundation/operations/device-explorer)

The device explorer is the primary navigation surface for browsing containers, racks, and miners. It combines a filter `Cascader`, a tag-based search, device-type tabs, and a selectable data table so operators can drill into fleet inventory.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

### `DeviceExplorer`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `deviceType` | Required | `'container' \| 'miner' \| 'cabinet'` | required | Current view type |
| `data` | Required | `Device[]` | none | Array of devices to display |
| `filterOptions` | Required | `DeviceExplorerFilterOption[]` | none | `Cascader` filter options |
| `searchOptions` | Required | `DeviceExplorerSearchOption[]` | none | Search autocomplete options |
| `searchTags` | Required | `string[]` | none | Current search tags |
| `onSearchTagsChange` | Required | `function` | none | Search tags change handler |
| `onDeviceTypeChange` | Required | `function` | none | Device type tab change handler |
| `onFiltersChange` | Required | `function` | none | Filter change handler |
| `selectedDevices` | Optional | `DataTableRowSelectionState` | `{}` | Selected row state |
| `onSelectedDevicesChange` | Optional | `function` | none | Selection change handler |
| `renderAction` | Optional | `function` | none | Custom action column renderer |
| `getFormattedDate` | Required | `function` | none | Date formatter function |
| `className` | Optional | `string` | none | Additional CSS class |

#### Basic usage

```tsx
<DeviceExplorer
  deviceType="container"
  data={containers}
  filterOptions={[
    { value: 'site-a', label: 'Site A' },
    { value: 'site-b', label: 'Site B' },
  ]}
  searchOptions={[
    { value: 'container-001', label: 'Container 001' },
  ]}
  searchTags={searchTags}
  onSearchTagsChange={setSearchTags}
  onDeviceTypeChange={setDeviceType}
  onFiltersChange={handleFilters}
  getFormattedDate={(date) => date.toLocaleDateString()}
/>
```

#### With selection

```tsx
<DeviceExplorer
  deviceType="miner"
  data={miners}
  filterOptions={filterOptions}
  searchOptions={searchOptions}
  searchTags={[]}
  onSearchTagsChange={setSearchTags}
  onDeviceTypeChange={setDeviceType}
  onFiltersChange={handleFilters}
  selectedDevices={selected}
  onSelectedDevicesChange={setSelected}
  getFormattedDate={formatDate}
  renderAction={(device) => (
    <Button size="sm" onClick={() => viewDetails(device.id)}>
      View
    </Button>
  )}
/>
```

#### Styling

- `.mdk-device-explorer`: Root element
- `.mdk-device-explorer__toolbar`: Toolbar container
- `.mdk-device-explorer__toolbar__filter`: Filter `Cascader`
- `.mdk-device-explorer__toolbar__search`: Search input
- `.mdk-device-explorer__toolbar__tabs`: Device type tabs
- `.mdk-device-explorer__toolbar__tabs-list`: Tabs list container
- `.mdk-device-explorer__toolbar__tab-trigger`: Individual tab trigger

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useGetAvailableDevices`](/reference/app-toolkit/hooks/components#usegetavailabledevices) | Transforms the device list into available container and miner type sets consumed by `<DeviceExplorer />` |

## Next steps

- For selecting and acting on an individual device, see the [details view](/reference/ui/react/foundation/operations/details-view) pages.
- For container-level controls alongside the explorer, see [`ContainerControlsBox`(../details-view/controls#containercontrolsbox) on the Controls page.

# Pool Manager (/reference/ui/react/foundation/pool-manager)

The Pool Manager section provides UI for landing, exploring miners, and managing pool configurations. It is rendered as a top-level product area with three sibling workflows.

## Prerequisites

<Accordions>
    <Accordion title="Adapter store hooks used across these components">
      - `PoolManagerMinerExplorer` reads pool configs through `usePoolConfigs` and queues miner-action events through `useActions()`
      - `PoolManagerPools` reads and mutates pool configuration state through `useActions()`; formatting relies on `useTimezone()` for display-local timestamps
      - The standalone dashboard has no adapter store dependencies
    </Accordion>
  </Accordions>

## Component groups

The section is split into five subpages plus this index:

- [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard): landing page composing stats, navigation blocks, and a recent alerts feed
- [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer): cross-pool miner browser with filter, search, and selection; used to assign miners to pool configurations
- [Pools](/reference/ui/react/foundation/pool-manager/pools): pools page with the collapsible pool list and the **Add Pool** dialog for authoring new pool configurations
- [Sites overview](/reference/ui/react/foundation/pool-manager/sites-overview): multi-site landing screen showing every site as a status card with pool assignment, miner counts, and hashrate
- [Site overview details](/reference/ui/react/foundation/pool-manager/site-overview-details): rack-level miner grid detail view for a single site with drag-to-select and pool assignment

## All pool manager components

# Assign pool (/reference/ui/react/foundation/pool-manager/assign-pool)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

`AssignPoolModal` opens from the miner explorer to let operators assign a configured pool to one or more selected miners. It shows the selected miner list, a pool selector with live metadata, an endpoints preview, and an optional credential template preview. Submission is async; the modal stays open with a loading state until the parent resolves.

For the miner selection surface see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For pool authoring see [Pools](/reference/ui/react/foundation/pool-manager/pools).

## Prerequisites

## Components

### `AssignPoolModal`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isOpen` | Required | `boolean` | none | Controls dialog visibility |
| `onClose` | Required | `function` | none | Called when the user cancels or closes the dialog |
| `onSubmit` | Required | `function` | none | Async handler called on form submission; modal stays open with a loading state until the promise resolves |
| `miners` | Required | `Device[]` | none | Selected miners to assign; displayed in the miner summary table |
| `poolConfig` | Required | `PoolConfigData[]` | none | Pool configuration data from your API layer |

#### `PoolConfigData` type

The input shape passed to `poolConfig`. Each entry maps to one option in the pool selector.

```tsx
type PoolConfigData = {
  id: string
  poolConfigName: string
  description: string
  poolUrls: Array<{
    url: string
    pool: string
    workerName?: string
    workerPassword?: string
  }>
  miners: number
  containers: number
  updatedAt: string | number  // Unix timestamp (ms) or ISO string
}
```

#### `PoolSummary` type

The resolved pool object passed back through `onSubmit`.

```tsx
type PoolSummary = {
  id: string
  name: string
  description: string
  units: number
  miners: number
  workerName: string | undefined
  workerPassword: string | undefined
  endpoints: PoolEndpoint[]
  validation?: { status: string }
  updatedAt: Date
}

type PoolEndpoint = {
  role?: string   // Primary, Failover, etc.
  host: string
  port: string
  pool: string
  url?: string
}
```

#### Basic usage

```tsx

const poolConfig: PoolConfigData[] = [
  {
    id: 'pool-1',
    poolConfigName: 'Alpha Pool',
    description: 'Primary pool with failover',
    poolUrls: [
      { url: 'stratum+tcp://pool-primary.example.com:3333', pool: 'pool1', workerName: 'wn-1', workerPassword: 'x' },
      { url: 'stratum+tcp://pool-failover.example.com:3333', pool: 'pool1', workerName: 'wn-1', workerPassword: 'x' },
    ],
    miners: 120,
    containers: 4,
    updatedAt: Date.now(),
  },
]

const [isOpen, setIsOpen] = useState(false)
  const [selectedMiners, setSelectedMiners] = useState<Device[]>([])

const handleSubmit = async ({ pool }: { pool: PoolSummary }) => {
    await yourApi.assignMinersToPool(selectedMiners.map(m => m.id), pool.id)
    setIsOpen(false)
  }

return (
    <>
      <button onClick={() => setIsOpen(true)}>Assign Pool</button>
      <AssignPoolModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onSubmit={handleSubmit}
        miners={selectedMiners}
        poolConfig={poolConfig}
      />
    </>
  )
}
```

#### Behaviour

The modal renders three sections:

1. **Selected miners** — a `DataTable` showing each miner's short code, unit, current pool assignment, and status. Row count is shown in the section header.
2. **Choose pool** — a `FormSelect` dropdown built from `poolConfig`. On selection, a metadata row appears showing unit count, miner count, and last-updated time (displayed as a relative string via `intlFormatDistance`). Below the metadata, an **Endpoints Preview** lists each endpoint with its role label (Primary, Failover), host, and port.
3. **Credential template preview** (optional) — shown only when the `SHOW_CREDENTIAL_TEMPLATE` feature flag is enabled.

The **Assign** button is disabled during submission and shows "Assigning…" while the `onSubmit` promise is pending. The form resets automatically after a successful submission.

A `Loader` replaces the form body while pool configs are loading; a `CoreAlert` error is shown if pool config loading fails.

#### Styling

- `.mdk-pm-assign-pool-modal`: Root dialog element
- `.mdk-pm-assign-pool-modal__body`: Form body container
- `.mdk-pm-assign-pool-modal__section`: Each labelled content section
- `.mdk-pm-assign-pool-modal__section-header`: Section header row (title + optional value)
- `.mdk-pm-assign-pool-modal__section-title`: Section label text
- `.mdk-pm-assign-pool-modal__section-value`: Section summary value (e.g. "3 miners selected")
- `.mdk-pm-assign-pool-modal__pool-meta`: Metadata row shown after a pool is selected
- `.mdk-pm-assign-pool-modal__endpoints-list`: Endpoints preview list container
- `.mdk-pm-assign-pool-modal__endpoint`: Single endpoint row
- `.mdk-pm-assign-pool-modal__endpoint-role`: Endpoint role label wrapper
- `.mdk-pm-assign-pool-modal__endpoint-role-name`: Role label text
- `.mdk-pm-assign-pool-modal__endpoint-fields`: Host and port fields wrapper
- `.mdk-pm-assign-pool-modal__endpoint-host`: Endpoint hostname
- `.mdk-pm-assign-pool-modal__endpoint-port`: Endpoint port
- `.mdk-pm-assign-pool-modal__credential-template`: Credential template preview section
- `.mdk-pm-assign-pool-modal__footer`: Dialog footer containing Cancel and Assign buttons

# Dashboard (/reference/ui/react/foundation/pool-manager/dashboard)

The Pool Manager dashboard aggregates pool health stats, quick-navigation blocks into the miner explorer and pools workflows, and a feed of recent alerts. It is the entry point rendered when operators land on the Pool Manager area.

For miner-to-pool assignment, see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For pool and endpoint management, see [Pools](/reference/ui/react/foundation/pool-manager/pools).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Components

### `PoolManagerDashboard`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `stats` | Optional | `DashboardStats` | none | Dashboard statistics |
| `isStatsLoading` | Optional | `boolean` | `false` | Stats loading state |
| `alerts` | Optional | `Alert[]` | `[]` | Recent alerts list |
| `onNavigationClick` | Required | `function` | none | Navigation handler |
| `onViewAllAlerts` | Required | `function` | none | View all alerts handler |

#### `DashboardStats` type

```tsx
type StatItem = {
  label: string
  value: number
  type?: 'ERROR' | 'SUCCESS'
  secondaryValue?: string
}

type DashboardStats = {
  items: StatItem[]
}
```

#### Basic usage

```tsx
<PoolManagerDashboard
  stats={{
    items: [
      { label: 'Active Pools', value: 3, type: 'SUCCESS' },
      { label: 'Total Miners', value: 150 },
      { label: 'Offline', value: 2, type: 'ERROR' },
    ],
  }}
  alerts={recentAlerts}
  onNavigationClick={(url) => router.push(url)}
  onViewAllAlerts={() => router.push('/alerts')}
/>
```

#### Loading state

```tsx
<PoolManagerDashboard
  isStatsLoading
  alerts={[]}
  onNavigationClick={handleNav}
  onViewAllAlerts={handleViewAlerts}
/>
```

#### Dashboard sections

The component displays:
1. **Stats blocks**: Key metrics with optional success/error indicators
2. **Navigation blocks**: Quick links to pool management features
3. **Recent alerts**: Latest alerts with severity indicators

#### Styling

- `.mdk-pm-dashboard`: Root element
- `.mdk-pm-dashboard__stat-blocks`: Stats container
- `.mdk-pm-dashboard__stat-block`: Individual stat block
- `.mdk-pm-dashboard__stat-header`: Stat header with label and status
- `.mdk-pm-dashboard__stat-label`: Stat label text
- `.mdk-pm-dashboard__stat-status`: Status indicator
- `.mdk-pm-dashboard__stat-value-row`: Value container
- `.mdk-pm-dashboard__stat-value`: Primary value
- `.mdk-pm-dashboard__stat-secondary`: Secondary value
- `.mdk-pm-dashboard__nav-blocks`: Navigation blocks container
- `.mdk-pm-dashboard__nav-block`: Individual navigation block
- `.mdk-pm-dashboard__nav-header`: Block header with icon
- `.mdk-pm-dashboard__nav-icon`: Block icon
- `.mdk-pm-dashboard__nav-title`: Block title
- `.mdk-pm-dashboard__nav-description`: Block description
- `.mdk-pm-dashboard__nav-action`: Action button
- `.mdk-pm-dashboard__alerts-wrapper`: Alerts section container
- `.mdk-pm-dashboard__alerts-title`: Alerts heading
- `.mdk-pm-dashboard__alerts`: Alerts list
- `.mdk-pm-dashboard__alert-row`: Individual alert row
- `.mdk-pm-dashboard__alert-text`: Alert text content
- `.mdk-pm-dashboard__alert-status`: Alert severity indicator
- `.mdk-pm-dashboard__alerts-empty`: Empty alerts message

## Related hooks

| Hook | Purpose |
|------|---------|
| [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate per-pool stats into site-level totals surfaced by the stats strip |
| [`useActiveIncidents`](/reference/app-toolkit/hooks/data#useactiveincidents) | Fetch the live list of currently-firing alerts for the alerts panel |
| [`useSitesOverviewData`](/reference/app-toolkit/hooks/data#usesitesoverviewdata) | Project container rows and pool stats into the sites overview view-model |

## Next steps

- For pool summary widgets that surface on the top-level operations dashboard, see
[`PoolDetailsCard`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#pooldetailscard) and [`PoolDetailsPopover`](/reference/ui/react/foundation/dashboard/stats/generic-widgets#pooldetailspopover).

# Miner explorer (/reference/ui/react/foundation/pool-manager/miner-explorer)

Surface for browsing miners across the fleet and assigning them to pool configurations. `PoolManagerMinerExplorer` is the plug-and-play feature composite that the demo ships with.

For pool configuration authoring, see [Pools](/reference/ui/react/foundation/pool-manager/pools). For the Pool Manager landing surface, see [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up (used by `PoolManagerMinerExplorer` to queue `SETUP_POOLS` actions)
- Pool configuration data (`PoolConfigData[]`) and miner `Device[]` arrays. The `Device` shape is documented in [reference types](/reference/app-toolkit/ui-devkit/types)

## Components

### `PoolManagerMinerExplorer`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `miners` | Required | `Device[]` | none | Fleet miners to browse |
| `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations used for the pool filter and assign flow |
| `backButtonClick` | Required | `function` | none | Fires when the operator clicks the "Pool Manager" back link |

#### Behaviour

- Renders a page header with title, a back link, and an **Assign Pool** button gated by the `ACTION_TYPES.SETUP_POOLS` permission
- Lists miners across the fleet with filter, search, and multi-select
- On submit, queues a submission through `useActions()` with the selected miners and the chosen pool, then resets the selection
- The Assign Pool button is hidden when the `ASSIGN_POOL_POPUP_ENABLED` feature flag is off

#### Basic usage

```tsx
<PoolManagerMinerExplorer
  miners={fleetMiners}
  poolConfig={poolConfigs}
  backButtonClick={() => router.push('/pool-manager')}
/>
```

#### Styling

- `.mdk-pm-miner-explorer-page`: Root element
- `.mdk-pm-miner-explorer-page__header`: Title and action row
- `.mdk-pm-miner-explorer-page__title`: Page title
- `.mdk-pm-miner-explorer-page__subtitle`: Back-link wrapper
- `.mdk-pm-miner-explorer-page__back-link`: Back link button

# Pools (/reference/ui/react/foundation/pool-manager/pools)

Authoring UI for mining pools. `PoolManagerPools` is the plug-and-play feature composite used by the demo; it opens an internal pool-authoring dialog on demand when the **Add Pool** button is clicked.

For miner-to-pool assignment via the explorer, see [Miner explorer](/reference/ui/react/foundation/pool-manager/miner-explorer). For the landing surface, see [Dashboard](/reference/ui/react/foundation/pool-manager/dashboard).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up. `PoolManagerPools` queues pool-config actions through the adapter store
- Pool configuration data (`PoolConfigData[]`) sourced from your API layer
- Feature flags that gate optional controls: `ADD_POOL_ENABLED`, `SHOW_CREDENTIAL_TEMPLATE`, `SHOW_POOL_VALIDATION` (re-exported from `@tetherto/mdk-react-devkit/foundation`)

## Components

### `PoolManagerPools`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `poolConfig` | Required | `PoolConfigData[]` | none | Pool configuration source; hydrated by `usePoolConfigs` |
| `backButtonClick` | Required | `function` | none | Fires when the operator clicks the "Pool Manager" back link |

#### Behaviour

- Renders a page header (title + back link) with an **Add Pool** button gated by the `ADD_POOL_ENABLED` flag
- Shows a loader while `usePoolConfigs` is loading, or a `CoreAlert` on error
- Lists every pool in a collapsible accordion: each row shows the pool name, description, unit/miner counts, and a validation badge; expanding a row reveals the endpoints list, credentials template, and a Test Configuration action
- Opens an internal pool-authoring dialog when the **Add Pool** button is clicked

#### Basic usage

```tsx
<PoolManagerPools
  poolConfig={poolConfigs}
  backButtonClick={() => router.push('/pool-manager')}
/>
```

#### Styling

- `.mdk-pm-pools`: Root element
- `.mdk-pm-pools__header`: Title and action row
- `.mdk-pm-pools__header-title`: Page title
- `.mdk-pm-pools__back-link`: Back link button
- `.mdk-pm-pools__accordion`: Accordion root
- `.mdk-pm-pools__accordion-item`, `.mdk-pm-pools__accordion-trigger`, `.mdk-pm-pools__accordion-content`: Accordion parts

## Related hooks

| Hook | Purpose |
|------|---------|
| [`usePoolRows`](/reference/app-toolkit/hooks/data#usepoolrows) | Fetch per-pool stats and transform them into `PoolRow[]` objects for the pool manager table |
| [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate per-pool stats into site-level totals (workers, mismatch count, hashrate) |
| [`usePoolConfigs`](/reference/app-toolkit/hooks/components#usepoolconfigs) | Map caller-provided query data into `PoolSummary[]` for pool summary display |

# Site overview details (/reference/ui/react/foundation/pool-manager/site-overview-details)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

`PoolManagerSiteOverviewDetails` is the detail view for a single container site in the Pool Manager. It renders a rack/PDU miner grid, a status legend, and a pool-assignment panel. Operators can multi-select miners by dragging a rectangle over socket cells, then assign pool configurations from the sidebar or modal.

For the site card grid that navigates here see [Sites overview](/reference/ui/react/foundation/pool-manager/sites-overview). For the miner-level assign dialog see [Assign pool](/reference/ui/react/foundation/pool-manager/assign-pool).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` wired up
- Site data as a `Device` row from your API layer
- Pool configuration data (`PoolConfigData[]`) from your API layer
- Optionally, `useSiteOverviewDetailsData` from `@tetherto/mdk-react-adapter` to supply `dataOptions`

## Components

### `PoolManagerSiteOverviewDetails`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `unit` | Required | `Device` | none | The site (container unit) to render details for |
| `unitName` | Required | `string` | none | Display name shown in the breadcrumb (`Site Overview / <unitName>`) |
| `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations powering the per-pool detail rows |
| `dataOptions` | Optional | `SiteOverviewDetailsDataOptions` | none | Data-fetch knobs forwarded to `useSiteOverviewDetailsData` |
| `isLoading` | Optional | `boolean` | `false` | Show a centered loader instead of the detail container |
| `backButtonClick` | Required | `VoidFunction` | none | Called when the operator clicks the "Site Overview" back link |

#### Basic usage

```tsx

<PoolManagerSiteOverviewDetails
    unit={site}
    unitName={site.name}
    poolConfig={poolConfig}
    isLoading={isLoading}
    backButtonClick={() => router.push('/pool-manager/sites')}
  />
)
```

#### More examples

```tsx
<PoolManagerSiteOverviewDetails
  unit={site}
  unitName={site.name}
  poolConfig={[]}
  isLoading={true}
  backButtonClick={handleBack}
/>
```

</Accordion>
  <Accordion title="With data options">

```tsx

const { dataOptions } = useSiteOverviewDetailsData({ unit: site })

<PoolManagerSiteOverviewDetails
  unit={site}
  unitName={site.name}
  poolConfig={poolConfig}
  dataOptions={dataOptions}
  backButtonClick={handleBack}
/>
```

</Accordion>
</Accordions>

#### Behaviour

The component renders a breadcrumb header (`Site Overview / <unitName>`) with a back link, then delegates the body to the internal `SiteOverviewDetailsContainer`.

The container renders:

- A rack/PDU miner grid (`GridUnit`) with each socket showing hashrate, status color, and socket ID
- A status legend
- A pool-assignment panel when miners are selected:
  - **Desktop**: sticky sidebar column with `SetPoolConfiguration`
  - **Tablet**: a fixed FAB button that opens `SetPoolConfigurationModal`

On submission the selected miners are queued as a `SETUP_POOLS` action through `useActions().setAddPendingSubmissionAction`, and the selection is cleared. Only miners in `mining` or `not_mining` status are eligible for pool assignment.

A `Loader` is shown while `isLoading` is true.

## Miner selection

Miners are selected using [`react-selecto`](https://github.com/daybrush/selecto). Selection is always available once the grid has loaded — no prop is required to enable it.

### Interaction reference

| Interaction | Result |
|-------------|--------|
| Drag a rectangle | Selects all miner socket cells intersected by the rectangle |
| Click a socket | Selects that single miner |
| Shift + click or drag | Adds to the current selection |
| Click a rack bar | Selects all miners in that rack |
| Control / Command + click a rack bar | Deselects all miners in that rack |
| **Select All** (header button) | Selects every miner in the grid |
| **Deselect All** (header button) | Clears the selection |

Empty sockets (no connected miner) are not selectable.

## Styling

### `PoolManagerSiteOverviewDetails` (feature wrapper)

- `.mdk-pm-sod`: Root element
- `.mdk-pm-sod__header`: Breadcrumb header row
- `.mdk-pm-sod__title`: "Site Overview" label
- `.mdk-pm-sod__subtitle`: Back-link wrapper
- `.mdk-pm-sod__back-link`: "Site Overview" back button

### `SiteOverviewDetailsContainer` (inner container)

- `.mdk-sodc`: Flex row wrapping rack column and sticky column
- `.mdk-sodc__racks-col`: Rack grid column; narrows when a sticky sidebar is visible
- `.mdk-sodc__racks-col--narrow`: Applied when miners are selected and the sidebar is shown (desktop)
- `.mdk-sodc__sticky-col`: Sticky pool-assignment sidebar column (desktop)
- `.mdk-sodc__tablet-btn`: Fixed FAB button (tablet, when miners are selected)

### `GridUnit` (rack grid)

- `.mdk-grid-unit`: Root of each rack/PDU grid section
- `.mdk-grid-unit__row-label`: Rack row label (`Rack {pdu}`)
- `.mdk-grid-unit__socket-container`: Selectable miner socket cell (drag-select target)
- `.mdk-grid-unit__socket-container--disabled`: Socket cell not eligible for pool assignment
- `.mdk-grid-unit__miner-box--selected`: Applied to a miner cell when selected

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useSiteOverviewDetailsData`](/reference/app-toolkit/hooks/components#usesiteoverviewdetailsdata) | Data options forwarded to the container via `dataOptions` prop |

# Sites overview (/reference/ui/react/foundation/pool-manager/sites-overview)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

`PoolManagerSitesOverview` is the multi-site landing screen for pool management. It renders every site as a status card showing pool assignment, online miner count, hashrate, and active incidents. Selecting one or more cards exposes a pool-assignment panel (sidebar on desktop, modal on tablet) backed by `useActions()`.

For the rack-level miner grid shown after selecting a site card see [Site overview details](/reference/ui/react/foundation/pool-manager/site-overview-details). For the miner-level pool assignment dialog see [Assign pool](/reference/ui/react/foundation/pool-manager/assign-pool). For the pool manager landing page see [Pool Manager overview](/reference/ui/react/foundation/pool-manager).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter` with `useActions()` and `useDeviceResolution()` wired up
- Site data normalised through `useSitesOverviewData` from `@tetherto/mdk-react-adapter`
- Pool configuration data (`PoolConfigData[]`) from your API layer

## Components

### `PoolManagerSitesOverview`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `units` | Required | `ProcessedContainerUnit[]` | none | Sites to render, normalised through `useSitesOverviewData` |
| `poolConfig` | Required | `PoolConfigData[]` | none | Pool configurations used to resolve pool names on each card |
| `isLoading` | Optional | `boolean` | none | Show a skeleton loader while site data is fetching |
| `error` | Optional | `unknown` | none | Surface a "Failed to load data" error alert when defined |
| `backButtonClick` | Required | `function` | none | Called when the operator clicks the "Pool Manager" back link |
| `onCardClick` | Required | `function` | none | Called with the clicked unit id — typically navigates to `/sites/:id` |

#### `ProcessedContainerUnit` type

Produced by `useSitesOverviewData` from `@tetherto/mdk-react-adapter`. Pass the result directly to `units`.

```tsx
type ContainerUnit = {
  id?: string
  type?: string
  info?: {
    container?: string
    nominalMinerCapacity?: string
    poolConfig?: string        // pool config id currently assigned
  }
  miners?: {
    total: number
    disconnected: number
    actualMiners: number
  }
  last?: {
    snap?: {
      stats?: { status?: string; [key: string]: unknown }
    }
  }
}

type ProcessedContainerUnit = ContainerUnit & {
  hashrateMhs: number          // per-container hashrate in MH/s
  status: 'mining' | 'offline'
  poolStats?: ContainerPoolStat
}
```

#### Basic usage

```tsx

rawUnits,
  poolStats,
  tailLog,
  poolConfig,
}: {
  rawUnits: ContainerUnit[]
  poolStats: ContainerPoolStat[]
  tailLog: SitesOverviewTailLogItem
  poolConfig: PoolConfigData[]
}) => {
  const { units } = useSitesOverviewData({ units: rawUnits, poolStats, tailLog })

return (
    <PoolManagerSitesOverview
      units={units}
      poolConfig={poolConfig}
      backButtonClick={() => router.push('/pool-manager')}
      onCardClick={(id) => router.push(`/pool-manager/sites/${id}`)}
    />
  )
}
```

#### More examples

```tsx
<PoolManagerSitesOverview
  units={[]}
  poolConfig={[]}
  isLoading={true}
  backButtonClick={handleBack}
  onCardClick={handleCardClick}
/>
```

</Accordion>
  <Accordion title="Error state">

```tsx
<PoolManagerSitesOverview
  units={[]}
  poolConfig={poolConfig}
  error={new Error('Failed to fetch sites')}
  backButtonClick={handleBack}
  onCardClick={handleCardClick}
/>
```

</Accordion>
</Accordions>

#### Behaviour

The component renders a page header ("Site Overview" title + "Pool Manager" back link) and delegates the card grid to the internal `SitesOverviewStatusCardList`.

Each site card shows:
- Container / unit name
- Assigned pool name (resolved from `poolConfig` via `usePoolConfigs`)
- Formatted hashrate
- Online miner count
- Pool override count
- Status indicator (`mining` / `offline`)

Selecting one or more cards activates a pool-assignment panel:
- **Desktop**: a sticky sidebar column with `SetPoolConfiguration`
- **Tablet**: a FAB button that opens `SetPoolConfigurationModal`

On submission the selected units are queued as a `SETUP_POOLS` action through `useActions().setAddPendingSubmissionAction`, and the selection is cleared.

A `Loader` is shown while `units` or pool configs are loading; a `CoreAlert` error is shown if either fails.

#### Styling

- `.mdk-pm-sites-overview`: Root element
- `.mdk-pm-sites-overview__header`: Title and back-link row
- `.mdk-pm-sites-overview__title`: "Site Overview" heading text
- `.mdk-pm-sites-overview__subtitle`: Back-link wrapper
- `.mdk-pm-sites-overview__back-link`: "Pool Manager" back button
- `.mdk-pm-sites-list`: Card grid container (rendered by internal list component)
- `.mdk-pm-sites-list__row`: Flex row containing card grid and optional sticky sidebar
- `.mdk-pm-sites-list__unit-col`: Card grid column
- `.mdk-pm-sites-list__unit-grid`: CSS grid of status cards
- `.mdk-pm-sites-list__sticky-col`: Sticky sidebar column (desktop, when units are selected)
- `.mdk-pm-sites-list__fab`: Floating action button (tablet, when units are selected)

## Related hooks

The following hooks supply live data to `<PoolManagerSitesOverview />`.

| Hook | Supplies |
|------|---------|
| [`useSitesOverviewData`](/reference/app-toolkit/hooks/data#usesitesoverviewdata) | Projects raw container rows and pool stats into the shape accepted by `units` and `isLoading` props |
| [`usePoolStats`](/reference/app-toolkit/hooks/data#usepoolstats) | Aggregate pool worker counts and hashrate passed as the `poolStats` option to `useSitesOverviewData` |

# Repairs (/reference/ui/react/foundation/repairs)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Repairs components display spare-part changes recorded in device repair batch actions. Pair with the [Operations centre](/reference/ui/react/foundation/operations) for full device-management context.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Components

### `RepairLogChangesSubRow`

Expandable sub-row that lists the spare-part changes recorded in a repair batch action. Each non-miner repair action is resolved against its device to show the part type, serial number, MAC address, and whether the part was added or removed. Renders as a `DataTable`; shows a `Spinner` when `isLoading` is `true`.

The component does no data fetching — the parent fetches the batch action and its associated devices (for example via the things API) and passes them as props.

#### Import

```tsx
  RepairLogChangesSubRowProps,
  RepairBatchAction,
  RepairDevice,
} from '@tetherto/mdk-react-devkit/foundation'
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `batchAction` | Required | `RepairBatchAction` | none | The repair batch action whose part changes are displayed |
| `devices` | Required | `RepairDevice[]` | none | Devices referenced by the batch action, pre-fetched by the parent |
| `isLoading` | Optional | `boolean` | `false` | When `true`, renders a spinner instead of the table |

#### Supporting types

```tsx
type RepairBatchAction = Partial<{
  params: RepairAction[]
}>

type RepairAction = Partial<{
  params: RepairActionParam[]
}>

type RepairActionParam = Partial<{
  comment: string
  id: string
  rackId: string
  info: { parentDeviceId: string | null }
}>

type RepairDevice = Partial<{
  id: string
  rack: string
  info: Partial<{
    serialNum: string
    macAddress: string
  }>
}>
```

#### Basic usage

```tsx

const batchAction: RepairBatchAction = {
  params: [
    {
      params: [
        {
          id: 'inventory-miner_part-hashboard-001',
          rackId: 'inventory-miner_part-hashboard',
          info: { parentDeviceId: null },
        },
      ],
    },
  ],
}

const devices: RepairDevice[] = [
  {
    id: 'inventory-miner_part-hashboard-001',
    rack: 'inventory-miner_part-hashboard',
    info: { serialNum: 'HB-SN-0001', macAddress: 'AA:BB:CC:00:00:01' },
  },
]

<RepairLogChangesSubRow batchAction={batchAction} devices={devices} />
```

#### Loading state

```tsx
<RepairLogChangesSubRow
  batchAction={batchAction}
  devices={[]}
  isLoading
/>
```

#### Behavior notes

- Miner rack actions and actions with a `comment` field are filtered out — only spare-part changes appear in the table
- A part is marked **Removed** when `parentDeviceId` is `null`; **Added** when `parentDeviceId` references a parent device
- Part type labels come from `MINER_TYPE_NAME_MAP` and `SparePartNames`; unrecognised rack IDs display as `Unknown`
- Pagination is disabled by default

## Next steps

- For device-level details, see the [Operations centre](/reference/ui/react/foundation/operations) pages

# Reporting tool (/reference/ui/react/foundation/reporting)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Reporting-tool components cover financial and operational analytics. Host apps supply API or tail-log data; components handle layout, charts, and tab navigation. Every report shares one date-range model through `TimeframeControls`, `ReportTimeFrameSelector`, and `useFinancialDateRange`.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Component groups

- [Financial reporting](./financial): revenue, cost, EBITDA, energy balance, hash balance, and subsidy fee reports
- [Operational reporting](./operational): operational dashboard, energy consumption, and hashrate reports
- [Operational efficiency](./operations-efficiency): three-tab efficiency dashboard (`OperationsEfficiency`)
- [Multi-site reporting](./multi-site): portfolio-level `SiteReports` composite

## Reporting components

### `TimeframeControls`

Date-range picker for financial reporting pages. Supports year, month, and optional week granularity via connected selects. Drives the date range for the cost, EBITDA, energy balance, and other financial reports.

#### Import

```tsx
```

#### Props

All props are optional.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `dateRange` | Optional | `{ start, end }` | none | Controlled date range in ms epoch; when omitted the control manages its own state |
| `onRangeChange` | Optional | `function` | none | Called with `([start, end], { year, month, period })` when the user changes the selection |
| `isMonthSelectVisible` | Optional | `boolean` | `true` | Show or hide the month select |
| `isWeekSelectVisible` | Optional | `boolean` | `true` | Show or hide the week select |
| `showResetButton` | Optional | `boolean` | `false` | Show a Reset button at the end of the toolbar |
| `onReset` | Optional | `function` | none | Called when the user clicks Reset |
| `layout` | Optional | `'horizontal' \| 'stacked'` | `'horizontal'` | Selects row layout |
| `hint` | Optional | `string` | none | Hint text shown above the toolbar in a banded strip |
| `timeframeType` | Optional | `TimeframeTypeValue \| null` | none | Controlled timeframe type (year / month / week) |
| `onTimeframeTypeChange` | Optional | `function` | none | Called when the resolved timeframe type changes |

#### Basic usage

```tsx

function ReportPage() {
  const [dateRange, setDateRange] = useState<FinancialDateRange>()

return (
    <TimeframeControls
      isMonthSelectVisible
      isWeekSelectVisible={false}
      showResetButton
      dateRange={dateRange}
      onRangeChange={(range, opts) =>
        setDateRange({ start: range[0].getTime(), end: range[1].getTime(), period: opts.period })
      }
      onReset={() => setDateRange(undefined)}
    />
  )
}
```

For the backing state machine see [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols).

### `ReportTimeFrameSelector`

Compact preset-window picker (1D / 7D / 30D / custom range) used inside the Miner Type and Mining Unit bar views of the operational efficiency and hashrate reports. Pair it with [`useReportTimeFrameSelectorState`](/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate) for the full controlled state.

#### Import

```tsx
```

#### Props

Props come directly from the `useReportTimeFrameSelectorState` return value; spread them onto the component:

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `presetTimeFrame` | Required | `number \| null` | none | **Required.** Active preset window in days (`1`, `7`, `30`) or `null` when the custom range is active |
| `dateRange` | Required | `{ start, end } \| null` | none | **Required.** Controlled date range; `null` while a preset is active |
| `setPresetTimeFrame` | Required | `function` | none | **Required.** Setter called when the user selects a preset |
| `setDateRange` | Required | `function` | none | **Required.** Setter called when the user picks a custom date range |

#### Basic usage

```tsx
  ReportTimeFrameSelector,
  useReportTimeFrameSelectorState,
} from '@tetherto/mdk-react-devkit/foundation'

function EfficiencyBarPanel() {
  const { presetTimeFrame, dateRange, setPresetTimeFrame, setDateRange } =
    useReportTimeFrameSelectorState()

return (
    <ReportTimeFrameSelector
      presetTimeFrame={presetTimeFrame}
      dateRange={dateRange}
      setPresetTimeFrame={setPresetTimeFrame}
      setDateRange={setDateRange}
    />
  )
}
```

#### Styling

- `.mdk-report-time-frame-selector`: Root element

### `MetricCard`

Compact card displaying a labelled metric value with an optional unit, highlight state, and transparency. Used across financial and operational reporting composites for cost, EBITDA, hash, and energy metric tiles.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `label` | Required | `string` | none | **Required.** Metric label text |
| `value` | Required | `number \| string \| null` | none | **Required.** Metric value; `null` renders a fallback dash |
| `unit` | Required | `string` | none | **Required.** Unit suffix appended after the value when value is not `null` |
| `bgColor` | Optional | `string` | `rgba(0,0,0,0.05)` | Background color CSS value |
| `isHighlighted` | Optional | `boolean` | `false` | Apply highlight text color to the value |
| `isTransparentColor` | Optional | `boolean` | `false` | Render the value text in a muted / transparent color |
| `isValueMedium` | Optional | `boolean` | `false` | Render the value at medium font weight |
| `showDashForZero` | Optional | `boolean` | `false` | When `true`, render a dash instead of `0` |
| `noMinWidth` | Optional | `boolean` | `false` | Remove the default minimum card width |
| `className` | Optional | `string` | none | Root class name from the host app |

#### Basic usage

```tsx

<MetricCard label="Total Cost" value={42500} unit="USD" />
```

#### Styling

- `.mdk-metric-card`: Root element
- `.mdk-metric-card--no-min-width`: Modifier removing the min-width constraint
- `.mdk-metric-card__label`: Label text
- `.mdk-metric-card__value`: Value text
- `.mdk-metric-card__value--medium`: Medium-weight value modifier

# Financial reporting (/reference/ui/react/foundation/reporting/financial)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Financial reporting components cover cost summary, EBITDA, energy balance, hash balance, subsidy fee, and revenue views. Most are self-contained reporting page composites — supply your API data and a `<TimeframeControls>` period selector; the component handles layout, charts, and metric tiles. `RevenueChart` is a standalone stacked-bar chart you can drop into a multi-site financial view.

For operational reporting see [Operational](/reference/ui/react/foundation/reporting/operational). For shared controls see the [Reporting tool overview](/reference/ui/react/foundation/reporting).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter`

## Components

### `TimeframeControls`

The shared period selector for the reporting composites on this page — pass it into each composite's controls slot (`controls`, `datePicker`, or `timeframeControls` depending on the component). It drives year, month, and week granularity and is also used by the operational surfaces.

#### Import

```tsx
```

#### Props

All props are optional.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `dateRange` | Optional | `TimeframeControlsDateRange` | — | Currently selected date range driving the connected selects |
| `timeframeType` | Optional | `TimeframeTypeValue \| null` | `null` | Active granularity (year / month / week) |
| `onRangeChange` | Optional | `TimeframeControlsOnRangeChange` | — | Fires when the selected date range changes |
| `onTimeframeTypeChange` | Optional | `(type: TimeframeTypeValue) => void` | — | Fires when the granularity changes |
| `isMonthSelectVisible` | Optional | `boolean` | — | Toggles visibility of the month select |
| `isWeekSelectVisible` | Optional | `boolean` | — | Toggles visibility of the week select |
| `layout` | Optional | `'horizontal' \| 'stacked'` | — | Arrangement of the connected selects |
| `showResetButton` | Optional | `boolean` | — | Renders a reset button |
| `onReset` | Optional | `VoidFunction` | — | Fires when the reset button is clicked |
| `hint` | Optional | `string` | — | Helper text shown alongside the selector |

#### Basic usage

Pair it with the [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols) state machine, then pass it into a composite's controls slot:

```tsx

const { dateRange, timeframeType, onRangeChange, onTimeframeTypeChange } = useTimeframeControls({ /* … */ })

<Cost
  controls={
    <TimeframeControls
      dateRange={dateRange}
      timeframeType={timeframeType}
      onRangeChange={onRangeChange}
      onTimeframeTypeChange={onTimeframeTypeChange}
    />
  }
/>
```

#### Behavior

Renders connected year / month / week selects. Hide the month or week select via `isMonthSelectVisible` / `isWeekSelectVisible`, switch between inline and stacked arrangement with `layout`, and optionally surface a reset button (`showResetButton` + `onReset`). The selection state itself is owned by [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols).

### `Cost`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `metrics` | Required | `CostSummaryDisplayMetrics \| null` | none | Derived metric tiles from `buildCostSummaryViewModel` |
| `costLog` | Required | `ReadonlyArray<CostTimeSeriesEntry>` | none | Monthly cost time-series for the bar charts |
| `btcPriceLog` | Required | `ReadonlyArray<BtcPriceTimeSeriesEntry>` | none | BTC price overlay series |
| `totals` | Required | `CostSummaryMonetaryTotals \| null` | none | Aggregate totals for the summary tile |
| `dateRange` | Required | `FinancialDateRange \| null` | none | Active period — drives chart x-axis |
| `avgAllInCostData` | Optional | `ReadonlyArray<AvgAllInCostDataPoint>` | none | Revenue vs cost series for the Avg All-in Cost panel |
| `controls` | Required | `ReactElement` | none | Period selector slot — pass `<TimeframeControls>` |
| `setCostAction` | Optional | `ReactElement` | none | Optional header action slot (e.g. a "Set Monthly Cost" link) |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state |
| `error` | Optional | `unknown` | none | Show an error state when defined |

#### Data preparation

Use `buildCostSummaryViewModel` to transform a raw API response into the props the component expects:

```tsx

const viewModel = buildCostSummaryViewModel({ data: apiResponse })
// → { metrics, costLog, btcPriceLog, totals }
```

#### `FinancialDateRange` type

```tsx
type FinancialDateRange = {
  start: number   // epoch ms
  end: number     // epoch ms
  period?: 'daily' | 'weekly' | 'monthly' | 'yearly'
}
```

#### Basic usage

```tsx
  Cost,
  buildCostSummaryViewModel,
  TimeframeControls,
  PERIOD,
} from '@tetherto/mdk-react-devkit/foundation'

const [dateRange, setDateRange] = useState<FinancialDateRange>({
    start: startOfMonth(new Date()).getTime(),
    end: endOfMonth(new Date()).getTime(),
    period: PERIOD.MONTHLY,
  })

const viewModel = useMemo(
    () => buildCostSummaryViewModel({ data: apiResponse }),
    [apiResponse],
  )

return (
    <Cost
      {...viewModel}
      dateRange={dateRange}
      controls={
        <TimeframeControls
          isMonthSelectVisible
          isWeekSelectVisible={false}
          dateRange={{ start: dateRange.start, end: dateRange.end }}
          onRangeChange={(range, opts) =>
            setDateRange({ start: range[0].getTime(), end: range[1].getTime(), period: opts.period })
          }
        />
      }
    />
  )
}
```

#### Behavior

Renders a "Cost Summary" page header, the `controls` slot (period selector), and the `CostContent` 2×2 grid of charts and metric tiles (production cost chart, operations energy chart, avg all-in cost chart, and cost metric cards).

#### Styling

- `.mdk-cost`: Root element
- `.mdk-cost__header`: Title and optional action row
- `.mdk-cost__page-title`: "Cost Summary" heading
- `.mdk-cost__controls`: Controls slot wrapper

### `Ebitda`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `metrics` | Required | `CostSummaryDisplayMetrics \| null` | none | Derived metric tiles from `buildCostSummaryViewModel` |
| `ebitdaChartInput` | Required | `ToBarChartDataInput \| null` | none | EBITDA bar chart series |
| `btcProducedChartInput` | Required | `ToBarChartDataInput \| null` | none | BTC produced bar chart series |
| `hasBtcProducedAllZeros` | Required | `boolean` | none | Hides the BTC produced series when all values are zero |
| `showEbitdaBarChart` | Required | `boolean` | none | Toggle the EBITDA bar chart panel |
| `currentBTCPrice` | Required | `number` | none | Live BTC price used in metric calculations |
| `datePicker` | Required | `ReactElement` | none | Period selector slot |
| `hasDateSelection` | Required | `boolean` | none | When `false` shows a "select a period" hint instead of empty data |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state |
| `errors` | Optional | `string[]` | `[]` | Error messages displayed as an alert |
| `setCostHref` | Optional | `string` | none | When provided, shows a "Set Monthly Cost" gear link in the header |

#### Basic usage

```tsx

<Ebitda
  metrics={ebitdaMetrics}
  ebitdaChartInput={ebitdaChartData}
  btcProducedChartInput={btcProducedData}
  hasBtcProducedAllZeros={false}
  showEbitdaBarChart={true}
  currentBTCPrice={65000}
  datePicker={<TimeframeControls {...timeframeProps} />}
  hasDateSelection={true}
/>
```

#### Behavior

Renders an "EBITDA" page header, period selector slot, and (when `hasDateSelection` is true and data is available) the `EbitdaMetrics` card grid and `EbitdaCharts` panels. Shows a "please select a period" hint when `hasDateSelection` is false. A full-page spinner appears while `isLoading` is true.

#### Styling

- `.mdk-ebitda`: Root element
- `.mdk-ebitda__header`: Title and optional action row
- `.mdk-ebitda__page-title`: "EBITDA" heading
- `.mdk-ebitda__header-actions`: "Set Monthly Cost" link wrapper
- `.mdk-ebitda__controls`: Date picker slot
- `.mdk-ebitda__loading`: Spinner overlay
- `.mdk-ebitda__error`: Error / empty state container

### `EnergyBalance`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `viewModel` | Required | `EnergyBalanceViewModel` | none | Full view-model from `useEnergyBalance` hook |
| `onTabChange` | Required | `function` | none | Called when the Revenue/Cost tab changes |
| `onRevenueDisplayModeChange` | Required | `function` | none | Called when the revenue chart display mode toggles |
| `onCostDisplayModeChange` | Required | `function` | none | Called when the cost chart display mode toggles |
| `timeframeControls` | Optional | `ReactNode` | none | Period selector slot rendered above the tabs |
| `setCostHref` | Optional | `string` | none | When provided, shows a "Set Monthly Cost" gear link in the header |
| `isDemoMode` | Optional | `boolean` | `false` | Suppresses error alerts (for demo/storybook use) |

#### `EnergyBalanceTab` type

```tsx
type EnergyBalanceTab = 'revenue' | 'cost'
```

#### Basic usage

```tsx

const viewModel = useEnergyBalance({ data: apiData, dateRange })

return (
    <EnergyBalance
      viewModel={viewModel}
      onTabChange={(tab) => setActiveTab(tab)}
      onRevenueDisplayModeChange={(mode) => setRevenueMode(mode)}
      onCostDisplayModeChange={(mode) => setCostMode(mode)}
      timeframeControls={<TimeframeControls {...timeframeProps} />}
    />
  )
}
```

#### Behavior

Renders an "Energy Balance" page header, optional timeframe controls, and a two-tab layout:
- **Energy Revenue** — revenue metrics cards, revenue bar chart, [`AverageDowntimeChart`](/reference/ui/react/core/components/charts#averagedowntimechart) (curtailment vs operational issues), power chart
- **Energy Cost** — cost metrics cards, cost bar chart, power chart

Empty and no-selection states are handled internally. A loading spinner overlays the view while data fetches.

#### Styling

- `.mdk-energy-balance`: Root element
- `.mdk-energy-balance__header`: Title and optional action row
- `.mdk-energy-balance__controls`: Timeframe controls slot
- `.mdk-energy-balance__tabs`: Tab container
- `.mdk-energy-balance__tabs-list`: Tab switcher row
- `.mdk-energy-balance__tabs-trigger`: Individual tab button
- `.mdk-energy-balance__tabs-content`: Tab panel content area
- `.mdk-energy-balance__loading`: Spinner overlay
- `.mdk-energy-balance__error`: Error / empty state

### `HashBalance`

#### Import

```tsx
```

#### Props

All props are optional (the component renders an empty/loading state when omitted).

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `HashRevenueResponse \| null` | — | Hash revenue API response |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state |
| `isError` | Optional | `boolean` | `false` | Show an error alert |
| `errorMessage` | Optional | `string` | `'Error loading hash balance data…'` | Override error message text |
| `initialDateRange` | Optional | `FinancialDateRange` | current month | Starting period for the integrated timeframe controls |
| `onDateRangeChange` | Optional | `function` | — | Fires when the user changes the period |
| `className` | Optional | `string` | — | Root class override |
| `tabsClassName` | Optional | `string` | — | Class on the tab container |
| `tabsListClassName` | Optional | `string` | — | Class on the tab list |

#### Basic usage

```tsx

<HashBalance
  data={hashRevenueData}
  isLoading={isLoading}
  onDateRangeChange={(range, query) => fetchHashBalance(query)}
/>
```

#### Behavior

Renders integrated `TimeframeControls` (year/month/week) with a reset button, and a two-tab layout:
- **Hash Revenue** — site hash revenue, network hashrate, and network hashprice charts with metric cards; includes a currency toggle (USD / BTC)
- **Hash Cost** — hash cost vs revenue comparison charts

Date range is managed internally unless `initialDateRange` is supplied; `onDateRangeChange` fires on every period change.

#### Styling

- `.mdk-hash-balance`: Root element
- `.mdk-hash-balance__loading`: Spinner overlay
- `.mdk-hash-balance__error`: Error alert
- `.mdk-hash-balance__tabs`: Tab container
- `.mdk-hash-balance__tabs-list`: Tab row
- `.mdk-hash-balance__tabs-trigger`: Individual tab button
- `.mdk-hash-balance__tabs-content`: Tab panel

### `SubsidyFee`

#### Import

```tsx
```

#### Props

All props are optional.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `HashRevenueResponse \| null` | — | Hash revenue API response |
| `log` | Optional | `SubsidyFeesLogEntry[]` | — | Per-block log entries (alternative to `data`) |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state |
| `isError` | Optional | `boolean` | `false` | Show an error alert |
| `errorMessage` | Optional | `string` | `'Error loading hash balance data…'` | Override error message text |
| `showSummaryCards` | Optional | `boolean` | `false` | Show Total Subsidy, Total Fees, and Average Fees stat cards above the charts |
| `onDateRangeChange` | Optional | `function` | — | Fires when the user changes the period |

#### Basic usage

```tsx

<SubsidyFee
  data={subsidyFeesData}
  isLoading={isLoading}
  showSummaryCards={true}
  onDateRangeChange={(range, query) => fetchSubsidyFees(query)}
/>
```

#### Behavior

Renders integrated `TimeframeControls` (year/month/week) and two chart panels side by side:
- **Subsidy/Fees** — stacked bar chart of mining reward breakdown (subsidy vs transaction fees) with a % fee ratio overlay on the right y-axis
- **Average Fees** — average fees in sats/vbyte bar chart

When `showSummaryCards` is true, three `SingleStatCard` tiles (Total Subsidy, Total Fees, Average Fees) appear above the charts.

#### Styling

- `.mdk-subsidy-fee__panel`: Each chart panel wrapper
- `.mdk-subsidy-fee__panel--primary`: Primary variant

### `RevenueChart`

Stacked bar chart showing monthly Bitcoin revenue across multiple mining sites. Values display in BTC when the per-label average exceeds 1 BTC, otherwise they are converted to Sats.

#### Import

```tsx
```

#### Props

All props are optional (the component renders an empty/loading state when omitted).

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `data` | Optional | `RevenueDataItem[]` | `[]` | Pre-fetched revenue records — each entry is one time period with a `timeKey`, `period`, `timestamp`, and one numeric value per site ID |
| `isLoading` | Optional | `boolean` | `false` | Shows a loading spinner while data is being fetched |
| `siteList` | Optional | `(string \| SiteItem)[]` | `[]` | Resolves `data` site IDs to display names in the legend; pass `string[]` of IDs or `{ id, name? }[]` objects |
| `legendPosition` | Optional | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Chart legend position |
| `legendAlign` | Optional | `'start' \| 'center' \| 'end'` | `'start'` | Chart legend alignment |

#### Data shape

Each array element is one time bucket; site IDs are dynamic keys holding that site's revenue in BTC:

```ts
{
  timeKey: 'Jan 2024',   // X-axis label
  period: 'monthly',
  timestamp: 1704067200000,
  'site-a': 0.0042,      // Revenue in BTC for site-a
  'site-b': 0.0031,      // Revenue in BTC for site-b
}
```

#### Basic usage

```tsx

const siteList = [
  { id: 'site-a', name: 'Paraguay' },
  { id: 'site-b', name: 'Uruguay' },
]

<RevenueChart data={revenueData} siteList={siteList} isLoading={isLoadingRevenue} />
```

#### Behavior

Renders a stacked column chart with one series per site inside a `ChartContainer`. Currency is auto-detected: if any per-label daily average is greater than 1 BTC the chart displays BTC (₿); otherwise values are multiplied by 1,000,000 and shown in Sats. While `isLoading` is true a spinner replaces the chart. No internal data fetching — pass data from your query layer.

#### Styling

- `.mdk-revenue-chart`: Root element
- `.mdk-revenue-chart__header`: Title and currency-unit row
- `.mdk-revenue-chart__title`: "Revenue" heading
- `.mdk-revenue-chart__unit`: Currency unit label

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useFinancialDateRange`](/reference/app-toolkit/hooks/components#usefinancialdaterange) | Resolves the active financial date range consumed by reporting-section queries |
| [`useEbitda`](/reference/app-toolkit/hooks/components#useebitda) | Transforms raw EBITDA API response into the view-model shape for `<Ebitda />` |
| [`useEnergyBalanceViewModel`](/reference/app-toolkit/hooks/components#useenergybalanceviewmodel) | Computes the full energy-balance view model (tab and display-mode state) for `<EnergyBalance />` |
| [`useHashBalance`](/reference/app-toolkit/hooks/utilities#usehashbalance) | Derives the hash-balance view model for `<HashBalance />` |
| [`useSubsidyFees`](/reference/app-toolkit/hooks/utilities#usesubsidyfees) | Derives subsidy-fee series for `<SubsidyFee />` |

# Multi-site reporting (/reference/ui/react/foundation/reporting/multi-site)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

`SiteReports` is the multi-site report index — a duration toggle (weekly / monthly / yearly) and a sortable table of published report windows. Each row has a "View Report" action that the caller handles, so the component stays routing-agnostic.

For single-site financial reporting see [Financial](/reference/ui/react/foundation/reporting/financial).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Components

### `SiteReports`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `pageTitle` | Optional | `string` | `'Reports'` | Heading displayed above the toolbar |
| `siteName` | Optional | `string` | — | Optional site label shown below the heading |
| `duration` | Optional | `ReportDuration` | — | Controlled duration (`'weekly'`, `'monthly'`, `'yearly'`) |
| `defaultDuration` | Optional | `ReportDuration` | `'weekly'` | Initial duration when uncontrolled |
| `onDurationChange` | Optional | `function` | — | Fires when the user switches duration |
| `reports` | Optional | `SiteReportRecord[]` | auto-generated | Explicit report windows — when omitted, windows are auto-generated from the current date |
| `referenceDate` | Optional | `Date` | `new Date()` | Reference point for auto-generating report windows |
| `onViewReport` | Optional | `function` | — | Called when the user clicks "View Report" on a row; button is disabled when omitted |
| `className` | Optional | `string` | — | Optional root class override |

#### `SiteReportRecord` type

```tsx
type SiteReportRecord = {
  from: Date        // report window start
  to: Date          // report window end
  publishedAt: Date // when this report was published
}
```

#### `ReportDuration` type

```tsx
type ReportDuration = 'weekly' | 'monthly' | 'yearly'
```

#### `SiteReportViewContext` type

Passed as the second argument to `onViewReport`:

```tsx
type SiteReportViewContext = {
  duration: ReportDuration
  siteName?: string
}
```

#### Basic usage

```tsx

<SiteReports
  pageTitle="Reports"
  siteName="EU Site 01"
  onViewReport={(record, context) =>
    router.push(`/reports/${context.duration}/${record.from.toISOString()}`)
  }
/>
```

#### More examples

```tsx
const [duration, setDuration] = useState<ReportDuration>('monthly')

<SiteReports
  pageTitle="Reports"
  duration={duration}
  onDurationChange={setDuration}
  onViewReport={handleViewReport}
/>
```

</Accordion>
  <Accordion title="Providing explicit report windows">

When your API returns pre-computed report records, pass them directly to bypass auto-generation:

```tsx
<SiteReports
  pageTitle="Reports"
  reports={[
    {
      from: new Date('2026-01-01'),
      to: new Date('2026-01-07'),
      publishedAt: new Date('2026-01-08'),
    },
    {
      from: new Date('2026-01-08'),
      to: new Date('2026-01-14'),
      publishedAt: new Date('2026-01-15'),
    },
  ]}
  onViewReport={handleViewReport}
/>
```

</Accordion>
</Accordions>

#### Behaviour

Renders a two-part surface:

1. **Toolbar** — page heading, optional site name, and a segmented duration toggle (Weekly / Monthly / Yearly) implemented as side-variant `Tabs`.
2. **Table** — `DataTable` with three columns: Date (the formatted report window), Date of Publish (formatted `publishedAt`), and Actions (a "View Report" button). Both date columns are sortable. The "View Report" button is disabled when `onViewReport` is not provided.

When `reports` is omitted, the component auto-generates windows backwards from `referenceDate` based on the active duration.

Duration is uncontrolled by default; pass `duration` + `onDurationChange` to make it controlled.

#### Styling

- `.mdk-site-reports`: Root element
- `.mdk-site-reports__toolbar`: Heading + duration toggle row
- `.mdk-site-reports__heading`: Page title text
- `.mdk-site-reports__site-name`: Site name label
- `.mdk-site-reports__duration`: Duration tab container
- `.mdk-site-reports__table`: Data table wrapper
- `.mdk-site-reports__view-button`: "View Report" action button

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | Normalises grouped-hashrate query results into the shape consumed by `<SiteReports />` |
| [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite) | Per-site energy data for the multi-site energy tab |

# Operational reporting (/reference/ui/react/foundation/reporting/operational)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

Operational reporting components cover a consolidated operations dashboard (`OperationalDashboard`), energy consumption (`EnergyReport`), and hashrate (`Hashrate`) views. `EnergyReport` and `Hashrate` are multi-tab reporting surfaces with site, miner-type, and mining-unit breakdown charts; `OperationalDashboard` is a 2×2 grid composite of the four core site-operations charts. Each is self-contained — supply your API data and the component handles layout, charts, and tab navigation.

For financial reporting see [Financial](/reference/ui/react/foundation/reporting/financial). For operational efficiency see [Operational efficiency](/reference/ui/react/foundation/reporting/operations-efficiency).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- `<MdkProvider>` from `@tetherto/mdk-react-adapter`

## Components

### `OperationalDashboard`

#### Import

```tsx
```

#### Props

All props are optional.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `hashrate` | Optional | `{ data, isLoading }` | none | Pre-shaped hashrate trend data from `useOperationsDashboard` |
| `consumption` | Optional | `{ data, isLoading }` | none | Pre-shaped power-consumption trend data |
| `efficiency` | Optional | `{ data, isLoading }` | none | Pre-shaped site-efficiency trend data |
| `miners` | Optional | `{ data, isLoading }` | none | Pre-shaped miners-status stacked-bar data |
| `controls` | Optional | `ReactElement` | none | Optional slot rendered above the grid (for example a date-range picker) |

#### Basic usage

```tsx

function OperationsDashboardPage({ hashrateLog, consumptionLog, efficiencyLog, minersLog }) {
  const vm = useOperationsDashboard({
    hashrate: { log: hashrateLog, isLoading },
    consumption: { log: consumptionLog, isLoading },
    efficiency: { log: efficiencyLog, isLoading },
    miners: { log: minersLog, isLoading },
  })

return (
    <OperationalDashboard
      hashrate={vm.hashrate}
      consumption={vm.consumption}
      efficiency={vm.efficiency}
      miners={vm.miners}
    />
  )
}
```

#### Behavior

Renders a 2×2 grid of four `LineChartCard`-based chart cards: hashrate trend, power consumption trend, site efficiency trend, and miners status (stacked bar). Each card has an expand toggle that widens it to full grid width; expand state persists across remounts. Assumes a single `OperationalDashboard` instance is mounted at a time.

#### Styling

- `.mdk-operational-dashboard`: Root element
- `.mdk-operational-dashboard__controls`: Controls slot wrapper (only rendered when `controls` is supplied)
- `.mdk-operational-dashboard__grid`: 2×2 chart grid
- `.mdk-operational-dashboard__cell`: Individual chart cell
- `.mdk-operational-dashboard__cell--expanded`: Modifier applied when a card is expanded to full width

### `EnergyReport`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `defaultTab` | Optional | `EnergyReportTabValue` | `'site-view'` | Tab shown on first render — defaults to `'site-view'` |
| `siteView` | Optional | `HashrateSiteViewProps` | none | Props for the Site View tab |
| `minerTypeView` | Optional | `HashrateMinerTypeViewProps` | none | Props for the Miner Type View tab |
| `minerUnitView` | Optional | `EnergyReportMinerUnitViewProps` | none | Props for the Mining Unit View tab |
| `className` | Optional | `string` | none | Optional root class override |

#### `EnergyReportTabValue` type

```tsx
type EnergyReportTabValue = 'site-view' | 'miner-type-view' | 'miner-unit-view'
```

#### `EnergyReportSiteViewProps` key fields

```tsx
type EnergyReportSiteViewProps = {
  consumptionLog?: MetricsConsumptionLogEntry[]  // power/consumption time-series
  nominalPowerAvailabilityMw?: number | null      // site nominal capacity
  containers?: EnergyReportContainer[]            // container inventory
  tailLog?: EnergyReportTailLogItem[][]           // snapshot tail-log for power-mode table
  dateRange?: EnergyReportDateRange               // controlled date range
  onDateRangeChange?: (range: EnergyReportDateRange) => void
}
```

#### Basic usage

```tsx

<EnergyReport
    siteView={{
      consumptionLog: consumptionData,
      nominalPowerAvailabilityMw: 500,
      containers,
      tailLog,
    }}
    minerTypeView={{ groupedConsumption, containers }}
    minerUnitView={{ groupedConsumption: unitGroupedData, containers }}
  />
)
```

#### More examples

```tsx

<EnergyReport
  siteView={{
    consumptionLog: [
      { ts: Date.now() - 86_400_000, powerW: 180_000_000, consumptionMWh: 4.3 },
      { ts: Date.now(), powerW: 220_000_000, consumptionMWh: 5.1 },
    ],
    nominalPowerAvailabilityMw: 500,
  }}
/>
```

</Accordion>
  <Accordion title="Starting on a specific tab">

```tsx
<EnergyReport
  defaultTab="miner-type-view"
  minerTypeView={{ groupedConsumption, containers }}
/>
```

</Accordion>
</Accordions>

#### Behavior

Renders a three-tab layout:

- **Site View** — power consumption trend chart against nominal capacity, power-mode breakdown table per container. A `DateRangePicker` and Reset button appear above this tab only. Date range is managed internally unless `siteView.dateRange` is provided.
- **Miner Type View** — consumption grouped by miner type as a bar chart with per-miner-type breakdown.
- **Mining Unit View** — consumption grouped by mining unit as a bar chart.

Each tab fetches independently via its own prop bag.

#### Styling

- `.mdk-energy-report`: Root element
- `.mdk-energy-report__date-controls`: Date picker + Reset row (site view only)

### `Hashrate`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `defaultTab` | Optional | `HashrateTabValue` | `'site-view'` | Tab shown on first render |
| `siteView` | Optional | `HashrateSiteViewProps` | none | Props for the Site View tab |
| `minerTypeView` | Optional | `HashrateMinerTypeViewProps` | none | Props for the Miner Type View tab |
| `miningUnitView` | Optional | `HashrateMiningUnitViewProps` | none | Props for the Mining Unit View tab |

#### `HashrateTabValue` type

```tsx
type HashrateTabValue = 'site-view' | 'miner-type-view' | 'mining-unit-view'
```

#### Site view tab props

`HashrateSiteView` renders an aggregate hashrate trend line across the whole site, with an optional miner-type filter that scopes the sum to a subset. A date-range picker and optional reset button appear in the control row.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `log` | Optional | `HashrateGroupedLog` | `[]` | Hashrate log grouped by miner type |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state on the chart |
| `dateRange` | Optional | `HashrateDateRange` | none | Controlled date range `{ start, end }` in ms epoch; drives the upstream query |
| `onDateRangeChange` | Optional | `function` | none | Fires when the user selects a new range from the date picker |
| `onReset` | Optional | `function` | none | When provided, renders a Reset button next to the date picker |

#### Miner type and mining unit tab props

Both `minerTypeView` and `miningUnitView` render bar charts. Charts share axis scaling when both tabs are visible so relative comparisons remain accurate.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `chartInput` | Optional | `ToBarChartDataInput` | none | Declarative bar data (`{ labels, series }`) |
| `isEmpty` | Optional | `boolean` | `false` | When `true`, shows the chart empty state |
| `isLoading` | Optional | `boolean` | `false` | Show a loading state on the bar chart |

#### Basic usage

```tsx

<Hashrate
  siteView={{
    log: groupedHashrateLog,
    isLoading,
    dateRange,
    onDateRangeChange: setDateRange,
  }}
  minerTypeView={{ chartInput: minerTypeInput, isLoading }}
  miningUnitView={{ chartInput: miningUnitInput, isLoading }}
/>
```

#### More examples

The component renders an empty shell when no props are supplied — safe to render while data is loading.

```tsx
<Hashrate />
```

</Accordion>
  <Accordion title="Starting on miner type view">

```tsx
<Hashrate
  defaultTab="miner-type-view"
  minerTypeView={{ chartInput: minerTypeInput }}
/>
```

</Accordion>
</Accordions>

#### Behavior

Renders a three-tab layout using a shared `Tabs` shell. Each tab fetches independently via its own prop bag:

- **Site View** — aggregate hashrate trend line for the whole site with optional miner-type filter; date-range picker and Reset button in the control row
- **Miner Type View** — hashrate broken down by miner model/type as a bar chart with a toggle legend
- **Mining Unit View** — hashrate broken down per mining unit (container) as a bar chart with a toggle legend

Miner type and mining unit bar charts share Y-axis scaling so relative comparisons across tabs remain accurate. Active tab is managed internally.

#### Styling

- `.mdk-hashrate`: Root element

### `OperationalDashboard`

A 2×2 grid of the four site-operations charts — **Hashrate**, **Power Consumption**, **Site Efficiency** (line trends with an optional nominal reference line), and **Miners Status** (stacked daily breakdown). Each card can expand to full width, and the expand state persists across remounts.

The composite is pure glue: it renders pre-shaped data. Use the `useOperationsDashboard` hook to turn raw metric logs into the chart-ready payloads, then spread them in — the hook never fetches, so wire your own data layer.

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `hashrate` | Optional | `{ data?, isLoading? }` | none | Shaped hashrate trend (`LineChartCardData`) |
| `consumption` | Optional | `{ data?, isLoading? }` | none | Shaped power-consumption trend |
| `efficiency` | Optional | `{ data?, isLoading? }` | none | Shaped site-efficiency trend |
| `miners` | Optional | `{ data?, isLoading? }` | none | Shaped stacked miners-status data |
| `controls` | Optional | `ReactElement` | none | Controls slot (e.g. a date-range picker) rendered above the grid |

#### `useOperationsDashboard(input)`

`input` accepts one entry per chart. Trend inputs take `{ log, nominalValue?, isLoading?, error? }` where `log` is `{ ts, value }[]` in base units (hashrate MH/s, power W, efficiency W/TH/s). The miners input takes per-day `{ ts, online, error, offline, sleep, maintenance }` counts.

#### Basic usage

```tsx

const Dashboard = ({ queries }) => {
  const viewModel = useOperationsDashboard({
    hashrate: { log: queries.hashrate.log, nominalValue: queries.nominalHashrateMhs },
    consumption: { log: queries.consumption.log, nominalValue: queries.nominalPowerW },
    efficiency: { log: queries.efficiency.log, nominalValue: queries.nominalEfficiency },
    miners: { log: queries.miners.log },
  })

return <OperationalDashboard {...viewModel} controls={<DateRangePicker />} />
}
```

#### Behavior

Renders the four charts in a 2×2 grid; any card expands to full width and the expand state persists across remounts. Hashrate is displayed in TH/s, power in MW, and efficiency in W/TH/s. A `nominalValue` renders a flat reference line. The individual chart components (`OperationalHashrateChart`, …) and `ChartExpandAction` are exported as `advanced` building blocks for custom layouts.

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useOperationsDashboard`](/reference/app-toolkit/hooks/components#useoperationsdashboard) | Shapes raw operational metric logs into chart-ready payloads for the four `OperationalDashboard` cards |
| [`useHashrate`](/reference/app-toolkit/hooks/components#usehashrate) | Normalises a grouped-hashrate query result into the shape consumed by `<Hashrate />` |
| [`useEnergyReportSite`](/reference/app-toolkit/hooks/components#useenergyreportsite) | Merges consumption metrics with tail-log and container data for `<EnergyReport />` |
| [`useReportTimeFrameSelectorState`](/reference/app-toolkit/hooks/components#usereporttimeframeselectorstate) | Active time-frame window and setters for the time-frame selector |
| [`useTimeframeControls`](/reference/app-toolkit/hooks/components#usetimeframecontrols) | Year/month/week state machine for `TimeframeControls` |

# Operational efficiency (/reference/ui/react/foundation/reporting/operations-efficiency)

<PackageBadge>@tetherto/mdk-react-devkit/foundation</PackageBadge>

`OperationsEfficiency` is a three-tab reporting surface:

- Site View
- Miner Type View
- Mining Unit View

Your app loads metrics or tail-log data, passes it through the `siteView`, `minerTypeView`, and `minerUnitView` prop bags, and the 
shell renders charts and time-frame controls.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)
- [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core) (tabs and charts are composed from core primitives)

### Import

```tsx
  OperationsEfficiency,
  toOperationsEfficiencyMinerType,
  toOperationsEfficiencyMinerUnit,
  TAIL_LOG_MINER_TYPE_KEY,
  TAIL_LOG_CONTAINER_KEY,
} from '@tetherto/mdk-react-devkit/foundation'
  EfficiencyDateRange,
  MetricsEfficiencyLogEntry,
} from '@tetherto/mdk-react-devkit/foundation'
```

## `OperationsEfficiency`

Tab shell built on [`Tabs`](/reference/ui/react/core/components/navigation#tabs) from `@tetherto/mdk-react-devkit/core`. Each tab receives an 
optional props object; omit a tab’s props to render it with empty defaults.

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `defaultTab` | Optional | `'site-view' \| 'miner-type-view' \| 'mining-unit-view'` | `'site-view'` | Initial active tab key |
| `siteView` | Optional | `EfficiencySiteViewProps` | none | Data and callbacks for the Site View line chart |
| `minerTypeView` | Optional | `EfficiencyMinerTypeViewProps` | none | Bar chart input for [Miner Type View](#miner-type-and-mining-unit-tabs) |
| `minerUnitView` | Optional | `EfficiencyMinerUnitViewProps` | none | Bar chart input for Mining Unit View (same shape as miner type) |

### Site view tab

Wire the Site View to **`/auth/metrics/efficiency`** (v2). Map the response log array to 
[`MetricsEfficiencyLogEntry`](/reference/app-toolkit/ui-devkit/types#metricsefficiencylogentry) and pass it on `siteView.log`.

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `log` | Optional | `MetricsEfficiencyLogEntry[]` | `[]` | Time series for the line chart (`ts`, `efficiencyWThs`) |
| `avgEfficiency` | Optional | `number \| null` | `null` | Average efficiency for the selected range; shown in the chart header |
| `nominalValue` | Optional | `number \| null` | `null` | Nominal efficiency target; when set, adds a nominal series to the chart |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading state on the chart container |
| `dateRange` | Optional | `EfficiencyDateRange` | none | `{ start, end }` millisecond range for the date picker |
| `onDateRangeChange` | Optional | `function` | none | Called when the user selects a new range from the chart brush or date picker |
| `onReset` | Optional | `function` | none | Called when the user activates **Reset** on the site chart header |

### Miner type and mining unit tabs

Miner Type View and Mining Unit View use bar charts fed by **`ToBarChartDataInput`** (`{ labels, series }`). Until 
the metrics API supports `groupBy=miner`, build that input from **tail-log** (`stat-5m` / `t-miner`) using the pure helpers below. 
A backend follow-up will allow swapping the data source in foundation without changing this props contract.

| Helper | Input | Output |
|--------|--------|--------|
| `toOperationsEfficiencyMinerType` | `{ tailLog }` | `{ chartInput, isEmpty }` — reads `TAIL_LOG_MINER_TYPE_KEY` from tail-log |
| `toOperationsEfficiencyMinerUnit` | `{ tailLog, containers? }` | `{ chartInput, isEmpty }` — reads `TAIL_LOG_CONTAINER_KEY`; optional `containers` for labels |

Pass the result on `minerTypeView` / `minerUnitView`:

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `chartInput` | Optional | `ToBarChartDataInput` | none | Declarative bar data; convert with [`buildBarChartData`](/reference/ui/react/core/components/charts/composition#chart-utilities) if you need Chart.js `data` elsewhere |
| `isEmpty` | Optional | `boolean` | `false` | When `true`, shows the chart empty state |
| `isLoading` | Optional | `boolean` | `false` | When `true`, shows loading on the bar chart container |
| `onTimeFrameChange` | Optional | `function` | none | Called with `(start: Date, end: Date)` when the preset or custom range changes |

Each bar view mounts a single-series toggle legend via `ChartContainer`'s `legendData` and `onToggleDataset` props. Clicking the legend item hides or shows the bar series. MDK tooltips on the bars format values with the efficiency unit (`W/TH/s`), consistent with the rest of the reporting surface.

### Example

```tsx
  OperationsEfficiency,
  toOperationsEfficiencyMinerType,
  toOperationsEfficiencyMinerUnit,
} from '@tetherto/mdk-react-devkit/foundation'

function OperationalEfficiencyPanel({
  efficiencyLog,
  minerTypeTailLog,
  containerTailLog,
}: {
  efficiencyLog: MetricsEfficiencyLogEntry[]
  minerTypeTailLog: Record<string, unknown>
  containerTailLog: Record<string, unknown>
}) {
  const [dateRange, setDateRange] = useState<EfficiencyDateRange | undefined>()

const minerType = useMemo(
    () => toOperationsEfficiencyMinerType({ tailLog: minerTypeTailLog }),
    [minerTypeTailLog],
  )
  const minerUnit = useMemo(
    () => toOperationsEfficiencyMinerUnit({ tailLog: containerTailLog }),
    [containerTailLog],
  )

return (
    <OperationsEfficiency
      siteView={{
        log: efficiencyLog,
        dateRange,
        onDateRangeChange: setDateRange,
      }}
      minerTypeView={{
        chartInput: minerType.chartInput,
        isEmpty: minerType.isEmpty,
      }}
      minerUnitView={{
        chartInput: minerUnit.chartInput,
        isEmpty: minerUnit.isEmpty,
      }}
    />
  )
}
```

## Next steps

Consider related reference materials:

- [Metrics efficiency types](/reference/app-toolkit/ui-devkit/types#metrics-efficiency-types): `MetricsEfficiencyLogEntry` and 
response wrapper for the site tab
- [Chart composition](/reference/ui/react/core/components/charts/composition): `buildBarChartData` for bar chart `data` shapes

# Settings components (/reference/ui/react/foundation/settings)

The [`@tetherto/mdk-react-devkit/foundation`](/reference/ui/react/foundation) package provides pre-built settings UI for common administrative tasks.

Either use:

1. **All-in-one dashboard** ([`SettingsDashboard`](#settings-dashboard)): renders all settings sections in collapsible accordions.
2. **Individual components**: use [`FeatureFlagsSettings`](/reference/ui/react/foundation/settings/feature-flags),
   [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls), etc. directly for custom layouts.

## Settings dashboard

Each section renders if you provide its props, giving you control over the sections you need.

```tsx
```

## Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `showFeatureFlags` | Optional | `boolean` | `false` | Show the feature flags section (requires `featureFlagsProps`) |
| `headerControlsProps` | Optional | [`HeaderControlsSettingsProps`](/reference/ui/react/foundation/settings/header-controls) | none | Props for header controls section |
| `rbacControlProps` | Optional | [`RBACControlSettingsProps`](/reference/ui/react/foundation/settings/access-control) | none | Props for RBAC/user management section |
| `importExportProps` | Optional | [`ImportExportSettingsProps`](/reference/ui/react/foundation/settings/import-export) | none | Props for import/export section |
| `featureFlagsProps` | Optional | [`FeatureFlagsSettingsProps`](/reference/ui/react/foundation/settings/feature-flags) | none | Props for feature flags section |
| `dangerActions` | Optional | `ActionButtonProps[]` | none | Entries forwarded to [`ActionButton`](/reference/ui/react/core/components/forms#actionbutton) (`@tetherto/mdk-react-devkit/core`). See [advanced usage for danger actions with confirmation](#advanced-usage-for-danger-actions-with-confirmation). |
| `className` | Optional | `string` | none | Additional CSS class |

## Basic usage

```tsx

function SettingsPage() {
  return (
    <SettingsDashboard
      headerControlsProps={{
        preferences: headerPrefs,
        onToggle: handleToggle,
        onReset: handleReset,
      }}
      rbacControlProps={{
        users,
        roles,
        rolePermissions,
        permissionLabels,
        canWrite: true,
        onCreateUser,
        onUpdateUser,
        onDeleteUser,
      }}
      importExportProps={{
        onExport: handleExport,
        onImport: handleImport,
        onParseFile: parseSettingsFile,
      }}
      dangerActions={[
        {
          label: 'Reboot system',
          variant: 'danger',
          confirmation: {
            title: 'Reboot system',
            description: 'This restarts device Workers. Ensure no pending actions remain.',
            onConfirm: handleReboot,
          },
        },
      ]}
    />
  )
}
```

## Advanced usage for danger actions with confirmation

Use **`dangerActions`** when you need high-impact controls below the **Settings** heading and above the accordion sections. Each item follows **[`ActionButton`](/reference/ui/react/core/components/forms#actionbutton)** props: at minimum `label`, `variant`, and a **`confirmation`** object. Set **`mode: 'dialog'`** for modal confirmations (for example two side-by-side danger actions).

```tsx
<SettingsDashboard
  headerControlsProps={/* ... */}
  rbacControlProps={/* ... */}
  importExportProps={/* ... */}
  dangerActions={[
    {
      label: 'Restart orchestration',
      variant: 'danger',
      mode: 'dialog',
      confirmation: {
        title: 'Restart orchestration',
        description: (
          <p>
            Restarts orchestration Workers. Ensure maintenance windows are respected.
          </p>
        ),
        onConfirm: () => {
          void restartOrchestration()
        },
      },
    },
    {
      label: 'Disable automation policy',
      variant: 'danger',
      mode: 'dialog',
      confirmation: {
        title: 'Disable automation policy',
        description:
          'Automated mitigations will stop until you re-enable the policy.',
        onConfirm: () => {
          void disableAutomationPolicy()
        },
      },
    },
  ]}
/>
```

Full **`ActionButton`** semantics (**`confirmation`** fields, **`mode`**, **`loading`**, etc.) live under **[Form components: ActionButton](/reference/ui/react/core/components/forms#actionbutton)**.

## Accordion sections

The dashboard renders each settings section inside an [`Accordion`](/reference/ui/react/core/components/data-display#accordion) component
from [`@tetherto/mdk-react-devkit/core`](/reference/ui/react/core):

- **[Header Controls](/reference/ui/react/foundation/settings/header-controls)**: toggle visibility of header metrics
- **[Access control](/reference/ui/react/foundation/settings/access-control)**: manage users and role-based permissions
- **[Import / Export](/reference/ui/react/foundation/settings/import-export)**: backup and restore configuration
- **[Feature Flags](/reference/ui/react/foundation/settings/feature-flags)**: toggle feature flags (requires `showFeatureFlags={true}`)

## Styling

The component uses the `.mdk-settings-dashboard` CSS class. Key selectors:

- `.mdk-settings-dashboard__title`: main heading
- `.mdk-settings-dashboard__danger-actions`: container for danger action buttons
- `.mdk-settings-dashboard__accordions`: container for accordion sections

## Individual components

Use these components directly when you need a custom layout or only one settings section:

# Access control settings (/reference/ui/react/foundation/settings/access-control)

It manages:

1. **Access control** (`canWrite`): if `false`, hides edit/delete actions.
2. **User data** (`users`): array of users to display.
3. **Role configuration** (`roles`, `rolePermissions`, `permissionLabels`): define available roles and permissions.
4. **Callbacks** (`onCreateUser`, `onUpdateUser`, `onDeleteUser`): handle CRUD operations.
5. **State** (`isLoading`): loading indicator.
6. **Styling** (`className`): optional CSS class.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `canWrite` | Required | `boolean` | none | If `false`, hides edit/delete actions |
| `users` | Required | `SettingsUser[]` | none | Array of users to display |
| `roles` | Required | `RoleOption[]` | none | Available roles for assignment |
| `rolePermissions` | Required | `Record<string, Record<string, PermLevel>>` | none | Permissions matrix by role |
| `permissionLabels` | Required | `Record<string, string>` | none | Human-readable permission names |
| `onCreateUser` | Required | `function` | none | Create user callback |
| `onUpdateUser` | Required | `function` | none | Update user callback |
| `onDeleteUser` | Required | `function` | none | Delete user callback |
| `isLoading` | Optional | `boolean` | `false` | Loading state |
| `className` | Optional | `string` | none | Additional CSS class |

## Data structure

```tsx
  SettingsUser,
  RoleOption,
  PermLevel,
} from '@tetherto/mdk-react-devkit/foundation'

type SettingsUser = {
  id: string
  name?: string
  email: string
  role: string
  lastActive?: string
  last_login?: string
}

type RoleOption = {
  value: string
  label: string
}

type PermLevel = 'r' | 'rw' | false  // read, read-write, none

type CreateUserData = {
  name: string
  email: string
  role: string
}

type UpdateUserData = CreateUserData & { id: string }
```

## Callbacks

### `onCreateUser`

Called when end user submits the add user form. Receives `CreateUserData`:

```tsx
const handleCreateUser = async (data: CreateUserData) => {
  const newUser = await api.createUser(data)
  setUsers(prev => [...prev, newUser])
}
```

### `onUpdateUser`

Called when end user saves changes in the manage modal. Receives `UpdateUserData`:

```tsx
const handleUpdateUser = async (data: UpdateUserData) => {
  await api.updateUser(data)
  setUsers(prev => prev.map(u => u.id === data.id ? { ...u, ...data } : u))
}
```

### `onDeleteUser`

Called after end user confirms deletion. Receives the user ID:

```tsx
const handleDeleteUser = async (userId: string) => {
  await api.deleteUser(userId)
  setUsers(prev => prev.filter(u => u.id !== userId))
}
```

## Basic usage

```tsx

function UserManagementSection() {
  const [users, setUsers] = useState<SettingsUser[]>([])
  const [isLoading, setIsLoading] = useState(true)

useEffect(() => {
    api.getUsers().then(data => {
      setUsers(data)
      setIsLoading(false)
    })
  }, [])

const handleCreateUser = async (data) => {
    const newUser = await api.createUser(data)
    setUsers(prev => [...prev, newUser])
  }

const handleUpdateUser = async (data) => {
    await api.updateUser(data)
    setUsers(prev =>
      prev.map(u => u.id === data.id ? { ...u, ...data } : u)
    )
  }

const handleDeleteUser = async (userId) => {
    await api.deleteUser(userId)
    setUsers(prev => prev.filter(u => u.id !== userId))
  }

return (
    <RBACControlSettings
      canWrite={true}
      users={users}
      roles={[
        { value: 'admin', label: 'Admin' },
        { value: 'operator', label: 'Operator' },
        { value: 'viewer', label: 'Viewer' },
      ]}
      rolePermissions={{
        admin: { miners: 'rw', settings: 'rw', users: 'rw' },
        operator: { miners: 'rw', settings: 'r', users: false },
        viewer: { miners: 'r', settings: 'r', users: false },
      }}
      permissionLabels={{
        miners: 'Miner Management',
        settings: 'Settings',
        users: 'User Management',
      }}
      isLoading={isLoading}
      onCreateUser={handleCreateUser}
      onUpdateUser={handleUpdateUser}
      onDeleteUser={handleDeleteUser}
    />
  )
}
```

## Features

### User table

Displays users in a table with columns:

- **User**: name with tooltip
- **Email**: email address with tooltip
- **Assigned Roles**: role badge with color coding
- **Last Active**: formatted timestamp
- **Manage**: opens edit modal
- **Delete**: deletes with confirmation

### Search

Filter users by name, email, or role using the search input.

### Role badges

Roles are displayed as colored badges. Colors are determined by [`getRoleBadgeColors()`](/reference/app-toolkit/ui-devkit/constants#getrolebadgecolors)
from the foundation constants.

### Integrated modals

The component includes three modal dialogs:

- `AddUserModal`: create new users
- `ManageUserModal`: edit user details and view permissions
- `ChangeConfirmationModal`: confirm destructive actions

## Permission check

When `canWrite` is `false`:

- **Add User** button is hidden
- **Manage** and **Delete** buttons are hidden
- User list is read-only

```tsx
<RBACControlSettings
  canWrite={false}  // Read-only mode
  // ...other props
/>
```

## Styling

The component uses the `.mdk-settings-rbac` CSS class. Key selectors:

- `.mdk-settings-rbac__description`: header text
- `.mdk-settings-rbac__actions-row`: search and add button row
- `.mdk-settings-rbac__table`: user table container
- `.mdk-settings-rbac__role-badge`: role badge styling
- `.mdk-settings-rbac__manage-btn`: manage button
- `.mdk-settings-rbac__delete-btn`: delete button

# Feature flags settings (/reference/ui/react/foundation/settings/feature-flags)

It manages:

1. **User access control** (`isEditingEnabled`): if `false`, shows empty state and user is not provided with toggles.
2. **What data?** (`featureFlags`): the flags to display as toggles.
3. **What happens on save?** (`onSave`): callback receiving updated flags.
4. **State indicators** (`isLoading`, `isSaving`): optional user feedback on loading/saving states.
5. **Styling** (`className`): optional CSS class.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `isEditingEnabled` | Required | `boolean` | none | If `false`, shows empty state and other props have no effect |
| `featureFlags` | Required | `Record<string, boolean>` | none | Object mapping flag names to enabled/disabled state |
| `onSave` | Required | `function` | none | Callback when save is clicked |
| `isLoading` | Optional | `boolean` | `false` | Loading state |
| `isSaving` | Optional | `boolean` | `false` | Saving state |
| `className` | Optional | `string` | none | Additional CSS class |

## Data structure

The `featureFlags` prop accepts an object where:
- **Keys** are flag names (arbitrary strings defined by your application)
- **Values** are booleans (`true` = enabled, `false` = disabled)

```tsx
{
  darkMode: true,
  betaFeatures: false,
  advancedMetrics: true,
}
```

This component renders toggles for whatever flags you pass in. Your application or backend determines the available flags.

## Basic usage

Changes are held locally until the user clicks Save. The `onSave` callback receives the updated flags object:

```tsx
const handleSave = async (updatedFlags: Record<string, boolean>) => {
  await api.saveFeatureFlags(updatedFlags)  // persist to backend
  setFlags(updatedFlags)                     // update local state
}
```

<Callout type="warning">
The component does not persist data, you must implement the save logic.
</Callout>

### Example

```tsx

function FeatureFlagsPage() {
  // Flags reflecting your API or app config
  const [flags, setFlags] = useState<Record<string, boolean>>({
    darkMode: true,
    betaFeatures: false,
    advancedMetrics: true,
  })
  const [isSaving, setIsSaving] = useState(false)

const handleSave = async (updatedFlags: Record<string, boolean>) => {
    setIsSaving(true)
    await api.saveFeatureFlags(updatedFlags)
    setFlags(updatedFlags)
    setIsSaving(false)
  }

return (
    <FeatureFlagsSettings
      featureFlags={flags}
      isEditingEnabled={true}
      isSaving={isSaving}
      onSave={handleSave}
    />
  )
}
```

## Features

### Add flags

Developers add new feature flags through the UI by entering comma-separated names. Flag names are arbitrary strings; the component does not validate
against a predefined list.

### Toggle flags

Each flag displays a toggle switch to enable/disable it. Changes are held locally until the end user clicks **Save**.

### Delete flags

End user can click the trash icon next to any flag to remove it from the list.

## Permission check

When `isEditingEnabled` is `false`, the component renders an empty state:

```tsx
<FeatureFlagsSettings
  featureFlags={flags}
  isEditingEnabled={false}  // Shows "Update feature flags not enabled"
  onSave={handleSave}
/>
```

## Integration

Feature flags are typically fetched from your backend API. This component provides the UI for viewing and editing them, it does not manage persistence.
Use the `onSave` callback to sync changes back to your server.

## Styling

The component uses the `.mdk-settings-feature-flags` CSS class. Key selectors:

{/* todo when on public (verify link) The component uses the [`.mdk-settings-feature-flags`](https://github.com/tetherto/mdk/blob/main/ui/packages/react-devkit/src/foundation/components/settings/feature-flags/USAGE.md) CSS class. Key selectors: */}

- `.mdk-settings-feature-flags__add-row`: Input and add button container
- `.mdk-settings-feature-flags__toggles`: Grid of flag toggles
- `.mdk-settings-feature-flags__flag-item`: Individual flag row
- `.mdk-settings-feature-flags__save`: Save button container

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useIsFeatureEditingEnabled`](/reference/app-toolkit/hooks/utilities#useisfeatureeditingenabled) | Permission guard that returns `true` when the current user can toggle feature flags |

# Header controls settings (/reference/ui/react/foundation/settings/header-controls)

It provides:

1. **Data** (`preferences`): current visibility state for header items.
2. **Callbacks** (`onToggle`, `onReset`): handle changes and reset to defaults.
3. **State** (`isLoading`): optional loading feedback.
4. **Styling** (`className`): optional CSS class.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `preferences` | Required | [`HeaderPreferences`](/reference/app-toolkit/ui-devkit/constants#headerpreferences-type) | none | Current header visibility preferences |
| `onToggle` | Required | `function` | none | Callback when a toggle changes |
| `onReset` | Required | `function` | none | Callback to reset to defaults |
| `isLoading` | Optional | `boolean` | `false` | Loading state |
| `className` | Optional | `string` | none | Additional CSS class |

## Data structure

The `HeaderPreferences` type maps header item keys to visibility booleans. See [constants](/reference/app-toolkit/ui-devkit/constants#header-controls) for the full list.

```tsx

type HeaderPreferences = {
  poolMiners: boolean
  miners: boolean
  poolHashrate: boolean
  hashrate: boolean
  consumption: boolean
  efficiency: boolean
}
```

## Basic usage

Changes apply instantly via `onToggle`. The callback receives the preference key and new value:

```tsx
const handleToggle = (key: keyof HeaderPreferences, value: boolean) => {
  setPreferences(prev => ({ ...prev, [key]: value }))
  api.updateHeaderPreference(key, value)  // persist immediately
}
```

<Callout type="info">
There is no **Save** button, each toggle immediately persists via your callback.
</Callout>

### Example

```tsx

function HeaderSettingsSection() {
  const [preferences, setPreferences] = useState<HeaderPreferences>({
    poolMiners: true,
    miners: true,
    poolHashrate: true,
    hashrate: false,
    consumption: true,
    efficiency: true,
  })

const handleToggle = (key: keyof HeaderPreferences, value: boolean) => {
    setPreferences(prev => ({ ...prev, [key]: value }))
    api.updateHeaderPreference(key, value)
  }

const handleReset = () => {
    setPreferences(DEFAULT_HEADER_PREFERENCES)
    api.resetHeaderPreferences()
  }

return (
    <HeaderControlsSettings
      preferences={preferences}
      onToggle={handleToggle}
      onReset={handleReset}
    />
  )
}
```

## Features

### Table layout

The component renders a table with:
- **Header Item** column: label for the metric
- **Visibility Toggle** column: switch to show/hide

Items are defined by [`HEADER_ITEMS`](/reference/app-toolkit/ui-devkit/constants#header_items). Labels for the in-app rows (`miners`, `hashrate`) are composed from [`WEBAPP_SHORT_NAME`](/reference/app-toolkit/ui-devkit/constants#webapp_short_name), so they reflect the brand string the foundation kit ships with.

### Reset to default

The **Reset to Default** button calls your `onReset` callback. You define what "default" means:

```tsx

const handleReset = () => {
  setPreferences(DEFAULT_HEADER_PREFERENCES)
  api.resetHeaderPreferences()
}
```

## Loading state

When `isLoading` is `true` and no preferences are available, a spinner is shown:

```tsx
<HeaderControlsSettings
  preferences={null}
  isLoading={true}
  onToggle={handleToggle}
  onReset={handleReset}
/>
```

## Styling

The component uses the `.mdk-settings-header-controls` CSS class. Key selectors:

- `.mdk-settings-header-controls__description`: Explanatory text
- `.mdk-settings-header-controls__table`: Table container
- `.mdk-settings-header-controls__table-header`: Header row
- `.mdk-settings-header-controls__table-row`: Data rows
- `.mdk-settings-header-controls__actions`: Reset button container

## Related hooks

| Hook | Supplies |
|------|---------|
| [`useHeaderControls`](/reference/app-toolkit/hooks/components#useheadercontrols) | Read/write access to the global header-controls store — toggle visibility, set sticky state, and read current values |

# Header items (/reference/ui/react/foundation/settings/header-controls/header-items)

The header bar components that render live stats and controls in the persistent app header. Visibility for each item is governed by [`HeaderControlsSettings`](/reference/ui/react/foundation/settings/header-controls) and the `HeaderPreferences` object.

For vendor-agnostic dashboard body cards see [Dashboard › Stats › Generic widgets](/reference/ui/react/foundation/dashboard/stats/generic-widgets).

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Components

---

### `HeaderStatsBar`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `children` | Required | `ReactNode` | none | Stat box components to render left-to-right |
| `className` | Optional | `string` | none | Optional root class override |

#### Basic usage

`HeaderStatsBar` is a slot-based container. Pass the stat boxes you want to show as children — the bar inserts an angled chevron divider between each pair automatically.

```tsx
  HeaderStatsBar,
  HeaderMinersBox,
  HeaderHashrateBox,
  HeaderConsumptionBox,
  HeaderEfficiencyBox,
} from '@tetherto/mdk-react-devkit/foundation'

<HeaderStatsBar>
  <HeaderMinersBox
    total={2188}
    online={158}
    error={1}
    offline={57}
    mosTotal={216}
    poolTotal={205}
    poolOnline={201}
    poolMismatch={4}
  />
  <HeaderHashrateBox mosPhs={63.262} poolPhs={52.687} />
  <HeaderConsumptionBox valueMw={1.663} />
  <HeaderEfficiencyBox valueWthS={26.29} />
</HeaderStatsBar>
```

#### Styling

- `.mdk-header-stats-bar`: Root flex strip
- `.mdk-header-stats-bar__divider`: Angled chevron icon between children

---

### `HeaderMinersBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `total` | Optional | `number` | none | Total miners on site (denominator) |
| `online` | Optional | `number` | none | Online miner count (green, also the numerator in the ratio) |
| `error` | Optional | `number` | none | Miners in warning state (amber) |
| `offline` | Optional | `number` | none | Offline miners (red) |
| `mosTotal` | Optional | `number` | none | Total miners reporting to MOS |
| `poolTotal` | Optional | `number` | none | Total miners as reported by upstream pools |
| `poolOnline` | Optional | `number` | none | Pool-side online count (green) |
| `poolMismatch` | Optional | `number` | none | Pool-side mismatch count (red) |
| `icon` | Optional | `ReactNode` | none | Override the default miner icon |
| `className` | Optional | `string` | none | Optional root class override |

All numeric values fall back to `—` when undefined.

#### Basic usage

```tsx
<HeaderMinersBox
  total={2188}
  online={158}
  error={1}
  offline={57}
  mosTotal={216}
  poolTotal={205}
  poolOnline={201}
  poolMismatch={4}
/>
```

#### Styling

- `.mdk-header-stat-box`: Shared stat cell root
- `.mdk-header-stat-box__icon`: Icon slot
- `.mdk-header-stat-box__body`: Text content area
- `.mdk-header-stat-box__row`: Each label/value row
- `.mdk-header-stat-box__success`: Green value (online)
- `.mdk-header-stat-box__warning`: Amber value (error)
- `.mdk-header-stat-box__danger`: Red value (offline / mismatch)
- `.mdk-header-stat-box__accent`: Highlighted online ratio
- `.mdk-header-stat-box__muted`: Subdued label text

---

### `HeaderHashrateBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `mosPhs` | Optional | `number` | none | MOS-side aggregate hashrate in PH/s |
| `poolPhs` | Optional | `number` | none | Pool-side aggregate hashrate in PH/s |
| `unit` | Optional | `string` | varies | Unit label — see individual component for default |
| `icon` | Optional | `ReactNode` | none | Override the default miner icon |
| `className` | Optional | `string` | none | Optional root class override |

#### Basic usage

```tsx
<HeaderHashrateBox mosPhs={63.262} poolPhs={52.687} />
```

---

### `HeaderConsumptionBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `valueMw` | Optional | `number` | none | Current site-level power consumption in megawatts |
| `unit` | Optional | `string` | varies | Unit label — see individual component for default |
| `icon` | Optional | `ReactNode` | none | Override the default miner icon |
| `className` | Optional | `string` | none | Optional root class override |

The value is formatted to 3 decimal places and rendered in the accent (orange) colour token.

#### Basic usage

```tsx
<HeaderConsumptionBox valueMw={1.663} />
```

---

### `HeaderEfficiencyBox`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `valueWthS` | Optional | `number` | none | Efficiency in W/TH/s (`power_w / hashrate_th`) |
| `unit` | Optional | `string` | varies | Unit label — see individual component for default |
| `icon` | Optional | `ReactNode` | none | Override the default miner icon |
| `className` | Optional | `string` | none | Optional root class override |

The value is formatted to 2 decimal places.

#### Basic usage

```tsx
<HeaderEfficiencyBox valueWthS={26.29} />
```

---

### `DashboardDateRangePicker`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `value` | Required | `DashboardDateRange` | none | Current range as `{ start, end }` epoch-millisecond timestamps |
| `onChange` | Required | `function` | none | Fires with the next `{ start, end }` window when the user applies a range |
| `dateFormat` | Optional | `string` | `'dd/MM/yyyy'` | Display format — defaults to `dd/MM/yyyy` |
| `disabled` | Optional | `boolean` | `false` | Disable the trigger |
| `className` | Optional | `string` | none | Optional root class override |

#### `DashboardDateRange` type

```tsx
type DashboardDateRange = {
  start: number  // epoch ms
  end: number    // epoch ms
}
```

#### Basic usage

Designed to slot directly into `useDashboardDateRange` from `@tetherto/mdk-react-adapter`:

```tsx

const { start, end, setRange } = useDashboardDateRange()

return (
    <DashboardDateRangePicker
      value={{ start, end }}
      onChange={({ start, end }) => setRange(start, end)}
    />
  )
}
```

#### Styling

- `.mdk-dashboard-date-range-picker__trigger`: Trigger button
- `.mdk-dashboard-date-range-picker__modal`: Calendar modal

---

### `ExportButton`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `onExport` | Required | `function` | none | Fires with `'csv'` or `'json'` when the user picks a format |
| `formats` | Optional | `readonly ExportFormat[]` | `['csv', 'json']` | Formats to offer in the dropdown — defaults to `['csv', 'json']` |
| `label` | Optional | `string` | `'Profile menu'` | Accessible label for the trigger button — defaults to `'Profile menu'` |
| `disabled` | Optional | `boolean` | `false` | Disable the trigger |
| `className` | Optional | `string` | none | Optional root class override |

#### `ExportFormat` type

```tsx
type ExportFormat = 'csv' | 'json'
```

#### Basic usage

```tsx

<ExportButton
  onExport={(format) => {
    if (format === 'csv') downloadCsv(data)
    else downloadJson(data)
  }}
/>
```

#### Styling

- `.mdk-export-button`: Trigger button wrapper
- `.mdk-export-button__label`: Label text span
- `.mdk-export-button__chevron`: Dropdown chevron icon
- `.mdk-export-button__menu`: Dropdown menu container

---

### `ProfileMenu`

#### Import

```tsx
```

#### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `items` | Required | `ProfileMenuItem[]` | none | Items rendered in the dropdown, top-to-bottom. Defaults to a single "Sign out" item. |
| `user` | Optional | `ReactNode` | none | Optional user label rendered at the top of the dropdown (e.g. an email) |
| `icon` | Optional | `ReactNode` | none | Override the default miner icon |
| `label` | Optional | `string` | `'Profile menu'` | Accessible label for the trigger button — defaults to `'Profile menu'` |
| `className` | Optional | `string` | none | Optional root class override |

#### `ProfileMenuItem` type

```tsx
type ProfileMenuItem = {
  label: string
  onSelect: () => void
  danger?: boolean       // render as a destructive action (red)
  icon?: ReactNode       // optional leading icon
  description?: ReactNode // optional secondary line (e.g. "Current: Europe/Podgorica")
  disabled?: boolean
}
```

#### Basic usage

```tsx

<ProfileMenu
  user="admin@example.com"
  items={[
    {
      label: 'Timezone',
      description: 'Current: Europe/Podgorica',
      onSelect: () => openTimezoneDialog(),
    },
    {
      label: 'Sign out',
      danger: true,
      onSelect: () => auth.signOut(),
    },
  ]}
/>
```

#### Styling

- `.mdk-profile-menu__trigger`: Trigger button
- `.mdk-profile-menu__user`: User label at top of dropdown
- `.mdk-profile-menu__item`: Menu item row
- `.mdk-profile-menu__item--two-line`: Modifier when `description` is present
- `.mdk-profile-menu__item--danger`: Modifier for destructive items
- `.mdk-profile-menu__item-icon`: Leading icon slot
- `.mdk-profile-menu__item-body`: Label + description wrapper
- `.mdk-profile-menu__item-label`: Primary label text
- `.mdk-profile-menu__item-description`: Secondary description text

# Import/export settings (/reference/ui/react/foundation/settings/import-export)

It manages:

1. **Export** (`onExport`): callback to generate and download settings JSON.
2. **Import** (`onImport`): callback when end user confirms import.
3. **File parsing** (`onParseFile`): validate and parse uploaded files.
4. **State indicators** (`isExporting`, `isImporting`): show loading feedback.
5. **Styling** (`className`): optional CSS class.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## Import

```tsx
```

## Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `onExport` | Required | `function` | none | Callback to trigger settings export |
| `onImport` | Required | `function` | none | Callback when import is confirmed |
| `onParseFile` | Optional | `function` | none | Parse and validate uploaded file |
| `isExporting` | Optional | `boolean` | `false` | Export in progress |
| `isImporting` | Optional | `boolean` | `false` | Import in progress |
| `className` | Optional | `string` | none | Additional CSS class |

## Data structure

The [`SettingsExportData`](/reference/app-toolkit/ui-devkit/types#settingsexportdata) type defines the structure for exported settings:

```tsx

type SettingsExportData = {
  headerControls?: HeaderPreferences
  featureFlags?: Record<string, boolean>
  timestamp?: string
}
```

## Callbacks

### `onExport`

Called when end user clicks **Export JSON**. Generate settings and trigger download:

```tsx
const handleExport = async () => {
  const data = await api.getSettingsExport()
  downloadJson(data, 'settings-backup.json')
}
```

### `onImport`

Called after end user confirms import. Receives parsed `SettingsExportData`:

```tsx
const handleImport = async (data: SettingsExportData) => {
  await api.importSettings(data)
}
```

### `onParseFile`

Validates and parses the uploaded file. Must return a `Promise<SettingsExportData>`:

```tsx
const parseFile = async (file: File): Promise<SettingsExportData> => {
  const text = await file.text()
  return JSON.parse(text)
}
```

## Basic usage

```tsx

function ImportExportSection() {
  const [isExporting, setIsExporting] = useState(false)
  const [isImporting, setIsImporting] = useState(false)

const handleExport = async () => {
    setIsExporting(true)
    const data = await api.getSettingsExport()
    downloadJson(data, 'settings-backup.json')
    setIsExporting(false)
  }

const handleImport = async (data: SettingsExportData) => {
    setIsImporting(true)
    await api.importSettings(data)
    setIsImporting(false)
  }

const parseFile = async (file: File): Promise<SettingsExportData> => {
    const text = await file.text()
    return JSON.parse(text)
  }

return (
    <ImportExportSettings
      onExport={handleExport}
      onImport={handleImport}
      onParseFile={parseFile}
      isExporting={isExporting}
      isImporting={isImporting}
    />
  )
}
```

## Features

### Export

Clicking **Export JSON** triggers the `onExport` callback. The developer is responsible for:

- Fetching current settings
- Converting to JSON
- Triggering file download

### Import flow

1. End user clicks **Import JSON**.
2. Modal opens with file upload area.
3. End user selects a `.json` or `.csv` file.
4. `onParseFile` validates and parses the file.
5. Confirmation modal shows what will be imported.
6. End user confirms and `onImport` is called with parsed data.

### Confirmation modal

Before importing, end users see a confirmation dialog listing:

- Header Controls (if present)
- Feature Flags (if present)
- Export timestamp (if available)

## Accepted file formats

The file input accepts:

- `.json`: JSON format
- `.csv`: CSV format (requires custom `onParseFile` handling)

## Warning message

The component displays a warning:

<Callout type="warning">
Importing settings will overwrite your current configuration. Make sure to export your current settings before importing.
</Callout>

## Styling

The component uses the `.mdk-settings-import-export` CSS class. Key selectors:

- `.mdk-settings-import-export__description`: explanatory text
- `.mdk-settings-import-export__actions`: button container
- `.mdk-settings-import-export__warning`: warning message
- `.mdk-settings-import-export__upload-area`: file drop zone in modal

# User management modals (/reference/ui/react/foundation/settings/user-management)

These modal components handle user creation, editing, and confirmation dialogs.

While they are designed to be used within
[`RBACControlSettings`](/reference/ui/react/foundation/settings/access-control) the three modal components can stand alone:

1. **[`AddUserModal`](#addusermodal)**: create new users with form validation.
2. **[`ManageUserModal`](#manageusermodal)**: edit users and view effective permissions.
3. **[`ChangeConfirmationModal`](#changeconfirmationmodal)**: confirm destructive or important actions.

## Prerequisites

- Complete the [@tetherto/mdk-react-devkit installation and add the dependency](/reference/ui/react/foundation#prerequisites)

## `AddUserModal`

## Import

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Whether the modal is visible |
| `roles` | Required | `array` | none | Available roles for selection |
| `onSubmit` | Required | `function` | none | Called with form data on submit |
| `onClose` | Required | `function` | none | Called when modal should close |
| `isSubmitting` | Optional | `boolean` | `false` | Shows loading state on submit button |

### `RoleOption` structure

Full type: [`RoleOption` in Types reference](/reference/app-toolkit/ui-devkit/types#roleoption).

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string` | Role identifier |
| `label` | `string` | Display name |

### Callbacks

The `onSubmit` callback receives the validated form data:

```tsx
const handleSubmit = async (data) => {
  // data: { name: string, email: string, role: string }
  await api.createUser(data)  // persist to backend
  refetchUsers()               // refresh list
}
```

The modal resets its form after successful submission.

#### Example

```tsx
function UserActions() {
  const [isOpen, setIsOpen] = useState(false)

const handleSubmit = async (data) => {
    await api.createUser(data)
    setIsOpen(false)
  }

return (
    <>
      <Button onClick={() => setIsOpen(true)}>Add User</Button>
      <AddUserModal
        open={isOpen}
        onClose={() => setIsOpen(false)}
        roles={[
          { value: 'admin', label: 'Admin' },
          { value: 'operator', label: 'Operator' },
        ]}
        onSubmit={handleSubmit}
      />
    </>
  )
}
```

### Form fields

- **Name**: required, trimmed
- **Email**: required, must be valid email
- **Role**: required, select from available roles

Validation uses Zod schema with `react-hook-form`. The modal displays **Add User** and **Cancel** buttons.

## `ManageUserModal`

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Whether the modal is visible |
| `user` | Required | [`SettingsUser`](/reference/app-toolkit/ui-devkit/types#settingsuser) | none | User being edited |
| `roles` | Required | `array` | none | Available roles |
| `rolePermissions` | Required | `object` | none | Permissions by role |
| `permissionLabels` | Required | `object` | none | Permission display names |
| `onSubmit` | Required | `function` | none | Called with updated data on submit |
| `onClose` | Required | `function` | none | Called when modal should close |
| `isSubmitting` | Optional | `boolean` | `false` | Shows loading state on submit button |

### Data structures

The `rolePermissions` object maps role IDs to their permissions:

```tsx
const rolePermissions = {
  admin: { users: 'rw', settings: 'rw', reports: 'r' },
  operator: { users: 'r', settings: 'none', reports: 'r' }
}
```

The `permissionLabels` object provides display names:

```tsx
const permissionLabels = {
  users: 'User Management',
  settings: 'System Settings',
  reports: 'Reports'
}
```

### Callbacks

The `onSubmit` callback receives the updated user data:

```tsx
const handleSubmit = async (data) => {
  // data: { id: string, name: string, email: string, role: string }
  await api.updateUser(data)  // persist to backend
  refetchUsers()               // refresh list
}
```

### Example

```tsx
function UserRow({ user }) {
  const [isEditing, setIsEditing] = useState(false)

const handleSubmit = async (data) => {
    await api.updateUser(data)
    setIsEditing(false)
  }

return (
    <>
      <Button onClick={() => setIsEditing(true)}>Manage</Button>
      <ManageUserModal
        open={isEditing}
        onClose={() => setIsEditing(false)}
        user={user}
        roles={roles}
        rolePermissions={rolePermissions}
        permissionLabels={permissionLabels}
        onSubmit={handleSubmit}
      />
    </>
  )
}
```

### Sections

The modal is divided into three sections:

1. **User Information**: edit name and email.
2. **Assigned Role**: select role from dropdown.
3. **Effective Permissions**: read-only table showing what the selected role can do.

### Permission icons

Permissions display icons based on level:

- `rw`: Read/Write (full access)
- `r`: Read (view only)
- `none`: No access

The modal displays **Save Changes** and **Cancel** buttons.

## `ChangeConfirmationModal`

```tsx
```

### Props

| Prop | Status | Type | Default | Description |
|------|--------|------|---------|-------------|
| `open` | Required | `boolean` | none | Whether the modal is visible |
| `title` | Required | `string` | none | Modal title |
| `children` | Required | `ReactNode` | none | Modal body content |
| `onConfirm` | Required | `function` | none | Called when end user confirms |
| `onClose` | Required | `function` | none | Called when end user cancels or closes |
| `confirmText` | Optional | `string` | `'Confirm'` | Text for confirm button |
| `destructive` | Optional | `boolean` | `false` | Use danger styling (red button) |

### Example

```tsx
function DeleteButton({ user }) {
  const [showConfirm, setShowConfirm] = useState(false)

const handleDelete = async () => {
    await api.deleteUser(user.id)
    setShowConfirm(false)
  }

return (
    <>
      <Button onClick={() => setShowConfirm(true)}>Delete</Button>
      <ChangeConfirmationModal
        open={showConfirm}
        title={`Delete ${user.email}?`}
        onClose={() => setShowConfirm(false)}
        onConfirm={handleDelete}
        confirmText="Delete"
        destructive
      >
        Are you sure you want to delete this user? This action is permanent
        and cannot be undone.
      </ChangeConfirmationModal>
    </>
  )
}
```

### Variants

#### Standard confirmation

```tsx
<ChangeConfirmationModal
  title="Save Changes?"
  confirmText="Save"
  destructive={false}
>
  Your changes will be applied immediately.
</ChangeConfirmationModal>
```

#### Destructive confirmation

```tsx
<ChangeConfirmationModal
  title="Delete Item?"
  confirmText="Delete"
  destructive
>
  This action cannot be undone.
</ChangeConfirmationModal>
```

The modal displays a **Cancel** button alongside the configurable confirm button.

## Dependencies

All user management modals depend on `@tetherto/mdk-react-devkit/core` components:

- `Dialog`, `DialogContent`, `DialogFooter`
- `Button`
- `Form`, `FormInput`, `FormSelect`

They also use:

- `react-hook-form` for form state
- `zod` for validation
- `@hookform/resolvers` for Zod integration

# Code of Conduct (/support/community/code-of-conduct)

## Our Commitment

MDK is committed to fostering an open, professional, and respectful community.

We welcome contributors of all backgrounds and experience levels. Participation in the MDK community should be harassment-free and inclusive for everyone.

---

## Expected Behavior

All participants in the MDK community are expected to:

- Be respectful and constructive in communication
- Provide helpful and professional feedback
- Assume good intent
- Focus on what is best for the project
- Accept constructive criticism gracefully

---

## Unacceptable Behavior

The following behaviors are not tolerated:

- Harassment, discrimination, or hateful conduct
- Personal attacks or insulting language
- Public or private harassment
- Trolling, intimidation, or deliberate disruption
- Publishing private information without consent
- Any conduct that would be considered unprofessional in a workplace setting

---

## Scope

This Code of Conduct applies to:

- GitHub repositories
- Issues and pull requests
- Discussions and community channels
- Official MDK communication platforms
- Any other space officially associated with the MDK project

---

## Enforcement

The Community Manager is responsible for enforcing this Code of Conduct.

**Community Manager:** Gio\
**Lead Maintainer:** Hemant T

If you experience or witness unacceptable behavior, report it privately to the Community Manager.

Reports will be handled confidentially and reviewed in coordination with the MDK core team.

---

## Enforcement Guidelines

The MDK core team may take any action deemed appropriate, including:

- Warning the participant
- Temporarily restricting access
- Permanently banning a participant from the community
- Removing content that violates this Code of Conduct

Decisions regarding enforcement are final.

---

## Amendments

This Code of Conduct may be updated from time to time by the MDK core team to reflect evolving community needs.

# Contributing (/support/community/contributing)

# Contribute to MDK

Thank you for your interest in contributing to [MDK](https://github.com/tetherto/mdk/).

This document outlines the contribution workflow for the MDK repository, from setting up your development environment to
submitting pull requests and participating in releases.

## Security

If you discover a security vulnerability, do not report it in a public issue.

Please follow the private disclosure instructions in [SECURITY.md](https://github.com/tetherto/mdk/blob/main/SECURITY.md).

## Monorepo structure

MDK is a monorepo with separate backend and frontend workspaces:

- Backend:
  - `backend/core/`: Backend services, container modules, and integration/unit tests (npm-based)
  - `backend/workers/`: Protocol-translator worker packages (miners, miner-pools, power-meter, temperature, containers), per-worker mock servers, and per-worker tests (npm-based)
- Frontend: `ui/`: Frontend packages, demo app, and shared UI foundation (npm + Turbo-based)

Choose the backend or frontend workflow that matches the area you are contributing to.

### Root configuration must be domain-aware

The repo top level is a fixed set of domains (`ui/`, `backend/`, `docs/`, `examples/`) plus tooling and repo-meta files.
Shared root config (today just `.gitignore`) is read across all of them, so every pattern must be written so it cannot
silently match another domain's source:

- **Anchor anything that targets one domain's build or runtime output.** Use `/name/` for the repo root or `domain/**/name/`
for a subtree. A bare `status` / `store` / `tmp` / `Checklist*` matches a file or directory of that name *anywhere*,
including UI source. That is exactly what caused a prior root ignore regression, where bare `status` / `store`
swallowed `ui/packages/ui-foundation/src/store/`.
- **Keep per-domain ignores in that domain's own `.gitignore`** (`ui/.gitignore`, the per-package backend `.gitignore`s),
not the root. Things like `dist`, `.turbo`, and `build` belong to a domain.
- **Lint/format/type config is domain-owned, not shared at the root.** `ui/` ships its own `eslint.config.mjs` /
`tsconfig.base.json` / `.prettierrc`; backend uses `standard`. Do not add a root-level eslint/tsconfig/prettier
that would apply across domains.
- **A genuinely shared convention is fine if it applies identically to every domain** - e.g. committing
`config/*.json.example` while ignoring the generated `config/*.json`. Note it as shared so the intent is clear.

## Get started

### Prerequisites

Before contributing, ensure you have the following installed:

- **Node.js** (version >=24)
- **Git** (latest stable version)
- **npm** (version 11 or higher)

### Licensing

MDK is released under the [**Apache License 2.0**](https://github.com/tetherto/mdk/blob/main/LICENSE).

By contributing, you agree that:

- You retain copyright over your contributions
- You grant a perpetual, worldwide, royalty-free license for their use
- Contributions are provided **“AS IS”**, without warranty

## Development environment setup

<details>
<summary>1. Fork and clone</summary>

1. Fork [the repository](https://github.com/tetherto/mdk.git) on GitHub.
2. Clone your fork locally and navigate into the project directory:
```bash
git clone https://github.com/username/mdk.git
cd mdk
```

1. Add the upstream remote:

```bash
git remote add upstream https://github.com/tetherto/mdk.git
```

</details>

Keep your fork in sync with the main repository. For example:

```bash
git fetch upstream
git merge --ff-only upstream/main   # fails loudly if main has diverged
```

</details>

### Backend contribution setup

Use this workflow when contributing to backend code under `backend/core/`.

```bash
cd backend/core
npm install
```

#### Common commands

```bash
# Lint backend code
npm run lint

# Run backend test suite (lint + unit + integration + package tests)
npm test

```

### Frontend contribution setup

Use this workflow when contributing to frontend code under `ui/`.

```bash
cd ui
npm install
```

#### Common commands

```bash
# Build packages
npm run build

# Run dev mode (all packages + demo)
npm run dev

# Lint and type-check
npm run lint
npm run typecheck

# Run tests
npm test
```

## Pull request workflow

### Conventional types

MDK uses Conventional Commits-style types for both branch names and PR titles.

| Type | Use for |
|---|---|
| `feat` | New features |
| `fix` | Bug fixes |
| `docs` | Documentation changes |
| `refactor` | Code refactoring without behaviour change |
| `test` | Test additions or changes |
| `chore` | Tooling, dependencies, repo maintenance |
| `perf` | Performance improvements |
| `style` | Formatting only (no logic change) |
| `ci` | CI configuration changes |
| `build` | Build system or external dependency changes |

### Branch naming convention

Create branches using the following pattern:

```bash
{type}/{short-description}
```

Where `{type}` is one of the [conventional types](#conventional-types).

#### Branch naming examples

```bash
# New feature
git checkout -b feat/mdk-new-device

# Bug fix
git checkout -b fix/timeout-handling
```

### Commit message template

The repository ships a commit message template at `.gitmessage` that pre-fills the
commit editor with the expected format (type, summary, body, and Asana/Related PR references).
Enable it once per clone:

```bash
git config commit.template .gitmessage
```

This is a local convenience only — it is not enforced, and the [conventional types](#conventional-types)
above remain the source of truth for commit, branch, and PR naming.

### Pull request steps

1. Sync your local main with upstream `main`.
2. Create a branch from local `main`.
3. Make your code changes.
4. Write or update tests.
5. Run linting and tests locally in the workspaces you changed:
   - `core`: `npm run lint && npm test`
   - `ui`: `npm run lint && npm test` (and `npm run typecheck` for TypeScript changes)
6. Commit changes with meaningful messages.
7. Push your branch and open a Pull Request targeting the upstream `main`.

### PR checklist

Before submitting your PR, ensure that:

- [ ] Code builds locally (`npm run build` for `ui` changes)
- [ ] Tests pass in affected workspaces (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Type-check passes for frontend TypeScript changes (`npm run typecheck`)
- [ ] New features include tests
- [ ] Public behavior or APIs changes have a [`docs-needed` issue](https://github.com/tetherto/mdk/issues/new?template=docs-needed.yml) linked to the PR

### PR title format

Use the following convention:

```bash
{type}({scope}): {description}
```

Where `{type}` is one of the [conventional types](#conventional-types) and `{scope}` is the affected area,
for example `miner` or `ui`.

Examples:

- `feat(miner): add Antminer S21 support`
- `fix(timeout): resolve action timeout handling`
- `docs(api): update stats documentation`

## PR review

All pull requests go through the following review steps:

1. **Automated checks**: Linting and tests must pass.
2. **Code review**: At least 2 maintainer approvals are required.
3. **Feedback resolution**: All requested changes must be addressed.
4. **Squash and merge**: Maintainers squash commits to keep history clean.

### Workflow diagram

```mermaid
flowchart TB
    subgraph contributor [Contributor]
        start((Start)) --> createBranch[Create branch from main]
        createBranch --> test[Run tests]
        test --> testGw{Tests pass?}
        testGw -->|No| fix[Fix issues]
        fix --> test
        testGw -->|Yes| createPR[Create PR]
        createPR --> review
        address[Address feedback] --> pushFixes[Push fixes]
        pushFixes --> test
    end

subgraph reviewer [Reviewer / Maintainer]
        review[Code review]
        reviewGw{Approved?}
        review --> reviewGw
        reviewGw -->|Request changes| address
        reviewGw -->|Rejected| cancel[Close PR]
        reviewGw -->|Approved| merge[Merge to main]
        merge --> tagGw{Tag release?}
        tagGw -->|No| endNoTag((End))
        tagGw -->|Yes| tag[Tag version]
        tag --> deploy[Deploy]
        deploy --> deployGw{Deploy success?}
        deployGw -->|Yes| endSuccess((End))
        deployGw -->|No| rollback[Rollback]
        rollback --> fix
    end
```

## Code standards

MDK uses **StandardJS** style to keep the codebase consistent and easy to review across repositories.

Key rules:

- 2-space indentation
- No semicolons
- Single quotes for strings
- Space after keywords (`if`, `for`, `while`)
- No unused variables

## Versioning and tagging

MDK follows **Semantic Versioning**:

- **MAJOR** (`1.x.x`): breaking changes
- **MINOR** (`x.1.x`): new backward-compatible features
- **PATCH** (`x.x.1`): backward-compatible bug fixes

When the MDK team provides a release, they are cut from a `release/<version>` branch, verified in CI,
promoted to the public repo, then tagged. For the full release process and checklist, see RELEASING.md.

Happy contributing, and thanks for helping improve MDK! 🚀

# Governance (/support/community/governance)

This document describes how the MDK project is governed and how decisions are made.

MDK is an open-source project. While the code is publicly available and community contributions are welcome, final decision-making authority rests with the MDK core team.

---

## Project Roles

### Users
Anyone who uses MDK and provides feedback, bug reports, or feature requests.

### Contributors
Community members who contribute code, documentation, tests, or other improvements via pull requests or issues.

Contributors do not have merge access.

---

### Maintainers
Maintainers are responsible for reviewing pull requests, maintaining code quality, and ensuring alignment with the project roadmap.

Maintainers may be appointed by the Lead Maintainer.

The following GitHub IDs currently hold maintainer status for MDK:
- arif-dewi
- eugeneglova
- robdll
- eskawl
- boris91
- habrahamyanbf
- efr-nox
- rob-aslanian
- mukama
- paragmore
- tekwani

Only the GitHub accounts listed above have maintainer privileges within the MDK repositories. Maintainer status is granted based on demonstrated technical expertise, sustained contribution, and alignment with project goals.

---

### MDK core team
The MDK Core Team consists of all active developers, the Project Manager, and the Community Manager.

The Core Team is responsible for the overall health, sustainability, and long-term success of the project. While specific authorities are defined for the Lead Maintainer (technical) and the Community Manager (strategic), the Core Team operates as the primary collaborative decision-making body.

### Lead Maintainer
**Hemant T** is the Lead Maintainer and Technical Lead for MDK.

The Lead Maintainer has final authority over:

- Pull request approval and merging
- Architecture and design decisions
- Release planning and versioning
- Accepting or rejecting features
- Appointing or removing maintainers

If consensus cannot be reached among maintainers, the Lead Maintainer makes the final decision.

---

### Community Manager
**Gio** is the Community Manager for MDK.

The Community Manager is responsible for:

- Managing community communication channels
- Moderating discussions and enforcing the Code of Conduct
- Supporting contributors during onboarding
- Acting as a bridge between the community and the MDK core team
- Defining, maintaining, and communicating the project vision and long-term direction
- Leading roadmap prioritization and strategic planning

---

## Decision-Making Process

- Community members may propose changes via issues or pull requests
- Maintainers review contributions for quality, security, and alignment with MDK goals
- The Lead Maintainer has final approval authority on all technical decisions
- Strategic, roadmap, or breaking changes are determined by the MDK core team
- The Community Manager has final decision-making authority over all strategic and directional matters, including project vision, roadmap prioritization, major feature introductions, partnerships, and significant pivots
- In cases where strategic direction and technical considerations intersect, the Community Manager determines the final strategic outcome, while the Lead Maintainer determines the final technical implementation approach.

---

## Contribution Review Process

- All contributions must follow `CONTRIBUTING.md`
- Pull requests require review by a maintainer
- Final approval and merge is performed by the Lead Maintainer
- The MDK team reserves the right to decline contributions that do not align with the project direction

---

## Inactivity and Removal

Maintainers who become inactive for an extended period or violate project policies may be removed by the Lead Maintainer.

---

## Code of Conduct

All participants are expected to follow the project's Code of Conduct.
Violations are handled by the Community Manager in coordination with the MDK core team.

See [Code of Conduct](/support/community/code-of-conduct) for details.

---

## Changes to Governance

This governance model may evolve over time.
Any changes will be proposed and approved by the MDK core team.

# MDK Repositories (/support/resources/repositories)

The MDK monorepo makes the frontend and backend components publicly accessible:

- [https://github.com/tetherto/mdk](https://github.com/tetherto/mdk)

*MDK is developed by Tether and released under the [Apache 2.0 license](/support/community/contributing#licensing).*

# Roadmap (/support/resources/roadmap)

MDK follows a **two-week release cadence** to keep progress visible, collect feedback early, and progressively 
harden the platform — from a rudimentary end-to-end foundation toward a production-ready release.

## Release principles

- **Release every two weeks** to keep momentum and feedback loops short
- **Use four maturity phases** to mark clear readiness jumps
- **Start with a working end-to-end developer experience**, then harden progressively
- **Reach production readiness progressively**, not by a single large release
- **Follow standard [semantic versioning](https://semver.org)** — the `0.x` line means MDK is still in 
development and not intended for production

## Versioning and naming strategy

MDK uses standard [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`):

- A **new version ships every two weeks**, bumping the **minor**: `0.2.0` → `0.3.0` → `0.4.0` → …
- **Patch** releases (`0.x.1`) go out only when a fix is needed between the scheduled releases, e.g. 0.2.1
- While MDK is in the **`0.x` line**, interfaces may change and the platform is **not intended for production** — 
this is the standard semver signal, and we use it deliberately so developers can read it literally
- **`1.0.0`** marks the first **production-ready** release

Maturity is tracked by **phase**, not by version number — each phase spans several bi-weekly releases. The four 
phases describe how ready MDK is at each stage:

| Phase | Production-readiness |
|---|---|
| **Foundation** | Experimental. End-to-end but rudimentary. Not stable. |
| **Lab testing** | Complete enough to build against end-to-end, in a lab. Not stable, not for production. |
| **On site testing** | Stable enough to test at real sites under real operating conditions, closely monitored. Not yet production-ready. |
| **Production Ready** | Ready for production deployment, with stable interfaces and compatibility guarantees. |

## 2026

2026 moves MDK through **four phases**:

- **May:** [Foundation](#foundation)
- **July:** [Lab testing](#lab-testing)
- **October:** [On site testing](#on-site-testing)
- **December:** [Production Ready](#production-ready)

Between phases, MDK ships a new release **every two weeks**, starting from the Foundation release at the end of May.
The diagram below shows only the phase milestones; the bi-weekly releases land in the windows between them.

```mermaid
graph TB
    subgraph foundation [Foundation]
        p1([May 2026<br/><b>Foundation</b><br/>Public, end-to-end but rudimentary])
        it1[[Jun–Jul 2026<br/>New release every 2 weeks]]
    end

subgraph lab [Lab testing]
        p2([Jul 2026<br/><b>Lab testing</b><br/>Complete end-to-end, lab only])
        it2[[Aug–Oct 2026<br/>New release every 2 weeks]]
    end

subgraph onsite [On site testing]
        p3([Oct 2026<br/><b>On site testing</b><br/>Testing at real sites])
        it3[[Nov–Dec 2026<br/>New release every 2 weeks]]
    end

subgraph prod [Production Ready]
        p4([Dec 2026<br/><b>Production Ready</b><br/>Production-ready baseline])
    end

p1 --> it1 --> p2 --> it2 --> p3 --> it3 --> p4

style foundation fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style lab fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style onsite fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
    style prod fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A
```

## Release plan

Phase descriptions below focus on the **level of maturity and production-readiness** at each stage. The 
exact feature scope of each two-week release is decided as we go and is not fixed by this roadmap.

### Foundation

*Released end of May 2026.*

The first public release is about **visibility, direction, and feedback**. It is intentionally rudimentary: 
developers can clone it, run an end-to-end example, and get a concrete feel for how MDK fits together. 
Interfaces are expected to change. The goal is to show where MDK is heading and invite feedback from 
developers, partners, and early contributors — not to support real workloads.

### Lab testing

*Target: end of July 2026.*

At this stage MDK is **complete enough to build against end to end**. Developers can run a full workflow 
and experiment with MDK in their own labs. It is **not stable** — breaking changes are still expected 
between releases — and it is **not ready for production**. The goal is to validate the end-to-end 
developer workflow and surface integration gaps before MDK is exposed to real operational conditions.

### On site testing

*Target: end of October 2026.*

This is the first stage intended for **testing at real sites**. MDK should be stable enough to run on 
site under real operating conditions, while still being monitored closely. The goal is to validate performance, 
robustness, deployment workflows, and operational fit in real scenarios. This is not yet a stability commitment — 
interfaces may still change before production readiness.

### Production Ready

*Target: end of December 2026.*

This is the first **production-ready** release (`1.0.0`). By this point MDK offers a solid baseline for production
deployment, with stable core interfaces, validated workflows, and documentation that supports adoption by operators,
integrators, and developers building on top of the platform. From here, standard semver compatibility guarantees apply.

# Tutorials (/tutorials)

## New to MDK? Go from stack to dashboard

Three short tutorials take you from a running MDK stack to a browser dashboard demo. First you watch the stack run, 
then you drive it from the CLI, then you launch the demo dashboard on top. Climb straight through, or jump to the 
rung you need.

<Cards className="grid-cols-1 md:grid-cols-3">
  <Card
    icon={<Play />}
    className="@max-lg:col-span-1"
    title={<span style={cardTitle}>1. Run the stack</span>}
    href="/tutorials/backend-stack/run"
    description={
      <span style={cardProse}>
        <strong>Observe</strong> — one command brings up Kernel with a mock device registered
      </span>
    }
  />
  <Card
    icon={<Terminal />}
    className="@max-lg:col-span-1"
    title={<span style={cardTitle}>2. Control from the CLI</span>}
    href="/tutorials/backend-stack/cli"
    description={
      <span style={cardProse}>
        <strong>Interact</strong> — drive a running stack from a REPL over IPC
      </span>
    }
  />
  <Card
    icon={<LayoutDashboard />}
    className="@max-lg:col-span-1"
    title={<span style={cardTitle}>3. Run a dashboard demo</span>}
    href="/tutorials/full-stack/dashboard"
    description={
      <span style={cardProse}>
        <strong>Demo</strong> — run a React dashboard with live charts on the stack
      </span>
    }
  />
</Cards>

{/* ## Build with MDK

<Cards>
  <Card
    icon={<Layers />}
    title={<span style={cardTitle}>Add MDK data to an existing app</span>}
    href="#framework-quickstarts"
    description={
      <span style={cardProse}>
        Use the <strong>frontend tools</strong> to bring MDK telemetry and controls into a React app
      </span>
    }
  />
  <Card
    icon={<Terminal />}
    title={<span style={cardTitle}>Connect directly to Kernel from any client</span>}
    href="/tutorials/backend-stack"
    description={
      <>
        <span style={cardProse}>
          Start with the backend stack tutorials: run Kernel with a mock device, then control it from a CLI
        </span>
        <span style={cardCta}>Start the backend stack path →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Build a full MDK app from scratch</span>}
    href="/support/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Coming soon: Adopt the App Toolkit shell. Frontend and backend wired together, extended via plugins
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Align the MDK backend with your business logic</span>}
    href="/support/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Coming soon: Use the <strong>backend tools</strong> to plug a library of custom routes and aggregations into the MDK Gateway
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
</Cards> */}

## Get started with your framework

<Cards>
  <Card
    icon={<Atom />}
    title={<span style={cardTitle}>React</span>}
    href="/tutorials/ui/react"
    description={
      <span style={cardProse}>
        Pick a path: lean Quickstart, full Tutorial, or browse the component packages
      </span>
    }
  />
   <Card
    icon={<Bot />}
    title={<span style={cardTitle}>Build with your AI agent</span>}
    href="/quickstart/connect-agents"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Vue
        </span>
      </>
    }
  />
  {/* <Card
    icon="🚧"
    title={<span style={cardTitle}>Vue</span>}
    href="/support/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Vue
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Svelte</span>}
    href="/support/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Reactive hooks for Svelte
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  />
  <Card
    icon="🚧"
    title={<span style={cardTitle}>Web Components</span>}
    href="/support/resources/roadmap"
    description={
      <>
        <span style={cardProse}>
          Framework-agnostic Web Components
        </span>
        <span style={cardCta}>Learn about the release schedule →</span>
      </>
    }
  /> */}
</Cards>

## Next steps

- Learn more about the high-level [architecture](/concepts/architecture): runtime stack and deployment modes
- Compare [deployment topologies](/concepts/deployment-topologies): single process or supervised services
- Run a site from the [deployment guides](/guides/deployment)
- [Contribute](/support/community/contributing)

# Backend stack tutorials (/tutorials/backend-stack)

<Callout type="idea">
See the [whole stack demo at once](/tutorials/quickstart/full-stack) booting all the Worker families for a live site, mock hardware,
a Gateway API, and a React dashboard in one command.
</Callout>

## Overview

This page presents three short tutorials that build on each other. Each rung adds one layer of capability: first you watch the stack run, then
you drive it, then you run a browser demo on top.

| Rung | You'll | You'll end with | Mock hardware | Time |
|---|---|---|---|---|
| [1. Run the stack](/tutorials/backend-stack/run) | **Observe** — run one command and watch a stack come up | Device list, telemetry, and commands printed | Whatsminer M56S | `< 3 min` |
| [2. Control devices from the CLI](/tutorials/backend-stack/cli) | **Interact** — drive a running stack from a REPL | Live telemetry and commands over HRPC via the kernel key file | Whatsminer M56S | `< 3 min` |
| [3. Run the dashboard demo](/tutorials/full-stack/dashboard) | **Run** — launch a browser dashboard on the stack | A React dashboard with live charts at `:3030` | Whatsminer M56S | `< 15 min` after a one-time UI build |

**New to MDK? Start with [1. Run the stack](/tutorials/backend-stack/run).** Each rung links to the next, so you can climb straight through.

<Callout type="info">
All three rungs use the same Whatsminer example to keep things simple. To see MDK working with different hardware, check out the
[full site example](/tutorials/quickstart/full-stack) which runs multiple Worker families (Antminers, Whatsminers, containers, power meters) simultaneously —
all using the same MDK API.
</Callout>

Each rung is self-contained and repeats the clone-and-install step, so you can start at whichever one you need.

## Next steps

- If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary)
- Build the [smallest version of the full MDK stack: **one Worker, one Gateway route, one static HTML page](/tutorials/quickstart/build-a-dashboard)
- Run the [full stack demo](/tutorials/quickstart/full-stack)

# 2. Control from CLI (/tutorials/backend-stack/cli)

*Get started · 2 of 3 · Control devices from the CLI*

<Callout type="info">
If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first.
</Callout>

## Overview

This is rung 2 of the [Get started](/tutorials/backend-stack) ladder: **interact**. It walks the shortest path from a fresh clone to a fully wired MDK stack
you can drive interactively from a CLI. Everything runs in one Node process, no real hardware required.

What you'll have at the end:

- A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028`
- An Kernel with one Worker registered and one device discovered
- An interactive `client.js` REPL talking to Kernel over HRPC — pull metrics, list Workers, send commands like `reboot` and `setpower`
- (Optional) A Gateway HTTP API on `:3000` so non-Node consumers (browsers, AI agents over MCP) can hit the same stack over REST

<Callout type="info">
Same shape as [rung 1](/tutorials/backend-stack/run): the stack still boots with `getKernel()`, `startWhatsminerWorker()`, and `kernel.registerWorker()`.
What's new here is a second process — `client.js` — that connects over HRPC (using the key Kernel publishes to its key file) and drives the running stack.
</Callout>

The example lives in [`examples/backend/mdk-e2e/`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md#end-to-end-mdk-e2e) and contains six runnable scripts. This tutorial uses
three of them: `run.js` for a smoke test, `server.js` for the long-running stack, and `client.js` for interactive control.

## Prerequisites

- Node.js >=24 (LTS)
- npm >=11

<Callout type="warn">
HRPC relies on HyperDHT for peer connectivity, including when Kernel and the Worker share a process.
Review the [network requirements and checks](/guides/miners/troubleshooting#example-does-not-print-a-kernel-key) if startup stalls.
</Callout>

<Steps>

<Step>

### Clone and install

#### 1.1 Clone the repo

```bash
git clone git@github.com:tetherto/mdk.git
cd mdk
```

#### 1.2 Install dependencies

The monorepo has two workspaces with their own dependency trees. Install both:

```bash
backend/core/install-packages.sh ci
backend/workers/install-packages.sh ci
```

<Callout type="info">
Each script walks every `package.json` under its workspace and runs `npm ci`. The `examples/mdk-e2e/` package is included automatically — no extra
install step needed.
</Callout>

</Step>

<Step>

<details>
<summary>(1.3 Optional) Smoke test the stack</summary>

Before going interactive, prove the wiring works. `run.js` starts a mock Whatsminer + Worker + Kernel in one process, exercises a few queries, prints the
results, and exits cleanly:

```bash
node examples/backend/mdk-e2e/run.js
```

Expected output (the UUID and metric values vary):

```text
Devices: [ '8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b [miner-wm-m56s]' ]
Telemetry: ONLINE hashrate=170000 power=3500W
Commands: reboot, setPowerMode, setLED, setPowerPct, setupPools, saveComment
```

If you see those three lines, every layer is working: the mock is responding, the Worker registered the device with Kernel directly in-process (no DHT lookup), and envelope routing is delivering messages both ways. The script tears itself down and exits with code 0.

<Callout type="warn">
If the smoke test fails with `EADDRINUSE` on port 14028, a previous run left a Node process alive. Kill stragglers with `pkill -f mdk-e2e` and retry.
</Callout>

</details>

</Step>

<Step>

### Run the interactive demo

#### 3.1 Start the stack

In your terminal:

```bash
node examples/backend/mdk-e2e/server.js
```

`server.js` starts the same mock + Worker + Kernel as `run.js`, but stays running and prints the IDs you'll need:

```text
  Kernel key:  7a4c8b...e3f0
  Device:   8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b

hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}'
  hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}'

Ctrl+C to stop.
```

The `Kernel key` is a 64-char hex public key. `Device` is a UUIDv4 generated at registration time. Both vary per run — note the device UUID for the next step.

The two `hp-rpc-cli` lines are paste-ready commands for inspecting Kernel over HRPC from another machine. You don't need them for this tutorial — they're
there if you have [`hp-rpc-cli`](https://github.com/holepunchto/hp-rpc-cli) installed and want to go off-script.

#### 3.2 Connect the interactive client

Open a second terminal in the same `mdk` directory:

```bash
node examples/backend/mdk-e2e/client.js
```

`client.js` reads the Kernel key from the key file Kernel published at startup (`os.tmpdir()/mdk/.kernel-key` — or pass a key as
the first argument), connects over HRPC, and gives you an MDK REPL:

```text
  Client — connected to Kernel over HRPC: 7a4c8b…
  Type "help" for commands, "quit" to exit.

mdk>
```

#### 3.3 Drive the stack

3.3.1 Discover the telemetry of your (mock) device by entering commands at the `mdk>` prompt, substituting `<deviceId>` with the UUID printed in Step 3.1:

```text
mdk> metrics <deviceId>
```

Each command builds an MDK Protocol envelope, sends it to Kernel over HRPC, and prints the JSON response.

3.3.2 Try changing the power mode and observing the effect:

```text
mdk> setpower <deviceId> low
mdk> metrics <deviceId>
```

After `setpower ... low` the second `metrics` call should reflect the power mode change.

{/* sync with examples/backend/mdk-e2e/client.js help block */}
<details>
<summary>Full command reference</summary>

**Reads**

```text
workers                      — list workers
list [deviceId]              — list devices
count [deviceId]             — device count
metrics <deviceId>           — live telemetry from hardware
logs <deviceId>              — recent logs
settings [deviceId]          — worker settings
stats [deviceId]             — fleet stats
config <deviceId>            — device config (pools, etc.)
capabilities <deviceId>      — mdk-contract capabilities
state [deviceId]             — worker state snapshot
```

**Commands**

```text
reboot <deviceId>            — reboot miner
setpower <deviceId> <mode>   — set power mode (normal/low/high)
setled <deviceId> [on|off]   — toggle LED
```

```text
quit / exit                  — exit client
```

</details>

#### 3.4 Tear down

When you're done, exit the client and stop the stack:

```text
mdk> quit
```

Then `Ctrl+C` in Terminal 1.

</Step>

<Step>

### 4 (Optional) enable Gateway for HTTP access

In **Terminal 1**, `Ctrl+C` the running stack, then restart with `--gateway`:

```bash
node examples/backend/mdk-e2e/server.js --gateway
```

You'll see an extra line in the startup banner:

```text
  Gateway: http://localhost:3000 (noAuth mode)
```

Confirm it's alive — Gateway has no index page, so hit `/auth/site` directly:

```bash
curl http://localhost:3000/auth/site
```

You should see something like `{"site":"Site_Name"}`.

<Callout type="warn">
In `noAuth` mode, routes that call `services.authLib` (`/auth/miners`, `/auth/permissions`) crash with
`Cannot read properties of undefined` because `authLib` is never instantiated. Routes that call `services.dataProxy`
(`/auth/list-things`) fail with `UNKNOWN_METHOD` because the underlying RPC method requires the full DCS cluster
registration that the production Gateway service provides. Use `/site-monitor/workers` and `/site-monitor/hashrate`
for local inspection — those routes call `services.mdkClient` directly over HRPC and work without auth.
</Callout>

<Callout type="warning">
`--gateway` runs in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost.
</Callout>

</Step>

</Steps>

## What just happened

Your stack wired up, in order:

1. **Mock device**:`server.js` calls `wmMock.createServer({ port: 14028, ... })` — an HTTP server speaking the Whatsminer protocol with canned telemetry.
2. **Kernel**: `getKernel()` boots the kernel, generates a random DHT topic, and publishes its HRPC public key to the well-known key file (`os.tmpdir()/mdk/.kernel-key`).
3. **Worker**: `startWhatsminerWorker({ ..., seedDevices })` constructs a `WorkerRuntime` seeded with one device at `127.0.0.1:14028` and starts it.
4. **Registration**: `kernel.registerWorker(worker.runtime.getPublicKey())` registers the Worker with Kernel directly — no DHT round-trip because
they share the process.
5. **Client**: `client.js` reads the key file from a second process, connects over HRPC, and sends MDK Protocol envelopes (`worker.list`, `telemetry.pull`, `command.request`, ...).
Kernel routes them to the Worker, the Worker hits the mock, and the response flows back over HRPC.

<Callout type="info">
No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel.
`client.js` already speaks MDK Protocol over HRPC, so it talks to Kernel directly. Gateway becomes mandatory only when the consumer can't speak HRPC.
See [`architecture.md#gateway`](/concepts/architecture#gateway).
</Callout>

## Cleanup

`Ctrl+C` in Terminal 1 stops the Worker, Kernel, and mock cleanly. `run.js` deletes its own state directory on exit. `server.js` leaves data
under `os.tmpdir()/mdk/` — safe to ignore, or remove with:

```bash
rm -rf "$TMPDIR/mdk" /tmp/mdk
```

## Continue

Next: [3. Run the dashboard demo](/tutorials/full-stack/dashboard): put a browser dashboard on a running stack with live charts.

## Go deeper

- Walk the simpler single-script path: [1. Run the stack](/tutorials/backend-stack/run)
- Run a [full site (multiple Workers and devices):](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js)
- Understand the [install pattern for any Worker](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md)
- Read all [runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md)

# 1. Run the stack (/tutorials/backend-stack/run)

*Get started · 1 of 3 · Run the stack*

<Callout type="info">
If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first.
</Callout>

## Overview

This is rung 1 of the [Get started](/tutorials/backend-stack) ladder: **observe**. It walks the shortest path from a fresh clone to a running Kernel with one mock Whatsminer registered, no hardware required. Everything runs in one Node process.

What you'll have at the end:

- A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028`
- An Kernel started and aware of one registered device
- Device list, telemetry, and available commands printed to the terminal

## Prerequisites

- Node.js >=24 (LTS)
- npm >=11

<Steps>

<Step>

### Clone and install

#### 1.1 Clone the repo

```bash
git clone git@github.com:tetherto/mdk.git
cd mdk
```

#### 1.2 Install dependencies

The monorepo has two workspaces with their own dependency trees. Install both:

```bash
backend/core/install-packages.sh ci
backend/workers/install-packages.sh ci
```

<Callout type="info">
Each script walks every `package.json` under its workspace and runs `npm ci`.
</Callout>

</Step>

<Step>

### Run the example

```bash
node examples/backend/mdk-e2e/run.js
```

Expected output:

```text
Devices: [ 'WM-001 [miner-wm-m56s]' ]
Telemetry: mining hashrate=295764693.45 power=4000W
Commands: reboot, setPowerMode, setLED, setupPools, setPowerPct, setUpfreqSpeed, registerThing, updateThing, forgetThings, saveSettings, saveComment, editComment, deleteComment
```

If you see those three lines, the whole stack is up: mock device responding, Worker registered, Kernel started and aware of the device. The script queries the device and then exits cleanly.

<Callout type="warn">
If the example fails with `EADDRINUSE`, a previous run left port 14028 bound. Kill stale Node processes with `pkill -f mdk-e2e` and retry.
</Callout>

</Step>

</Steps>

## What just happened

Here is what `run.js` does — the minimum runnable shape for an MDK stack:

```js
const { getKernel, waitForDiscovery } = require('../../../backend/core/mdk')
const { createMdkClient } = require('../../../backend/core/client')
const { startWhatsminerWorker } = require('../../../backend/workers/miners/whatsminer')
const wmMock = require('../../../backend/workers/miners/whatsminer/mock/server')

// Start a mock Whatsminer M56S on port 14028
wmMock.createServer({ port: 14028, host: '127.0.0.1', type: 'm56s', serial: 'WM-001', password: 'admin' })

// Start the Whatsminer Worker with one seeded device
const worker = await startWhatsminerWorker({
  workerId: 'whatsminer-m56s-e2e',
  model: 'm56s',
  storeDir: path.join(ROOT, 'worker-store'),
  kernelTopic: TOPIC,
  seedDevices: [{
    id: 'WM-001',
    info: { serialNum: 'WM-001' },
    opts: { address: '127.0.0.1', port: 14028, password: 'admin' }
  }]
})

// Start Kernel — discovers the Worker via DHT
const kernel = await getKernel({ root: ROOT, topic: TOPIC })
await waitForDiscovery(kernel)

// Connect an MDK client over HRPC
const client = createMdkClient({ hrpc: { key: kernel.getPublicKey() } })
await client.connect()

// Query the device and print results
const list = await client.pullTelemetry(deviceId, 'list')
const tel = await client.pullTelemetry(deviceId, 'metrics')
const caps = await client.getCapabilities(deviceId)
```

Six steps, in order:

1. **Starts a mock miner.** `wmMock.createServer({ port: 14028, type: 'm56s', serial: 'WM-001', password: 'admin' })` binds port 14028 with a Whatsminer-compatible API serving canned telemetry.
2. **Starts a Worker.** `startWhatsminerWorker({ ...seedDevices })` instantiates the Whatsminer manager and seeds it with one device registration at `127.0.0.1:14028`. The Worker stores the registration and begins polling the mock.
3. **Starts Kernel.** `getKernel({ topic })` brings up the kernel and joins the DHT topic. It discovers the Worker and pulls its identity and capabilities.
4. **Waits for discovery.** `waitForDiscovery(kernel)` blocks until the Worker appears in Kernel's registry.
5. **Connects a client.** `createMdkClient({ hrpc: { key: kernel.getPublicKey() } })` creates an MDK Protocol client that speaks to Kernel over HRPC.
6. **Queries and prints.** The script pulls device list, telemetry, and capabilities, prints them, cleans up, and exits.

<Callout type="info">
No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel. This script holds the Kernel handle in-process and speaks MDK Protocol to it directly. See [`architecture.md#gateway`](/concepts/architecture#gateway) for when Gateway is mandatory.
</Callout>

## Cleanup

The script cleans up automatically on exit. Temporary data lives at `os.tmpdir()/e2e-run/` and is removed by the script. If needed, you can manually clean with:

```bash
rm -rf "$TMPDIR/e2e-run" /tmp/e2e-run
```

## Continue

Next: [2. Control devices from the CLI](/tutorials/backend-stack/cli) — keep a stack running and drive it interactively (Whatsminer plus an MDK REPL).

## Next steps

- Try different miner hardware — the same MDK API works with [Antminers](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/USAGE.md), [Avalonminers](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md), and more
- Run a full site (5 Workers, 26 devices) — [`examples/backend/mdk-site/site.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js)
- See Kernel and a Worker as separate OS processes — [`dht-worker.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/dht-worker.js) + [`dht-kernel.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/dht-kernel.js) + [`client.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-e2e/client.js)
- Understand the install pattern for any Worker — [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md)
- Read all runnable examples in one place — [`examples/backend/README.md`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md)

# Run a demo from stack to dashboard (/tutorials/full-stack/dashboard)

*Get started · 3 of 3 · Run the dashboard demo*

<Callout type="info">
If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first.
</Callout>

## Overview

This is rung 3 of the [Get started](/tutorials/backend-stack) ladder: **run**. It puts a real browser dashboard on top of the stack you already know, using
the [`mdk-site-monitor`](https://github.com/tetherto/mdk/tree/main/examples/e2e) example.

What you'll have at the end:

- The same mock Whatsminer M56S stack from [rung 2](/tutorials/backend-stack/cli), fronted by a Gateway REST API on `:3000`
- A React dashboard on `:3030` — total hashrate, total power, and active device count as metric cards, a live hashrate chart, and a per-device breakdown
- The dashboard polling Gateway every 5 seconds, built entirely from MDK UI components (`MetricCard`, `HashRateLineChart`, `Typography`, ...)

<Callout type="info">
Same shape as rungs 1 and 2: underneath, the stack still boots with `getKernel()`, `startWhatsminerWorker()`, and `kernel.registerWorker()`, and the
device is the same Whatsminer M56S mock as [rung 2](/tutorials/backend-stack/cli). What's new is two layers on top — Gateway translating MDK Protocol to REST, and a
Vite React UI consuming that REST.
</Callout>

## Prerequisites

- Node.js >=24 (LTS)
- npm >=11

<Steps>

<Step>

### Clone and install the stack

#### 1.1 Clone the repo

```bash
git clone git@github.com:tetherto/mdk.git
cd mdk
```

#### 1.2 Install dependencies

```bash
backend/core/install-packages.sh ci
backend/workers/install-packages.sh ci
```

</Step>

<Step>

### Build the UI packages (one time)

The dashboard imports pre-built MDK UI packages from `ui`. Build them once:

```bash
cd ui
npm install
npm run build
cd -
```

<Callout type="info">
This is the slow step — it compiles the UI workspace. You only do it once; re-running the dashboard later skips straight to the next step.
</Callout>

</Step>

<Step>

### Install the dashboard's dependencies

```bash
cd examples/e2e/ui
npm install
cd -
```

</Step>

<Step>

### Start everything

`start.js` is an interactive launcher. From the repo root:

```bash
node examples/e2e/start.js
```

It prints the available services and a prompt. Type `start all` to launch the backend and UI together:

```text
mdk> start all
```

This starts:

1. **Gateway** (`server.js --gateway`) — Kernel + mock Whatsminer + a REST API on `http://localhost:3000`, in `noAuth` mode
2. **UI** — a Vite dev server on `http://localhost:3030`, launched with `VITE_NO_AUTH=true` so it skips the login screen

Wait a few seconds for both to come up, then open:

```text
http://localhost:3030
```

You'll see the dashboard populate within ~5 seconds (its first poll), then update live.

Other launcher commands:

```text
status                       — show running services and their URLs
stop  [kernel|gateway|ui|all]  — stop a service (default: all)
start [kernel|gateway|ui|all]  — start a service (default: all)
help                         — show usage
exit                         — stop everything and quit
```

<Callout type="warning">
`start all` runs Gateway in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost.
</Callout>

</Step>

</Steps>

## What you'll see

```mermaid
flowchart TD
  mock["Mock Whatsminer M56S (TCP :14028)"] --> worker["MDK Worker"]
  worker --> kernel["Kernel (HRPC)"]
  kernel --> gateway["Gateway (HTTP :3000)"]
  gateway -->|"GET /site-monitor/hashrate every 5s"| ui["Dashboard (Vite :3030)"]
```

The page renders three metric cards (Total Hashrate in TH/s, Total Power in W, Active Devices), a live hashrate line chart that grows as new data points
arrive, and a per-device table. All of it comes from `@tetherto/mdk-react-devkit` components driven by the `@tetherto/mdk-react-adapter` data hooks —
no hand-rolled UI. See [`SiteHashratePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/e2e/ui/src/SiteHashratePage.tsx) for the page source.

## Cleanup

At the launcher prompt:

```text
mdk> exit
```

`exit` stops Gateway, the mock, Kernel, and the UI dev server. `server.js` leaves data under `os.tmpdir()/mdk-e2e/` — safe to ignore, or remove with:

```bash
rm -rf "$TMPDIR/mdk-e2e" /tmp/mdk-e2e
```

<details>
<summary>Add real auth (Google OAuth)</summary>

The `start all` shortcut above runs in `noAuth` mode so you can see the dashboard immediately. To exercise the real authentication flow — a Google
sign-in that issues a bearer token the dashboard sends on every request — configure OAuth and start the services without the `noAuth` shortcut.

**1. Create a Google OAuth 2.0 client**

1. Go to [Google Cloud Console API credentials](https://console.cloud.google.com/apis/credentials)
2. Create an **OAuth 2.0 Client ID** (type: *Web application*)
3. Add to **Authorized redirect URIs**: `http://localhost:3000/oauth/google/callback`
4. Add to **Authorized JavaScript origins**: `http://localhost:3030`
5. Copy the **Client ID** and **Client Secret**

**2. Configure Gateway**

Edit `backend/core/gateway/config/facs/httpd-oauth2.config.json` (copy from `.example` if it doesn't exist) and fill in your client ID and secret:

```json
{
  "h0": {
    "method": "google",
    "credentials": { "client": { "id": "<YOUR_CLIENT_ID>", "secret": "<YOUR_CLIENT_SECRET>" } },
    "startRedirectPath": "/oauth/google",
    "callbackUri": "http://localhost:3000/oauth/google/callback",
    "callbackUriUI": "http://localhost:3000",
    "users": []
  }
}
```

**3. Set yourself as super-admin**

In `backend/core/gateway/config/facs/auth.config.json`, set `superAdmin` to your Google account email:

```json
{ "a0": { "superAdmin": "you@example.com" } }
```

**4. Run with auth**

Start Gateway and the UI without the `VITE_NO_AUTH` shortcut (run them directly rather than via `start all`), open `http://localhost:3030`,
click **Sign in with Google**, and authorise with the super-admin email. The dashboard then shows live data behind the token.

For the full setup, see the example's [`README.md`](https://github.com/tetherto/mdk/tree/main/examples/e2e).

</details>

## Continue

Previous: [2. Control devices from the CLI](/tutorials/backend-stack/cli)

You've climbed the whole ladder: observed a stack, driven it from a CLI, and built a live UI on it.

## Go deeper

- The [full example, including the OAuth setup and how to add a new data panel](https://github.com/tetherto/mdk/tree/main/examples/e2e)
- Learn more about [MDK UI toolkit (components, hooks, theming)](https://github.com/tetherto/mdk/blob/main/ui/README.md)
- [Run a full site (multiple Workers and devices)](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js)
- Read [all runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md)

# Build a minimal single-page dashboard (/tutorials/quickstart/build-a-dashboard)

# Build a minimal single-page dashboard

[`examples/full-site`](https://github.com/tetherto/mdk/tree/main/examples/full-site) is the fullest demonstration of the MDK stack: multiple Worker processes spanning miners,
containers, power meters, sensors, and miner pools, plus a multi-page React + Vite dashboard built on
`@tetherto/mdk-react-devkit`. That breadth is the point of that example — but it also means it's a lot to read
through if all you want is to understand (or prototype against) the actual wiring: Kernel, one Worker, a Gateway
route, a page that polls it.

This guide builds the smallest version of that same shape: **one Worker, one Gateway route, one React page**. It
teaches the same end-to-end shape as `examples/full-site` — including its UI layer, `@tetherto/mdk-react-devkit`
components driven by `@tetherto/mdk-react-adapter` hooks — without that example's family-specific adapters,
persistence, history, commands, multi-page router, or chart aggregation.

<Callout type="info">
If **Kernel**, **Worker**, or **Gateway** are unfamiliar terms, read [the architecture overview](/concepts/architecture)
first. This tutorial also assumes you've skimmed [Build a third-party Worker](/guides/workers/build-a-worker) — the one Worker used
here is [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js), the same zero-dependency reference Worker that tutorial
is built around.
</Callout>

## Overview

This tutorial builds the smallest version of the full MDK stack: **one Worker, one Gateway route, one React page**.

What you'll have at the end:

```text
examples/minimal-dashboard/
  package.json
  start.js                     # boots Kernel + the one Worker + Gateway, one process
  plugins/
    dashboard/
      mdk-plugin.json           # one route: GET /overview
      controllers/
        overview.js             # lists every Worker's devices + live telemetry
  ui/
    package.json
    tsconfig.json
    vite.config.ts
    index.html
    src/
      main.tsx                  # <MdkProvider> + render OverviewPage
      OverviewPage.tsx           # polls /overview, renders devkit components
```

No router, no charts, no hand-rolled CSS — one page built from three
`@tetherto/mdk-react-devkit` primitives (`LabeledCard`, `DataTable`, `Badge`) and one
`@tetherto/mdk-react-adapter` hook (`useQuery`), the same building blocks `examples/full-site/ui` uses, minus the
parts (router, sidebar, line charts, domain panels) this single-page, single-Worker dashboard doesn't need.

## Prerequisites

- Node.js `>=24`
- This repo checked out, with the backend and UI dependencies installed once from the repository root:

```bash
  npm run setup:core
  npm run setup:workers
  npm run setup:ui
  npm run build:ui
  ```

Running `npm run setup` from `examples/full-site` is also supported, but it is broader: it installs these backend
  and UI dependencies plus the full-site example and UI dependencies and builds the UI packages.
- Commands below assume a new `examples/minimal-dashboard/` directory alongside `examples/full-site/`

<Steps>

<Step>

### Pick the Worker

Use [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js) as-is — it needs no worker-infra services (provisioning
stores, alert templates), just `WorkerRuntime` and its own bundled mock device. Nothing in the steps below is
specific to it, though: swap in `startWhatsminerWorker`, `startAntminerWorker`, or your own Worker from
[Build a third-party Worker](/guides/workers/build-a-worker) and everything past the next step is unchanged.

</Step>

<Step>

### Boot Kernel and Worker in the same process

The simplest of the three discovery modes ([full trade-offs here](/concepts/deployment-topologies#the-trade-off)): one Node process owns both the
Kernel and the Worker, so there's no key file or DHT topic to manage.

`examples/minimal-dashboard/start.js`:

```js
'use strict'

const path = require('path')
const { getKernel, waitForDiscovery } = require('../../backend/core/mdk')
const { startDemoWorker } = require('../backend/demo-worker-caller')
const demoMock = require('../../backend/workers/samples/demo-worker/mock/server')

const ROOT = path.join(__dirname, '.mdk-data')
const MOCK_PORT = 9101
const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000

function onceListening (mock) {
  if (mock.server.listening) return Promise.resolve()
  return new Promise((resolve) => mock.server.once('listening', resolve))
}

async function main () {
  // the one fake device this dashboard will show — swap for real hardware later
  const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' })
  await onceListening(mock)

// Kernel + the one Worker, same process
  const kernel = await getKernel({ root: ROOT })
  const worker = await startDemoWorker({
    workerId: 'demo-worker-1',
    storeDir: path.join(ROOT, 'demo-worker-store'),
    seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }]
  })
  await kernel.registerWorker(worker.runtime.getPublicKey())
  await waitForDiscovery(kernel, { minWorkers: 1 })

console.log('worker registered: %s', worker.deviceIds.join(', '))
}

module.exports = { main, ROOT, HTTP_PORT }
if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) })
```

The demo Worker package exports a plugin and SQLite helper, not a boot function. The separate
[`demo-worker-caller`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) used here owns `WorkerRuntime`, device configuration, persistence,
sampling, and shutdown.

`getKernel({ root: ROOT })` with no `topic`/`discovery` option defaults to DHT discovery with a fresh random topic.
This example then registers the Worker's public key directly because both objects are in the same process. See the
[discovery model](/concepts/stack/workers#discovery-model) for the DHT, Local, and Same-process options to use in other deployments.

</Step>

<Step>

### Write the one Gateway plugin route

A [Gateway plugin](/guides/gateway/plugins) is a directory with a manifest and a controller. This one has a single read-only
route that lists every registered Worker's devices and pulls each one's default `metrics` telemetry bundle — no
per-device-family branching, because there's only one family here.

#### 3.1 Write the plugin manifest

`examples/minimal-dashboard/plugins/dashboard/mdk-plugin.json`:

```json
{
  "name": "@your-org/mdk-plugin-dashboard",
  "version": "0.1.0",
  "description": "Minimal dashboard plugin: one route that lists every registered device and its live telemetry.",
  "routes": [
    {
      "id": "dashboard.overview",
      "handler": "./controllers/overview.js",
      "auth": false,
      "http": { "method": "GET", "path": "/overview" },
      "description": "Live snapshot of every device across every registered Worker.",
      "safety": "read-only"
    }
  ]
}
```

#### 3.2 Write the controller

`examples/minimal-dashboard/plugins/dashboard/controllers/overview.js`:

```js
'use strict'

module.exports = async function overview (req, services) {
  const { workers } = await services.mdkClient.listWorkers()

const devices = await Promise.all(
    workers.flatMap((w) => (w.deviceIds || []).map(async (deviceId) => {
      const tel = await services.mdkClient.pullTelemetry(deviceId, 'metrics')
      return { deviceId, workerId: w.workerId, workerState: w.state, ...tel.metrics }
    }))
  )

return { ts: Date.now(), devices }
}
```

A controller is `async (req, services) => value` — return a plain object, the Gateway serializes it to JSON itself;
you never touch `res`. `services.mdkClient` is the same client used everywhere else in MDK — no knowledge of the
underlying MDK Protocol envelope required.

<Callout type="info">
With more than one Worker family mixed in (miners, powermeters, sensors, ...) you'd branch by
`deviceFamily` instead of spreading `tel.metrics` blindly — see [`examples/full-site/plugins/site/lib/site.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/lib/site.js)
for that pattern once you outgrow this one.
</Callout>

</Step>

<Step>

### Serve the plugin and static page from the same Gateway

Add `startGateway` to `start.js`, mounting the plugin via `extraPluginDirs` and the built UI (Step 5's `ui/dist`) via
`common.staticRootPath`. This is the complete canonical file; its boot order is mock, Kernel, Worker, registration,
readiness, then Gateway:

```js
'use strict'

const path = require('path')
const { getKernel, startGateway, waitForDiscovery } = require('../../backend/core/mdk')
const { startDemoWorker } = require('../backend/demo-worker-caller')
const demoMock = require('../../backend/workers/samples/demo-worker/mock/server')

const ROOT = path.join(__dirname, '.mdk-data')
const MOCK_PORT = 9101
const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000

function onceListening (mock) {
  if (mock.server.listening) return Promise.resolve()
  return new Promise((resolve) => mock.server.once('listening', resolve))
}

async function main () {
  // Start the mock device before its Worker tries to connect.
  const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' })
  await onceListening(mock)

// Start Kernel, then the Worker runtime that hosts the demo Worker plugin.
  const kernel = await getKernel({ root: ROOT })
  const worker = await startDemoWorker({
    workerId: 'demo-worker-1',
    storeDir: path.join(ROOT, 'demo-worker-store'),
    seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }]
  })

// Register the Worker and wait until it is ready before accepting HTTP traffic.
  await kernel.registerWorker(worker.runtime.getPublicKey())
  await waitForDiscovery(kernel, { minWorkers: 1 })

await startGateway({
    kernel,
    noAuth: true,
    port: HTTP_PORT,
    root: path.join(ROOT, 'gateway'),
    tmpdir: path.join(ROOT, 'gateway'),
    extraPluginDirs: [path.join(__dirname, 'plugins', 'dashboard')],
    common: { staticRootPath: path.join(__dirname, 'ui', 'dist') }
  })

console.log('worker registered: %s', worker.deviceIds.join(', '))
  console.log(`dashboard up: http://localhost:${HTTP_PORT}/`)
}

module.exports = { main, ROOT, HTTP_PORT }
if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) })
```

<Callout type="warn">
The route's `"auth": false` and Gateway's `noAuth: true` are **local-development settings**. Do not expose this
Gateway directly to an untrusted network. Production deployments require TLS termination, authentication,
authorization, and network policy. Before production, remove `noAuth: true`, set the route's `"auth"` to `true`,
and declare its required `"permissions"`. Write routes also need input validation, rate limits, and auditing.
</Callout>

<Callout type="warn">
Serve the built page from `common.staticRootPath`, not a separate server on its own port. Gateway plugin
controllers only receive `(req, services)` — never the underlying reply object — so a controller has no way to set
`Access-Control-Allow-Origin`, and Gateway has no built-in CORS support. Building the UI (Step 5) and serving
`ui/dist` from `staticRootPath` keeps `fetch('/overview')` same-origin with zero CORS configuration. This is also
why `examples/full-site`'s Vite *dev* server proxies `/site/*` to the Gateway port instead of calling it
cross-origin — Step 5's `vite.config.ts` proxies `/overview` the same way for hot-reload development.
</Callout>

</Step>

<Step>

### Write the single-page UI with MDK devkit components

Instead of hand-rolled HTML, the page is a small React + Vite app built from the same packages
`examples/full-site/ui` uses — `@tetherto/mdk-react-adapter` for the provider and data hook, `@tetherto/mdk-react-devkit`
for the components — scaled down to what one route needs: no router (one page), no charts (no history endpoint
here), no sidebar. Three primitives do the job: `LabeledCard` for the section container, `DataTable` for the sortable
device grid, and `Badge` to color-code `workerState`.

`examples/minimal-dashboard/ui/package.json`:

```json
{
  "name": "@your-org/mdk-minimal-dashboard-ui",
  "type": "module",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build"
  },
  "dependencies": {
    "@tetherto/mdk-react-adapter": "file:../../../ui/packages/react-adapter",
    "@tetherto/mdk-react-devkit": "file:../../../ui/packages/react-devkit",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^4.3.4",
    "typescript": "^5.7.3",
    "vite": "^6.3.5"
  }
}
```

`examples/minimal-dashboard/ui/tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "types": ["vite/client"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src/**/*", "vite.config.ts"],
  "exclude": ["node_modules", "dist"]
}
```

`examples/minimal-dashboard/ui/vite.config.ts` — the dev-only proxy so `fetch('/overview')` stays same-origin
against the Gateway port, the same pattern [`examples/full-site/ui/vite.config.ts`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/vite.config.ts) uses for `/site/*`:

```ts

declare const process: { env: Record<string, string | undefined> }

const apiPort = process.env.VITE_API_PORT || '3000'

plugins: [react()],
  server: {
    port: Number(process.env.MDK_UI_PORT) || 3041,
    proxy: { '/overview': `http://localhost:${apiPort}` }
  }
})
```

`examples/minimal-dashboard/ui/index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>MDK dashboard</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

`examples/minimal-dashboard/ui/src/main.tsx` — `<MdkProvider>` wires the TanStack Query client `useQuery` needs and
resolves the API base URL, exactly as it does in [`examples/full-site/ui/src/main.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/main.tsx):

```tsx

const rootElement = document.getElementById('root')
if (!rootElement) throw new Error('ERR_ROOT_ELEMENT_MISSING')

// Same-origin: the Vite dev proxy forwards /overview to the gateway;
// in production the Gateway serves this build from staticRootPath.
ReactDOM.createRoot(rootElement).render(
  <StrictMode>
    <MdkProvider apiBaseUrl="">
      <OverviewPage />
    </MdkProvider>
  </StrictMode>
)
```

`examples/minimal-dashboard/ui/src/OverviewPage.tsx` — `useQuery` polls the route from Step 3 the same way
[`examples/full-site/ui/src/SitePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/SitePage.tsx) polls `/site/overview`; `DataTable` and `Badge` replace that page's
hand-rolled markup:

```tsx

type Device = {
  deviceId: string
  workerId: string
  workerState: string
  hashrate_rt?: number
  power?: number
  temperature?: number
}

type Overview = { ts: number; devices: Device[] }

function get<T>(base: string, path: string): Promise<T> {
  return fetch(`${base}${path}`).then((res) => {
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    return res.json() as Promise<T>
  })
}

function stateBadgeStatus(state: string): 'success' | 'error' | 'default' {
  if (state === 'ready') return 'success'
  if (state === 'offline') return 'error'
  return 'default'
}

const columns: DataTableColumnDef<Device, unknown>[] = [
  { accessorKey: 'deviceId', header: 'Device' },
  { accessorKey: 'workerId', header: 'Worker' },
  {
    id: 'workerState',
    header: 'Worker state',
    cell: ({ row }) => {
      const state = (row.original.workerState || 'unknown').toLowerCase()
      return <Badge status={stateBadgeStatus(state)} text={state} />
    }
  },
  {
    accessorKey: 'hashrate_rt',
    header: 'Hashrate (TH/s)',
    cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(2)
  },
  {
    accessorKey: 'power',
    header: 'Power (W)',
    cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(0)
  },
  {
    accessorKey: 'temperature',
    header: 'Temp (°C)',
    cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(1)
  }
]

const { apiBaseUrl } = useMdkContext()
  const overview = useQuery({
    queryKey: ['dashboard-overview'],
    queryFn: () => get<Overview>(apiBaseUrl, '/overview'),
    refetchInterval: 3000
  })

return (
    <div style={{ padding: 24 }}>
      <LabeledCard label="Devices" isFullWidth>
        <DataTable<Device>
          data={overview.data?.devices ?? []}
          columns={columns}
          getRowId={(row) => row.deviceId}
          loading={overview.isLoading}
          enablePagination={false}
        />
      </LabeledCard>
    </div>
  )
}
```

A controller is `async (req, services) => value`; a page is `useQuery` + devkit components — neither one touches the
other's plumbing. `OverviewPage` never imports `mdkClient`, and `overview.js` never imports React.

</Step>

<Step>

### Run it

#### 6.1 Add package.json

`examples/minimal-dashboard/package.json`:

```json
{
  "name": "@your-org/mdk-minimal-dashboard",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "build": "npm --prefix ui run build",
    "start": "node start.js"
  }
}
```

#### 6.2 Start the dashboard

Install each package's own dependencies, build the UI once, then boot the backend:

```bash
cd examples/minimal-dashboard
npm install
npm --prefix ui install
npm run build
npm run start
```

Open `http://localhost:3000/` — the page polls `/overview` every 3 seconds and shows the one `demo-0` device
reporting live telemetry from its mock. Confirm the API directly with:

```bash
curl -s http://localhost:3000/overview
```

You should see JSON shaped like `{ "ts": ..., "devices": [{ "deviceId": "demo-0", "workerId": "demo-worker-1", "workerState": "READY", "hashrate_rt": ..., "power": ..., "temperature": ... }] }`.

### Hot-reload UI development

Vite does **not** replace the Gateway. Without hot reload you open `:3000` (Gateway serves the built `ui/dist`). With hot
reload you still need the Gateway for `/overview`, and Vite only serves the React app and proxies that path.

Keep **both** terminals running:

**Terminal 1 — Gateway** (do not stop this):

```bash
cd examples/minimal-dashboard
npm run start
```

Wait for `dashboard up: http://localhost:3000/`.

**Terminal 2 — Vite**:

```bash
cd examples/minimal-dashboard
VITE_API_PORT=3000 npm --prefix ui run dev
```

Open **`http://localhost:3041/`** (the Vite port), not `:3000`. Step 5's proxy forwards `/overview` to the Gateway on
`VITE_API_PORT`. If Terminal 1 is down, Vite logs `http proxy error: /overview` / `ECONNREFUSED` and the table stays empty.

</Step>

</Steps>

## Next steps

- **More Workers, zero controller changes**: `overview.js` already loops over every registered Worker generically.
  Register a second Worker the same way (Step 2's `startDemoWorker` + `startWhatsminerWorker`, etc., both followed by
  `kernel.registerWorker(...)`) and it appears in `/overview` for free.
- **A write route**: Add a second manifest entry (`POST /devices/{deviceId}/command`) calling
  `services.mdkClient.sendCommand(deviceId, 'setPowerMode', { mode })`, following the `command.js` example in
  [Gateway plugins](/guides/gateway/plugins), and a `Button` in `OverviewPage.tsx` that `POST`s to it. Before deploying any
  physical write command, require narrowly scoped authorization, validate its payload and target state, apply rate
  limits, and record an audit trail.
- **More pages, charts, history**: Add `react-router-dom` and a second route/page, or graduate to the domain layer
  (`@tetherto/mdk-react-devkit/domain`'s `LineChartCard`, `MetricCard`, header stats bar) once the Gateway plugin
  grows a history endpoint to feed them — see [`examples/full-site/ui/src/DashboardPage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/DashboardPage.tsx) and
  [`examples/full-site/plugins/site/controllers/history.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/controllers/history.js) for that shape.
- **Separate processes or hosts**: Replace the direct registration in Step 2 with Local discovery for processes on
  one machine or DHT discovery for separate hosts, as described in the [discovery model](/concepts/stack/workers#discovery-model).

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| `/overview` returns `{ devices: [] }` | `kernel.registerWorker(...)` wasn't awaited, or `startGateway` was called before `waitForDiscovery` resolved |
| `/overview` returns `500` / `Cannot read properties of null` | Controller spread `tel.metrics` when `pullTelemetry` returned `null` — use `(tel && tel.metrics) \|\| {}` as in Step 3 |
| `pullTelemetry` throws / device shows zeros | The Worker's `connect()` couldn't reach the mock at boot — confirm the mock's `listening` event fired before `startDemoWorker` seeded it (Step 2's `onceListening`) |
| Vite shows `http proxy error: /overview` / `ECONNREFUSED`, page at `:3041` has no data | Gateway is not listening on the proxy target — keep `npm run start` running in another terminal, and set `VITE_API_PORT` to that Gateway port (default `3000`). Open `:3041`, not `:3000` |
| Browser `fetch('/overview')` fails from Vite with CORS / wrong host when Gateway is up | See the CORS note in Step 4 — the Vite proxy must target the Gateway (`VITE_API_PORT`); do not call a different origin from the page |
| `ERR_PLUGIN_HANDLER_NOT_FOUND: routes.dashboard.overview: ./controllers/overview.js` on Gateway boot | `extraPluginDirs` must point at the directory *containing* `mdk-plugin.json`, not the controller file itself |
| Gateway boots but the page 404s | `common.staticRootPath` must be an absolute path (`path.join(__dirname, 'ui', 'dist')`) pointing at a *built* UI (`npm run build` in Step 6), not a relative string or the unbuilt `ui/src` |
| `Cannot find module '@tetherto/mdk-react-devkit'` when building `ui/` | Run the Prerequisites' `npm run setup:ui && npm run build:ui` from the repo root first — the UI packages ship pre-built `dist/` output that `ui/`'s `package.json` depends on via `file:` links |

# Run the full-site example (/tutorials/quickstart/full-stack-demo)

## Overview

This tutorial presents the [full-site example](https://github.com/tetherto/mdk/tree/main/examples/full-site) end to end running the full MDK stack: multiple
configured Workers across a range of device families, their mock device servers, a Gateway HTTP API, and a React
dashboard, all in one command.

What you'll have at the end:

- The supported fleet: multiple miner types, container types, and power meters;
  one sensor family with two inlet sensors; and two mining pools, each backed by
  mock hardware that speaks the real wire protocol
- A Gateway API at `:3007` serving `/site/overview`, `/site/history`, and `/site/miners/:id/command`
- A React dashboard at `:3040` with live hashrate, power, and device status
- An MCP server exposing the site's device registry, telemetry, and commands as tools for AI agents

The example can boot in one Node.js process (`node start.js`) or as separate processes through an interactive REPL (`node cli.js`).
This tutorial uses `start.js` — the simplest path.

## Prerequisites

- Node.js >=24 (LTS)
- npm >=11

<Steps>

<Step>

### Install the example

#### 1.1 Clone the repo

```bash
git clone git@github.com:tetherto/mdk.git
cd mdk
```

#### 1.2 Run setup

```bash
cd examples/full-site
npm run setup
```

`setup` installs `backend/core`, `backend/workers`, the UI workspace devkit packages, and this example's own dependencies. It runs once; subsequent
starts skip it.

<Callout type="info">
The script walks several workspaces; first run takes 1-2 minutes.
</Callout>

</Step>

<Step>

### Start the site

Start with a small fleet (3 miners per family, 9 total) for a fast first boot:

```bash
node start.js --miners 3
```

Wait for the terminal to print the Gateway and UI URLs:

```text
Gateway  http://localhost:3007
UI       http://localhost:3040
```

Open `http://localhost:3040` in a browser. The dashboard shows live hashrate, total power, and a per-device breakdown.

Verify via the API:

```bash
curl -s http://localhost:3007/site/overview | jq '{miners: (.miners|length), containers: (.containers|length), pools: (.pools|length), sensors: (.sensors|length)}'
```

Expected output:

```text
{
  "miners": 9,
  "containers": 2,
  "pools": 2,
  "sensors": 2
}
```

<Callout type="warn">
The default fleet (100 miners per family, 300 total) opens 900+ file descriptors simultaneously. Before switching from `--miners 3` to the full
fleet, run `ulimit -n 4096` in the same terminal session.
</Callout>

</Step>

</Steps>

## What just happened

1. **Setup** installed `backend/core`, `backend/workers`, the MDK UI devkit, and this example — all the packages `start.js` imports at boot.
2. **Mock hardware** — `mocks.js` started one server per device family (miners on TCP, containers on HTTP and MQTT, power meters and sensors on
   Modbus, pools on REST). They speak the real wire protocols; every Worker driver runs its true connect, collect, and command paths against them.
3. **Kernel** — `getKernel()` started the orchestration layer that discovers Workers as they register and routes telemetry pulls and commands to them.
4. **Workers** — eleven `bootWorker()` calls, one per configured Worker spec, each dispatching to that family's `start{X}Worker()` boot function
(`startWhatsminerWorker`, `startAvalonWorker`, ...) to construct a `WorkerRuntime` and connect it to the Kernel.
5. **Gateway** — `startGateway()` mounted the site plugin from `plugins/site/` and opened the HTTP server on `:3007`. The plugin aggregates data across
the configured Workers through `mdkClient`.
6. **UI** — a Vite React dev server started on `:3040`, serving a dashboard built from MDK devkit components.
7. **MCP server** — an MCP server started over HRPC, exposing the site's device registry, telemetry, and command dispatch as tools for AI agents.

## Cleanup

`Ctrl+C` stops mocks, Workers, Kernel, Gateway, and the UI dev server cleanly.

State (Kernel key, Worker seeds, device registry, and tail-log history) persists in `.mdk-data/`. To wipe it:

```bash
rm -rf examples/full-site/.mdk-data
```

## Next steps

- If Kernel, Gateway, Worker, manager, or thing are unfamiliar, read [terminology](/reference/glossary)
- Run the same supported Worker fleet under PM2 or Docker — [Multi-process deployment guide](/guides/deployment/run-all-workers-site)
- Add [custom plugins to the Gateway HTTP API](/guides/gateway/plugins)
- Connect an [AI agent to the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command the site
- Explore [the interactive CLI process manager](https://github.com/tetherto/mdk/tree/main/examples/full-site) for per-process logs, runtime seeding, and live status

# Explore the demo (/tutorials/ui/explore-the-demo)

This page presents a copy/paste method to clone the MDK UI monorepo, run the demo, and browse the full component library live.

## Prerequisites

- **Node.js** >=24
- **npm** >=11
- **React** 19+ and **react-dom** 19+

{/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */}

## Run the demo

One copy/paste: four steps — clone, install, build, run.

```bash
# Requires an SSH key configured for your GitHub account
git clone git@github.com:tetherto/mdk.git
cd mdk/ui
npm install && npm run build
npm run dev:catalog
```

</Tab>
  <Tab value="https" label="HTTPS">

```bash
git clone https://github.com/tetherto/mdk.git
cd mdk/ui
npm install && npm run build
npm run dev:catalog
```

</Tab>
</Tabs>

Open [http://localhost:5173/mdk](http://localhost:5173/mdk). You'll land in the demo browser — a sidebar of the full MDK component library, covering core
primitives (buttons, inputs, tables, charts, dialogs) and mining-domain components (operations centre, vendor containers, alerts, pool manager, settings).

### What the demo wires

The demo app uses [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation), `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-react-devkit` with `<MdkProvider>`.

## Next steps

- [Wire React](/quickstart/wire-react): install all three packages and wrap your app in `MdkProvider`
- [Wire a React app](/tutorials/ui/react/tutorial): scaffold an app with `MdkProvider` and adapter hooks
- [Learn more about the React MDK UI Devkit](/tutorials/ui/react)

# Get started with React (/tutorials/ui/react)

## TL;DR

- **One provider, zero Redux**: install and wrap your app in `<MdkProvider>` so connected foundation components and adapter hooks share the 
same stores and API client
- Presentational [`/core`](/reference/ui/react/core) and [`/foundation`](/reference/ui/react/foundation) imports can work without the provider
- Anything that reads app state needs the provider

## Choose your path

<Cards>
  <Card
    icon={<Rocket />}
    title={<span style={cardTitle}>Quickstart</span>}
    href="/quickstart/wire-react"
    description={
      <>
        <span style={cardProse}>
          Install all three packages, wrap in MdkProvider, wire stores and theming
        </span>
        <span style={cardTime}>⏱️ <3 min</span>
      </>
    }
  />
  <Card
    icon={<Compass />}
    title={<span style={cardTitle}>Explore the demo</span>}
    href="/tutorials/ui/explore-the-demo"
    description={
      <>
        <span style={cardProse}>
          Single copy/paste to clone the monorepo and browse the full demo app in your browser
        </span>
        <span style={cardTime}>⏱️ <1 min</span>
      </>
    }
  />
  <Card
    icon={<BookOpen />}
    title={<span style={cardTitle}>Tutorial</span>}
    href="/tutorials/ui/react/tutorial"
    description={
      <>
        <span style={cardProse}>
          Step-by-step app scaffold with MdkProvider, adapter hooks, and foundation components
        </span>
        <span style={cardTime}>⏱️ <5 min</span>
      </>
    }
  />
  <Card
    icon={<Bot />}
    title={<span style={cardTitle}>Build dashboards with your AI agent</span>}
    href="/quickstart/connect-agents"
    description={
      <span style={cardProse}>
        Wire Cursor or Claude to MDK with the UI CLI, then build from plain-language prompts
      </span>
    }
  />
</Cards>

## Prerequisites

- **Node.js** >=24
- **npm** >=11
- **React** 19+ and **react-dom** 19+

{/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */}

## About the React stack

The React UI Devkit is published as **three workspace packages** in the [MDK monorepo](https://github.com/tetherto/mdk):

- **[`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation)** — headless state (Zustand vanilla stores), a TanStack `QueryClient` factory, telemetry primitives, and the command state machine. No React.
- **`@tetherto/mdk-react-adapter`** — React bindings: `<MdkProvider>`, store hooks (`useAuth`, `useDevices`, `useNotifications`, `useTimezone`, `useActions`) and re-exports of `useQuery` / `useMutation`.
- **`@tetherto/mdk-react-devkit`** — the React UI library: `./core` primitives and `./foundation` mining-domain components, hooks, and styles.

`@tetherto/mdk-ui-foundation` is framework-agnostic; the adapter and devkit are React-specific.
Add all three to your app’s `package.json`, then wrap the tree once in **`<MdkProvider>`** from `@tetherto/mdk-react-adapter`.

**`@tetherto/mdk-ui-foundation`** is the brain in the back room. It remembers who is logged in, which miners are selected, and what timezone the operator uses — but it has no buttons and no React. Other code (including non-React utilities) can read and update it with `getState()` / `setState()`.

**`@tetherto/mdk-react-adapter`** plugs that brain into React. `<MdkProvider>` turns it on for your whole app. Hooks like `useAuth` and `useDevices` let components listen to one slice of state and re-render when that slice changes.

**[`/core`](/reference/ui/react/core)** (`import … from '@tetherto/mdk-react-devkit/core'`) is the generic UI toolkit. Buttons, inputs, dialogs, tabs, charts, sidebars, toasts, tables. Nothing in it knows what a miner is. It owns colours, fonts, spacing, and the shared styling recipes.

**[`/foundation`](/reference/ui/react/foundation)** (`import … from '@tetherto/mdk-react-devkit/foundation'`) is built on top of core. It knows about miners, containers, pools, hashrate, alarms, operators, permissions, and settings dashboards. Domain hooks and connected components expect `<MdkProvider>` to be in place.

</Accordion>
</Accordions>

## Next steps

- Explore the [Core primitives](/reference/ui/react/core) in `@tetherto/mdk-react-devkit/core`: buttons, forms, charts, and themes
- Explore the [Foundation components](/reference/ui/react/foundation) in `@tetherto/mdk-react-devkit/foundation`: mining-domain components and hooks
- See the [UI Devkit overview](/reference/ui) for how the headless layer fits other frameworks
- Browse the [Hooks](/reference/app-toolkit/hooks) reference — [state](/reference/app-toolkit/hooks/state), [component](/reference/app-toolkit/hooks/components), and [utility](/reference/app-toolkit/hooks/utilities) hooks

# Build a dashboard with an agent (/tutorials/ui/react/build-any-dashboard-with-an-agent)

This tutorial walks a **realistic agent session** end to end: the same two-step flow as
[Build dashboards with your AI agent](/quickstart/connect-agents).

## Overview

MDK's React UI Devkit's library of presentational and composable building blocks can be used wherever suits you.

Mining is one of many disciplines that benefits from charts, tables, tabs, and stat cards. Your telemetry; your dash.

You bring *your* labels, *your* mock data, and *your* layout.

The first thing we built was [Mining Dashboards](/tutorials/ui/react). What will you build?

IoT fleet backend reporting, workout metrics motivation app, weather stats? Your data; your choice.

The prompt asked for a **statistics tutorial page** so students can explore
distributions, trends, and raw grades. You see every:

- [UI CLI](/reference/app-toolkit/ui-cli) command the agent would run
- Resulting page code
- Run instructions

<Callout type="info">
We use mock JSON in the browser. No Kernel, Worker, pool API, or fleet backend is required. Presentational imports from
`@tetherto/mdk-react-devkit/core` are enough for a highly visual, shippable UI.
</Callout>

## What you'll learn

1. **Domain is yours.** Component contracts describe shape and behavior (chart datasets, table columns), not industry vocabulary.
2. **The agent path is unchanged.** `init` → plain-language intent → local manifests → scaffold → `check`.
3. **Visual density is supported.** Bar charts, line trends, sortable tables, and stat cards compose into a dashboard that *looks*
   like a product, not a wireframe.

The demo app is **Stats Lab**: a fictional intro statistics course where Teaching Assistants review quiz score histograms, weekly class averages,
and per-student grades.

## Prerequisites

- **Node.js** >=24
- **npm** >=11
- **React** 19+ and **react-dom** 19+

{/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */}

- A project folder inside the MDK UI monorepo (this walkthrough uses `apps/stats-lab`, same pattern as
  [Wire a React app](/tutorials/ui/react/tutorial#create-your-app))
- [Build dashboards with your AI agent](/quickstart/connect-agents) wired once (`mdk-ui init`) or willingness to run `init` in step 1

## Agent session walkthrough

<Steps>

<Step>

### Wire the IDE (same as agents)

From your app or monorepo project root:

```bash
npx @tetherto/mdk-ui-cli init --ide cursor
```

This writes `.mdk/context.md` and `.cursor/rules/mdk.mdc` so the session already knows the UI CLI surface. See
[init](/reference/app-toolkit/ui-cli#init).

</Step>

<Step>

### State a non-mining intent

Paste a prompt that names the domain explicitly so the agent does not reach for hashrate widgets:

> Build a **statistics tutorial dashboard** for students in `apps/stats-lab`. Include:
>
> - A **histogram** of final exam scores (bar chart buckets 50–59 through 90–100)
> - A **line chart** of weekly class average over six weeks
> - A **sortable table** of students with midterm, final, and section
> - Three **summary stat cards**: mean final, median final, enrollment count
>
> Use mock data in the repo. Import only from `@tetherto/mdk-react-devkit/core` and `@tetherto/mdk-react-devkit/foundation` where
> needed. No mining APIs.

The agent's job is unchanged from [Build dashboards with your AI agent](/quickstart/connect-agents#prompt-your-agent): discover exports,
scaffold, and verify compile.

</Step>

<Step>

### Discovery commands the agent runs

Behind the prompt, a well-behaved session issues deterministic CLI lookups (no model calls). A representative transcript:

```bash
npx @tetherto/mdk-ui-cli suggest "statistics dashboard histogram line chart data table stat cards"
```

Typically returns chart-category components near the top — `BarChart`, `LineChart`, and closely related chart primitives. General-purpose components like `DataTable`, `SingleStatCard`, and `Tabs` score lower on chart-focused queries and are best found with the `find --category` commands in the next accordion. Because we asked for
mock data only, the agent skips adapter hooks like `useDevices`.

</Accordion>

```bash
npx @tetherto/mdk-ui-cli find --category charts --format table
npx @tetherto/mdk-ui-cli find --category tables --format table
```

Narrows to chart primitives and table components with stable exports.

</Accordion>

```bash
npx @tetherto/mdk-ui-cli docs BarChart
npx @tetherto/mdk-ui-cli docs LineChart
npx @tetherto/mdk-ui-cli example LineChart
npx @tetherto/mdk-ui-cli docs DataTable
```

The agent copies real prop shapes (`LineChartData` millisecond `x` values, `DataTableColumnDef` accessors) instead of inventing
APIs.

</Accordion>

```bash
npx @tetherto/mdk-ui-cli add page StatsLab \
  --component BarChart \
  --component LineChart \
  --component DataTable \
  --component SingleStatCard

npx @tetherto/mdk-ui-cli check apps/stats-lab/src/App.tsx
```

`add page` emits a starter layout; the agent fills in mock datasets and labels. `check` validates imports and component prop
contracts against the real package barrels; the app build in the local run verifies the final Vite project.

</Accordion>

</Accordions>

Full command reference: [UI CLI](/reference/app-toolkit/ui-cli).

</Step>

<Step>

### Review the scaffolded page

After the agent edits `App.tsx`, a Stats Lab dashboard might look like this:

```tsx
  BarChart,
  LineChart,
  DataTable,
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
} from '@tetherto/mdk-react-devkit/core'

type Student = {
  id: string
  name: string
  section: 'A' | 'B'
  midterm: number
  final: number
}

const students: Student[] = [
  { id: '1', name: 'Alex Kim', section: 'A', midterm: 82, final: 88 },
  { id: '2', name: 'Jordan Lee', section: 'B', midterm: 74, final: 79 },
  { id: '3', name: 'Sam Rivera', section: 'A', midterm: 91, final: 94 },
  { id: '4', name: 'Taylor Ng', section: 'B', midterm: 68, final: 72 },
  { id: '5', name: 'Casey Park', section: 'A', midterm: 85, final: 90 },
]

const weekStart = (weekIndex: number): number =>
  new Date(2025, 0, 6 + weekIndex * 7).valueOf()

const StatsLab = (): React.JSX.Element => {
  const [sorting, setSorting] = useState<DataTableSortingState>([])

const finals = students.map((s) => s.final)
  const meanFinal = finals.reduce((a, b) => a + b, 0) / finals.length
  const sortedFinals = [...finals].sort((a, b) => a - b)
  const medianFinal = sortedFinals[Math.floor(sortedFinals.length / 2)]

const histogram = useMemo(
    () => ({
      labels: ['50–59', '60–69', '70–79', '80–89', '90–100'],
      datasets: [
        {
          label: 'Students',
          data: [1, 2, 4, 6, 3],
          backgroundColor: '#6366f1',
        },
      ],
    }),
    [],
  )

const weeklyAverage = useMemo(
    () => ({
      datasets: [
        {
          label: 'Class average',
          borderColor: '#22c55e',
          data: [71, 74, 76, 79, 81, 83].map((y, i) => ({
            x: weekStart(i),
            y,
          })),
        },
      ],
    }),
    [],
  )

const columns: DataTableColumnDef<Student>[] = [
    { accessorKey: 'name', header: 'Student' },
    { accessorKey: 'section', header: 'Section' },
    { accessorKey: 'midterm', header: 'Midterm' },
    { accessorKey: 'final', header: 'Final' },
  ]

return (
    <div style={{ padding: '2rem', display: 'grid', gap: '1.5rem' }}>
      <header>
        <h1 style={{ margin: 0 }}>Stats Lab</h1>
        <p style={{ margin: '0.5rem 0 0', opacity: 0.8 }}>
          Intro statistics — interpret distributions and trends
        </p>
      </header>

<Tabs defaultValue="charts">
        <TabsList>
          <TabsTrigger value="charts">Charts</TabsTrigger>
          <TabsTrigger value="roster">Roster</TabsTrigger>
        </TabsList>
        <TabsContent value="charts">
          <div
            style={{
              display: 'grid',
              gap: '1.5rem',
              gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
            }}
          >
            <section>
              <h2 style={{ fontSize: '1rem' }}>Final exam distribution</h2>
              <BarChart data={histogram} height={280} />
            </section>
            <section>
              <h2 style={{ fontSize: '1rem' }}>Weekly class average</h2>
              <LineChart
                data={weeklyAverage}
                height={280}
                unit="pts"
                beginAtZero
              />
            </section>
          </div>
        </TabsContent>
        <TabsContent value="roster">
          <DataTable
            columns={columns}
            data={students}
            sorting={sorting}
            onSortingChange={setSorting}
          />
        </TabsContent>
      </Tabs>
    </div>
  )
}

```

</Accordion>

</Accordions>

Nothing in this file references pools, workers, or TH/s. The same components appear on mining pages because the **data model is
generic**.

</Step>

</Steps>

## Run Stats Lab locally

Follow the same monorepo workflow as [Wire a React app](/tutorials/ui/react/tutorial). If you already completed that tutorial,
skip to **Run the app** with `stats-lab` as the workspace name.

<Steps>

<Step>

### Clone and build the UI monorepo

```bash
git clone https://github.com/tetherto/mdk.git
cd mdk
```

</Tab>
  <Tab value="ssh" label="SSH">

```bash
git clone git@github.com:tetherto/mdk.git
cd mdk
```

</Tab>
</Tabs>

```bash
npm install
npm run build
```

</Step>

<Step>

### Scaffold `apps/stats-lab`

```bash
cd apps
npm create vite@latest stats-lab -- --template react-ts
cd stats-lab
```

Add workspace dependencies to `package.json`:

```jsonc
"@tetherto/mdk-react-devkit": "*",
"@tetherto/mdk-react-adapter": "*",
"@tetherto/mdk-ui-foundation": "*",
```

Install from the monorepo root:

```bash
cd ../..
npm install
```

</Step>

<Step>

### Wrap with `MdkProvider`

In `apps/stats-lab/src/main.tsx`, mirror
[Wire a React app — Wrap your app in MdkProvider](/tutorials/ui/react/tutorial#wrap-your-app-in-mdkprovider):

```tsx

// …
<MdkProvider apiBaseUrl="https://example.invalid">
  <App />
</MdkProvider>
```

Mock data does not call the API; the provider satisfies components that expect React context.

</Step>

<Step>

### Run the app

From the monorepo root:

```bash
npm -w stats-lab run build
```

Then start Vite:

```bash
npm -w stats-lab run dev
```

Or from the app folder:

```bash
cd apps/stats-lab
npm run dev
```

Open the URL Vite prints (typically `http://localhost:5173`). You should see **Stats Lab** with histogram, trend line, stat cards,
and a sortable roster tab.

</Step>

<Step>

### Optional: compare with the MDK demo app

Same commands as [Wire a React app — Run the demo app](/tutorials/ui/react/tutorial#run-the-demo-app):

```bash
npm run dev:catalog
```

Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse mining-oriented examples, then contrast with Stats Lab:
**same primitives, different story**.

</Step>

</Steps>

## Why the agent stays accurate

Manifests list real exports, `check` catches many invented props, and `docs` / `example` ground the session in shipped contracts.
The app build remains the final TypeScript and Vite verification.

## Next steps

- [Build dashboards with your AI agent](/quickstart/connect-agents): the two-step entry point
- [UI CLI reference](/reference/app-toolkit/ui-cli): every command in the discovery transcript
- [Chart components](/reference/ui/react/core/components/charts): `BarChart`, `LineChart`, and related data shapes
- [Data display](/reference/ui/react/core/components/data-display): `DataTable` sorting and pagination
- [Wire a React app](/tutorials/ui/react/tutorial): hands-on monorepo setup without an agent

# Your first component (/tutorials/ui/react/first-component)

This tutorial assists first-time users to understand how to render a single MDK component in a React app as fast as possible.

<Callout type="warn">
This path skips `<MdkProvider>` which works for presentational `/core` and `/foundation` imports. For adapter hooks or connected foundation components, 
continue with [Wire a React app](/tutorials/ui/react/tutorial).
</Callout>

## Prerequisites

- **Node.js** >=24
- **npm** >=11
- **React** 19+ and **react-dom** 19+

{/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */}

<Steps>

<Step>

### Clone and build

<Callout type="info">
The MDK UI (`mdk/ui`) is an npm workspace. Clone the repository, install at the workspace root, and 
build all packages before adding an app or running the demo.
</Callout>

#### 1.1 Clone the repository

```bash
git clone https://github.com/tetherto/mdk.git
cd mdk/ui
```

</Tab>
  <Tab value="ssh" label="SSH">

```bash
# Requires an SSH key configured for your GitHub account
git clone git@github.com:tetherto/mdk.git
cd mdk/ui
```

</Tab>
</Tabs>

#### 1.2 Install and build

```bash
npm install
npm run build
```

This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace.

</Step>

<Step>

### Create your app

#### 2.1 Scaffold a Vite React app

Create a new React app in the `apps/` folder:

```bash
cd apps
npm create vite@latest my-app -- --template react-ts
cd my-app
```

<Callout type="info">
Ignore the CLI "Now run" instructions — follow the MDK-specific steps below.
</Callout>

#### 2.2 Add MDK to `package.json`

Open `package.json` and add the workspace dependency:

```jsonc
    "@tetherto/mdk-react-devkit": "*",
```

</Tab>
  <Tab value="context" label="In context">

```jsonc
{
  "name": "my-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "@tetherto/mdk-react-devkit": "*", // [!code ++]
    "react": "^19.2.6", // [!code highlight]
    "react-dom": "^19.2.6" // [!code highlight]
  },
}
```
<Callout type="info">
Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is.
</Callout>

</Tab>
</Tabs>

#### 2.3 Install from the workspace root

```bash
cd ../..    # from apps/my-app back up to the workspace root mdk/ui
npm install
```

</Step>

<Step>

### Import styles

#### 3.1 Import the MDK stylesheet

Import the MDK stylesheet once in your app's entry point (typically `src/main.tsx`):

```tsx
```

</Tab>
  <Tab value="context" label="In context">

```tsx

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)
```

</Tab>
</Tabs>

</Step>

<Step>

### Render your first component

> This example replaces `App.tsx` with a single mining metric tile that toggles between a normal and an alarmed state.

#### 4.1 Replace `App.tsx` with the demo

This pulls a button from `@tetherto/mdk-react-devkit/core` and a domain component (`SingleStatCard`) from `@tetherto/mdk-react-devkit/foundation`:

```tsx

function App() {
  const [overheating, setOverheating] = useState(false)

return (
    <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 320 }}>
      <h1>Miner status</h1>
      <SingleStatCard
        name="Inlet temperature"
        value={overheating ? 78 : 28}
        unit="°C"
        variant={overheating ? 'tertiary' : 'primary'}
        color="red"
        flash={overheating}
      />
      <Button onClick={() => setOverheating((on) => !on)}>
        {overheating ? 'Cool down' : 'Simulate overheat'}
      </Button>
    </div>
  )
}

```

#### 4.2 Run your app

From the workspace root mdk/ui, start the dev server for your app. The `-w` name must match the `name` 
field in `apps/my-app/package.json` (`my-app` from step 2.1):

```bash
npm -w my-app run dev
```

Alternatively, from the app folder:

```bash
cd apps/my-app
npm run dev
```

You should see a card showing `Inlet temperature 28 °C` with a **Simulate overheat** button below it. 
Click the button and the card flips into an alarm state: red border, red text, value jumps to `78 °C`, 
and the whole card pulses. Click **Cool down** to reset.

That is `@tetherto/mdk-react-devkit/core` (the `Button`) and `@tetherto/mdk-react-devkit/foundation` (the `SingleStatCard`) working 
together: generic primitives plus mining-domain components, in one app.

</Step>

</Steps>

## Next steps

- To browse the full kit in one app first, see [Explore the demo](/tutorials/ui/explore-the-demo)
- [Wire a React app](/tutorials/ui/react/tutorial): add `<MdkProvider>` and adapter hooks for connected foundation components
- [Quickstart](/quickstart/wire-react): minimum integration reference (install, provider, stores, theming)
- [Core](/reference/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`)
- [Foundation](/reference/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`)

# Wire a React app (/tutorials/ui/react/tutorial)

This tutorial walks you through the full React stack: three workspace packages, `<MdkProvider>`, and adapter hooks.

<Callout type="info">
For a faster path that renders one presentational component without the provider, see [Your first component](/tutorials/ui/react/first-component). 
</Callout>

## Prerequisites

- **Node.js** >=24
- **npm** >=11
- **React** 19+ and **react-dom** 19+

{/* npm packages are not yet published to the registry; clone the MDK UI monorepo and use workspace dependencies until publish. */}

<Steps>

<Step>

### Clone and build

<Callout type="info">
The `mdk/ui` directory is the npm workspace root. Clone the repository, install at the workspace root, 
and build all packages before adding an app or running the demo.
</Callout>

#### 1.1 Clone the repository

```bash
git clone https://github.com/tetherto/mdk.git
cd mdk/ui
```

</Tab>
  <Tab value="ssh" label="SSH">

```bash
# Requires an SSH key configured for your GitHub account
git clone git@github.com:tetherto/mdk.git
cd mdk/ui
```

</Tab>
</Tabs>

#### 1.2 Install and build

```bash
npm install
npm run build
```

This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace.

</Step>

<Step>

### Create your app

#### 2.1 Scaffold a Vite React app

Create a new React app in the `apps/` folder:

```bash
cd apps
npm create vite@latest my-app -- --template react-ts
cd my-app
```

<Callout type="info">
Ignore the CLI "Now run" instructions — follow the MDK-specific steps below.
</Callout>

#### 2.2 Add MDK to `package.json`

Open `package.json` and add all three workspace packages:

```jsonc
    "@tetherto/mdk-react-devkit": "*",
    "@tetherto/mdk-react-adapter": "*",
    "@tetherto/mdk-ui-foundation": "*",
```

</Tab>
  <Tab value="context" label="In context">

```jsonc
{
  "name": "my-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "@tetherto/mdk-react-devkit": "*", // [!code ++]
    "@tetherto/mdk-react-adapter": "*", // [!code ++]
    "@tetherto/mdk-ui-foundation": "*", // [!code ++]
    "react": "^19.2.6", // [!code highlight]
    "react-dom": "^19.2.6" // [!code highlight]
  },
}
```
<Callout type="info">
Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is.
</Callout>

</Tab>
</Tabs>

#### 2.3 Install from the workspace root

```bash
cd ../..    # from apps/my-app back up to the workspace root mdk/ui
npm install
```

</Step>

<Step>

### Wrap your app in MdkProvider

`<MdkProvider>` wires the headless stores from [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) into React and sets up the TanStack `QueryClient`. It is required for adapter hooks and connected foundation components. See also [Quickstart — Wrap your app in MdkProvider](/quickstart/wire-react#wrap-your-app-in-mdkprovider).

#### 3.1 Update `main.tsx`

```tsx
```

Wrap `<App />`:

```tsx
<MdkProvider apiBaseUrl="https://app-node.example.com">
  <App />
</MdkProvider>
```

</Tab>
  <Tab value="context" label="In context">

```tsx

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <MdkProvider apiBaseUrl="https://app-node.example.com"> {/* [!code ++] */}
      <App />
    </MdkProvider> {/* [!code ++] */}
  </StrictMode>,
)
```

</Tab>
</Tabs>

</Step>

<Step>

### Use adapter hooks and render a component

Adapter hooks subscribe to Zustand stores and re-render when the selected slice changes. This example uses `useAuth` and `useDevices` from the adapter, then renders a presentational `SingleStatCard` from foundation.

#### 4.1 Replace `App.tsx`

```tsx

function App() {
  const { permissions } = useAuth()
  const { selectedDevices } = useDevices()

return (
    <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 360 }}>
      <h1>Operator dashboard</h1>
      <p>Selected devices: {selectedDevices?.length ?? 0}</p>
      <p>Permissions loaded: {permissions ? 'yes' : 'no'}</p>
      <SingleStatCard
        name="Inlet temperature"
        value={28}
        unit="°C"
        variant="primary"
      />
      <Button onClick={() => console.log('Ready for connected components')}>
        Log readiness
      </Button>
    </div>
  )
}

```

<Callout type="info">
Connected foundation components (device explorers, pool manager, settings dashboards) expect `<MdkProvider>` and often read multiple stores. Start with presentational imports while you wire your API; swap in connected components as your backend comes online.
</Callout>

</Step>

<Step>

### Run your app

From the workspace root `mdk/ui`:

```bash
npm -w my-app run dev
```

Or from the app folder:

```bash
cd apps/my-app
npm run dev
```

You should see the operator dashboard with device and permission readouts plus a temperature card. The adapter hooks confirm `<MdkProvider>` is wired — without it, they would throw.

</Step>

</Steps>

## Next steps

- [Quickstart](/quickstart/wire-react): install reference, store hooks, and theming
- [Core](/reference/ui/react/core): primitives reference (`@tetherto/mdk-react-devkit/core`)
- [Foundation](/reference/ui/react/foundation): mining-domain components (`@tetherto/mdk-react-devkit/foundation`)

### Run the demo app

If you are already at the workspace root `mdk/ui`:

```bash
npm run dev:catalog
```

If your shell is still in the app folder:

```bash
cd ../..    # apps/my-app → apps → workspace root mdk/ui
npm run dev:catalog
```

Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse examples.